sap bc developers guide

7/23/2019 Sap Bc Developers Guide

http://slidepdf.com/reader/full/sap-bc-developers-guide 1/338

B2B Developer’s Guide Version 3.0 1

C H A P T E R

Introduction

Welcome!.....................................................................................2

Typographical Conventions..........................................................2

Related Documentation................................................................3

Printing this Guide........................................................................4



C H A P T E R 1 I n t r o d u c t i o n

2 B2B Developer’s Guide Version 3.0

Welcome!

This guide shows you how to create B2B services. It contains information for developers

who want to build B2B services using the webMethods flow language or a programming

language such as Java, C/C++, or Visual Basic. It also contains information aboutcreating client applications, working with output templates, and accessing databases

through webMethods B2B.

To use this guide effectively, you should:

Understand the basic concepts described in Getting Started with webMethods B2B.

Have completed the tutorial in Getting Started with webMethods B2B or have a

general idea about how to perform basic tasks with B2B Developer.

Know how to program in Java, C/C++, and/or Visual Basic if you will be creating

services in those languages.

Typographical Convent ions

This document uses the following typographical conventions:

Convention Example

Procedures are described as a series of

numbered steps.

1. On the Activity menu, click File.

Terms that identify elements, options,

selections, commands on the screen are

shown in bold.

The Service field on the Properties tab specifies the

name of the requested B2B service.

Characters that you must type exactly are

shown in a typewriter font.

Type: setup

and then press ENTER.

Variable information that you must type

based on your specific situation or

environment is shown in italics.

Type: webmethods\setup

and then press ENTER.

Keyboard keys are shown in uppercase. Press ENTER; then press TAB.

Keys that you must press simultaneously

are joined with the “+” symbol.

Press CTRL+ALT+M.

Directory paths are shown with the “\”

directory delimiter unless the subject is

UNIX-specific. In these cases, the “/” is

used. If you are working in a UNIX

environment, substitute a “/” for the “\”

shown in the procedures in this book.

webMethods\Server3\packages\Default



Related Documentation


Convention Example

Information that you must read before

beginning a procedure or that alerts you

to negative consequences of certain

actions is denoted with this special

symbol.

!If the interface is not already open in the Document

Browser, open it before you start the following

procedure.

Notes that provide related, but non-

critical, information are denoted with this

special symbol.

When you start B2B Developer, you are prompted to log

on to a B2B Integration Server.

Program Code Conventions

For programming code and command syntax, this document uses the following

typographical conventions:

Convention Example

Keywords and values that you must typeexactly as printed are shown in

typewriter font.

%CoSymbol%

Variable values or parameters that you

must supply are shown in italics.

%VarName%

Keywords or values that are optional are

enclosed in [ ]. Do not type the [ ]

symbols in your own code.

%loop LoopVar [null=NullValue]%

Related Documentat ion

The following documents are companions to this guide. Some documents are in PDF

format and others are in HTML.

Refer to this book… For…

Getting Started with

webMethods B2B

Information that orients you to B2B and shows you how to create a

simple application. It includes basic conceptual information about

B2B. This book is aimed at new users of B2B and webMethods’

products.

Location:

webMethods\Developer3\doc\B2BTutorial.pdf

B2B Server

Administrator’s Guide

Information about using the Server Administrator to configure,

monitor, and control the B2B Integration Server. This book is aimed at

server administrators.



C H A P T E R 1 I n t r o d u c t i o n


Refer to this book… For…

Location:

webMethods\Server3\doc\B2BAdministratorsGuide.pdf

B2B API Reference Descriptions of the Java classes and built-in services you use to create

B2B services. This reference is aimed at developers who build B2B

services.

Location:

webMethods\Developer3\doc\api\index.html

B2B Developer Online

Help

Information about the controls in B2B Developer application windows

and step-by-step procedures describing how to perform tasks with

B2B Developer.

Location:

In any application window or dialog box, click Help or press F1.

Print ing th is Guide

You can print this guide from Adobe Acrobat Reader 4.0. The document’s title page and

table of contents are at the end of the printed copy. To create a traditional, paper-based

manual, simply move these pages to the front of the document after it is printed.




C H A P T E R

Getting Started with B2B Developer

What is B2B Developer?..............................................................6

Before You Use B2B Developer...................................................6

Starting B2B Developer................................................................7

The B2B Developer Window........................................................9

Basic Operations........................................................................12



C H A P T E R 2 G e t t i n g S t a r t e d w i t h B 2 B D e v e l o p e r


What is B2B Developer?

B2B Developer is an integrated development environment (IDE) that you use to create

B2B services on a B2B Integration Server. It provides all of the tools necessary to build

and test B2B services, generate stubs for client applications, and create output templates.

Before You Use B2B Developer

B2B Developer builds and edits services directly on a B2B Integration Server. To use

B2B Developer you must:

Have access to a B2B Integration Server on which you can build and test B2B

services.

Have a user account on that B2B Integration Server.

Belong to a group that is a member of the “Developers” ACL (access control list) onthat B2B Integration Server.

You will not be able to use B2B Developer unless these requirements are satisfied. If you

do not have access to a B2B Integration Server or you do not have an appropriate user

account or access rights, see you server administrator. See “Creating User Accounts for

Developers” in the B2B Server Administrator’s Guide.



Starting B2B Developer


Start ing B2B Developer

Use the following procedure to start B2B Developer on your workstation.

!Make sure that the B2B Integration Server with which you want to use B2B Developer is running.You cannot work with B2B Developer if the server is not running.

!If you are running UNIX, make sure that the DEVDIR and JDKDIR settings in developer.sh have

been updated to specify the paths where B2B Developer 3.0 (DEVDIR) and Java Runtime

Environment (JDKDIR) reside. If you have not already configured these settings, do so before

starting B2B Developer. These should have been updated by the installation program.

To start B2B Developer

1 Depending on which operating system is running on your workstation, do

the following:

If you are running… Do this…

Windows 1 On the Start menu, click Programs, and thenclick webMethods.

2 Click B2B Developer 3.0.

UNIX 1 Navigate to the directory where you installed B2BDeveloper.

2 Run bin/developer.sh.

Specify the name and portassignment of a B2B

Integration Server…

…and enter a user account that has

developer privileges

2 In the Connect to B2B Integration Server dialog box, complete the

following:

In this field… Specify…

Server The name and port assignment of the B2B IntegrationServer in ServerName:PortNum format.

Example rubicon:5555






!Servers to which you have successfully logged on in the past

are listed in the Server list. You can select a server from this

list or type its name and port number .

Username The name of a valid user account on this server. (Theuser name must be a member of a group belonging to theDevelopers ACL.)

Use the exact combination of upper- and lower-casecharacters with which it was originally defined. B2B user names are case-sensitive.

The server is installed with a default user account called

“Developer” that has developer privileges. (That is, the

Developer user account is a member of the Developers group,

which is a member of the Developers ACL.)

Password The password for the user account in Username. Use the

exact combination of upper- and lower-case characterswith which it was originally defined. B2B passwords arecase-sensitive.

The default password for the Developer user account is

b2bdev.

Uses secure connection Whether the connection will be made through HTTP or HTTPS. If you want to connect to the selected server using the Secure Socket Layer (SSL), enable this option.

Uses proxy Whether the connection will be made through the defaultproxy server. If you want to connect to the selected

server using your proxy server, enable this option.

3 Click OK. You connect to the specified server.



The B2B Developer Window



The B2B Developer window is divided into two panes: the “Service Browser” (on the

left) and the “Editor” (on the right).

B2B Developer Main Window

The Service Browser

The Service Browser displays the contents of packages on the B2B Integration Server to

which you are connected. In the Service Browser, you can:

– Select an element that you want to view or edit.

– Copy, move, delete, or rename an element.

Elements in the Service Browser are shown in a hierarchical structure where packages are

the topmost element in the hierarchy. Packages contain one or more interface elements,

which contain elements that you can create and edit using B2B Developer (e.g., services,

specifications, records).

Service Browser Icons

The icon adjacent to the name of an element denotes the element’s type.

Select a component in theService Browser …

…to view and/or edit thatcomponent in the Editor





This icon… Represents…

A package. A package contains a set of services and related files, such as

specifications, records, and output templates. To display the contents of a

package, click the symbol next to its name.

An interface. An interface contains related services and optional interfaces (calledsubinterfaces). To display the contents of an interface, click the symbol next to

its name.

A flow service. A flow service is a service written in webMethods’ flow language

(WQL). To display or edit the attributes of a flow service, click its name.

A Java service. A Java service is a service written in Java. To display or edit the

Java class file for this service, click its name.

A WebTap service. A WebTap service provides control of an end-user’s browser

experience while allowing B2B services to intercept and modify data that passes

through the B2B integration server. To display or edit the attributes of a WebTap

service, click its name.

A C service. A C service is a service written in C/C++. To display or edit the

attributes of a C service, click its name.

A service specification. A specification is a formal description of a B2B service’s

inputs and outputs. To display or edit a specification, click its name.

A record. A record contains a set of variables. To display or edit a record

definition, click its name.

!The Service Browser on your screen is not dynamically updated when other users on the same

server add, delete, or rename elements in a package. To refresh the contents of the Service

Browser while you are working with B2B Developer, click Refresh on the Service Browser’stoolbar.

Click Refresh to update thecontents of the Service

Browser





The Edi tor

The Editor contains the controls that you use to examine and edit an element you select in

the Service Browser. The contents of the Editor vary depending on the type of element

you select. For example, the Editor is empty when you select a package or interface,

because these elements are containers that do not have any properties you can view or

edit with B2B Developer. However, when you select an editable element such as a flowservice or a specification, the Editor displays the appropriate interface for that particular

element.

Interface for Viewing/Editing Service Flows

Interface for Viewing/Editing Specifications

If you select a serviceflow in the ServiceBrowser…

…the service-editinginterface is displayed

in the Editor

If you select as ecification…

…the specification-editing interface is

displayed





Basic Operat ions

Working in a PaneTo perform an operation on an object displayed in the B2B Developer window, the pane

in which that object appears must be the “selected” pane (i.e., that pane must have the

focus). Only one pane can be selected at a time. For example, when you work in theService Browser, it is the “selected” pane—menu commands and toolbar buttons operate

only within that pane. Commands and buttons that cannot be used with the selected pane

are unavailable.

To switch from one pane to another, simply click any white area within the pane to which

you want to switch. This action changes the focus to the new pane and makes its menu

commands and toolbar buttons available for use.

Multiple Panes and Tabs

For some element types, the Editor is divided into multiple panes. You switch among

panes within the Editor just as you would between the Service Browser and the Editor— to select a different pane, simply click any white area in that pane.

Multiple Panes and Tabs in the Editor

Sometimes, editing controls within a pane are grouped in tabs. To display the contents of

a tab, click the tab’s name.

Creating New ElementsTo create a new element, on the File menu, click New. Follow the instructions given by

B2B Developer. If you need assistance at any step in the process, click Help. For element

descriptions, see “Service Browser Icons” on page 9.

Sometimes the Editor contains multiple

panes…

…and tabs



Basic Operations


!You cannot use B2B Developer to create a new package on a B2B Integration Server. To create a

new package, you (or a server administrator) must create it using the B2B Server Administrator.

Saving Your Work

When you open B2B Developer and select an element in the Service Browser, B2BDeveloper opens a copy of that element for you to edit. Changes that you make to the

element are not written to the B2B Integration Server until you explicitly save your work

using the Save command.

If you attempt to close B2B Developer or disconnect from the current server without

saving your changes, B2B Developer will prompt you to save them before you exit.

!If you are editing elements on a server that you share with other developers, be sure to coordinate

your work with the others so that you do not inadvertently edit the same element simultaneously

and overwrite one another’s work. To avoid conflicts, you may want to make a practice of

allowing only one developer to work on a given package at a time.

Resizing PanesYou can resize panes in the B2B Developer window by dragging borders with your

mouse. Movable borders are marked with symbols. You can also click the

symbols to expand a pane to the full height or width of the current window.

Drag movable bordersto resize panes





Connecting and Disconnecting from a Server When you start B2B Developer you are prompted to log on to the B2B Integration Server

that you want to work with. You remain connected to that server until you exit B2B

Developer or switch to another server.

You can connect to only one B2B Integration Server at a time. If you want to switch to

another server, you must disconnect from the current server and connect to a new one.

! While you are connected to a B2B Integration Server through B2B Developer, you are using a

licensed seat for that server. At times when you are not actively using B2B Developer, you may

want to disconnect from the server or close B2B Developer to free a seat on the server for others

to use.

To disconnect from the current server

1 Save any work that you want to keep.

2 On the Service Browser toolbar, click Disconnect .

To connect to a different server

1 On the Service Browser toolbar, click Connect .

If you are already connected to a B2B Integration Server, B2B Developer

automatically disconnects you from that server. If you have unsaved work, you

are prompted to save it.

2 Complete the Connect to B2B Integration Server dialog box. If you need

procedures for this step, see “To start B2B Developer” on page 7.

3 Click OK.

Using Online HelpYou can access online Help at any point in B2B Developer by clicking the Help button

(available in most dialog boxes) or pressing F1. You can also use the On Topic and

Contents commands on the Help menu.




C H A P T E R

Building Flow Services

Basic Concepts ..........................................................................16

A Process Overview...................................................................20

Creating a New Flow Service.....................................................21

Inserting Flow Operations ..........................................................22

Using the Flow Control Operations ............................................27

Creating a Specification for a Service ........................................45

Mapping the Pipeline..................................................................53



C H A P T E R 3 B u i l d i n g F l o w S e r vi c e s


Basic ConceptsTo successfully build a flow service, you should understand the following basic concepts

and terms.

What is a Flow Service?A flow service is a service that is written in webMethods’ flow language. This simple yet

powerful language lets you encapsulate a sequence of B2B services within a single

service and manage the flow of data among them. For example, you might create a flow

service that takes a purchase order from a buyer and executes the following series of B2B

services before submitting it to an internal ordering system:

1. Gets a purchase order submitted by a buyer

2. Logs the order in an audit-trail file

3. Performs a credit check

4. Posts the order to the ordering system

Flow Services Encapsulate Other B2B Services

Client application invokes

Purch:SubmitPO...

INVOKE Purch:LogOrder

INVOKE Purch:CreditAuth

INVOKE Purch:PostPO

Purch:SubmitPO

INVOKE Purch:GetOrders

…which performs a sequence

of four B2B services

1

2

3

4

Any B2B 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 by webMethods, and/or services from a webMethods add-on product such as

B2B for R/3 or B2B for BAAN.



Basic Concepts


Flow Services and WIDL

In webMethods B2B Developer 3.0, flow services replace WIDL services as the standard framework for

building business applications. If you have WIDL services, they will continue to run on the webMethods

B2B Integration Server 3.0. However, if you need to edit a WIDL service, you must do so using B2B

Developer 2.x.

Once you install B2B Developer 3.0, we strongly recommend that you use it to create all new services as

flow services. Flow services provide the same capabilities as WIDL services, plus much more.

Flow Control

In addition to letting you combine multiple B2B services into single, callable units,

webMethods’ flow language also provides a set of “flow-control” operations that allow

you to direct the execution of a flow service at run time. The flow-control operations

allow you to:

– Conditionally execute a specified sequence based on a variable value.

– Retry a specified sequence until it succeeds.

– Repeat a specified sequence (loop) for each element in an array variable.

In the following flow service, flow-control operations have been inserted to loop through

a subset of the flow service and branch to one of two services in the last step of the loop.

Flow control operations are used to direct the execution of a flow

hgkg

INVOKE Purch:LogOrder


INVOKE Purch:PostPO

INVOKE Purch:BouncePO

Purch:SubmitPO

LOOP PurchaseOrders

BRANCH AuthOK

INVOKE Purch:GetOrders

Yes

No

A LOOP operationrepeats a set of

operations

A BRANCH operation selects a

specified operationfor execution





Creating Flow Services

You create flow services using B2B Developer. They are saved in XML files on the B2B

Integration Server.

! Although flow services are written as XML files, they are maintained in a format that can only be

created and understood by B2B Developer. You cannot create or edit a flow service with a texteditor.

What is a Flow Operation?

A flow service contains flow operations. A flow operation is a basic unit of work

(expressed in webMethods flow language) that the B2B Integration Server interprets and

executes at run time.

A flow service can contain the following flow operations:

Invocation Operations

INVOKE Executes a specified service. For more information about this operation,

see “Invoking Services from a Flow” on page 25.

Flow Control Operations

BRANCH Executes a specified operation based on the value of a specified variable

in the pipeline. For more information about this operation, see “The

BRANCH Operation” on page 27.

REPEAT Re-executes a set of operations up to a specified number of times based

on the successful or non-successful completion of the set. For more

information about this operation, see “The REPEAT Operation” on page

33.

SEQUENCE Groups a set of operations into a series. The SEQUENCE operation is

implicit in most flow operations (that is, operations in a flow are treated

as a series). However, at times it is necessary to explicitly group a subset

of operations using SEQUENCE so that they can be treated as a unit.

For more information about this operation, see “The SEQUENCE

Operation” on page 38.

LOOP Executes a set of operations once for each element in a specified array.

For more information about this operation, see “The LOOP Operation”

on page 39.

EXIT Controls the execution of a flow operation; for example, abort an entire

flow from within a series of deeply nested operations, throw an

exception without writing a Java service, or exit a LOOP or REPEAT

without throwing an exception. For more information about this

operation, see “The EXIT Operation” on page 42.



Basic Concepts


Data-Handling Operations

MAP Performs specified editing operations on the pipeline (e.g., adding

variables to the pipeline, dropping variables from the pipeline, and so

forth). For more information about this operation, see “Working with the

MAP Operation” on page 63.

See Appendix A for a detailed description of each flow operation provided by the

webMethods flow language.

What is the Pipeline?

The pipeline is the general term used to refer to the data structure in which input and

output values are maintained for a flow service. It allows services in the flow to share

data.

The pipeline starts with the input to the flow service and collects inputs and outputs from

subsequent services in the flow. When a service in the flow executes, it has access to all

data in the pipeline at that point.

The Pipeline holds the input and output for a flow service

Flow Service

Name:Kings Sport

ONum:46-77135

INVOKE Purch:LogPO

Tnum:128824993554

AuthNum:TW99123554

Phone:201-887-1544

Qty:20


Acct:128824993554

Date:04/04/99

Item:PK8801-NS

OrderDate:19990404

Ship:UPS Ground

INVOKE Purch:ConvertDate

INVOKE Purch:SendPO

Terms:30N

Freight:65.00

Status:Received

Total:5732.78

The Pipeline

input

input

input

output

output

output

output

input

Services in a flow get their

input and put their output in

the pipeline

When you build a flow service, you use B2B Developer to specify how information in the

pipeline is mapped to and from services in the flow.





What is a Specification?

A specification is the component of a B2B service that describes the names and types of

variables that the service requires as input and generates as output. For example, a service

that takes two string values—an account number ( AcctNum) and a dollar amount

(OrderTotal )—as input and produces an authorization code ( AuthCode) as output, has the

following specification:

A Specification Defines the Service’s Inputs and Outputs

Input Output

Name Data Type Name Data Type

AcctNum String AuthCode String

OrderTotal String

Part of the process of creating a B2B service is defining its specification—i.e., explicitly

specifying the variables it expects as input and produces as output.

Using External Specifications

A external specification is a free-standing description of a specific set of inputs and

outputs. When you build a service, you can optionally define its specification through an

external specification instead of an using an explicit definition within the service itself.

The use of an external specification allows you define a specification once, and reference

it from multiple services. It also facilitates easy maintenance by allowing you to

implement changes in one place—the specification—as opposed to many individual

services.

A Process Overview

Building a flow service is a process that involves the following basic stages:

Stage 1 Creating a new service on the B2B Integration Server. During this stage,

you create the new service on the B2B Integration Server where you will

do your development and testing. For information about this stage, see

“Creating a New Flow Service” which follows.

Stage 2 Inserting flow operations into the new service. During this stage, you

specify the work that you want the service to perform by adding flowoperations to the service. For information about this stage, see “Inserting

Flow Operations” on page 22.



Creating a New Flow Service


Stage 3 Specifying the signature (inputs and outputs) of the service. During this

stage, you define the service’s inputs and outputs. For information about

this stage, see “Creating a Specification for a Service” on page 45.

Stage 4 Mapping pipeline data. During this stage, you route input and output

values between services that are invoked in the flow. For informationabout this stage, see “Mapping the Pipeline” on page 53.

Stage 5 Specifying the run-time parameters. During this stage, you assign

parameters that configure the run-time environment for this service. For

information about this stage, see “Specifying Run Time Parameters” on

page 67.

Stage 6 Create an output template. If the new service returns HTML or XML text

as output, during this stage you can create an output template for the

service. For information about this stage, see “Creating Output

Templates” on page 97.The remaining sections in this chapter provide detailed information about each stage.

Creat ing a New Flow Service

The first step you take when you build a flow service is to create a new service on the

B2B Integration Server where you do your development.

Package and Interface Requirements

Before you create a new flow service, you must:

— Make sure the package in which you want to create the service already exists. If the package

does not already exist, use the B2B Server Administrator to create it. See the online

help system for step-by-step procedures. (If you do not have administrative

privileges on the B2B Integration Server, ask your server administrator to do this.)

— Make sure the interface in which you want to create the service already exists. If the interface

does not already exist, use B2B Developer to create it. See online Help for step-by-

step procedures.

Once the package and interface are in place, you use the FileNew command to start the

wizard that leads you through the process of creating a new service. See online Help for step-by-step procedures.





Using the Default Logic Options

The wizard that creates a new flow service gives you the option of starting with an empty

flow (one that contains no predefined flow operations) or starting with a service that

contains a set of default logic for extracting information from an HTML or XML

document (a common flow-service function).

If you are building a flow service that extracts data from an HTML or XML document,

you can select an option to automatically generate the logic (i.e., the set of flow

operations) that will get data from a specified document, rather than building this logic

manually.

Use this option… To…

Load and Query anHTML Page

Automatically generate a flow service that invokes the

loadDocument service (which gets a document from a URL that

you specify) and the queryDocument service (which extracts a

specified set of elements from the document returned by

loadDocument).

For additional information about the loadDocument and

queryDocument services, see “Creating a Load-and-Query

Service from a URL” on page 127.

Record in Browser Automatically generate a service based on URLs that you select

in your browser. When you use this option, B2B Developer

automatically generates an INVOKE loadDocument and

INVOKE queryDocument operation for each URL that you visit.

For additional information about recording load-and-query

operations from a browser, see “Using the Browser Recorder” on

page 129.

Receive an XMLDocument

Automatically generate a service that receives an XML document

object as input. If you specify the format by providing a DTD,

B2B Developer maps the incoming document to its corresponding

record structure.

!The flow operations produced by these options are no different than those produced by

manually inserting INVOKE loadDocument and INVOKE queryDocument operations in a

flow service. Once the B2B Wizard inserts the set of default operations into your flow

service, you can edit the default operations and insert additional operations just as you would

any ordinary flow service.

Insert ing F low Operat ions

To insert flow operations in a flow service, you must first select that service in the

Service Browser and click the Flow tab in the Editor. The flow operations in the service



Inserting Flow Operations


are listed in the “Flow Pane” at the top of the tab. (If you just created the service, and it

does not contain any default logic, the Flow Pane is empty).

Operations for the Selected Service are Displayed in the Flow Pane

Flow operations are inserted into a service using the following toolbar buttons at the top

of the Flow Pane (you cannot directly type an operation into the Flow Pane—all editing

is performed through the toolbar):

Click this button… To insert…

A flow-control or data-handling operation (for example,

BRANCH, LOOP, MAP).

An INVOKE operation.

Note If you select an existing operation in the flow pane before inserting a new one, the Editor

inserts the new operation below the one that is selected. If you do not have an operation selected, it

adds the new operation to the end of the flow. You can move an operation to a new location using

the arrow buttons on the toolbar. See “Changing the Position of an Operation” which follows.

Changing the Position of an Operation

Operations run in the order in which they appear in the Flow Pane. To move an operationup or down in a flow, you select that operation in the Flow Pane, and then use the arrow

buttons on the toolbar to move it up or down in the list.

Operations are displayedin the Editor’s “flow pane”





Click this button… To…

Move the operation up in the list.

Move the operation down in the list.

You can also move an operation by dragging it up or down with your mouse or by using

the Shift commands on the Compose menu.

Changing the Level of an Operation

Some flow operations have subordinate operations on which they operate. Subordinate

operations are referred to as children. For example, when you use the LOOP operation,

the set of operations that make up the loop are referred to as “children” of that LOOP

operation.

Children are specified by indenting them beneath their parent operation. In the followingexample, a LOOP operation has three children. Note that one of its children is a

BRANCH operation, which has its own set of children.

Child operations are indented beneath their parent operation

To promote or demote an operation within a parent/child hierarchy, select the operation in

the Flow Pane, and then use one of the following buttons to move it left or right beneath

the current parent operation.

Click this button… To…

Demote an operation in the hierarchy. This action makes theselected operation a child of the preceding parent operation. (This

button will only be available if you select an operation that can become a child.)

Promote an operation in the hierarchy. This action moves theoperation one level up in the hierarchy.

These three operations are“children” of the LOOP

operation

These operations are “children”of the BRANCH operation





Setting the Properties of a Flow OperationEvery flow operation has a unique set of properties associated with it. The properties for a

flow operation are displayed on the Editor’s Properties tab. Values that you specify on the

Properties tab are applied only to the selected operation in the Flow Pane.

Properties of a Flow Operation

Although each type of flow operation has a set of unique properties, they all have the

following properties:

Property Description

comment Assigns an optional descriptive comment to the selected flow

operation.

label Assigns a name to the selected flow operation. When a label is

assigned, that label appears next to the operation in the Flow Pane. The

label allows you to reference that flow operation in other flow

operations. In addition, you use it to control the behavior of certain

flow operations. For example, the BRANCH operation uses the label

property to determine which alternative it is supposed to execute.

See “The BRANCH Operation” on page 27 and “The EXIT Operation”

on page 42 for additional information about this use of the label property.

For a complete description of the properties associated with each flow operation, see

Appendix A.

Invoking Services from a Flow

You use the INVOKE operation to request a B2B service within a flow.

Use the Properties tabto view and set theproperties of a flow

o eration





Flow containing four INVOKE operations

To insert an INVOKE operation, click on the toolbar in the Flow Pane and select

the service that you want to invoke.

Note When you install B2B Developer, the (Insert) menu displays a list of commonly-used

B2B services. You can use the EditPreferences command to customize this list of services to

suit your needs.

When you use the INVOKE operation, you may:

— Invoke any type of service, including other flow services.

— Invoke any service that resides on the B2B Integration Server to which you are

connected.

— Invoke flow services recursively (i.e., a flow service can call itself). If you use a flow

service recursively, bear in mind that you must provide a means to end the recursion.

Specifying the Service Property

The INVOKE operation’s service property specifies which service will be invoked at run

time. When you insert an INVOKE operation, B2B Developer automatically assigns the

name of that service to the service property.If you want to change the service assigned to an INVOKE operation, you edit the service

property. When you specify the service property, keep the following points in mind:

— You must specify the service’s fully-qualified name in interfacename:serviceName

format.

Example purchasing.orders:getOrders

— You must specify the service’s name exactly as it is defined on the server. Service

names are case-sensitive.

Invoking a Built-In ServiceThere is an extensive set of built-in services that you can invoke from a flow. The

webMethods’ library includes services for doing such things as transforming data values,

performing simple mathematical operations, extracting information from Web

documents, and accessing databases.





Built-in services reside in the WmPublic package. For a complete description of these

services, see Appendix C.

Note If you are using one of webMethods’ integration modules (e.g., B2B for SAP R/3, B2B for

BAAN), you will have additional built-in services provided. See the documentation provided with

those packages for details.

Using the Flow Control Operations

The flow control operations allow you to direct the course of execution in a flow. Unless

you specify otherwise, operations in a flow execute sequentially, one after another until

either an operation fails or the end of the flow service is reached. Flow-control operations

allow you to:

— Conditionally execute one operation from a set of specified alternatives (BRANCH)

— Repeat a set of operations up to a specified number of times or until an operation in

the set fails or succeeds as specified (REPEAT)

— Group a set of operations and control the way in which the failure of a member of the

set is processed (SEQUENCE)

— Repeat a set of operations over the elements of a specified array (LOOP)

— Exit the entire flow or exit a single flow operation (EXIT)

The BRANCH OperationThe BRANCH operation allows you to conditionally execute an operation based on the

value of a variable at run time. For example, you might use a BRANCH operation to

process a purchase order one way if the PaymentType value is “CREDIT CARD” and

another way if it is “CORP ACCT”.

To build a BRANCH operation, create a list of the conditional operations (target

operations) and make them children of the BRANCH operation. Then, complete the

following steps:

— In the Properties tab for the BRANCH operation, specify the name of the pipeline

variable whose value will act as the switch.

— In the label property of each target, specify the value that will trigger the operation.





Simple BRANCH Operation

Specifying the Switch Variable

The variable you use as the switch variable:

— Must be a string variable.

— Must be a variable that exists in the pipeline when the BRANCH operation is

executed at run time.

— Must be formatted as record /recordElement , if you are specifying a record element as

the switch variable. (e.g., SupplierInfo/ AccountNum)

Specifying the label Value

At run time, the BRANCH operation matches the value of the switch variable to the label

property of each of its targets. It executes the operation whose label matches the value of

the switch.

You may use a regular expression to specify the matching value for a BRANCH

operation. To do this, use the following syntax to specify the value in label:

/ RegularExpression/

For example, if you want to select an operation based on whether a PO number starts withthe string “REL” you use /^REL/ as the value of label.

Unlike other flow operations, whose children execute in sequence at run time, only one

child of a BRANCH operation is executed—the target whose label matches the value of

the switch variable. If none of the targets match the switch variable, none of them are

Each conditional operationhas a label that matches thevalue that triggers it

The switch property of the BRANCH operation

specifies the name of the variable that acts as

the switch





performed, and execution “falls through” to the next operation in the flow. For example,

in the following flow, execution passes directly to the Orders:LogTransaction service if the

value of PaymentType is “COD.”

An unmatched value will fall though the BRANCH

Keep the following points in mind when assigning labels to the targets of the BRANCH

operation:

— You must give each target operation 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 30.

— Each label value must be unique within the BRANCH operation.

— When you use specify a literal value as the label of a child operation, the value you

specify must match the run-time value of the switch variable exactly. The label

property is case-sensitive.

— You may use a regular expression as the value of label instead of a literal value.

— You can use the $null option in the label property to match a null value.

— You can use the $default value in the label property to designate a default operation for

all unmatched cases. For more information about using the $default setting, see the

following section.

Specifying a Default Operation

If you want to prevent the service from falling through a BRANCH operation when an

unmatched value occurs at run time, include a default operation to handle unmatched

cases. To specify the default alternative of a BRANCH operation, set the label property to

$default.

The following example shows a BRANCH operation that is used to calculate the shipping

charges for an order based on the value of a buyer’s account number ( BuyerAcctNumber ).

It contains three target operations. The first two targets single out two accounts for special

handling. Note that the labels for these targets specify the account numbers that will

If PaymentType is“COD,” execution

will fall through thisBRANCHoperation





trigger them. The third operation has the $default label, so it will process all other

accounts.

The default operation is set to $default

Branching on Null and Empty Values

You can use a null variable (a variable that has not been assigned a value or has been

explicitly set to null) or an empty string (a string variable that contains no characters) to

trigger the execution of a child in a BRANCH operation. To branch on one of these

values, set the label property for the child operation as follows.

To BRANCH on… Do the following…

A null variable Set the label property to $null.

An empty string Leave the label property blank (empty).

Note You may use $null with any type of switch variable. You may only use an empty value withString variables.

Using SEQUENCE as the Target of a BRANCH

In many cases, you may want a BRANCH operation to conditionally trigger a series of

multiple operations rather than just a single step. For these cases, you can use the

SEQUENCE operation as the target operation and group a series of flow operations

beneath it.

The following example illustrates a service that accepts a purchase order and processes it

one of three ways depending on the payment type specified in the PaymentType variable.

Because a series of steps are needed to process the PO in each case, the targets of the

BRANCH are defined as SEQUENCE operations, and the appropriate series of

operations are specified as children beneath each SEQUENCE.

The first two childrenhandle two specificaccount numbers…

and the default(unlabeled) childhandles the rest





Use a SEQUENCE operation as the target for a multi-step alternative

Define a multi-step alternative in a SEQUENCE

The SEQUENCE operation that you use as a target for a BRANCH operation can contain

any valid flow operation, including additional BRANCH operations. For additional

information about building a SEQUENCE, see “The SEQUENCE Operation” on page 38.

Building a BRANCH Operation

Use the following procedure to build a BRANCH operation in a flow service.

To build a BRANCH operation

1 If you are inserting a BRANCH operation into an existing flow service,

display that service in the Flow Pane and highlight the operation

immediately above where you want the BRANCH operation inserted.

2 Click on the Flow Pane toolbar and select BRANCH from the list.

3 Complete the following fields on the Properties tab:

Create a SEQUENCEoperation for each

multi-step alternative…

…and then specify theappropriate series of

operations as childrenbeneath eachSEQUENCE





For this property… Specify…

comment An optional descriptive comment for thisoperation.

scope The name of a record in the pipeline to whichyou want to restrict this operation. If you want

this operation to have access to the entirepipeline, leave this field blank.

timeout The maximum number of seconds that thisoperation should run. When the time isexceeded, the operation stops and raises anexception. However, if this operation contains anINVOKE operation, the INVOKE operation is notinterrupted when the timeout value is exceeded.Instead, the exception is raised after theINVOKE is complete.

If you do not want to specify a timeout period,

set timeout to zero or leave it blank.

label An optional name for this specific operation, or anull, unmatched, or empty string ($null, $default,blank). For details, see “Branching on Null andEmpty Values” on page 30.

Note If you use this operation as a target for a

BRANCH or EXIT operation, you must specify a value

in the label field. See “The BRANCH Operation” on

page 27 or “The EXIT Operation” on page 42 for

details.

switch The name of the string variable whose value will

be used to determine which child operation isexecuted at run time.

4 Insert the conditional operations that belong to the BRANCH using the

following steps:

1 Insert a flow operation using or on the Flow Pane

toolbar.

2 Indent the flow operation using on the Flow Pane toolbar. (Make

it a child of the BRANCH operation.)

3 In the label field on the Properties tab, specify the switch value that

will trigger this operation at run time. You may use any of the

following as values:

Specify… To match…

A string That exact string.

A regular expression Any string fitting the criteria





specified by the regular expression.

Example /^REL/

A blank field An empty string.

$null A null string.

$default Any unmatched string (i.e., executethe operation if the value does notmatch any other label).

4 Set other properties as needed.

The REPEAT OperationThe REPEAT operation allows you to conditionally repeat a sequence of child operations

based on the success or failure of those operations. You can use the REPEAT operation

to:

— Re-execute (retry) a set of operations if any operation within the set fails. This option is useful

to accommodate transient failures that might occur when accessing an external

system (e.g., databases, ERP systems, or Web servers) or device.

— Re-execute a set of operations until one of the operations within the set fails. This option is

useful for repeating a process as long as a particular set of circumstances exists (e.g.,

data items exist in a data set).

Use REPEAT to re-execute one or more operations

The INVOKE operationis repeated up to 10

times if it fails at run time





Specifying the REPEAT Condition

When you build a REPEAT operation, you set the repeat-on property to specify the

condition—success or failure—that will cause its children to be re-executed at run time.

If you set “repeat on” to… The REPEAT operation…

FAILURE Re-executes the set of child operations if any operation in the set fails.

SUCCESS Re-executes the set of child operations if all operations in the set completesuccessfully.

!Unless you set the REPEAT operation’s counter to 0, children of a REPEAT operation always

execute at least once. At the end of each iteration, the server checks to see whether the condition

for repeating was satisfied. If the condition is true and the repeat count is not met, the children are

re-executed. This process continues until the repeat condition is false or the repeat limit is met,

whichever occurs first.

Setting the REPEAT Counter

The REPEAT operation’s count property determines whether the REPEAT operation will be limited to a specified number of iterations, and if so, what that limit is.

If you set the count to… The REPEAT operation…

0 Skips the entire set of child operations. When you specify this

value, the children of the REPEAT are not executed even once.

Except for debugging purposes, when you may want to temporarily

disable a REPEAT operation, this value has no practical application

in a production service.

1 Executes the set of child operations once. Equivalent to a

SEQUENCE operation.

Any value > 1 Repeats the set of child operations no more than this number of

times.

-1 Repeats the set of child operations as long as the specified repeat

condition remains true.

Using REPEAT to Retry a Failed Operation

If your flow invokes services that access external systems, you can use the REPEAT

operation to accommodate network errors—busy servers, connection errors, and so

forth—at run time. If you use the REPEAT operation for this purpose, keep the following

points in mind:

The following types of failures satisfy the FAILURE condition:

— Expiration of a child operation’s timeout limit.

— An exception thrown by a Java service.

— A document query that returns a nonpermitted null value.





If you specify multiple children under a REPEAT operation, the failure of any one of

the children will cause the entire set of children to be re-executed.

The REPEAT operation immediately exits a set of children at the point of failure (i.e.,

if the second child in a set of three fails, the third child is not executed).

The failure of a child within a REPEAT operation will not cause the REPEAToperation itself to fail unless the count limit is reached.

The timeout property for the REPEAT operation specifies the amount of time in which

the entire REPEAT operation, including all 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.

As a developer, you must be thoroughly familiar with the processes you include

within a REPEAT operation. Make certain that the operations you specify can safely

be repeated in the event that a failure occurs. You don’t want to use REPEAT if there

is the possibility that a singular action—such as accepting an order or crediting an

account balance—could be applied twice.

To build a REPEAT operation that re-executes failed operations

1 If you are inserting a REPEAT operation into an existing flow service,


immediately above where you want the REPEAT operation inserted.

2 Click on the Flow Pane toolbar and select REPEAT from the list.


For this property… Specify…comment An optional descriptive comment for this

operation.

scope The name of a record in the pipeline to whichyou want to restrict this operation. If you wantthis operation to have access to the entirepipeline, leave this field blank.

timeout The maximum number of seconds that thisoperation should run. When the time isexceeded, the operation stops and raises anexception. However, if this operation contains an

INVOKE operation, the INVOKE operation is notinterrupted when the timeout value is exceeded.Instead, the exception is raised after theINVOKE is complete.

If you do not want to specify a timeout period,





set timeout to zero or leave it blank.

label An optional name for this specific REPEAToperation, or a null, unmatched, or empty string($null, $default, blank).

Note If you use this operation as a target for aBRANCH or EXIT operation, you must specify a value



details.

count The maximum number of times you want thechildren to be re-executed.

If you want the children re-executed until theyare all successful (i.e., no maximum limit), setthis value to –1.

backoff The length of time (in seconds) that you want theserver to wait between iterations of the children.

repeat on FAILURE

4 Beneath the REPEAT operation, use the following steps to insert each

operation that you want to repeat:


toolbar.

2 Indent that flow operation using on the Flow Pane toolbar. (Make

it a child of the REPEAT operation.)

3 Set the properties for the child operation as needed.

Using REPEAT to Repeat a Successful Operation

Apart from using REPEAT to retry a failed operation, you can also use it as a

looping device to repeat a series of operations until a failure occurs. In a Web-

automation service, you could use it to repeat a load and query operation until it fails

to produce a required value. For example, you might repeat a set of operations as

long as the query finds a “Next Page” button in the current document, indicating that

there are additional pages to be processed. In this situation, you would want to end

the loop when the query operation “fails” to retrieve a “Next Page” button in the

current document.

If you use the REPEAT operation to re-execute successful operations, keep the following

points in mind:

— The success condition is met if all children of the REPEAT operation execute without

returning a single exception.

— If one child in the set fails, the REPEAT operation exits at the point of failure,

leaving the remaining children unexecuted.





— The failure of a child does not cause the REPEAT operation to fail; it merely ends the

loop. (In this case, the REPEAT operation itself succeeds and execution of the flow

proceeds normally).

To build a REPEAT operation that repeats a set of successful operations1 If you are inserting a REPEAT operation into an existing flow service,


immediately above where you want the REPEAT operation inserted.

2 Click on the Flow Pane toolbar and select REPEAT from the list.





timeout The maximum number of seconds that thisoperation should run. When the time isexceeded, the operation stops and raises anexception. However, if this operation contains anINVOKE operation, the INVOKE operation is notinterrupted when the timeout value is exceeded.Instead, the exception is raised after theINVOKE is complete.

If you do not want to specify a timeout period,set timeout to zero or leave it blank.

label An optional name for this specific operation, or anull, unmatched, or empty string ($null, $default,blank).





details.

count The maximum number of times you want thechildren to be re-executed.

If you want the children re-executed until anyone of them fails (i.e., no maximum limit), set thisvalue to –1.





backoff The length of time (in seconds) that you want theserver to wait between iterations of the children.

repeat on SUCCESS

4 Beneath the REPEAT operation, use the following steps to insert each

operation that you want repeat:


toolbar.

2 Indent that flow operation using on the Flow Pane toolbar. (Make

it a child of the REPEAT operation.)


The SEQUENCE OperationYou use the SEQUENCE operation to build a set of operations that you want to treat as a

group. Operations in a group are executed in order, one after another. By default, all

operations in a flow, except for children of a BRANCH operation, are executed as though

they were members of an implicit SEQUENCE operation—i.e., they execute in order, one

after another. However, there are times when it is useful to explicitly group a set of

operations. The most common reasons to do this are:

— To group a set of operations as a single alternative beneath a BRANCH operation.

For details about this use of the SEQUENCE operation, see “Using SEQUENCE as

the Target of a BRANCH” on page 30.

— To specify the conditions under which the server will exit a sequence of operations

without executing the entire set.

Using SEQUENCE to Specify an Exit Condition

In an implicit sequence, when an operation fails, the server automatically exits the

sequence (i.e., the exit on property is set to FAILURE). By grouping operations into an

explicit sequence, you can override this default behavior, and specify the condition on

which the sequence exits. To do this, you set the exit on parameter as follows:

Set exit-on to… If you want the server to…

FAILURE Exit the sequence when an operation in the sequence fails. (Executioncontinues with the next flow operation in the flow service.) This is the defaultbehavior of a sequence of operations.

This setting is useful if you have a series of operations that build upon oneanother. For example, if you have a set of operations that gets aauthorization code and then submits a PO, you will want to skip the POsubmission if the authorization step fails.

When a SEQUENCE exits under this condition, the SEQUENCE operationfails.





SUCCESS Exit the sequence when any operation in the sequence succeeds. (Executioncontinues with the next operation in the flow service.)

This setting is useful for building a set of alternative operations that are eachattempted at run time. Once one of the members of the set runs successfully,the remaining operations in the sequence are skipped.

When a SEQUENCE exits under this condition, the server considers theSEQUENCE operation successful. The only time it fails is if all its children fail.

DONE Execute every operation in the sequence even if one of the operations in thesequence fails.

The server considers a SEQUENCE operation successful as long as itexecutes all of its children within the specified timeout limit. The success or failure of a child within the sequence is not taken into consideration. If a childfails under this condition, any changes that it made to the pipeline are rolledback (undone), and processing continues with the next operation in theSEQUENCE.

The LOOP OperationThe LOOP operation repeats a sequence of child operations once for each element in an

array that you specify. For example, if your pipeline contains an array of purchase-order

line items, you could use a LOOP operation to process each line item in the array.

To specify the sequence of operations that make up the body of the loop (i.e., the set of

operations you want the LOOP to repeat), you indent those operations beneath the LOOP

as shown in the following example.

Simple LOOP Operation

You may include any valid flow operation within the body of a LOOP, including

additional LOOP operations. The following example shows a pair of nested LOOPs. Note

how the indentation of the operations determines the LOOP to which they belong.

The body of the loopmust be indented

beneath the LOOPoperation.





Nested LOOP Operations

Speci fy ing the Input Array

The LOOP operation requires you to specify an input array that contains the individual

elements that will be used as input to one or more operations in the LOOP. At run time,

the LOOP operation executes one pass of the loop for each member in the specified array.For example, if you want to execute a LOOP for each line item stored in a purchase order,

you would use the Record List in which the order’s line items are stored as the LOOP’s

input array.

You specify the name of the input array on the LOOP operation’s Properties tab. The

array you specify can be any of the following data types:

— String List

— String Table

— Record List

— Object List

LOOP Properties

This entire LOOPoperation is a child of

the outer LOOP

The LOOP operationexecutes once for each

member of the arrayspecified in in-array.





When you design your flow, bear in mind that since 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 Record List called LineItems that contains

children called Item, Qty, and UnitPrice, you would specify LineItems as the in-array for

the LOOP operation, but services within the loop would take the individual elements of

LineItems (e.g., Item, Qty, UnitPrice, and so forth) as input.

Collecting Output from a LOOP Operation

If your LOOP operation produces an output variable, the server can automatically collect

that output into an array in the pipeline.

To do this, you use the out-array parameter to specify the name of the variable that you

want the server to collect for each iteration of the loop. For example, if your loop checks

inventory status of each line item in a purchase order and produces a String called

InventoryStatus each time it executes, you would specify InventoryStatus as the value of

out-array. At run time, the server will automatically transform InventoryStatus to an arrayvariable that contains the output from each iteration of the loop. (If you examined the

output stage of the pipeline, InventoryStatus would appear as an array variable).

To collect output from each pass of the loop, specify the name of the output variable that

you want the server to collect for each iteration.

Bui lding a LOOP Operat ion

Use the following procedure to build a LOOP operation in a flow service.

To build a LOOP operation

1 If you are inserting a LOOP operation into an existing flow service, display

that service in the Flow Pane and select the operation immediately above

where you want the LOOP operation inserted.

2 Click on the Flow Pane toolbar and select LOOP from the list.





timeout The maximum number of seconds that thisoperation should run. When the time is





exceeded, the operation stops and raises anexception. However, if this operation contains anINVOKE operation, the INVOKE operation is notinterrupted when the timeout value is exceeded.Instead, the exception is raised after theINVOKE is complete.

If you do not want to specify a timeout period,set timeout to zero or leave it blank.

label An optional name for this specific LOOPoperation, or a null, unmatched, or empty string($null, $default, blank).





details.

in-array The name of the array variable on which theLOOP will operate. This variable must be one of the following types: String List, String Table,Record List, Object List.

out-array The name of the element that you want theserver to collect each time the LOOP executes.You do not need to specify this property if theloop does not produce output values.

4 Build the body of the loop using the following steps:


toolbar.

2 Indent the flow operation using on the Flow Pane toolbar. (Make

it a child of the LOOP operation.)


5 Use the Pipeline Editor to map the elements of the input array to the

input variables required by each child of the LOOP operation. See

“Mapping the Pipeline” on page 53 for additional information about using

the Pipeline Editor .

The EXIT Operation

The EXIT flow operation allows you to exit the entire flow service or a single flowoperation. You specify whether you want to exit from:

— The nearest ancestor LOOP or REPEAT flow operation to the EXIT flow operation

— The parent flow operation of the EXIT flow operation





— A specified ancestor flow operation to the EXIT flow operation

— The entire flow service

When you use the EXIT operation, you indicate whether exiting should return a

successful condition or a failure condition. If the exit is considered a failure, an exception

is thrown. You specify the text of the error message that is displayed.

Examples of when to use the EXIT operation include to:

— Exit an entire flow service from within a series of deeply nested operations.

— Throw an exception when you exit a flow or a flow operation without having to write

a Java service to call Service.throwError().

— Exit a LOOP or REPEAT flow operation without throwing an exception.

To build an EXIT operation

1 If you are inserting an EXIT operation into an existing flow service, displaythat service in the Flow Pane and select the operation immediately

above where you want the EXIT operation inserted.

2 Click on the Flow Pane toolbar and select EXIT from the list.




label An optional name for this specific operation, or anull, unmatched, or empty string ($null, $default,blank).





details.

from The flow operation that you want to exit from.Specify one of the following:

Specify… To exit from the…

$loop Nearest ancestor LOOP or REPEAT flow operation.

$parent Parent flow operation, regardlessof the type of operation.

$flow Entire flow.





label Nearest ancestor flow operationthat has a label that matches thisvalue.

Note If the label you specify doesnot match the label of an ancestor

flow operation, the flow will exitwith an exception.

signal Whether the exit is to be considered a successor a failure. Specify one of the following:

Specify… To..

SUCCESS Exit the flow service or flowoperation with a successcondition.

FAILURE Exit the flow service or flowoperation with a failure condition.

An exception is thrown after the

exit. You specify the error message with thefailure-message property.

failure-message The text of the exception message you want todisplay. This property is not used when signal isset to SUCCESS.



Creating a Specification for a Service


Creat ing a Speci f icat ion for a Service

A specification is a formal description of a B2B service’s inputs and outputs (some

systems refer to these as “imports” and “exports.”). A specification describes the

following information about a service:

— The names of input variables it takes and their data types.

— The names of output variables it produces and their data types.

You create specifications for all types of B2B services: flow services, Java services, and

services written in other supported programming languages.

Although you are not required to create specifications for a B2B service, (the B2B

Integration Server will execute a service regardless of whether it has a specification or

not), there are good reasons to do so:

A specification makes the service’s input and outputs visible to B2B Developer. Without a

specification, you cannot:

− Map data to and/or from the service using B2B Developer’s Pipeline Editor.

− Assign default input values to the service with the Pipeline Editor.

− Test the service in B2B Developer and enter initial input values.

− Generate skeleton code for invoking the service from a client.

A specification 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 generate a

specification for every B2B service that you create.

Completing the Input/Output Tab

You define the input/output specification for a service using the Input/Output tab. On

the left side of this tab, you define the variables that the service requires as input. On

the right side, you define the variables it returns to the client or calling program.





Input/Output tab

For a flow service, the input side of the specification describes the initial contents of the

pipeline. In other words, it specifies the variables that this flow service expects to find in

the Values object it receives.

Specifying Input Variables

When you define the input specification for a flow service, keep the following points in

mind:

Specify all inputs that a calling program must supply to this flow service. For example, if aflow service invokes two other services, one that takes a variable called AcctNum and

another that takes OrderNum, you must define both AcctNum and OrderNum in the

flow service’s specification.

The purpose of the input specification is to define the inputs that a calling program or

client must provide when it invokes this flow service. You do not need to define inputs

that are obtained from within the flow itself. For example, if the input for one service

in the flow is derived from the output of another service in the flow, you do not need to

include that variable in the specification.

When possible, use variable names that match the names used by the services in the flow.

Variables with the same name are automatically mapped to one another in the

pipeline. (Remember that variable names are case-sensitive.) If you use the same

variable names used by flow’s constituent services, you reduce the amount of manual

data mapping that needs to be done. When you specify names that do not match the

ones used by the constituent services, you must use the Pipeline Editor to manually

Define the flow’s inputrequirements on this

side…

..and outputrequirements on this

side





map them to one another. For information about the Pipeline Editor, see “Mapping

the Pipeline” on page 53.

Make sure the variables match the data types of the variables they represent in the flow. For

example, if a service in the flow takes a Record List called LineItems, define that

input variable as a Record List in the flow’s input specification. For a complete

description of the data types supported by a B2B service, see Appendix D.

Specifying the Output Variables

On the output side of the Input/Output tab you specify the variables that you want the flow

to return to the calling program or client. The guidelines for defining the output

specification are similar to those for an input specification:

Specify all of the output variables that you want this flow service to return to the calling

program or client.

Make sure the names of output variables in your specification match the names used by the

services that produce them. Like input variables, if you do not specify names that

match the ones produced by the flow’s constituent services, you must use the Pipeline

Editor to manually map them to one another. For information about the Pipeline

Editor, see “Mapping the Pipeline” on page 53.

Make sure the variables match the data types of the variables they represent in the flow. For

example, if a service produces a Record List called LineItems, make sure you define

that variable as a Record List in the flow’s output specification. For a complete

description of the data types supported by a B2B service, see Appendix D.

To create a specification for a service

1 In the Service Browser , select the service for which you want to create aspecification.

2 In the Editor , click the Input/Output tab.

3 If you want to reference an external specification, do the following:

1 In the Specification field, type the specification’s name or click to

select it from a list. See “Creating an External Specification” on page

48 for information about creating external specifications.

2 Skip the rest of this procedure.

!When an external specification is assigned to a service, you cannot add,delete, or modify the variable definitions using the service’s Input/Output

tab.

4 If you want to reference an external record for the Input or Output half of

the specification, do the following:





1 In the Input or Output field (depending on which half of the

specification you want to assign the record to), type the record name

or click to select the record from a list. See “Creating an External

Record Definition” on page 51 for information about creating external

records.

2 If you assigned an external record name to both the Input and Output

sides of this specification, skip the rest of this procedure. Otherwise,

continue to the next step to specify the variables in the other half of the

specification.

!When an external record is assigned to the Input or Output side of a

specification, you cannot add, delete, or modify the variable definitions on

that half of the Input/Output tab.

5 For each input or output variable that you want to define, do the following:

1 Select the half of the specification (Input or Output) where you want

to define the variable by clicking anywhere in that half’s large white

text box.

2 Click on the toolbar and select the type of variable that you

want to define.

3 Type the name of the variable and press ENTER.

4 If the variable is a Record or a Record List, repeat steps 2 and 3 to

define each of its members. Then use to indent each member

beneath the Record or Record List variable.

Creating an External Specification

An external specification is a “free-standing” B2B 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 external specification rather than

manually specifying individual input and output variables in each service.

Using external 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 variable name.

— It makes future specification changes easier to implement, because you can make

the change in one place—the external specification—rather than in each individual

service.

If you use an external specification, keep in mind that:





— Any change that you make to the external specification is automatically

propagated to all services that reference that specification. (This happens the

moment you save the updated specification to the server.)

— An external specification wholly defines the specification for a service that

references it. This means that you cannot directly alter the service’s specification

through its Input/Output tab. (B2B Developer displays the specification, but does

not allow you to change it.) To make changes to the specification for the service,

you must modify the external specification (which, of course will affect all

services that reference it) or detach the external specification so you can manually

define the variables on the service’s Input/Output tab.

You create an external specification with B2B Developer. You assign an external

specification to a service using the Input/Output tab.

To create an external specification

1 On the File menu, click New. The B2B Wizard starts.

2 On the New panel, click Service Specification and then click Next.

3 On the Enter Name panel, do the following:

1 In the Interface tree, select the interface to which you want to save the

specification.

2 In the Name field, type a name for the specification using any

combination of letters, numbers, and the underscore character.

!

B2B Developer does not allow you to use certain reserved words

(such as for , while, and i f) as names. If you specify a name that is areserved 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.

3 Click Finish.

4 If you want this specification to reference another external specification, do

the following:

1 In the Specification field, type the external specification’s name or

click to select it from a list.

2 Skip the rest of this procedure.

!Typically, you do not build an external specification by referencing

another specification. However, it is useful to do this in the situation

where you will use the specification with a group of services whose

requirements are expected to change (i.e., they match an existing

specification now, but are expected to change at some point in the





future). Referencing an external specification gives you the convenience

of using an existing specification and the flexibility to change the

specification for only that single group of services in the future.

5 If you want to reference an external record for the Input or Output half of

the specification. Do the following:

1 In the Input or Output field (depending on which half of the

specification you want to assign the record to) type the record name or

click to select the record from a list. See “Creating an External

Record Definition” on page 51 for information about creating external

records.

2 Proceed to the next step to specify the variables for the other half of

the specification. (If you assigned external record names to both the

Input and Output sides of this specification, skip the rest of this

procedure.)

!Once you assign an external record to the Input or Output side of a

specification, you cannot add, delete, or modify the variable definitions on

that half of the Input/Output tab.

6 For each input or output variable that you want to define, do the following:

1 Select the half of the specification (Input or Output) where you want

to define the variable by clicking anywhere in that half’s large white

text box.


want to specify.

3 Type the name of the variable and then press ENTER.


define each of its members. Then use to indent each member

beneath the Record or Record List variable.

7 On the File menu, click Save (or click in the Service Browser ). The

external specification is saved to the B2B Integration Server.

To assign an external specification to a service

1 In the Service Browser , select the service to which you want to assign a

specification.

2 Click its Input/Output tab.





3 In the Specification field, type the fully-qualified name of the external

specification, or click to select it from a list.

!When an external specification is assigned to a service, you cannot add, delete,

or modify the variable definitions using that service’s Input/Output tab.

Creating an External Record Definition

An external record definition is a “free-standing” B2B element that defines the contents

of a record. You can use an external record to specify a set of input or output variables in

a specification. You can also use it to build a Record or Record List in a specification or

the pipeline.

Like external specifications, using an external record provides the following benefits:

— It reduces the effort required to build a flow.

— It improves accuracy, because there is less opportunity to introduce a typing error

typing variable names.

— It makes future changes easier to implement, because you can make a change in

one place—the external record—rather than everywhere the record is used.

You create an external record with B2B Developer. You can assign an external record to

the input or output half of the Input/Output tab. You can also use it anywhere the

Developer permits you to build a Record or Record List variable from an “Existing

Record” or an “Existing Record List.”

To create an external record1 On the File menu, click New. The B2B Wizard starts.

2 On the New panel, click Record and then click Next.

3 On the Record panel, do the following:

1 In the Interface tree, select the interface into which you want to save

the record.

2 In the Name field, type a name for the record using any combination of

letters, numbers, and/or the underscore character.

!B2B Developer does not allow you to use certain reserved words (such as

for , while, and if ) as names. If you specify a name that is a reserved word,

you receive an error message. When this happens, use a different name or

try adding a letter or number to the name you have specified to make it

valid.





4 On the XML Format panel, select one of the following to specify whether you

want to build a record based on the structure defined in an existing DTD.

Select… To…

None Create an empty record in which you define

variables.Local DTD or XML Document

Create a record that matches the structure of anXML document or DTD that resides on your localfile system.

URL to DTD or XML Document

Create a record that matches the structure of anXML document or DTD that resides on theInternet.

!If you specify an XML document, that document must have an associated

DTD for its root element.

5 Click Finish.

6 For each variable in the record, do the following:


want to specify.

2 Type the name of the variable and then press ENTER.


define its member variables. Then use to indent each member

variable beneath the Record or Record List variable.

7 On the File menu, click Save (or click in the Service Browser ). The

external record is saved to the B2B Integration Server.

To assign an external record to a specification

1 In the Service Browser , select the service to which you want to assign

the external record.

2 Click its Input/Output tab.

3 In the Input or Output field (depending on which half of the specification

you want to apply the external record to), type the fully-qualified name of

the external record or click to select the external record from a list.

!When an external record is assigned to a specification, you cannot add,

delete, or modify the variable definitions on that half of the Input/Output

tab.



Mapping the Pipeline


To use the external record to build a Record or Record List variable

1 Click on the toolbar and select one of the following:

Click… To…

Existing Record Create a Record variable based on anexternal record.

Existing Record List Create a Record List variable based on anexternal record.

2 In the Name field, type the fully-qualified name of the external record or

select it in the Interface tree.

3 Click OK.

4 Type the name of the variable.

5 Press ENTER.

Mapping the Pipel ine

When you include multiple services in a flow, you may encounter inconsistencies in the

way those services name their variables or represent input and output values. For

example:

The services might use different variable names for the same data item. For instance, one

service might use Telephone as the name of the variable for phone number

information and another might use PhoneNumber.

The services might use different formats to represent the same value. This most commonly

occurs with date and time variables, where, for instance, one service might use

“01/01/99” and another “January 1, 1999.” In other cases, your services may use

different notations for standard codes or values. For example, one service might use

shipping codes that look like this: “Freight, ” “Overnight,” and “Ground,” and

another might use “FR,” “ND,” and “GR” (or even something completely different

such as: “Fracht,” “Nachster Tag,” and “Normalzustellung”).

The services might use different data structures to represent a data item. For example, one

service might put the phone number in a string called Telephone, and the next service

may expect it to find it in an element of a record array called CustInfo.

To resolve these types of discrepancies, you use the Pipeline Editor and B2B’s built-in

data-handling services.





What is the Pipeline Editor?

The Pipeline Editor is the facility you use to inspect the pipeline and route input and

output between services in a flow. You access the Pipeline Editor by selecting the Pipeline

tab for a service in a flow. The Pipeline tab displays a “map” of the expected state of the

pipeline at run time.

As shown in the following diagram, the Pipeline Editor depicts two stages of the pipeline

with respect to the selected service.

The Pipeline Tab

This stage… Represents…

1The 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 of the preceding services).

Service In depicts the set of variables the selected service expects as input

(as defined by its specification).

Using the Pipeline Editor, you can insert “pipeline modifiers” at this stage

to adjust contents of the pipeline to suit the requirements of the service.

Modifications that you specify during this stage are performedimmediately before the service executes at run time.

2The 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 specification).

The Pipeline tabdepicts the service’s

specification withrespect to the

expected pipeline

21





This stage… Represents…

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.

Using the Pipeline Editor, you can insert “pipeline modifiers” at this stageto adjust contents of the pipeline to suit the requirements of the service.

Modifications that you specify during this stage are performed

immediately after the service executes at run time.

Pipeline ModifiersYou use the following buttons to add pipeline modifiers to a flow service. Pipeline

modifiers are special commands that you apply to adjust the pipeline at run time. They

execute immediately before or after the selected service, depending on where you add

them to your pipeline map.

Use this modifier… To…

Map a pipeline variable with a service variable. This modifier

lets you resolve variable-name differences by allowing you to

“map” (copy) the value of one variable to another at run time.

See “Mapping Pipeline Variables to Service Inputs and

Outputs,” below for information about using this pipeline

modifier.

Drop a variable from the pipeline. This modifier allows you to

remove extraneous variables from the pipeline. See “Dropping

Variables from the Pipeline” on page 61 for information about

using this pipeline modifier.

Assign a value to a variable. This modifier allows you to “hardcode” a value for a variable. See “Assigning Values to

Pipeline Variables” on page 59 for information about this

pipeline modifier.

Mapping Pipeline Variables to Service Inputs and Outputs

Within a flow, variables with the same name are automatically mapped to one another.

For example, the service in the following flow takes a variable called AcctNum. Since a

variable by this name already exists in Pipeline In, it is automatically mapped to the

AcctNum variable in Service In.





The Pipeline and Service Input Variables

In cases where the services in a flow do not use the same names for a piece of

information, you use the Pipeline Editor to map the variables to each other. It is the

means you use to accomplish name and structure transformations required in a flow.

Mapping Input Variables

On the input side of a pipeline map, you use the Pipeline Editor to map 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 —they are simply

different names for the same piece of data. To instruct the server to use the value of

BuyersTotal as the value for OrderTotal , you “map” the pipeline variable to the service

using the Map modifier.

At run time, the server will copy the value from the source variable ( BuyersTotal ) to the

target variable (OrderTotal ) before executing the service.

Pipeline variables areautomatically mapped to

service inputs of the

same name





Mapping the Pipeline to Service Input

When you map variables on the input side of a pipeline map, keep the following points in

mind:

— Pipeline In variables are source variables and the Service In variables are targets. By

mapping variables between these sets, you are actually copying data from the

pipeline variable to the service variable.

— A Service In variable can be the target of only one Map modifier. Similarly, a Record

(or a Record List) and its children cannot both be targets. Once you apply a Map

modifier to a Record or Record List, you cannot apply a different modifier to its

children.

— After a Map modifier is executed, both the source and target variables exist in the

pipeline. The target variable does not replace the source variable.

Mapping Output Variables with Different Names

All output variables produced by a service are automatically placed in the pipeline. Just as

you can map variables from the Pipeline In stage to a service’s input variables, you can

map the output from a service to a different variable in Pipeline Out.

In the following example, a variable called TransactionNumber is mapped to the element

Num in a record called TransRecord . At run time, the server will copy the value of

TransactionNumber to Num, and both TransactionNumber and Num will be available to

subsequent services in the flow.

When a pipeline variablename is different from theone used by the service,

you use the Map modifier to connect them





Mapping Service Output to the Pipeline

When you map variables on the output side of a pipeline map, keep the following points

in mind:

— Service Out variables are source variables and Pipeline Out variables are targets. By

mapping variables between these sets, you are actually copying data from the output

variable of the service to another variable in the pipeline.

— A Pipeline Out variable can be the target of only one Map modifier.

— After the Map modifier is executed, both the source and target variables exist in the

pipeline. The target variable does not replace the source variable.

Mapping Variables of Different Data Types

The Pipeline Editor allows you to map different, but compatible, data types to one

another. For example, you could map a String value called AccountNumber to a String

List called Accounts. At run time, the server automatically performs the structural

transformation necessary to map the data in AccountNumber to Accounts. (In this case,

the transformation will result in a single-element String List.)

If you map variables of different data types, keep the following points in mind:

— Not all data types can be mapped to one another. You cannot map an Object to a

String, for instance. If two data types are incompatible, the Pipeline Editor will notallow you to connect them with the Map modifier.

— If you map a scalar variable (one that holds a single value) to an array variable (one

that holds multiple values) you will get an array variable containing one element.

When an output variablename is different from

the name in the pipeline,you use the Map

modifier to connect them





— If you map an array variable to a scalar variable, the scalar variable will get the first

element in the array.

To map one variable to another

1 In the Flow Pane, select the INVOKE or MAP operation whose

variables you want to map.

2 Click the Pipeline tab.

3 If you want to map a variable from the pipeline to an input variable, do

the following:

1 In Pipeline In, click the pipeline variable.

2 In Service In, click the input variable.

3 Click on the toolbar.

4 If you want to map an output variable to the pipeline, do the following:

1 In Service Out, click the output variable.

2 In Pipeline Out, click the appropriate pipeline variable.


!If the Pipeline Editor does not display a connecting line

between the two variables you choose, the variable types are

incompatible and cannot be mapped to one another.

!

Tip You can use your mouse to map variables to one another.

To do this, select the source variable and the drag your mouse to the appropriate target variable.

Assigning Values to Pipeline Variables

The Set Value modifier allows you to assign values to variables in Service In or Pipeline

Out. You use it to explicitly “hardcode” a specific value in a variable. You can also use it

to assign a default value to a variable.

By attaching a Set Value modifier to a variable, you instruct the server to write a

specific value to that variable at run time. This action occurs just before the selected

service is executed (if you attach the modifier to a variable in Service In) or immediately

after the selected service is executed (if you attach the modifier to a variable in Pipeline

Out).





Hardcoding the Value of a Variable

To view (or change) the value that is assigned to the Set Value modifier, double click the

icon next to the variable’s name to open the Input For dialog box.

The Input For dialog box

Assigning a Default Value to a Variable

One common use of the Set Value modifier, is to specify a default value for a variable—a

value that is only assigned if the variable is empty (null) at run time. To use the Set Value

modifier in this way, disable the Overwrite Pipeline Value option in the Input For dialog box.

This instructs the server to use the specified value only when the selected variable is null.

Referencing Other Variables

In addition to assigning a literal value to a variable, the Set Value modifier lets you assign

the value of a variable to a variable. (You might do this if you wanted to derive thedefault value from a variable in the pipeline at run time, for example.)

To specify a variable name with the Set Value modifier, enclose the name of that variable between % symbols and then enable the Perform Variable Substitution option. This optioninstructs the server to interpret your value as a variable reference rather than a literalvalue.

You use the Set ValueModifier to assign a value

to a variable

Specify the value that youwant the server to assign to

this variable at run time





The Input For dialog box

To assign a value to a variable in the Pipeline


variable you want to alter.


3 Select the variable to which you want to assign a value.

! You can only assign values to variables that are in Service In or

Pipeline Out.


5 In the Input For dialog box, specify the value you want to assign to

this variable.

— If you want to assign a literal value to the variable, type that value.

— If you want to derive the value from a variable in the pipeline, type

the name of that variable enclosed in % symbols. (e.g.,

%Phone%). Then, enable the Perform Variable Substitutionoption.

6 If you want the server to use the specified value only if the variable

does not contain a value at run time, disable Overwrite Pipeline

Value. (If you enable this option, the server will always apply the

specified value.)

Dropping Variables from the Pipeline

The Drop pipeline modifier allows you to remove a variable from Pipeline In or Pipeline

Out. You can use it to eliminate pipeline variables that are not used by subsequent

services in a flow. Dropping unneeded variables reduces the size of the pipeline at run

time and reduces the length and complexity of the Pipeline In and Pipeline Out displays (this

can make the Pipeline Editor much easier to use when you are working with a complex

flow).

Enclose the variablename in % symbols…

…and then enable the

variable-substitutiono tion





!Once you drop a variable from the pipeline, it is no longer available to subsequent services in the

flow. Do not use this modifier unless you are sure the variable is not used by services invoked

after the point where you drop it.

At run time, the server removes a dropped variable from the pipeline just before it

executes the selected service (if you attach the Drop modifier to a variable in Pipeline In) or immediately after it executes the selected service (if you attach the Drop modifier to a

variable in Pipeline Out).

If you drop a mapped variable from Pipeline In, the server executes the Map modifier

before it drops the variable.

To drop a variable in the Pipeline


pipeline variables you want to drop.


3 Select the variable that you want to drop.

! You can only drop variables from Pipeline In and Pipeline Out.


Adding Variables with the Pipeline Editor The Pipeline Editor allows you to add variables that were not declared in the

specifications of the flow service itself or any of its constituent services. You can use it toadd variables that were omitted from a service’s specification or create temporary

variables for use within the flow. (For example, you might attach a variable to each of the

children in a BRANCH operation to mark the path taken by the service at run time.)

Variables that you create with the Pipeline Editor can be used just like any declared

variable in the flow.

!If you create a new variable in a flow, you must immediately do one of the following:

— Map a variable to it.

— Assign a value to it.

— Drop it.

If you do not take one of these steps, the Pipeline Editor automatically clears it from the map the

next time it refreshes the Pipeline tab.





To add a variable to the pipeline map

1 In the Flow Pane, select the INVOKE or MAP operation to which you

want to add a new variable.


3 Select the point where you want to add the new variable.

! You can add a new variable to any point in the map: Pipeline In, Service

In, Service Out or Pipeline Out.

4 Click and select the type of variable that you want to create.

5 Type the name of the variable and press ENTER.


define its member variables. Then use to indent each member

variable beneath the Record or Record List variable.

7 Assign one of the pipeline modifiers to the new variable (Map, Drop,

or Set Value). (If you do not assign a modifier to the variable, the

Pipeline Editor considers it extraneous to the flow and automatically

clears it from the map when it refreshes the Pipeline tab.)

Working with the MAP Operation

The MAP operation lets you adjust the pipeline at any point in a flow. It provides a way

to make pipeline modifications that are independent of an INVOKE operation.

When you insert a MAP operation in your flow, B2B Developer displays a Pipeline tab

with two sets of variables: Pipeline In and Pipeline Out.





The Pipeline Tab for the MAP Operation

Pipeline In represents input to the MAP operation. It contains the names all of the

variables in the pipeline at this point in the flow.

Pipeline Out represents the output of the MAP operation. It contains the names of

variables that will be available in the pipeline when the MAP operation completes.

When you first insert a MAP operation into your flow, Pipeline In and Pipeline Out are

identical. You use the following editing tools to adjust the contents of Pipeline Out so that

it reflects the set of variables that you want to pass to the next step in the flow.

Use this tool… To…

Map (copy) the value from a variable in Pipeline In to another

variable in Pipeline Out.

Drop a variable from the pipeline. (You can only apply this

modifier to variables in Pipeline In.)

Assign a value to a variable. (You can only apply this modifier

to variables in Pipeline Out.)

Create a new variable in the pipeline. (You create new

variables in Pipeline Out.)

Using MAP to Initial ize Variables in a Flow Service

The MAP operation is especially useful for hardcoding an initial set of input values in a

flow service. To use it in this way, insert the MAP operation at the beginning of your

flow, and then use the Set Value modifier to assign values to the appropriate variables in

Pipeline Out.





Performing Value Transformations on Pipeline Variables

Besides using different variable names to represent the same piece of information,

services can represent the same piece of information in different ways. This is common

with date and time variables, where, for instance, one service might use “01/01/99” and

another “January 1, 1999.”

To resolve data differences, webMethods B2B provides a set of value-transformation

services that you can use to transform values from one format to another.

The value transformation services are located in the following interfaces in the WmPublic

package:

This interface… Contains services to…

Pub.date Transform time and date information from one format to another.

Pub.string Transform string values in various ways (e.g., pad, concatenate, replace

through a lookup table).

Pub.math Perform simple arithmetic operations (add, subtract, multiply, and

divide) on string-based numeric information.

To use a value transformation service in a flow, take the following steps:

1. Determine which built-in service you need to use. See “Date Services,” “Math

Services,” and “String Services” in Appendix C for descriptions of available

transformation services.

2. Insert the transformation service into your flow at the point where you want the

transformation to take place. See “Invoking Services from a Flow” on page 25 if you

need procedures for this step.

3. Use the Pipeline Editor to:

− Map the appropriate variables in and out of the transformation service

− Assign literal values required by the service.

The following procedure describes the steps you take to convert a date value from one

format to another with the pub.date:dateTimeFormat service. Although this procedure

describes one specific service, it can be used as a model for when working with other

value-transformation services.

To convert a date value from one format to another

1 In the Service Browser , select the flow service into which you want to

insert the DateTimeFormat service.

2 In the Flow Pane, highlight the operation immediately above where you

want the DateTimeFormat service inserted.





3 On the Flow Pane toolbar, click , and then click Browse.

4 Locate and select the pub.data:DateTimeFormat service and then click

OK.

!You must insert this service at a point in the flow where the source date(the date you want to convert) is available in the pipeline.

5 Click the Pipeline tab. The Pipeline Editor for the DateTimeFormat service

appears.

6 Map the variable that contains the source date (the date you want to

convert) from Pipeline In to inString in Service In.

7 Take the following steps to describe the format of the source date.

1 Select currentPattern in Service In.


3 Type a pattern string that defines the format of your source date and

then click OK.

Example

You use the following string to define the format of

“January 15, 1999.”

MMMMM dd, yyyy

See “Date Services” on page 220 for a complete description of the

pattern-matching symbols.

8 Complete the following steps to describe the format to which you want the

source date converted.1 In Service In, select newPattern.


3 Type a pattern string that defines the format to which you want the

date converted and then click OK.

Example

You use the following string to define the format for “19990115.”

yyyyMMdd

9 Map the value variable (in Service Out) to the variable that requires the

converted date.



Specifying Run Time Parameters


Speci fy ing Run Time Parameters

As a developer of a B2B service, you can use the options on the Settings tab to specify

whether or not you want the server to treat it as a “stateless” service at run time and/or to

cache its results.

! The run-time options on the Settings tab should only be set by someone who is thoroughly

familiar with the structure and operation of the selected service. Improper use of these options

can lead to a service failure at run time and/or the return of invalid data to the client program.

Maintaining the State of a Service

When a remote client connects to a B2B Integration Server, the server automatically

builds a session object for that client. The server uses this object to maintain specific

information about the client requesting the service. It contains information such as user

name and password. The server maintains the session object for the duration of the

connection—i.e., until the client program explicitly disconnects from the server or times

out due to inactivity.

When you develop services in a language such as Java, C/C++, or Visual Basic, you can

use the “put” method to write information to the session object. You might do this to store

information that a sequence of services needs to maintain a connection to an external

system.

A service that is an atomic unit of work—i.e., one that is wholly self contained and not

part of a multi-service transaction to an external system—does not to need to have its

session object maintained when it is finished executing. For performance reasons, you

may want to configure these types of services to run in “stateless” mode. Services that run

in “stateless” mode use fewer resources and do not consume a licensed seat on the B2B

Integration Server.

! Do not use the stateless option unless you are certain that the service operates as an atomic unit

of work. If you are unsure, leave the Stateless option disabled.

To configure a service’s run-time state

1 In the Service Browser, select the service that you want to configure.

2 Select the Settings tab.

3 Under Runtime, enable the Stateless option if you do not want the server to maintain session information for this service. Otherwise, leave this

option disabled.





Configuring a Service’s Use of Cache

Caching is an optimization feature that can improve the performance of stateless services.

When you enable caching for a service, the server saves the results from invoking the

service in a local cache for the period of time that you specify. When the server receives

subsequent requests for a service with the same set of input values, it returns the cached

result to the client rather than invoking the service again. Caching can significantly

improve response time of services. For example, services that retrieve information from

busy data sources such as high-traffic commercial Web servers could benefit from

caching. The server can cache the results for all types of B2B services—flows, Java

services, and C/C++ services.

Types of Services to Cache

While caching service results can improve performance, not all services should be

cached. You should never cache services if the cached results might be incorrect for

subsequent invocations or if the service performs tasks that must be executed each time

the service is invoked. This section describes guidelines for you to consider when

determining whether to cache the results for a service.

Services Suited for Caching

Services that require no state information. If a service does not depend on state

information from an earlier transaction in the client’s session, you can cache its

results.

Services that retrieve data from data sources that are updated infrequently. Services whose

sources are updated on a daily, weekly, or monthly basis are good candidates for

caching.

Services that are invoked frequently with the same set of inputs. If a service is frequently

invoked by clients that identify the same input information, it is beneficial to cache

the results.

Services That You Should Not Cache

Services that perform required processing. Some services contain processing that must be

processed each time a client invokes it. For example, if a service contains accounting

logic to perform charge back and you cache the service results, the server does not

execute the service, so the service does not perform charge back for the subsequent

invocations of the service.

Services that require state information. Do not cache services that require state

information from an earlier transaction, particularly information that identifies the

client that invoked it. For example, you do not want to cache a service that produced





a price list for office equipment if the prices in the list vary depending on the client

who initially connects to the data source.

Services that retrieve information from frequently updated sources. If a service retrieves data

from a data source that is updated frequently, the cached results can become outdated.

Do not cache services that retrieve information from sources that are updated in real-time or near real-time, such as stock quote systems or transactional databases.

Services that are invoked with unique inputs. If a service handles a large number of unique

inputs and very few repeated requests, you will gain little by caching its results. You

might even degrade server performance by quickly consuming large amounts of

memory.

Controll ing a Service’s Use of Cache

You use the options on the Settings tab to enable caching and to configure the way in

which you want it to operate with the selected service. You use these settings to strike theright balance between data currency and memory usage. To gauge the effectiveness of

your cache settings, you can monitor its performance by viewing service statistics with

the Server Administrator and then adjusting your caching values accordingly.

If you do not have administrator privileges on your B2B Integration Server, work with your

server administrator to monitor and evaluate your service’s use of cache.

Specifying the Duration of a Cached Result

The server maintains results in cache for the period of time you specify in the Cache Expire

field on the Settings tab. The expiration timer begins when the server initially caches a

result, and it expires when the time you specify elapses. (The server does not reset theexpiration timer each time it satisfies a service request with a cached result.)

Using the Prefetch Option

You use the Prefetch option to specify whether or not you want the server to automatically

refresh the cache for this service when it expires. If you enable Prefetch, the server

automatically re-executes the service (using the same set of inputs as before) to update its

results in cache. This action also resets the cache expiration timer.

! Use Prefetch carefully. Overuse can quickly exhaust the memory available for cache.

! Do not use Prefetch with Java or C/C++ services that invoke access-controlled B2B services.

Such services will fail during prefetch because the embedded service will be invoked without

the proper access privileges. To avoid this problem, enable Prefetch on the invoked services

rather than on the Java or C/C++ services that call them.





When you enable Prefetch, you must also set the Prefetch Activation option to specify when

the server should initiate a prefetch. This setting specifies the minimum number of times

a cached result must be accessed (hit) in order for the server to prefetch results. If the

cache receives less than the number of hits you specify, the server will not perform a

prefetch when the results expire.

The following procedure describes how to use the B2B Developer to enable caching for a

service. You (or a system administrator) can also enable caching using the B2B Server

Administrator. See the B2B Server Administrator’s Guide for procedures.

To enable result caching

1 In the Service Browser, select the service that you want to configure.

2 Select the Settings tab.

3 Under Runtime, enable the Caching option.

4 In the Cache Expire field, type an integer representing the length of time

(in minutes) that you want the results for this service to be available in

cache.

5 If you want to use prefetch, do the following:

1 Enable the Prefetch option.

2 In the Prefetch Activation field, specify the minimum number of

hits needed to activate the use of Prefetch.




C H A P T E R

Building B2B Services with a Programming Language

The Values object ......................................................................74

Building B2B Services Using Java.............................................74

Building a B2B Service Using C/C++.........................................87

Building B2B Services Using COM ............................................91



C H A P T E R 4 B u i l d i n g B 2 B Se r v i c e s w i t h a P r o g r a m m i n g L a n g u ag e


Basic Concepts

In addition to using the built-in services that webMethods 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 clientapplication.

This chapter describes how to create your own B2B services using Java, C/C++, and

Visual Basic.

!Java is the native language for B2B services. When you create services in other languages,

you must wrap them to appear as a Java class to the B2B Integration Server.

The Values object

The Values object is the universal container that B2B services use to receive input from

and deliver output to other programs. The Values object is an ordered hashtable thatcontains the individual data elements on which a B2B service operates. It can contain any

number of elements of any valid Java data type, including additional Values objects.

A B2B service takes one, and only one, input variable—a Values object. When a B2B

service is invoked, the B2B Integration Server passes the Values object to it. The service

extracts the actual input values it needs from the elements of the Values object.

A B2B service also returns a Values object as output. Any information that is produced

by the service and must be returned to the calling program, must be written to an element

in the Values object.

Bui ld ing B2B Services Using Java

Since Java is the native language of B2B services, it is the easiest language in which to

build a B2B service.

The B2B Developer provides an Integrated Development Environment (IDE) that you can

use to create, compile, and publish Java services. The IDE automatically generates an

appropriately-structured source file that you simply “fill-in” using the built-in editor.

When you save the source file, the IDE automatically compiles it and registers it on the

B2B server.

Although the Developer’s IDE is useful for creating small, simple services, you may want

to use your own Java IDE to build large services. When you use your own IDE, you must

create all of the code yourself, compile it in your IDE, and then manually copy and

register the class file on the B2B server. The B2B Integration Server provides utilities to

publish services you write in your own IDE. For more information about creating Java



How Java Services are Organized on the Server


services without using the Developer, see “Building a Java Service with Your Own IDE”

on page 82.

How Java Services are Organized on the Server

A Java service is a public static method in a Java class file on the B2B Server. They

follow a simple naming scheme:

− The service name represents the Java method name

− The interface name represents the fully-qualified Java class name

Since Java class names can’t contain the “.” character, services that reside in nested B2B

interfaces are implemented in a class that is scoped within a package. For example, a

service named recording.accounts:createAccount is made up of a Java method called

createAccount in a Java class called accounts within the recording package.

All Java services created in the same B2B interface are methods of the same class.

When you build a Java service with the Developer, it automatically combines your

service into the class file associated with the B2B interface in which you created it.

However, if you build a Java service in your own IDE, you will need to add the class file

to the server yourself. And, if you want that service to be recognized by Developer, you

must insert special comment code in your source code. See

Bui ld ing a Java Service wi th the B2B Developer

The following describes the basic stages involved in creating a Java service.

Stage 1 Create the Java service using the B2B Developer. During this stage, youwrite your program in the Developer’s IDE. This stage is described in

the following section. For information about this stage, see “Creating a

Java Service with the Developer’s IDE” on page 78.

Stage 2 Specify the signature (inputs and outputs) of the service. During this

stage, you define the service’s inputs and outputs in a specification. For

information about this stage, see “Creating the Input/Output

Specification for a Java Service” on page 80.

Stage 3 Specify the service’s 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 82.

Before you create a Java service, you must:





— Make sure the package in which you want to create the service already exists. If the package

does not already exist, use the B2B Server Administrator to create it. See the online

help system for step-by-step procedures. (If you do not have administrative


— Make sure the interface in which you want to create the service already exists. If the interface

does not already exist, use B2B Developer to create it. See the Developer’s online

help for step-by-step procedures.

!All Java services that belong to the same interface reside in the same Java class file. This

class has the same name as the interface.

Using the Developer IDE

In the Developer IDE, you use two tabs to create your source code: the Source tab and the

Shared tab.

The Source Tab

You use the Source tab to build the body of your program. It is like a template you “fill-

in” with custom Java code. Standard blocks of required code appear in the shaded areas at

the top and bottom of the tab. You cannot alter the code in these areas.

The Source tab is like a template for building a service

The required code at the top of the tab defines a static method with the signature required

of a B2B service—i.e., it takes a Values object as input (called in) and produces a Values

object as output (called out ). This block also copies the contents of in to out . This ensures

that, by default, the service returns the set of variables it initially received from the client

The Developer automatically

generatesrequired code

for you



Building a Java Service with the B2B Developer


as well as those produced by your service. (Those elements that you do not want to

return, you can drop using the out.remove(keyName) method in the body of your program.)

The block of required code at the bottom returns the Values object to the caller.

When you build a Java service, you type (or paste) your code in the text box on the Source

tab. The following example shows a service that gets two values from the Values object

and uses them to compute a sales tax. It puts the computed tax into the Values object that

is returned to the client.

You use the Source tab to write the body of your service

The Shared Tab

You use the Shared tab to the specify common (i.e. shared) attributes of this class. This

includes the superclass and interface declarations, required imports, and member

variables that are shared but not exposed as B2B Services. The code on this tab is shared

by all services in this interface.

Type your code in here





You use the Shared tab to write the body of your service

The Extends field allows you to specify a super class for the implementation. You are not

required to specify a super class.

!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 interfaces that you want to implement in the

extended class.

The Import field specifies the names of additional Java packages whose classes are

available to the current class. When you create a Java service with the B2B Developer,

several Java packages are automatically added to the import list.

The Source field allows you to define global variables and methods that are shared by all

services in the current interface. This is useful for building shared data structures and

supporting functions that aren’t intended to be exposed as B2B 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.

! Since services are implemented as static methods, most shared code is usually static as well.

Creating a Java Service with the Developer’s IDE

The following procedure describes how to create the source code for a Java service using

the B2B Developer’s IDE.





To create a Java Service with B2B Developer

1 Select the New command from the File menu.

2 Select Java Service and click Next.

3 In the Interface tree, select the interface into which you want to save this

service and type a name for the service in the Name field.

4 Click Finish.

5 Type the code for your service on the Source tab. For information about

Java classes provided by webMethods, see webMethods online API in

webmethods/developer3/doc/api/index.html.

!Tip! If you know the set of inputs and outputs your program uses, you can use

the Developer to automatically generate Java code that gets and puts those

values in the Values object. See “Generating Java Code from a Specification” on

page 81 for proceudres.

6 If you want to make additional methods and/or structures available to the

service, complete the following fields on the Shared tab.

Use this field… To specify…

Extends The name of the superclass (if any) of which thisclass is an extension. If you specify asuperclass, type its Java class name (fully-qualified if necessary).

Implements The names of interfaces within the superclass

that this class implements. Take the followingsteps to specify each interface that you want toimplement:

1. Click to add a new row to the list.

2. Type the name of a valid Java class name(fully-qualified if necessary). You do notneed to type the “implements” keyword.

Imports The names of Java packages that this classimports. Take the following steps to specify eachpackage that you want to import:

1. Click to add a new row to the list

2. Type the name of a valid Java class name(e.g. com.wm.util.Table) or a packageimport specification (e.g. java.util.*). You donot need to type the “import” keyword.

Source Data structures, methods, and other Java code





that you want to make available to all services inthis interface.

7 When you finish specifying your code on the Source and Shared tabs,

click on the tool bar to save and compile the service.

8 Create the input/output specification for the service as described in thenext section.

Creating the Input/Output Specification for a Java Service

A specification for a Java service serves the same purpose as it does for a flow service—it

declares a service’s inputs and outputs. Although you are not required to create

specifications for a B2B service, (the B2B Integration Server will execute a service

regardless of whether it has a specification or not), doing so makes it easier to test your

service in the Developer and use it in a flow service.

The Input /Output TabYou use the Input/Output tab to define a specification for a Java service.

Input/Output tab defines the services input and output variables

On the left half of the tab, you specify the set of Variables that the service takes as input(These are the values your service expects to find in the Values object it receives at run

time). On the right side, you define the set of values your service produces and returns to

the client in the Values object.





!The B2B Integration Server returns everything that your service puts into the output Values object

regardless of what is defined in the input/output specification. A specification does not filter what

is actually extracted or returned, it simply describes to other developer and programs, what this

service requires for input and produces as output.

For additional information about specifications and how to create them, see “Creating a

Specification for a Service” on page 45.

Generating Java Code from a Specification

If, before you start writing your service, you know the set of inputs and outputs that it will

use, you can create the service’s input/output specification first and generate Java code

from it. This code gets the specified input values from the Values object and assigns them

to variables in your program. It also puts the output values into the output Values object.

For example, if your specification defines the following variables:

Input Variable Name Type

State String Amount String

Output Variable Name

Tax String

The Developer will generate the following Java code for your service:

// inString State = in.getString( "State" );String Amount = in.getString( "Amount" );

// outout.put( "Tax", "Tax" );

When Developer generates code from a specification, it places the code on the Clipboard.

From there, you can paste it into your program (on the Source tab or in your own IDE)and modify it as necessary.

The following procedure describes how to generate code from an input/output

specification.

To generate Java code from a specification

1 Open the Java service for which you want to generate code (if you are

creating the Java service in your own IDE, use the Developer to create a

new, empty Java service that you will use simply for the purpose of

creating a specification).

2 Select the Input/Output tab and define the inputs and outputs for this

service if they are not already specified. See “Error! Unknown switch

argument.” on page 47 if you need procedures for this step.





3 If you want to generate code for a subset of the variables in this

specification, select those variables by holding the CTRL key and clicking

theirs names with your mouse.

4 Select Generate Code from the Compose menu.

5 Select For Implementing This Service, then click Next.

6 Specify the following options.

In this group box… Specify…

Which Records? Whether you want to generate code for theinput variables, the output variables, or both.

Which Fields? Whether you want to generate code for allvariables in the specification or just theselected variables.

7 Click Finish. The Developer generates code and places it on the

Clipboard.

8 Paste the contents of the Clipboard into your source code.

Setting Run-time Options for a Java Service

When you create a Java service with the B2B developer, you can set options to specify

the run-time behavior of the service. These options determine:

− Whether the service runs in stateless mode

− Whether the results of the service are maintained in cache

− Whether an output template is applied to the service when it is invoked by a browser.

You specify these options on the Settings tab. For information about using these options,

see “Specifying Run Time Parameters” on page 67 and “Creating Output Templates” on

page 97.

Bui ld ing a Java Service wi th Your Own IDE

There may be times when you want to use your own IDE instead of the Developer to

build a Java service. When you do this, keep in mind that you service must be written as a

method that takes a Values object as input and returns a Values object as output.

Writing the Source Code for a Service

A Java service is a method that is public and static. It takes a single instance of

com.wm.util.Values as input and returns an instance of com.wm.util.Values as output. The

following code shows the basic framework for a Java service:

Building a Java Service with Your Own IDE


public final static Values myservice(Values in){

Values out = in;return out;

}

We recommend that you return the same Values object you receive in your service (as

shown in the example above), and modify it as necessary during the course of the service.However, this practice is not required.

!Services should not throw exceptions. Instead you should convert them to Values and return them

using the com.wm.app.b2b.server.Service.throwError method. See the API documentation in

webmethods/developer3/doc/api/index.html for information about this method.

Additionally,

Your Java class must import the following Java packages.

com.wm.util.Values;

com.wm.app.b2b.server.Service;

Your Java class must be public. We also recommend, for performance reasons, that

you make it final.

For a complete example of a Java service, see “ jcode Example” on page 315.

Using the webMethods API

webMethods provides classes that you can use with Java services that you build. See the

online API in webmethods/developer3/doc/api/index.html for a description of these

classes.

Commenting it for the B2B Integration Server

To install your finished service on the B2B Integration Server, you use B2B’s jcodeutility. To use this utility successfully, you must annotate your source code with jcode

tags (specially-formatted Java comments) to “mark” the following segments of code:

− Imports

− Shared code within the class

− Service definitions and signatures

The following code fragment shows the tags used to mark the beginning and end of the

import section.

.

.

.// --- <<B2B-START-IMPORTS>> ---import com.wm.util.Values;import java.util.*;// --- <<B2B-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 G. For additional

information about the jcode utility, see “Using the jcode” on page 85.

Publishing Java Services on the B2B Integra tion Server

In order to successfully publish (install) a Java service that you have created with your

own IDE, you need to understand exactly how Java service are stored on the B2B server.

The Namespace Directory

Each package on the B2B Server has a namespace directory, called “ns.” For example, a

B2B package called “purch” would have the following directory structure:

webmethods\server3\packages\purch\ns

The ns directory is contains information about the services in that package. An “entry” in

the namespace directory corresponds to a service or an interface. The contents of each

entry depends on what kind of entry it is:

Service entries contain information about properties of the service (for instance,

statelessness), the signature of the service (if one has been defined), as well as Java or

XML source if it’s available for that service.

Interface entries contain information about the interface–this is usually limited to Java

source shared between services in that interface, if it’s available.

For Java services, information about the service is stored in the namespace directory,

however the compiled code for that service (i.e., the class file) is stored in the code

subdirectory. The following shows the directory path to the class files in the orders

package.

webmethods\server3\packages\purch\code\classes\recording\accounts.class

When you use the Developer to build a Java service, it automatically updates and

maintains the interface and service information in the name space. However, if you build

your Java service in your own IDE, you need to use a utility called jcode to install your

service and generate the necessary information in the namespace.

!Although you may want to examine the contents of the namespace directories on your B2B

Integration Server, do not modify this information by hand. It must only be modified using the

appropriate B2B tools or utilities. Inappropriate changes—especially to the ns directory of the

WmRoot package—can disable your server.

The Source Code directory

Each package on the server has a source subdirectory that holds the Java source code for

that package, if it’s available.



Building a Java Service with Your Own IDE


When you finish coding your Java service, save its source file in this directory (subject to

the normal Java constraints based on package declarations). You must name the files and

intermediate directories according to the name of the service you are installing. For

instance, the source file for the recording accounts services shown in Appendix G would

have the following path:

webmethods\server3\packages\purch\code\source\recording\accounts.java

Using the jcode Util ity

When you finish creating and annotating your source code, you use the jcode utility to

compile it and store its service information in the ns directory.

Jcode operates in three basic modes:

Make Mode (for compiling Java source code).

Fragment Mode (for pulling apart source code and storing fragments and signatures in

the namespace).

Composite Mode (for rebuilding the source files from fragments in the namespace).

You must use the make and fragment modes to run your services on the B2B Server and

edit the source code from the B2B Developer.

Make Mode

You use this mode to examine source files for one or more interfaces 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 make only the code for a single interface (i.e. a single Java source file), type the

following on the command line:

jcode make Package Interface

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 destinationdirectory for the compiled classes, and fileList is a list of the names of source files to

compile.

If you don’t have the JDK installed, or you want to use another compiler, you can set the

B2B Integration Server’s watt.server.compile property to a new command line (using the





arguments described above). For instance, to use IBM’s jikes, you would set this property

to

jikes +E –nowarn –classpath pathName –d classDir fileList

Fragment Mode

You use this mode to update the Java code fragments and service signatures 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 the B2B 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 interface (i.e. a single Java source file), type the


jcode frag Package Interface

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.

! The existing source file, if there is one, is overwritten by the source file produced by jcode.

To construct a source file based on the current information in the namespace, type the


jcode comp Package Interface

Other jcode Commands

Because the two-step process of making and fragmenting source code is so common,

there are several shortcuts built in to jcode.

The “update” mode makes and fragments only source files which have changed. To

update (make and frag) all the interfaces within a package which have changed, type the

following at the command line:

jcode update Package

To update (make and frag) all the code in all packages on the B2B Server, type the

following at the command line:

jcode upall

To force a make and frag on all packages on the B2B Server, type:

jcode hailmary



Building a B2B Service Using C/C++


Bui ld ing a B2B Service Using C/C++

You can use the B2B Developer to build a set of starter files you can use to create a

C/C++ service. These files include:

— A Java service that calls your C program.

— A C/C++ source-code “template” that you use to create your C program.

— A make file you use to compile the finished program and place it on the server.

Before you create a C/C++ service, you must:

Make sure you have a C compiler installed on the B2B Integration Server that you will

use to develop and test the service.

Make sure the B2B package in which you want to create the service already exists. If the

package does not already exist, use the B2B Server Administrator to create it. See the

online help system for step-by-step procedures. (If you do not have administrative


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 interface in which you want to create the service already exists. If the interface

does not exist, use B2B Developer to create it. See the Developer’s online help

system for step-by-step procedures.

Create a specification that describes the inputs and outputs for the service. When the

Developer generates the starter code for your service, it creates code that extracts thespecified input values from the Values object and assigns them to variables in your

program. It also writes your service’s output variables into the output Values object.

In order to do this, the Developer must know the input and output requirements of

your service. You supply this information in a B2B specification. For information

about creating a specification, see “Creating a Specification for a Service” on page

45.

Generating Files for a C/C++ Service

If you have satisfied the prerequisites identified above, you can use the following

procedure to generate the files you need to build a C/C++ service.

To generate C/C++ project files






2 Select C Service and then click Next.


service, type a name for the service in the Name field, and click Next.

4 Select the platform that describes the machine on which your B2B

Integration Server is running (The Developer needs to know this in order to build the right make file).

5 Select the specification for this service.

6 Click Finish.

The Java Code for a C Service

When you build a C/C++ Service, the Developer builds a Java service that calls a DLL,

which you create by writing a C program. The Java service is the means by which your C

program is exposed to clients (B2B clients invoke this Java service, not the C program

directly). The Java service also supplies the input/output specification for the program,which makes it possible to include it in a flow service and map its inputs and output with

the Pipeline Editor.

The Developer generates all the Java code needed to successfully call your C program.

You may add your own custom code to the Source or the Shared tab if you want to execute

any special procedures before or after the C program is called, but other than that, this

service contains everything you need.

The Source Tab contains code that calls the Java wrapper for the C program



Building a B2B Service Using C/C++


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

The Input/Output Tab contains the specification for the service

Building the C/C++ Source CodeThe Developer also generates a source code file and a make file for you. It places these

files in the following directory:webmethods\server3\packages\ packageName\code\source

The names of the files will match the service name you specified in the Developer. After

you locate the files, do the following:





Copy the source code file to a new file (in the same directory) with the following file

name:

serviceNameImpl.c

Example

If your service name is postPO, you would…Copy… To…

postPO.c postPOImpl.c

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

Edit the make file to customize it for your development environment. Make sure to set

the following path settings:

Set… To…JDKDIR To the directory that contains the

Java Development Kit.

SEVRDIR The directory in which the B2B

Integration Server is installed

(e.g., c:\webmethods\server3).

Writing the Service

Edit the serviceNameImpl.c file as necessary to build your service. This file will contain

instructive comments that will guide your development. You can also refer to

webMethods C API for information about how to use the webMethods C/C++ API to

make the data in your service available to other B2B services. This file is located in the

webmethods\server3\doc\api\c\index.html.

Compil ing the Service

After you finish coding your service, run your make file to compile it. The following

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

Once your program compiles successfully, you must restart the B2B Server to reload the

code\libs directory. This makes the service available for execution and allows you to test

it with the Developer.



Building B2B Services Using COM


Bui ld ing B2B Services Using COM

There are two ways in which you can use COM objects with B2B. You can:

Create B2B Services using COM. webMethods B2B includes libraries for use in your own

Visual Basic or Visual C++ code. They allow you to create COM objects that

perform work on webMethods data structures (Values). These objects (compiled into

ActiveX DLLs or EXEs) can then be registered as native B2B services,

indistinguishable from their Java counterparts.

Invoke methods/properties on existing COM objects. webMethods B2B includes built-in

services for instantiating any COM object registered on your system and invoking its

methods and properties. This allows you to use existing COM APIs written in Visual

Basic or Visual C++ without writing low-level bridging code.

RequirementsTo use B2B with COM, your B2B Integration Server must be configured as follows:

It must be running Java Virtual Machine (JView), build 5.00.3177 or later (type

jview /? From the command prompt to check the build number).

Your B2B Integration Server must be set to run JView. To check this, open the

server.bat file that resides in webmethods\server3\bin and make sure that the USE

JVIEW setting is set to “true” as shown below:

USE JVIEW=true

If you change this setting (which is likely, since the B2B Integration Server uses the

Sun Java Runtime Environment by default), you must restart your server and then use

the Server Administrator to enable the WmWin32 package. This package contains the

win32 interface, which is the home for all COM services.

Wri t ing a V isual Basic Service

Writing services in Visual Basic is easy. To get started quickly, we suggest you examine

a sample project.

To do this, open wmVBDemo.vpb project file using Visual Basic 6.0. This file resides in

webmethods\server3\packages\WmWin32\code\source. When you open the project, look at the Services class. It contains two methods—the first is a simple “HelloWorld”

example. I simply returns “Hello” added to a name submitted to the service. The second

demonstrates a few advanced features of B2B services.





Notice how both methods receive a Values object as input and return a Values object as

output. This is the standard signature for a B2B Service.

!For a complete list of all the methods contained within Values and other objects in the

webMethods COM library, select Object Browser from the View menu in Visual Basic and

select the webMethods library. The DLL (webMethods.dll) is registered and copied into your

system directory during installation of the B2B Developer and the B2B Server.

Compiling a Visual Basic ServiceTo make a VB class available as a B2B service you need to compile it. To compile the

wmVBDemo.vpb example, open the project and choose Make wmVBDemo.dll from the File

menu. You can save the DLL in any directory that is listed in your system path. (If you're

not sure where to put it, webmethods/server3/packages/WmWin32/code/libs will work.)

Typically you do not need to create a libs directory in your own package since the native

invocation actually happens within WmWin32. But if you are an advanced COM

developer that wants to use early binding, you must store the DLL in a package with a

libs directory.

Invoking a V isual Basic Service

To execute a service that you have written in Visual Basic, you invoke it using one of

B2B’s COM services. There are two services you can use: the late-binding service

(win32.COM:invokeLate) and early-binding service (win32.COM:invoke). Each has its

advantages and disadvantages. The late-binding service is easier to use, but early binding

usually provides better performance.

Invoking a VB Service Using Late Binding

Use the following procedure to create a flow service that uses the late-binding service to

invoke a method from a compiled Visual Basic program.

To invoke a VB method using late binding

1 In the Service Browser, select the flow service in which you want to invoke

the VB method (if the service does not already exist, use the FileNew

command to create it).

2 Click in the Flow Pane and select COM Service from the drop-

down list. (Or clickOthers

and select the win32.COM:invokeLate service.)

3 Display the Pipeline tab

4 Use the pipeline modifier to assign values to the following variables in

Service In:



Invoking a Visual Basic Service


Set… To specify…

$progid The name of the library and class (a standardMicrosoft COM convention) containing the methodyou want to invoke. Specify these names usinglibraryName.className notation.

The following example shows the value you woulduse for the “Hello World” example:

Example: wmVBDemo.Services

$method The name of the method you want to invoke.


Example: helloWorld

$context One of the following values, specifying whether your COM object is a DLL or an EXE.

Set this value… If…

INPROC The component was compiled asan ActiveX DLL. This option tellsthe server to instantiate the objectin the same process as theserver.

LOCAL_SERVER The component was compiled asan ActiveX EXE. This option tellsthe server to instantiate the objectas its own process.

5 Select the Input/Output tab and define the specification for your service.

See “To create a specification for a service” on page 47 if you needprocedures for this step. (If you are building a flow for the “Hello World”

example, define a string variable called “name” as input, and a string

variable called “message” as output.)

6 Click on the Service Browser tool bar to save the flow service.

7 Click on the Service Browser tool bar to test the service.

The Developer will prompt you for input values and then display the results

of the service on the Results tab.

!

If you receive an “InvocationTargetException” instead of the results of your

service, you may be running an old version of the Microsoft Java VirtualMachine.





Invoking a VB Service Using Early Binding

Use the following procedure to create a flow service that uses the early binding service to

invoke a method from a compiled Visual Basic program. Although invokeLate may

service is easy to use, early binding usually provides better performance.

To use early binding, you create a Java class wrapper for the COM component so that theJava Virtual Machine knows how to create the component and pass values in and out of

it. (With late binding, this information is determined at run-time and results in a minor

performance penalty.)

!To use early binding, you must have the Microsoft Java SDK (3.2 or better) installed on a device

that is accessible to your B2B Integration Server. This SDK is required to compile Java code

with Microsoft's COM extensions. If you do not have the Microsoft Java SDK installed on your

machine, download it from www.microsoft.com/java.

The following procedures describe the steps you must take to wrap the VB service as a

Java class and then invoke it from a flow service.

To wrap the VB program as a Java class

1 Make sure the DLL or EXE that contains the VB service is in the

..\code\libs directory of a package on the B2B Integration Server. (e.g., if

you want the service to be a member of a package called MARKETING,

the DLL or EXE must reside in

webmethods\server3\packages\MARKETING\code\libs.)

2 Open the comwrap.bat file in an editor, and set JDKDIR to point to the BIN

directory of the Microsoft Java SDK. (this file resides in

webmethods\server3\support\win32)

3 From the webmethods\server3\support\win32 directory, run comwrap.bat

by typing the following on the command line:

comwrap package libraryName

Where: package is the name of the B2B package in which the VB

service resides, and .

LibraryName is the name of the DLL or EXE containing the

service.

The following example shows the value you would use for the “Hello

World” example:

Example: comwrap WmWin32 wmVBDemo.DLL

4 When comwrap finishes, verify that is created two class files for each

COM class in your DLL or EXE. (One file will be prefixed with a “_”



Invoking a Visual Basic Service


character, and the other will not.) You will find these files in the classes

directory of the package in which the DLL or EXE resides.

!If you receive an error in the “createProcess” while running comwrap, make sure

your JDKDIR setting is correct (see step 2 above). This error indicates the

comwrap could not locate jactivex.exe in the Microsoft Java SDK.

After the class files have been generated successfully, restart the B2B

Server. This will reload the package, and pick up the new service(s).

You can invoke the new services from a flow service as described in the

following procedure.

To invoke a VB method using early binding

1 In the Service Browser, select the flow service in which you want to invoke

the VB method (if the service does not already exist, use the FileNew

command to create it).

2 Click in the Flow Pane and select Other.

3 From the Interface tree, select the win32.COM:invoke service.

4 Display the Pipeline tab

5 Use the pipeline modifier to assign values to the following variables in

Service In:

Set… To specify…

$className The name of the COM object.


Example: wmVBDemo

$methodName The name of the method you want to invoke.


Example: helloWorld

6 Select the Input/Output tab and define the specification for your service.

See “To create a specification for a service” on page 47 if you need

procedures for this step. for information about creating external

specifications. (If you are building a flow for the “Hello World” example,define a string variable called “name” as input, and a string variable called

“message” as output.)

7 Click on the Service Browser tool bar to save the flow service.





8 Click on the Service Browser tool bar to test the service.

The Developer will prompt you for input values and then display the results

of the service on the Results tab.

Invoking Methods from Exist ing COM Objects

You can use B2B to access methods in existing COM libraries that do not use

webMethods Values objects. For example you may have a COM object that performs a

validation routine on a String and returns and encrypted String in response. It may not be

sensible or desirable to wrap this object with a B2B Service if the component is simple

enough and/or part of an existing, unmodifiable application. In these cases, the B2B

COM Dispatch services can help.

The win32.COM.dispatch:createObject service (located in the WmWin32 package) will create

an object given a Program ID or the Globally Unique Identifier (GUID) for that object.

You also need to supply the context for the object, which is INPROC (DLL) or LOCAL_SERVER (EXE). The service will return a reference to the object called

pDispatch or throw an error if the object cannot be created.

To invoke methods or properties on this object once you have created it, use

win32.COM.dispatch:invoke. You need to supply this service with the following inputs:

Name Description

pDispatch An object reference previously obtained by the call to createObject, or

obtained in the result value of a previous call to invoke.

dispName The name of the method or property you want to invoke.

accessType The type of operation (METHOD, GET, PUT, PUTREF) to be performed on dispName. Incorrect setting of this parameter will cause

the invoke to fail. If you're unsure whether a dispName is a method or

property, examine the component's type library using OLEVIEW or a

Microsoft development environment.

params An object array of parameters. This is exposed in the B2B Developer as

an array of Strings for usability (since Objects cannot be manipulated in

Developer), but is in reality an Object array. If you need to pass complex

or native types, you may have to create this value within your own B2B

Service.

If the invocation is successful, the return value is contained in “result.” If result is an

object variable, it can then be the target of subsequent calls to invoke by mapping result

into pDispatch in the next invoke operation.




C H A P T E R

Creating Output Templates

What is an Output Template? ....................................................98

What Does a Template Look Like? ............................................98

How do You Assign a Template to a Service?...........................99

When Does the B2B Server Use a Template?...........................99

Creating an Output Template...................................................101

C H A P T E R 5 C r e a t i n g O u t p u t T em p l a t e s


What is an Output Template?

Output Templates allow you to insert output values from a B2B service into a string that

you define. They work much like server-side includes in that they contain special “tags”

that the B2B Integration server processes before passing the string back to the client.

Templates are used most frequently to customize the HTML page that a service returns to

a browser-based application. However, they can also be used to generate an XML

document or any other formatted string. For example, you may have a service that

retrieves a record from a relational database and uses an output template to formats it as

an XML document or a comma-delimited record before returning it to the requestor.

What Does a Template Look Like?

A template is simply a String containing text and one or more B2B tags. B2B tags are

special commands, enclosed in % symbols, which cause the B2B Integration Server to

perform a specified action —typically to insert the value of a variable—at a specified

point in the String.

For example, if you have the following Values object:

Values Object

Variable Name Value

CompanyName Bitterroot Boards

AccountNum BTB-9590651

ContactName Lauren Cheung

PhoneNum 406-721-5000

You might create a template that looks as follows to return the values in an HTML

document to a browser-based client. The bolded stings are B2B tags instructing the server

to insert specified values from the Values object at run time.

Output Template for HTML Document

<!DOCTYPE HTML PUBLIC ><HTML><HEAD><TITLE></TITLE></HEAD><BODY>Contact information for account %value AccountNum% is:

<TABLE><TR><TD>Account Name</TD><TD>%value CompanyNum%</TD></TR>

<TR><TD>Contact Name</TD><TD>%value ContactName%</TD></TR><TR><TD>Phone Number</TD><TD>%value PhoneNum%</TD></TR>

</TABLE></BODY></HTML>

How do You Assign a Template to a Service?


Templates are not limited to HTML. For example, you could create a template that looks

this to return values in an XML document:

Output Template for XML Document

<?xml version="1.0"?>

<ACCOUNT_INFO><ACCOUNT_NAME>%value AccountNum%</ACCOUNT_NAME><COMPANY_NAME>%value CompanyNum%</COMPANY_NAME><CONTACT_NAME>%value ContactName%</CONTACT_NAME><PHONE_NUM>%value PhoneNum%</PHONE_NUM>

<ACCOUNT_INFO>

Or a template that looks like this to return values as a comma-separated record:

Output Template for XML Document

%value AccountNum%,%value CompanyNum%,%value ContactName%,%value PhoneNum%

How do You Assign a Template to a Service?

Templates are files that reside in the packages/ packageName/templates directory on the

B2B Integration Server. Use of an output template is optional. You assign a template to a

service using the B2B Developer or the Server Administrator. When using templates,

keep in mind that:

− You do not have to assign a template to a service.

− A service can have at most one template assigned to it at a time (you can

dynamically change the template assignment at run time, however,).

− You can assign the same template to more than one service.

− You may reference one template from within another.

When Does the B2B Server Use a Template?

Once you assign a template to a service, the B2B Integration Server automatically uses

that template to return output from the service to a browser-based client. However, you

can also direct the B2B Integration Server to apply an output template to a Values object

using the pub.report services. In this case, the result is returned in a String called $txt .

Using Templates to Return Output to a Browser-Based Client

Templates were initially designed to format the results of a service for a browser. That is

why the B2B Integration Server automatically applies a user-defined output template to





the results of services invoked from a browser-based client. If you don’t define an output

template for a service, and that service is requested by a browser-based client, the server

simply returns the contents of the Values object in an HTML document (formatted as a

two-column table).

Guidelines for Using Templates for Browser-Based Clients

If you use an output template to return HTML to a HTTP-based client, keep the following

points in mind:

Make sure the executed template produces a valid HTML document.

Make sure that all the information you want the server to return to the client either

appears as text in the template or is generated by a B2B tag. (If it isn’t in the

template, it won’t be returned to the user.)

If your client checks the Content-type value in the HTTP response header, make sure

to set the Type option to “HTML” when you assign an HTML-based template to aservice. This option instructs the server to set Content-Type to “text/html” when it

returns the results to the client.

Guidelines for Using Templates to Return XML

If you use an output template to return XML to a HTTP-based client, keep the following

points in mind:

Make sure that the template generates a valid and well-formed XML document.

Make sure to set the Type option to “XML” when you assign an HTML-based

template to a service. This option instructs the server to set Content-type to

“text/html” when it returns the results to the client.

If your client is a browser, make sure that it is able to accept and display XML (for

example, Microsoft Internet Explorer 5.0 will display XML) or that the client's

computer has a Mime definition for Content-type to “text/html”.

Using Templates to Return Output to Other Types of Clients

You can also apply templates to the output of services that are called from B2B client

applications or B2B services (clients other than browsers). However, you must do this

programmatically since the B2B Integration Server does not automatically apply a

template when it processes these types of requests. To combine the values in a Values

object with a template, you use the services in the pub.repor t interface. For information

about using these services, see “Report Services” on page 256.



Creating an Output Template


Creat ing an Output Template

A template is a text string that you create and save in a text file. You can use the B2B

Developer to create a template file or your can create it with an ordinary text editor.

When you create a template, keep the following points in mind:

You must create or copy the template file in the template directory with a package

on the B2B Integration Server.

You must give a template file a name that is unique within the package.

If you want to work with (i.e., edit or assign) a template in the B2B Developer, you

must give the file an HTML or XML extension.

To create the contents of a template file, type all literal text exactly as you want it to

appear in the result and then embed any of the following B2B tags where you want the

server to execute them at run time. For a complete description of each tag, see

Appendix F.

! B2B tags are case-sensitive.

Use this tag… To…

%value VarName% Insert the value of the specified variable into the

output string.

%scope RecordName%...

%end%

Restrict the range of the enclosed block of the

template to those elements in a specified Record

(Values object).

%loop VarName%

...%end%

Repeat the enclosed block of the template once

for each element in the a specified array variable

%ifvar VarName%...

%end%

Conditionally include the enclosed block of the

template if a variable exists or matches a

specified value.

%switch VarName%

%case Value1%

%case Value2%

%case Value3%...

%end%

Conditionally include a block of the template

depending on the value of a specified variable.

%include TemplateName% Insert and execute a specified output template.

%nl% Insert a new line in the output string.





Use this tag… To…

%comment%...

%end%

Omit the enclosed text from the output string.

%rename VarName NewVarName% Change the name of a variable to another for the purpose of referencing it in the template. This

may be necessary if you include pre-defined

templates that use different names than those in

your Values object.




C H A P T E R

Using the Load and Query Services

What are the Load and Query Services?..........................................104

Using the loadDocument Service ......................................................105

Using the queryDocument Service....................................................118

Load and Query Shortcuts ................................................................127



C H A P T E R 6 U s i n g t h e L o a d a n d Q ue r y S e r v i c e s


What are the Load and Query Services?

The B2B Integration Server is equipped with a set of “load and query” services that allow

you to fetch HTML or XML documents via HTTP or HTTPS and selectively extract

information from them for other B2B services. Through these services, you can connect aB2B service to virtually any document on the Internet.

Fetching a document from the Internet with B2B is a two-step process.

First, you use the pub.web:loadDocument service to retrieve the document that contains

the information you need.

Next, you extract the pieces of information you need to use and assign them to B2B

variables. For this step, you can use the pub.web:queryDocument service (to select

specific elements from the document) or the pub.web:documentToRecord service (to

convert all elements in the document to B2B variables).

Note to 2.x Users

In earlier versions of B2B, the process of extracting information from a document was referred to as

“binding.” In 3.0, a load-and-query service performs this process. It is equivalent to a WIDL service in

earlier versions of B2B. Conditional processing that was provided by WIDL is now provided by the more

powerful REPEAT, LOOP, and BRANCH operations.

Basic Concepts

To successfully use B2B's load and query services, you should understand the following

terms and concepts.

What is Parsing?

Parsing is the operation the server performs to convert an HTML or XML document (a

string) into a Document object whose elements can be addressed and extracted by B2B

services. The B2B Integration Server automatically parses documents that you fetch with

the loadDocument service.

What is a Document Object?

A Document object is the result of a parsing operation. It is an node-based representation

of an entire XML or HTML document. The Document object expresses a document in a

tree-like structure that allows the data within it to be efficiently addressed and mapped

into B2B services.

Once an HTML or XML document is converted to a Document object, you can

manipulate it (e.g., extract specific information from it or convert it into a Values object)

using any service that takes a document or node variable as input.



Using the loadDocument Service


What is a Node?

A node is Document object or an element of a Document object. B2B services that

require a node as input or produce a node as output, contain the variable name node in

their specifications.

!You may use a Document object anywhere a node variable is specified; however, you cannot usea node when a document variable is specified. Since a node is a subset of a Document object, it

does not include certain document-specific elements that are inherently part of a Document

object.

What is a Query?

With respect to XML and HTML documents, a query is an expression, written in the

XML Query Language (XQL) or the webMethods Query Language (WQL) that you use

to extract (filter) information from XML or HTML documents. (WQL was referred to as

“WOM” in earlier releases of B2B.)

Using the loadDocument ServiceYou use the pub.web:loadDocument service to retrieve an XML or HTML document from the

Internet. This service does the following:

− It submits an HTTP or HTTPS request for a specified XML or HTML document.

–AND THEN –

− It parses the returned document.

The output from loadDocument is a Document object that can be used with any B2B

service that takes a document or a node as input.

Adding loadDocument to a Flow Service

The following procedure describes the steps you use to insert pub.web:loadDocument into a

flow service.

! The following procedure explains how to manually insert and specify the loadDocument service.

If you are constructing a “load and query” service, however, you may want to use the B2B Wizard

instead. This wizard allows you to build a load and query sequence by pointing to a URL or

recording the actions in a browser. For information a bout using the B2B Wizard to create a load

and query sequence, see “Load and Query Shortcuts” on page 127.

To insert loadDocument into a Flow Service

1 In the Service Browser, select the service in which you want to insert

loadDocument.

2 Click in the Flow Pane toolbar and select loadDocument. (If

loadDocument does not appear on the menu, click Browse and select

pub.web:loadDocument from the Interface tree.)





3 Select the Pipeline tab if it is not already showing.

4 Complete the following steps to specify the URL of the document that you

want to retrieve.

1 In Service In, select url .


3 Type the url, starting with http: or https:, and then click OK.

Examples

The following string would retrieve the specified document via http:

http://www.rubicon.com/orders/orders.xml

The following string would retrieve the document via https:

https://www.rubicon.com/orders/orders.xml

5 Use the Set Value modifier to assign values to the remaining input

variables as needed. See "Inputs for loadDocument" on page 107 for a

detailed description of each variable.

Input and Output Values for loadDocument

The inputs for loadDocument specify what document you want to retrieve, what data (if

any) you want to submit with the request, and how you want the B2B Integration Server

to parse the document it receives.

When you use loadDocument in a flow service, you use the Set Value modifier in the

Pipeline Editor to assign values to these variables. If you call loadDocument from a

program, your program must set these variables in the Values object it passes to the

pub.web:loadDocument service





Service Inputs for loadDocument

Inputs for loadDocument

The following describes the input values used by the loadDocument service.

The url variable

Set this variable to specify the URL of the document you want to retrieve.

Example: http://www.rubicon.com/orders/orders.html

The value you specify must be a string that starts with the protocol specifier

“http:” or “https:”

You may include a query string (for example, a collection of “name=value” pairs)

with the string you specify. However, we suggest that you use the data variable for

this type of information instead. It is usually a more practical place for

“name=value” data, because it allows you to map individual variables in the query

string. See “The data variable,” below.

To assign url in a flow service

Do one of the following:

Use the Map modifier to assign a pipeline variable to url .—OR—

Use the Set Value modifier in the Pipeline Editor to specify the url

you want to use.

Use the Set Valuemodifier to assign input

values to loadDocument





The method variable

Set this value to specify the HTTP method (GET or POST) that you want the target server

to execute on the resource specified in url . This value determines the way in which

loadDocument submits data values (if any) to the resource identified in url .

If you set method to “get”, loadDocument appends the values you specify in data to

the value in url . (Note that only certain data elements are valid when you use the

GET method).

If you set method to “post”, loadDocument sends the values in data in the body of

the HTTP or HTTPS request. (The B2B Integration Server set the Content-Type

header to application/x=www-form-urlencoded for posted requests.)

To assign method in a flow service


Use the Map modifier to assign a pipeline variable to method .

—OR—

Use the Set Value modifier in the Pipeline Editor to select the

method you want to use.

Setting the method variable in a flow service

The data variable

Use the data variable to specify data that you want loadDocument to submit to the

resource identified in url .

! If you include your data with the string in url , do not specify a value in data.

The data variable is a Record that contains several pre-defined elements. Each element

allows you to specify data in a different way. When you use loadDocument, you assign

your data to one of these elements. (Note that some elements are valid for only one HTTPmethod—GET or POST).

Use this element… If you want to…

args Specify “name=value” pairs as a Record of string elements. When you

specify data in this manner, loadDocument automatically appends the

Select get or post from thedrop-down list






elements from args to url (if you are using the GET method) or inserts

them in the body of the message (if you are using the POST method).

You use this variable

To specify data in this manner, create one string element for each

“name=value” pair that you want to submit, where:− The name of the element defines the name portion of the pair,

and…

− The value of the element specifies the value portion of the pair.

Note that loadDocument will automatically:

− URL-encode values you specify.

− Insert the “&” character between each name=value pair that it

constructs from the args (for POST and GET). You do not have to

include this character in the values you specify.

− Insert the “?” character at the beginning of the query string its

generates from args for the GET method. You do not have to


! If you need to specify multiple values for a single variable (e.g.,

a=b&a=c&a=d), define a String List and populate the list.

The following procedure describes how to use the Pipeline Editor to

assign data to args in a flow service.

To assign name=value pairs in args

1. Select the loadDocument operation in the Flow pane, and then display the Pipeline tab.

2. In Service In, select args.

3. Click button on the toolbar and select String.

4. Type the name portion of the first “name=value” pair, then press ENTER.

5. Click to make that element a child of args.

6. If you want to assign a hard-coded value to this element, do the following:

1. Click on the toolbar to open the Input for dialog box.

2. Type the value portion of the “name=value” pair. You do not need to URL-encode the

value if you are using the GET method to submit data—loadDocument will do this at run

time (e.g., it will convert “Global Sporting Goods” to “Global+Sporting+Goods”).

3. Click OK.

7. If you want to assign a pipeline variable to this element, click and map the element to the

appropriate variable in Pipeline In.

8. Repeat steps 3 – 7 for each “name=value” pair you want to submit.

string Specify your data as a single string of text. When you specify data in

this manner, loadDocument automatically appends the specified string

to url (if you are using the GET method) or inserts it into the body of






the message (if you are using the POST method).

Keep the following points in mind when you use string to submit data

with loadDocument.

If you are specifying a set of name=value pairs, string must startwith the first name in the set.

Example: AccountNum=GSG-970414A

You do not need to include the “?”symbol at the beginning of thestring—loadDocument will automatically insert this symbolwhen it appends string to the contents of url .

If you are using the GET method, be sure to format string as avalid query string—i.e., separate variables with the “&” character (as shown in Example 1) and URL-encode their data values (asshown in Example 2).

Example1: AccountNum=GSG-970414A&postalCode=22031

Example 2: CompanyName=Global+Sporting+Goods

If you are using the POST method, format the string exactly asyou want it to appear in the body of the message.

bytes Specify your data as an array of bytes that you want posted to the

resource in url . You can use this variable when you need to send non-

textual data to an Internet resource.

To assign a value to bytes in a flow service, use the Pipeline Editor to

map the variable containing your byte array to bytes.

! loadDocument only uses the bytes when method is set to POST.

table Specify your data in a 2-column table of strings. When you specify data

in this manner, loadDocument automatically appends the elements from

table to url (if you are using the GET method) or inserts them in the

body of the message (if you are using the POST method).

The table variable is similar to the args, however table allows you to

submit values that are not part of a “name=value” construction. For

example, if your Internet resource expects a set of unnamed values

(e.g., http://www.rubicon.com/orders?GSG&40019&open ) instead of

name=value pairs, you must specify those values in table. (args only

produces name=value pairs.)

To submit data via the table element, create a row for each variable that

you want loadDocument to submit, where:− The contents of column 0 specifies the name portion of the pair. (If

it is an unnamed variable, leave this cell blank), and…

− The contents of column 1 specifies the value portion of the pair.

Note that loadDocument will automatically:






− URL-encode values you specify.

− Insert the “&” character between each name=value pair that it

constructs from table (for both POST and GET). You do not have

to include this character in the values you specify.

− Insert the “?” character at the beginning of the query string its

generates from table for the GET method. You do not have to


The following procedure describes how to use the Pipeline Editor to

assign data to args in a flow service.

To assign name=value pairs in table

1. Select the loadDocument operation in the Flow pane, and then display the Pipeline tab.

2. In Service In, select table.

3. If you want to assign a set of hard-coded values to table, do the following:

1. Click on the toolbar to open the Input for dialog box.

2. Click twice to create two columns (0 and 1).

3. Click to create an empty row.

4. Select cell 0 and type the name of the name=value pair that you want to submit to the

Internet resource in url . (If you are sending an unnamed variable, leave this cell empty).

5. Select cell 1 and type the value of the name=value pair that you want to submit to the

Internet resource in url . (If you are specifying an unnamed variable, type the value of the

variable in this cell.)

6. Repeat step 3 – 5 for each variable that you want to specify.

7. Click OK.

4. If you want to assign a pipeline variable to table, click and map the element to the

appropriate variable in Pipeline In. (Note that the variable you map to table must be a 2-

column table of strings)

The auth variable

You use this variable to specify the authorization and authentication credentials (e.g., user

name and password) that you want loadDocument to submit when it requests the

specified document.

To set the auth variable correctly, you must know:

Whether the Internet resource you are accessing is protected, and if so, what type of

authentication is required to access it. (If the resource is not protected—i.e., it does

not require a user name and password—you do not need to set any of the elements

in auth.)

The user name and password that is required by the resource you are requesting.





If the resource you are requesting is protected, you must specify the auth variable when

you use loadDocument. Each element in auth specifies a piece of the “Authorization”

field that loadDocument will submit to the target server.

Set this element… To specify…

type The protection scheme used to control access to the requested

document. This element must have one of the following values.

Set type to… To…

Basic Use the Basic Protection Scheme.

user A user name that has authority to access the resource specified in url .

This value defaults to the value of watt.net.httpUser in the server’s

configuration file (server.cnf).

pass The password associated with the user name specified in user . If the

user does not require a password, leave pass empty.

This value defaults to the value of watt.net.httpPass in the server’s

configuration file (server.cf).

To assign auth in a flow service


Use the Map modifier to assign a pipeline variable to the type,

user , and/or pass elements as needed.

—OR—

Use the Set Value modifier in the Pipeline Editor to hard-code the

type, user , and/or pass elements as needed.

The headers variable

You use this variable if you want to specify the value of a header field in the HTTP

request that loadDocument submits to the target server.

By default, loadDocument issues a standard set of header fields. (The values of some of

these fields are configured when your B2B Integration Server is installed. Consult your

server administrator if you want to know your server’s default settings.) To use a header

value other than the default, you can specify it in the headers variable.

!In most cases, the default headers that loadDocument uses are adequate. You should not add or change request header fields unless you are thoroughly familiar with the HTTP protocol.

If you want to assign specific values to header fields used by loadDocument, bear the

following points in mind:





When you specify the value of a header field, you override whatever value the

loadDocument service would otherwise use to issue the request. For example, if

you set the User-Agent field to “B2B/3.0,” that value will be used instead of the

B2B Integration Server default specified in watt.net.userAgent.

Be aware that some request fields are derived from other input variables that you

set in loadDocument. For example, the auth variable sets information in the

Authorization field, and the method variable sets both the Content-length and

Content-type headers. If you explicitly set these fields in headers, the values you

specify override the values (except for Content-Length) automatically generated by

the B2B Integration Server at run time.

The loadDocument service does not validate data that you specify in headers. It

simply passes it on to the target server in the request header. Make sure you specify

header field names and their values correctly. For a complete list of valid request

header fields, see http://www.w3.org for the latest HTTP specification published by the

W3C.

To specify request headers in headers, create a string element for each header that you

want to specify, where:

− The name of the element defines the name header field (e.g., User-Agent, If-

Modified-Since, Mail_Address), and…

− The value of the element specifies the value you want assigned to that field.

The following procedure describes how to use the Pipeline Editor to assign values to

headers in a flow service.

To specify header fields in headers

1 Select the loadDocument operation in the Flow pane, and then display thePipeline tab.

2 In Service In, select headers.

3 Click button on the toolbar and select String.

4 Type the name of the header field that you want to specify. (You do not

need to type a colon after the field name—loadDocument will

automatically insert the colon when it inserts this field into the request

header.)

5 Click to make the element a child of headers.

6 If you want to hardcode the value of this element, do the following:

1 Click on the toolbar to open the Input for dialog box.

2 Type the value that you want loadDocument to assign to field.





3 Click OK.

7 If you want to assign a value from the pipeline to this element, click

and map the element to the appropriate variable from Pipeline In.

8 Repeat steps 3 – 7 for each header field that you want to submit.

The encoding variable

You use this variable to specify the character set (e.g., ISO-8859-1) in which the returned

document is encoded. The parser uses this value to properly read the text in the document.

You may set encoding to “autoDetect” or to the name of a specific, IANA-registered

character set. When you set encoding to “autoDetect,” loadDocument sets the character

set based on whether the document contains XML or HTML. See table below for

defaults.

To explicitly specify a character set, specify the name of that character set in encoding .

Valid character-set names are listed in the Internet Assigned Numbers Authority (IANA)

character-set registry.

If you do not specify encoding , the parser assumes the following defaults depending on

the type of document it receives:

If the document type is… encoding defaults to …

HTML ISO-8859-1

XML UTF-8

The following procedure describes how to use the Pipeline Editor to assign values to

encoding in a flow service.

To set the encoding value

1 Select the loadDocument operation in the Flow pane, and then display the

Pipeline tab.

2 In Service In, select encoding .

If you want to hardcode the value of this element, do the following:

1 Click on the toolbar to open the Input for dialog box.

2 Type one of the following in the encoding field:

Type… If you want the parser to…

autoDetect Decode the document based on thedocument type. Assumes ISO-8859-1for HTML documents and UTF-8 for XML documents.

The name of aregistered IANAcharacter set.

Decode the document based on aspecified character set.

3 Click OK.

3 If you want to assign a value from the pipeline to this element, clickand map the element to the appropriate variable from Pipeline In.

The expandDTD variable

You use this variable to specify whether you want the loadDocument service to expand

instances of named-parameter entities in the returned document’s DTD. If you set

expandDTD to true, loadDocument will process parameter-entity references, expanding

them to their full definition. If you set expandDTD to false, loadDocument ignores

parameter-entity references when it validates the returned document.

You may want/need to use this variable in cases when you have a syntactically-correct

document that causes a parse error because it violates a definition in an external

parameter-entity reference. By setting expandDTD to false, you can bypass the external

definition so that loadDocument can parse the document successfully.

If you do not explicitly set expandDTD, loadDocument sets it to false.

To set expandDTD in a flow service


Use the Set Value modifier in the Pipeline Editor and select the

value of expandDTD from the drop-down list.

—OR—

Use the Map modifier to assign a pipeline variable to expandDTD.

The pipeline variable must set expandDTD to a value of true or

false. (This value is case-sensitive.)

The isXML variable

You use this variable to specify whether the document you want to fetch is contains

HTML or XML. The server requires this value in order to parse the contents of the

document correctly.

You may set isXML to any of the following values:

Value Description

autoDetect Parses the document based on its <!DOCTYPE HTML …> or <?xml

version=…?> tag. If it cannot determine what type of document it has,

it parses it as an HTML document.





Value Description

false Parses the returned document as HTML.

true Parses the returned document as XML.

If you know what type of document loadDocument will receive, we suggest that youexplicitly set isXML instead of using autoDetect. It will cut processing time, because the

server will not have to examine the document to determine its type. The default value is

autoDetect.

To set isXML in a flow service



value of isXML from the drop-down list.

—OR—

Use the Map modifier to assign a pipeline variable to expandDTD.

The pipeline variable must set isXML to a value of autoDetect,

true, or false. (This value is case-sensitive.)

The loadAs variable

You use this variable to specify the way in which loadDocument passes the parsed

document to subsequent B2B services that use it as input.

You may set loadAs to the following values:

Value Description

bytes Passes the parsed document as a byte array. You use this setting when

the output from loadDocument will be used as input to a service that

operates on whole documents (e.g., pub.web:queryDocument and

pub.web:documentToRecord).

stream Passes the parsed document as an input stream. You use this setting

when the output from loadDocument will be used as input to a service

that can incrementally process a document (e.g., pub.web:getNodeIterator ).

If you do not explicitly set loadAs, loadDocument sets it to bytes.

To set loadAs in a flow service



value of loadAs from the drop-down list.

—OR—





Use the Map modifier to assign a pipeline variable to loadAs. The

pipeline variable must set loadAs to a value of bytes or stream.

(This value is case-sensitive.)

Output Values from loadDocument

If loadDocument executes successfully, it produces a single output, node, which is a

Document object containing the parsed HTML or XML document. You use node as input

to other B2B services such as pub.web:queryDocument (to extract specific elements from the

document) and pub.web:documentToRecord (to extract all of the document's elements).

Error Handling With loadDocument

If loadDocument fails, it returns an exception. Common reasons for loadDocument to fail

include:

url does not begin with http: or https:

isXML is true, but document contains poorly-formed HTML.

You have attempted to access a protected document without authorization (i.e.,

missing or incorrect user auth/user and/or auth/pass settings).

loadDocument receives a syntactically incorrect document that cannot be parsed.

An “Out of Memory” error.

Network timeout.

Method is not GET or POST.

If a failure occurs at the target server (e.g., that server cannot locate the requesteddocument), a server exception is thrown and the flow operation fails.





Using the queryDocument Service

You use the pub.web:queryDocument service to selectively extract information from a parsed

HTML or XML document and assign that information to variables that can be mapped to

other B2B services.

When you use queryDocument, you extract information using either the XML Query

Language (XQL) or the webMethods Query Language (WQL). Both languages allow you

to address and select information from a node based on criteria that you specify in a query

statement.

Passing a node to queryDocument

The queryDocument service takes a node as input. When you invoke queryDocument in a

flow service, you must have a node variable (containing parsed XML or HTML) already

in the pipeline for queryDocument to run against.

There are several ways in which you can produce a node for queryDocument to run

against.

If you want your service to… Create a flow service that…

Fetch an XML or HTML document

from a specified URL.

1. Invokes pub.web:loadDocument (to get the documentfrom the Web and transform it to a node), and then…

2. Invokes pub.web:queryDocument.

Query a string of raw HTML or

XML that is stored in a pipeline

variable.

1. Invokes pub.web:stringToDocument (to transform thecontents of the string to a node), and then…

2. Invokes pub.web:queryDocument.

Query an XML document that is

submitted directly to the B2B

Integration Server.

1. Takes a node as input, and…

2. Invokes pub.web:queryDocument as the first service inthe flow.

For additional information about posting XML directly toa service, see “Posting an XML Document via HTTP” onpage 150.

The means you use to obtain an HTML or XML document, convert it to a node, and pass

it to the queryDocument service is a design decision you must make before you begin

building your flow.

Addressing Information in a node

When the B2B Integration Server parses an HTML or XML document, it transforms the

document into a tree-like structure containing the document’s HTML or XML elements.





Once a document is parsed, you can address individual elements within it using an XQL

or WQL query.

For example, in an HTML document, you could use the following query to extract the

contents of the first paragraph in the document

doc.p[0].text

In an XML document, you might use an XQL query that looks like this to extract the

phone number from an element called supplierInfo in a SalesOrder document:

/SalesOrder[0]/supplierInfo[0]/phoneNum[0]/text()

The queryDocument service allows you to use either language to define a query. It also

allows you to make this choice on a query-by-query basis—i.e., you can extract some

information from the document using XQL and other information with WQL.

The language you use is largely determined by personal choice and the needs of your

application. Each language has a few specific features that the other does not. When you build your service, you can test your queries using either language to decide which

provides the better results.

For a description of WQL, see Appendix B.

For a description of XQL, see The XML Query Language (XQL), at

http://www.w3.org/TandS/QL/QL98/pp/xql.html. (You can also refer to the XQL overview in

webmethods\developer3\doc\ExampleXQL.txt.)

Working with a Sample Document

To help you build queries faster and more accurately, the Developer lets you generate

queries by pointing to an element in a sample document. The sample document you use

should either be the actual document your service will execute against at run time or a

representative example of that document.

! Although you can define queries without loading a sample document, having one allows you to

create your queries faster and more accurately.

To load a sample document into the Developer, you execute your flow in “trace” mode

(i.e., run the Trace command on the Test menu). When you do this, the Developer displays

the parsed document on the Variables tab in the Edit pane. (The Variables tab only appears

when a queryDocument service is selected in the Flow Pane.)

The Document View tab displays the elements of a document

The Variables tab contains two additional tabs: the Document View tab and the Sample View

tab.

The Document View Tab

The Document View tab shows the nodes (addressable components) that are contained in a

document. It allows you to browse the contents of a document and generate queries by

“pointing” to the node you want to extract.

The Developer uses the following symbols to denote different types of nodes in a

document:

Symbol Description

An HTML or XML element (e.g., <poNum>…</poNum>). If an element contains

additional nodes, the symbol appears next to it. Click this symbol to view

additional nodes within an element.

An element attribute (e.g., name=”Intro”).

A comment.

The Sample View Tab

The Sample View tab displays the result of a query. When you create a query, the

Developer dynamically executes that query against the sample document and displays the

results on the Sample View tab.

After you runqueryDocument in trace

mode, the parseddocument appears on the

Document View tab





The Sample View tab displays the results of the selected query

Adding queryDocument to a Flow Service

The following procedure describes steps you use to insert pub.web:queryDocument into a

flow service. This procedure assumes you have access to a sample document that you can

load and display in the Developer.

! The following procedure explains how to manually insert and specify the queryDocument service.

If you are building a “load-and-query” sequence, you may want to use the B2B Wizard to build

your flow instead. It allows you to quickly create a load-and-query service from a URL that youspecify or by recording actions you make in an Web browser. For information a bout using the

B2B Wizard to create a load-and-query service, see “Load and Query Shortcuts” on page 127.

To insert queryDocument into a Flow Service

1 In the Service Browser, select the flow in which you want to insert the

queryDocument service.

2 In the Flow Pane, select the point where you want to invoke

queryDocument, then click in the Flow Pane toolbar and select

queryDocument from the drop-down menu. (If queryDocument does not

appear on the menu, click Browse and select pub.web:queryDocument

from the Interface tree.)

3 Do one of the following to load your sample XML or HTML document into

the Developer:

When you create aquery…

…you can view theresults on the Sample

view tab





If your flow passes a parsed XML or HTML document to

queryDocument via a loadDocument or stringToDocument operation,

select the Trace command from the Test menu to execute the flow.

(Make sure that the variables in the loadDocument or

stringToDocument service are already correctly specified so that it will

generate node successfully.)

If your flow expects the server to pass a parsed XML document to it,

select the Send XML File command from the Test menu, and then do

the following:

1 Select Trace in the Select Test Mode dialog box and click OK.

2 Select your sample XML file in the Select File dialog box and

then click Open.

4 When the trace finishes executing, display the Flow tab, select the

queryDocument operation in the Flow Pane, and then select Document

View on the Variables tab.

5 Create a query for each piece of information that you want to extract from

the document. See “Specifying a Query” on page 123 for detailed

procedures.

6 If you use a namespace prefix to qualify element names in your query

(e.g., /GSG:supplierInfo/name/text()), AND you want to map that prefix to

a specific namespace in the document, use the following procedure to

assign the prefix to the document’s namespace. (If you do not use

namespace prefixes in your queries OR the prefixes you use match the

ones used in the document, you can skip this step.)

1 Select the Pipeline tab.

2 Select the nsDecls variable in Service In and click on the toolbar

to open the Input for dialog box.

3 Click ,and specify the following:

In this field Specify…

prefix The prefix you use to represent anamespace in your queries.

uri The namespace represented by this prefix.(Namespaces are named using URL

notation.)

4 Click OK.

5 Repeat step 3 and 4 for each namespace prefix that you need to

define. When you are finished, click OK to close the Input for

dialog box.





Specifying a Query

You use the Variables tab to define the queries that queryDocument will execute to

populate a set of variables. The left side of the tab displays the list of variables that you

want queryDocument to populate. The right side of the tab contains the controls you use

to build a query that will populate a variable.

To examine and/or edit the query for a particular variable, you select the variable from

the list on the left side and view and/or adjust the settings (Query, Type, Allow Null, and so

forth) on the right.

The Variables tab to define and edit the variables that queryDocument will produce

There are two ways you can define a variable (and the query that will populate it) for

queryDocument:

You can manually type the query into the Variables tab.

—OR—

You can create the query by “pointing” to the node you want to extract.

Specifying a Query ManuallyIf you are familiar with the contents and structure of the document you want to query,

you can manually build a query to extract information from it. When you create a query

in this way, you do not need to load a sample document into the Developer (however, you

may eventually want to load one to test your queries and verify that they work correctly).

This list displays the setof variables that

queryDocument willprduce





The following procedure describes how to manually create an input variable for the

queryDocument service and assign a query to it.

To manually create a variable for a queryDocument service

1 If the toolbar on the Variables tab is not active, click anywhere in thevariable’s list box (the white area on the left side of the tab) to activate it.

2 Click on the tool bar to create a new variable in the list.

3 Type a name for the variable and press ENTER.

4 Set the following options:

Set this option To specify…

XQL/WQL The query language in which you will write the query.

Set… To…

XQL Use the XML Query Language.

WQL Use the webMethods QueryLanguage

Allow Nulls Whether a null or non-null result should cause theservice to fail at run time.

Set… If queryDocument should…

Allow Null Accept both null and non-nullresults.

Fail if Null Issue an exception if the queryproduces a null result.

Fail if Not Null Issue an exception if the queryproduces anything but a null result.

Type The data type of the variable in which you want thequery result stored.

5 In the Query field, type your query and then press ENTER.

! When querying an XML document, make sure to type node names exactlyas they are specified in the document. For XML, node names are case-sensitive! (HTML node names are not.)

The Developer automatically executes the query when you press ENTER.

If you have a sample document loaded, you can click the Sample View

tab to display the result.





Specifying a Query by Pointing to a Node

To create queries quickly and accurately, you can select a node in the Document View tab

and have the Developer automatically build a query that selects the text for that element.

After the Developer builds the query, you can use it “as is” or edit it to suit your needs.

!To use the following procedure, you must load the source document in the Document View tab. If you have not already done this, run the TestTrace command (if queryDocument receives the

node from a loadDocument or stringToDocument service) or TestSend XML File (if

queryDocument receives input directly from the server) before you begin.

! The following procedure produces a query in your Developer’s default query language. To view

and/or change your current default language, select the Preferences command from the Edit menu,

and adjust the QueryDocument setting on the General tab.

To create a query from a node in the Document View tab

1 On the Document View tab, select the node for which you want to

generate a query.

2 Click the right mouse button and select Create New Variable from Node.

3 Type a name for the variable that will hold the results of the query, and

press ENTER.

4 Set the following options:

Set this option To specify…

Allow Nulls What queryDocument should do if the query producesa null result at run time.

Set… If queryDocument should…

Allow Null Accept both null and non-nullresults.

Fail if Null Issue an exception if the queryproduces a null result.

Fail if Not Null Issue an exception if the queryproduces anything but a null result.

Type The data type of the variable in which you want thequery result stored.

5 If necessary, edit the query in the Query field. Press ENTER when you

finish editing to re-execute the query. To view the results, click the ViewSample tab.

Output Values for queryDocumentThe queryDocument service produces one output variable for each query that you specify

in the Variables tab.





Handling Errors from queryDocument

If queryDocument fails, it throws a server exception. Common reasons for

queryDocument to fail include:

A variable that has no query string assigned to it.

A syntax error in a query string.

A query fails the “Allows Nulls” test.

The node variable does not exist or it is null.

Load and Query Shortcuts



If you need to create a load-and-query service (a flow that invokes a loadDocument

service and a queryDocument service), you can optionally use the B2B Wizard to build it

for you. It can quickly generate this type of service based on a URL that you specify or byrecording your actions in an Internet browser.

Generating Default VariablesBesides speed and ease-of-use, the B2B Wizard offers another benefit—it can produce a

set of default variables to extract frequently-used elements (e.g., , <table>, <li>, and

so forth) from an HTML document. During development, the default variables are useful

way to locate a particular piece of information in a document and ascertain its address.

For example, if you want to select information from a particular table in document, you

can browse the Tables variable to obtain the index for that table.)

The following table describes the set of default variables the B2B Wizard can producewhen it builds a load-and-query service.

Variable Name Description

Title Extracts the text from the document’s <title>…</title> element.

Anchors Collects the values of all HREF attributes in the document.

Paragraphs Collects the text from all elements in the document and stores it

in a String Table.

Tables Collects the text from all <table> elements in the document and

stores it in a String Table.

Forms Collects information about each <form> element in the document

and stores it in a Record List.

Lists Collects the text from all <li> elements (from ordered and

unordered lists) in the document and stores it in a String Table.

! Default variables are not usually used by the service you build (although you may use them if they

suit your purpose). They are provided primarily as guides for locating and examining information

in a document during the development stage. You usually delete the default variables after you

finalize the variable list for queryDocument.

Creating a Load-and-Query Service from a URLThe following procedure describes how to use the B2B Wizard to create a load-and-query

service for a URL that you specify. When you use this method, the Developer generates a

flow service made up of a loadDocument service followed by a queryDocument service,





and automatically configures the input variables for these services based on options that

you specify in the B2B Wizard.

After the B2B Wizard generates the load-and-query service, you can do any of the

following:

Use the flow “as is.”

Edit the input values for the loadDocument and/or queryDocument service.

Insert additional operations into the flow.

Copy the loadDocument and queryDocument services into another flow.

To create a load and query service with the B2B Wizard


2 Select Flow Service and click Next.

3 In the Interface tree, select the interface into which you want to save the

service, type a name for the service in the Name field, and then click

Next.

4 Select Load and Query an HTML Page and then click Next. (Even

though the option refers to an HTML document, you can use this option

with XML documents, too).

5 In the URL field, type the URL of the resource you want to query and then

click Next. (The URL you specify must begin with http: or https:.)


6 Do one of the following depending on whether you are creating thisservice for an HTML or XML document:

− If you are querying an HTML document and you want the Developer

to generate a set of default variables for an HTML document, select

one or more of the following options.

Select… To create…

Title A String containing the title of thedocument.

Anchors A String List containing all the HREF=values from the document.

Paragraphs A String List containing the text of everyparagraph in the document.

Tables A String List containing the text from everytable in the document.

Forms A Record List containing information about






each form in the document.

Lists A String List containing the text from all of the list items in the document.

−

If you are querying an XML document, clear the settings on thispanel. The default variables generated by the B2B Wizard are not

useful for XML documents.

7 Do one of the following depending on whether you want the Developer to

automatically test (execute) the service it builds for you.

− If you want the Developer to execute the service immediately after it

builds it, select one of the following options and then click Finish.

Select… If you want the Developer to…

Run Run the service it from the Developer anddisplay the results in the Results tab.

Run in Browser Run the service from your Internet browser (results will appear in the browser, not theResults tab).

Trace Run the service in “trace” mode, which willdisplay the parsed document on the Variabletab so you can use it to develop additionalqueries.

Step Run the service in “step” mode. This willexecute the loadDocument service and thenstop.

−

If you do not want the Developer to execute the service immediatelyafter it builds it, select No and then click Finish.

! If your service accesses a protected resource, it will not executesuccessfully using any of the execution options in the preceding step. Thisis because the loadDocument service does not have the auth values itneeds to retrieve the requested document successfully. To create a load-and-query for a protected resource, select No in the preceding step. Then,after the Developer generates the service, assign the appropriate user-name and password to auth and execute the service manually from theTest menu.

Using the Browser Recorder The B2B Wizard’s “browser recorder” allows you to generate a series of load-and-query

operations by “recording” actions that you take in your Internet browser. When you use

this method, the B2B Wizard monitors your browser session and automatically generates

a load-and-query sequence for each hypertext link you select or HTML form you submit.





For example, if used the Browser Record to capture the following actions, it would create

a load-and-query sequence for each action as follows:

If you… The B2B Wizard will…

Access a Web site Create a load-and-query sequence for that URL.

Select a link from a Web

site

Create a load-and-query sequence for that URL

Submit a form Create a load and query for that URL, creating the appropriate

set of elements in data.args based on the variables in that

form.

The Browser Recorder is useful for generating flows for complex Web sites and for

capturing the URL’s of documents that are accessed through Javascript or derived from

an image map.

To generate a load and query service with the Browser Recorder


2 Select Flow Service and then click Next.



Next.

4 Select Record in Browser and then click Next.

5 In the URL field, type the URL of the HTML page you want to query and

then click Record. (The URL you specify must begin with http: or

https:.)

The B2B Wizard will launch your Internet browser and display the

requested page. From this point forward, it will capture the URLs of each

page you visit via a hypertext link or an HTML form. The URLs of pages

you visit are shown on the URLs Visited list.

! Tip! You may want to arrange the windows on your screen so that you cansee the B2B Wizard and your browser simultaneously.

!The Browser Recorder cannot capture URLs that you type directly on theaddress line in your browser. If you want the Browser Recorder to record the

address of a page that you visit, you must access that page through ahypertext link or a HTML form.

6 When you are finished recording, click Next.





7 If you want the Developer to generate a set of default variables for an

HTML document, select one or more of the following options, and then

click Next.


Title A String containing the title of the document.

Anchors A String List containing all the HREF= values fromthe document.

Paragraphs A String List containing the text of every paragraphin the document.

Tables A String List containing the text from every table inthe document.

Forms A Record List containing information about eachform in the document.

Lists A String List containing the text from all of the list

items in the document.8 Do one of the following depending on whether you want the Developer to

automatically test (i.e., execute) the service it builds for you.

− If you want the Developer to execute the service immediately after it

builds it, select one of the following options and then click Finish.

Select… If you want the Developer to…

Run Run the service from the Developer anddisplay the results in the Results tab.

Run in Browser Run the service from your Internet browser (results will appear in the browser, not the

Results tab).

Trace Run the service in “trace” mode, whichdisplays the parsed document on the Variabletab so you can use it to develop additionalqueries.

Step Run the service in “step” mode, which causesthe Developer to execute the first service inthe flow (loadDocument) and then halt. To runthe next service (queryDocument), you mustselect that operation in the Flow Pane andthen select the Step command from the Testmenu.

− If you do not want the Developer to execute the service immediately

after it builds it, select No and then click Finish.




C H A P T E R

Creating Cl ient Code

Basic Concepts ........................................................................134

Building a Java Client...............................................................134

Building a C/C++ Client............................................................135

Building a Visual Basic Client...................................................137

Building an Excel Client ...........................................................139

Building a Browser-Based Client..............................................141



C H A P T E R 7 C r e a t i n g Cl i e n t C o d e


Basic Concepts

B2B 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 B2B 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 record (if your service takes input)

Connects to the B2B Integration Server

Invokes a service

Receives output from the service

Disconnects from the B2B Integration Server

Displays the output to the user

The client code that B2B Developer generates can serve as a good starting point for your

own development.

Bui ld ing a Java Cl ient

You can use B2B Developer to generate Java client code that invokes a B2B service.

Assumptions

— The B2B Integration Server is running.

— A fully functional JDK is installed.

— Your classpath consists of at least the following:

yourJDKDir \lib\classes.zip:webmethods\Devloper3\lib\client.zip:

Limitations

B2B Developer cannot generate client code for services that use input or output variables

that are of type Object or Object List.

Procedure

Use the following procedure to have B2B Developer generate Java client code that

invokes a B2B service:



Building a C/C++ Client


To generate Java client code that invokes a service

1 In the Service Browser, select the service for which you want to generate

client code.

2 On the Compose menu, select Generate Code….

3 In the Code Generation dialog box, select For calling this service from

a client, and then click Next.

4 In the Language field, select Java, and then click Next.

5 Identify the directory where you want B2B 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, B2B

Developer creates the directory.

6 Click Finish.

B2B Developer generates the file that contains the Java client code

(ServiceName.java) and a Readme.txt file.

Modify the generated client code to meet your site’s need. 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 Appendix C. Documentation for the Java API can be found at

webMethods\developer3\doc\api\index.html.

7 To complete your client application, refer the Readme.txt file located in the

same directory as your client code.

Files That Are Generated

This section describes the files that B2B Developer generates for a Java client

application.

File Name Description

Readme.txt File that contains information and instructions for the Java client

code. Refer to this file for information about compiling and

running the Java client application.

ServiceName.java An example file that contains the application code for the Java

client. The applet includes a rudimentary user interface that uses

the classes in the InterfaceName directory. It is not intended for use “as is” in custom applications.

Bui ld ing a C/C++ Cl ient

You can use B2B Developer to generate C/C++ client code that invokes a B2B service.





Assumptions


— A platform that has the C/C++ compiler (i.e. GCC) is installed. webMethods

generates code for the following platforms: Windows, Solaris, HP-UX, Linux.

— The client.zip file is in the classpath for B2B Developer. The client.zip file is a

webMethods file that is located in the webMethods/developer3/lib directory.

— The Make facility is installed.

Procedure

Use the following procedure to have B2B Developer generate C/C++ client code that


To generate C/C++ client code that invokes a service


client code.



a client; then click Next.

4 In the Language field, select the C/C++ platform for which you are

creating client code. Select one of the following:

— C/C++ for Windows

— C/C++ for Solaris

— C/C++ for HP-UX

— C/C++ for Linux

Then click Next.





6 Click Finish.B2B Developer generates the file that contains the C client code

(ServiceName.c), a file that contains compiling settings

(ServiceName.make), and a CReadme.txt file.



Building a Visual Basic Client


Modify the generated client code to meet your site’s need. You can

update the client code to invoke built-in services and to use the

webMethods provided C API. For information about the built-in services

that are available, see Appendix C. For documentation about the C API,

see webMethods\developer3\doc\api\c\index.html.

7 To complete your client application, refer the CReadme.txt file located in

the same directory as your client code.


This section describes the files that B2B Developer generates for a C/C++ client

application.


CReadme.txt File that contains information and instructions for the C client

code. Refer to this file for information about compiling, running,

and deploying your C/C++ client application.

ServiceName.make A file that contains compiling settings for the C/C++ client. Be

sure to update this file with the correct settings for your

environment.

ServiceName.c An example file that contains the C/C++ client code. It is not

intended for use as-is in custom applications.

Bui ld ing a V isual Basic Cl ient

You can use B2B Developer to generate Visual Basic client code that invokes a B2B

service. B2B Developer creates files that contain the layout and the code for your

application.

Assumptions


— Visual Basic Version 5 or 6 is installed.

— webMethods Type Library 3.0 is installed.

! The webMethods Type Library 3.0 is a COM object that Visual Basic uses to interact with

the B2B Integration Server. B2B Developer automatically installed the webMethods TypeLibrary if you used Microsoft Java Virtual Machine 5.00.3176 or newer to install B2B

Developer.





Limitations

The client code that B2B Developer generates supports only input values and output

values of type String, String List, and String Table. If you want to use inputs or outputs

that are of type Record or Record List, you will need to modify the client code that B2B

Developer generates.

Procedure

Use the following procedure to have B2B Developer generate Visual Basic client code

that invokes a B2B service:

To generate Visual Basic client code that invokes a service


client code.




4 In the Language field, select Visual Basic 5/6; then click Next.





6 Click Finish.

B2B Developer generates several files, including theserviceNameReadMe.txt file. This file contains detailed information about

all generated files. Refer to it to complete your client application and for

information about deploying your client application.


This section describes the files that B2B Developer generates for a Visual Basic client

application.

General Fi les


ServiceName.vbp The Visual Basic project file.

ServiceNameReadme.txt The file that contains information and instructions for the

Visual Basic client code. Refer to this file for information

about deploying your Visual Basic client application.



Building an Excel Client


Files for the User Interface

The following files are the same for all Visual Basic client code you generate.


frmArrayInput.frm Contains layout and code that is used if any of the input

values for the service are of type String List.

frmOutput.frm Contains layout and code that is uses when the service

returns output. It also contains the Setup, Invoke, and Exit

buttons.

frmSetup.frm Contains layout and code that prompts for the server

properties for the B2B Integration Server on which the

service to execute resides.

frmStringInput.frm Contains layout and code that is used if any of the input

values for the service are of type String.

frmTableInput.frm Contains layout and code that is used if any of the inputvalues for the service are of type String Table.

wmSampleLib.bas Contains code that is specific to the sample template that

B2B Developer generates.

Files Containing the Code that Invokes the Service


ServiceName.bas An example file that illustrates how to use the service class

in an application. This module is dependent on objects in

the project template that webMethods provides. It is not


ServiceName.cls The service object. You include this object into your own

project.

File Containing the Code that Interacts with the B2B Integration Server


wmVBConnection.bas Code used as a layer of abstraction to interact with the B2B

Integration Server.

Bui ld ing an Excel Cl ient

You can use B2B Developer to generate client code that executes a B2B service from aMS Excel spreadsheet.

Assumptions






— Excel 97 or Excel 2000 is installed.

— webMethods Type Library 3.0 is installed.

! The webMethods Type Library 3.0 is a COM object that Visual Basic uses to interact with

the B2B Integration Server. B2B Developer automatically installed the webMethods Type

Library if you used Microsoft Java Virtual Machine 5.00.3176 or newer to install B2BDeveloper.

Limitations

The client code that B2B Developer generates only supports input values of type String

and output values of type String, String List, and String Table. If you want to use inputs

or outputs that use data types that are not supported, you will need to modify the client

code B2B Developer generates.

Procedure

Use the following procedure to have B2B Developer generate Excel client code that


To generate Excel client code that invokes a service


client code.




4 In the Language field, select Excel 97/2000; then click Next.





6 Click Finish.

B2B Developer generates several files, including the

serviceNameReadMe .txt file. This file contains detailed information about

all generated files.

7 Copy the wmXLTemplate.xls file, which webMethods provides, to the

directory that contains the client code that B2B Developer generated. The

wmXLTemplate.xls file is located in the

webMethods\Developer3\support\Excel directory.



Building a Browser-Based Client


8 Open the wmXLTemplate.xls file. When prompted to indicate whether you

want to enable macros, select Enable Macros.

9 Follow the instructions in the wmXLTemplate.xls file to complete your

client application.

See the ServiceNameReadMe.txt file for information about deployingyour client application.


This section describes the files that B2B Developer generates for an Excel client

application.


ServiceNameReadme.txt File that contains information and instructions for the

Visual Basic client code. Refer to this file for information

about deploying your Visual Basic client application.

ServiceName.bas An example file that illustrates how to use the service class

in a spreadsheet. This module is dependent on objects in

the project template that webMethods provides. It is not


ServiceName.cls The service object. You include this object into your own

project.

Bui ld ing a Browser-Based Cl ient

You can invoke B2B service with a URL. This means that you can invoke a service by

entering the URL into your Web browser or by embedding the URL in Web pages.

You cannot use B2B Developer to generate browser-based clients. To build a browser-

based client, create one or more Web pages that invoke URLs for one or more services.

When the B2B Integration Server receives the first URL from a Web browser, it creates a

session for the client on the B2B Integration Server. The session information is stored in a

cookie in the browser. As the user of the browser-based application clicks on links to

URLs that invoke services, the B2B Integration Server uses the cookies to find session

information for the client. The B2B Integration Server keeps the session information for

the client until the session expires. Sessions expire based on the configured session

timeout value. For more information about setting the session timeout limit, refer to the

B2B Server Administrator’s Guide.

Assumptions






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

Invoking Services with a URL

First, build your Web pages using any tool you choose. To invoke the URL, use either theHTTP GET or the POST method. In either case, you use a URL similar to the following:

http://B2Bserver:5555/invoke/sample.webPageDemo/getProductCost?sku=A1&quantity=1

1 2 3 4 5

Item Description

1 Identifies the B2B Integration Server on which the service you want to invoke

resides.

2 Specifies the required keyword invoke, which tells the B2B Integration Server

that the URL identifies a service that is to be invoked.

3 Identifies the interface in which the service to invoke resides. Separate

subinterfaces with periods. This field is case-sensitive. Be sure to use the exact

combination of upper and lower case letters as the interface is named on the B2B

Integration Server.

4 Identifies the service that you want to invoke. This field is case-sensitive. Be sure

to use the exact combination of upper and lower case letters as the service is named

on the B2B Integration Server.

5 Specifies the input values for the service. Specify a question mark (?) before the

input values. The question mark signals the beginning of input values. Each input

value is represented as variable=value. The variable portion is case-sensitive. Besure to use the exact 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.

If you are serving the Web pages that invoke services from a B2B 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.

Using the HTTP GET Method

To use the GET method, embed a URL that includes all the input values for the service in

the query string part of the URL. When the server receives the URL, it translates the input

values into a Values object. For more information about how the server creates the Values

object that it sends to the service, refer to “Input into the Service” on page 143.

Using the HTTP POST Method

To use the POST method, create an HTML form in your Web page. Create fields in the

HTML form in which a user will supply the input information. The values you specify for

the NAME attributes of the HTML form fields should match the name of input values

that the service expects. Be sure to use the exact combination of upper and lower case

letters as specified in your service. For example, if your service requires the input values sku and quantity, you might create an HTML form with following fields:

<SELECT NAME="sku">

<OPTION VALUE="A1">A1</OPTION>

<OPTION VALUE="B2">B2</OPTION>

<OPTION VALUE="C3">C3</OPTION>

</SELECT>

<INPUT TYPE="TEXT" NAME="quantity" VALUE="1">

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. The browser invokes the

URL identified in the ACTION attribute, which invokes the service on the B2B

Integration Server, and the browser posts the document that contains the user’s input

information to the B2B Integration Server. For more information about how the server

creates the Values object that it sends to the service, see “Input into the Service” on page

143.

Input into the Service

Regardless of whether the B2B Integration Server receives a URL that uses the HTTP

GET or POST method, it creates a Values object from the input information. It then

passes the Values object to the specified service.

To create the Values object, the B2B Integration Server creates two key/value pairs for

each input value—one of type String and one of type String List. For example, if the

input values contain the variable sku with value A1 and quantity with value 1, the service

is passed the following Values object:

Key Value Data Type

sku A1 String

skuList A1 String List

quantity 1 String

quantityList 1 String List

! Do not use input variable names that end in List. For example, if your service expects a list of

sku values, do not name the variable skuList .

When the server receives multiple input values that are associated with the same variable

name, the String variable in the Values object contains only the value of the first variable;

the String List variable contains all values. For example, the following shows a URL that

contains two values for the variable year and the resulting Values object that the server

creates:

/invoke/sample.webPageDemo/checkYears?year=1998&year=1999

Key Value Data Type

year 1998 String

1998 yearList

1999

String List

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 Values 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 as check boxes:

<INPUT TYPE="checkbox" NAME="Color" VALUE="blue">Blue 

<INPUT TYPE="checkbox" NAME="Color" VALUE="green">Green 

<INPUT TYPE="checkbox" NAME="Color" VALUE="red">Red 

If the browser user selects all check boxes, the document that is posted to the B2B

Integration Server will contain three values for the variable named Color. The following

shows the Values object the server passes to the service:

Key Value Data Type

Color blue String

blue

green

ColorList

red

String List

Output from the Service

By default, the B2B Integration Server displays the output from a service in a HTML

Web page, using a table to render the output values. However, you can format the output





by using output templates. You can use an output template that formats the output from

one service and includes a URL that invokes another service. For more information about

output templates, see “Creating Output Templates” on page 97.




C H A P T E R

Passing XML Data to a B2B Service

Sending XML Documents to the B2B Integration Server ..................148

Submitting an XML Document in a String Variable ...........................148

Submitting an XML Document in $ xmldata .......................................149

Posting an XML Document via HTTP................................................150

Sending an XML Document via FTP.................................................151



C H A P T E R 8 P a s s i n g X M L D a t a t o a B 2 B S e r v i c e


Sending XML Documents to the B2B Integrat ion Serv er

As discussed in the “Using the Load and Query Services” chapter, the B2B Integration

Server provides ways for a service to fetch XML documents from the Web. However, the

server also provides the following automated mechanisms for receiving arbitrary XMLdocuments, parsing them, and passing them as input to a specified service.

A client can submit an XML document to a flow service in a string variable (of any

name) and use web.pub:stringToDocument to convert it to a node.

A client can submit an XML document to a service in a special string variable

named $ xmldata, and the B2B server will automatically parse the variable and pass

it to the service as a node.

A client can post an XML document to a service via HTTP.

A client can FTP an XML document to a service.

Submit t ing an XML Document in a Str ing Var iable

One way to submit XML to a service is to pass the XML document to a flow service in a

String variable. When you use this approach, your flow service must include

web.pub:stringToDocument to convert the XML document into a Values object. See page 281

for information about the stringToDocument service.

The following code fragment shows a Java client that 1) loads an XML document into a

string, 2) puts that string in the Values object, and 3) invokes a service called

purch:postOrder .

import com.wm.app.b2b.client.*;import com.wm.util.*;import java.io.*;public class ArbitraryXMLClient

.

.

.//--Load XML into orders string

String orders = YourLoadXMLMethod(orderFile);

//--Put input values into Values objectinputs.put("orders", orders);inputs.put("authCode", authCode);

//--Submit request to server

c.connect("localhost:5555", "null", null);Values outputs = c.invoke("purch", "postOrder", inputs);

c.disconnect();...

2

3

1



Submitting an XML Document in $xmldata


The service invoked by this client must invoke web.pub:stringToDocument and pass orders to

it as input. stringToDocument will parse the contents of orders, producing a document object

that can be used by any B2B service that takes a node as an input variable (e.g.,

queryDocument, documentToRecord).

Submit t ing an XML Document in $ xmldata

Submitting an XML document to the B2B Integration Server using $xmldata is similar to

submitting it as a String variable, except in this case, the service receiving the document

does not need to include a parsing step—the B2B Integration Server automatically parses

the contents of $xmldata.

The name $xmldata has special meaning to the B2B Integration Server—it assumes the

value of this variable is an XML document. When it receives a request that includes an

input variable named $xmldata, the server automatically parses the contents of that

variable, producing a document object that can be used by any service that takes a node

as input.

The following example shows a client application that reads an XML document from a

file, assigns the text in the file to $xmldata and then passes $xmldata to a service called

sales:getOrder .

import com.wm.app.b2b.client.*;import com.wm.util.*;import java.io.*;

public class ArbitraryXMLClient

{public static void main(String args[])

throws Exception

{

//--Read XML document from a specified file (or from stdin)Context c = new Context();Values inputs = new Values();Reader in = null;if(args.length > 0){

in = new InputStreamReader(new FileInputStream(args[0]));}else{

in = new InputStreamReader(System.in);}char[] buf = new char[8192];int count = 0;StringBuffer sb = new StringBuffer();

while((count = in.read(buf)) != -1){sb.append(buf, 0, count);

}

//--Assign XML document to string variableString xmldata = sb.toString();

//--Put XML document into $xmldata in Values object





inputs.put("$xmldata", xmldata);

//--Submit request to serverc.connect("localhost:5555", "null", null);

Values outputs = c.invoke("sales", "getOrder", inputs);c.disconnect();

//--Display the returned output valuesSystem.out.println(outputs);

}}

The service invoked by this client must be a service that takes a node as an input variable

(e.g., queryDocument, documentToRecord), since this is what the B2B Integration Server will

produce when it receives this request.

! The example above shows a Java-based client, however, any type of B2B client can be used.,

even a browser-based client. With a browser-based client, you would post the XML document as

the value portion of a $xmldata=value pair. You would most likely construct the XML document

with a Javascript. You may post other name=value pairs with the request.

Post ing an XML Document v ia HTTP

A client can post an XML document to a service via HTTP. To use this approach, you

must have a client that can:

Send a string of data (an XML document) to the B2B Integration Server using the

HTTP POST method.

–AND–

Set the value of the Content-Type request-header field to text/xml.

When the B2B Integration Server receives an HTTP POST request where Content-Type

is text/xml, it automatically parses the body of the request (the XML document) and

passes it as a node to the service specified in the request’s URL.

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 B2B’s service, pub.client:http.

Regardless of which client you use, it must do the following:

Submit a POST request to the B2B Integration Server

Address the request to the URL of a B2B service (e.g.,

http://rubicon/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.



Sending an XML Document via FTP


! When you submit the XML document, place an extra CR/LF (\r\n) at the end of it to

indicate the end of the document.

The following example describes the values that you will set if you are using pub.client:http

to POST an XML document to a B2B service.

Set this Variable… To…

url The URL of the B2B service that you want to invoke. The following

value would invoke a service called purch:postOrder from a server

named “rubicon.”

Example: http://rubicon/invoke/purch/postOrder

method post

headers.Content-Type text/xml

data.string

–OR–

data.bytes

The XML document you want to post.

You will also set any optional HTTP parameters, such as authorization information, that

are required by your application.

Sending an XML Document v ia FTP

You can FTP an XML document to the B2B Integration Server’s FTP listening port. (By

default the FTP listener is assigned to port 8021. However, this assignment is

configurable, so you should check with your B2B server administrator to see which port

is used for FTP communications on your B2B Integration Server.)

When the B2B Integration Server receives an XML document on the FTP listening port,

it automatically parses the document and passes it as a node to the service in the directory

where the file was FTPed.

To use this method:

— The XML document must be contained in a file that has a file extension of “xml.”

— The B2B service to which you want to pass the document must take a node as input.

Building a Client that Sends an XML Document to a B2B Service

If you want to submit an XML document to a B2B service through FTP, the application

sending the document must do the following:

1. Initiate an FTP connection to the B2B Integration Server’s FTP listening port.





2. Point to the directory that contains the B2B service to which you want to pass the

XML document.

Example cd \ns\Purchasing\SubmitOrder

!

Note that the root directory for this operation is your B2B Integration Server’s namespace

directory (ns), not the root directory of the target machine. Therefore, if you want to FTPa file to a service in the Purchasing package, you use \ns\Purchasing\ServiceName as

the path to that service, not \webmethods\server\ns\Purchasing\ ServiceName.

3. Copy the XML document to this directory using the following command:

put XMLDoc.xml

Where XMLDoc.xml is the name of the file that you want to pass to the B2B

Integration Server.

Example put PurchaseOrder.xml

Note that the document you FTP to the B2B Integration Server is never actually

written to the servers file system. The document you send and the output file it

produces (see below), are written to a virtual directory system maintained in your

B2B session.

Getting Results from an FTPed Document

Results of a service that is executed from an FTP request are written as an XML

document to the same virtual directory where the XML document was initially FTPed.

The B2B Integration Server produces the result file by converting the Values object

returned by the service into an XML document. The name of the output file is:

XMLDoc.xml.out

Where XMLDoc.xml is the name of the XML file initially FTPed to the service.

You retrieve this document with the FTP get command. For example, if you put a

document called PurchaseOrder.xml to the B2B Integration Server, you would use the

following FTP command to get its results:

Example get PurchaseOrder.xml.out

!We recommend that you make each document name that you FTP to the B2B Integration Server

unique (perhaps by attaching a timestamp to the name) so you don’t inadvertently overwrite

FTPed documents or their results during an FTP session.

When you end the FTP connection, the B2B Integration Server automatically deletes the

original file and its results from your session.




C H A P T E R

Accessing Databases with B2B Services

The Types of Services You Can Create...................................154

Creating Database Flow Services ............................................155

Generating a Service from a SQL Statement ...........................156

Generating a Service from a Table ..........................................158

Creating Database Services with Java, C/C++, or VB .............161

Creating Clients that Access Databases..................................163



C H A P T E R 9 A c c e s s i n g D a t a b a s e s wi t h B 2 B S er v i c e s


The Types of Services You Can Create

All types of services can access databases—flows, Java, C/C++, and Visual Basic. You

can create:

Flow services using the Server Administrator. When you create a flow service, you make

selections from screens in the Server Administrator to describe the function that you

want the service to perform. The server generates the flow service for you.

Java, C/C++, and Visual Basic services using the B2B Developer or your own development

environment. webMethods B2B provides built-in services that perform basic database

operations, such as, connecting to a database, selecting rows, inserting rows, and

deleting rows. Your services can access these built-in services to perform database

operations or use other database APIs (for example, JDBC) to access databases.

Deciding What Type of Service to Create

Use the information in the following table to decide which type of service you should

create.

Type of Service Advantages and Disadvantages

Advantages You can easily create the flow service usingthe Server Administrator user interface.

You do not need to recompile code when youmake changes to the flow service.

Flow servicescreated with Server Administrator

Disadvantages The flow service might not be able to handlenonstandard database features, such as

Windows SQL types. You can only make JDBC calls in a flow

service. Use a Java, C/C++, or Visual Basicservice to connect to a database using other libraries.



Creating Database Flow Services


Advantages The service can be coded more flexibly interms of processing data. You can manipulatedata directly rather than invoking thewebMethods B2B libraries. For example, youcan use configuration files to guide processingsettings.

The service can include more robust error handling. For example, you can log errors toyour own files or send e-mail notes to several people.

The service can make direct calls to databaseAPIs (for example, JDBC, ADO, and ODBC)to handle nonstandard database features.

Java, C/C++, or Visual BasicServices

Disadvantages You have to code and compile the service.

Creat ing Database F low Services

Before you can use the Server Administrator to build flow services, the server must have

a configured database alias for the database that you want to access. The database alias

must be configured when you create a service and when the server executes the service.

For more information about how to configure a database alias, see the B2B Server

Administrator's Guide.

To create flow services using the Server Administrator, you go through a series of

screens, selecting options and specifying information to indicate the function you want

the service to perform. The server builds a flow service from the selections you specify.

The flow service invokes the same built-in services that you can invoke from Java,

C/C++, and Visual Basic. For descriptions of the services, refer to “Built-in DatabaseServices” on page 162.

You can choose from two options for how to create a flow service using the Server

Administrator:

Generating from a SQL statement. You specify the SQL statement that you want the

service to perform. You can specify more complex SQL statements than the server

generates when you generate from tables. In addition, you can specify database-

specific SQL. For example, use this option if you want to use database-specific SQL

that requires the fully qualified table names. For more information, refer to

“Generating a Service from a SQL Statement” on page 156.

Generating from tables. You select the table that you want the service to access. Then,you select the database operation you want your service to perform (Select, Insert,

Delete, or Update). The server displays the columns in the table that you can use to

indicate the input that the service expects. When you use this option, the server





automatically generates the required SQL statements. For more information, refer to

“Generating a Service from a Table” on page 158.

After a service is created, you can update it using the B2B Developer in the same manner

you would edit any other flow service. You can also invoke the flow service that you

generate from other services.

Generating a Service from a SQL Statement

When you select that you want to generate the service from a SQL statement, you must

specify the SQL statement you want the service to perform. You can specify a statement

that is static or include either question marks (?) or template tags in the SQL statement to

make it dynamic.

! The generated flow service is unable to properly call a stored procedure. It is unable to return the

result set or output parameters. If you want to call a stored procedure, create the service in Java,

C/C++, or Visual Basic and call the stored procedure using the pub.db:call service.

Specifying a Dynamic SQL Statement

When you specify a dynamic SQL statement, the service expects input values to replace

the question marks or template tags that you specify. You can specify the following to

make a SQL statement dynamic:

Question marks (?). Use a question mark in place of a single parameter that the service

expects as input. When you use the Server Administrator to test the service, it

recognizes the question marks and prompts for the required input.

Example

To select all rows from the Names table that match the values specified for theLast_Name column, specify the following SQL statement:

select * from Names where Last_Name=?

The service expects input for the value to use to match rows in the Last_Name

column.

Example

To add a new row to the Addresses table and populate it with specified values,specify the following SQL statement:

insert into Addresses (name,street,city,state,zip) values(?,?,?,?,?)

The service expects input for the values to use to populate the new row.

Template tags. The template tags you can use are the same as the tokens you use in an

output template. Use the tokens to make the service more flexible. Rather than just

replacing single parameters, you can use a token to replace a complete phrase in a

SQL statement. For a description of the template tags you can use in the SQL

statements, see “Creating Output Templates” on page 97.

Because the server does not recognize the template tokens in the SQL statement,

when you use the Server Administrator to test the service, the server does not prompt

you for the input. Use the B2B Developer to test the service.

Example

To select all the rows from the Names table that meet a specified condition,specify the following SQL statement:

select * from Names where %value condition%

The service expects an input variable named condition that it uses to replace the

entire token. The following shows examples of what a user can specify for %value

condition%:

name = 'Steve'name like 'Jim%'

Example

To delete all rows from the Music table that meet a specified condition, specifythe following SQL statement:

delete from Music where %value outdated%

The service expects input for an input variable named outdated that it uses to replace

the entire token. The following shows example of what a user can specify for %value

outdated%:

ReleaseDate < '1950'Format = '8-track'

Steps for Generating the Flow Service

Use the following procedure to generate a flow service by specifying a SQL statement.

To generate a flow service from a SQL statement

1 Open the Server Administrator if it is not already open. See the

webMethods B2B Server Administrator’s Guide if you need procedures for

this step.

2 Select the Database task on the navigation panel.

3 Click the Service Generation tab if it is not already displayed.

4 Select the database you want the service to access from the Source Alias

drop down list.

5 Select the package in which you want the service to reside from the drop

down list in the Package field.





6 Type the interface name for the service in the Interface field.

7 Type the name for the service in the Service field.

8 Click Generate from SQL.

9 Enter the SQL statement you want the service to execute in the Enter

SQL statement section of the screen.

10 If you included template tags in the SQL statement, click the Process

webMethods template tags (%value, %ifvar, etc.) in this SQL

statement checkbox.

11 Click Evaluate. The server displays the Input Binding Generation

screen.

If you specified question marks (?) in the SQL statement for input values,

the server displays a Bind parameters section of the screen. There is one

Parameter n field for each question mark you specified in the SQL

statement. The first question mark you specified corresponds toParameter 0, the second to Parameter 1, and so forth.

12 Use this section of the screen to indicate additional information about the

input parameters that a user will supply in place of the question marks. For

each Parameter n field in the Bind parameters set the associated

parameters as follows:

For this parameter Specify…

name: Name you want the service to use for theinput value.

type: Data type of the input value. Select thecorrect data type from the drop down list.

13 Click Generate.

Generating a Service from a Table

When you select that you want to generate the service from database tables, the server

displays information about the tables in the selected database. You are given the

opportunity to narrow down (or restrict) the list of tables that the server displays. Narrow

down the list of tables if your database contains many tables.

Restricting the List of Database Tables

You can restrict the list of database tables that the server displays by specifying one or

more of the following:

Catalog. You specify the name of the catalog whose tables you want to use.

— If you are not working with a distributed database, do not restrict by catalog.





— If your are working with a distributed database, you can specify the name of the

database with which you want to work. If you are using DB2, use this field to

specify the name of a DB2 location.

Schema pattern. You specify the schemas whose tables you want to work with (if you

are using DB2, use this field to specify an AuthID).

— If you want tables for all schemas in the selected database, do not restrict by

schema pattern.

— If you want to restrict your search to tables by selected schemas, specify the

schema name. You can specify a pattern-matching string if your JDBC

supports it. Most drivers support the pattern-matching characters described for

Table name pattern below. However, check your driver’s documentation for

information about its pattern-matching capabilities.

Table name pattern. You specify the names of the tables with which you want to work.

Specify a table name or a pattern-matching string that specifies the names of the

tables. Most drivers support the following pattern-matching characters; however,check your driver’s documentation for information about its pattern-matching

capabilities.

Use To match For example

% Any string of characters HR% matches: HR30all, HR15mgmt,

HR01payroll, and so forth.

_ A single character HR3_mgmt matches: HR30mgmt, HR31mgmt,

HR3Amgmt, and so forth.

Table type. The types of the tables for which you want information. You can choose

from the following common JDBC table types: Table, View, System Table, Global

Temporary, Local Temporary, Alias, and Synonym.

Steps for Generating the Flow Service

Use the following procedure to generate a flow service by specifying a SQL statement.

To generate a flow service from a table


webMethods B2B Server Administrator’s Guide if you need help with this

step.



4 Select the database you want the service to access from the Source Alias

drop down list.





5 Select the package in which you want the service to reside from the drop

down list in the Package field.

6 Type the interface name for the service in the Interface field.

7 Type the name for the service in the Service field.

8 Click Generate from table. If you are accessing a large database, you

might want to restrict your search to the tables with which you want to

work.

— To restrict your search, fill in one or more fields in the Restrictions

section of the screen, and then click Connect. For more information

about how to restrict the search, refer to “Restricting the List of

Database Tables” on page 158.

— To search all database tables, click Connect.

9 In the Select a table section of the screen, click on the table name that

you want to use to generate the service.

10 Select the database operation you want the service to perform (Select,

Insert, Delete, or Update) from the Service type section of the screen.

11 Select the columns you want to use as input in the Columns section of the

screen. When the service is executed, it will expect input values for each

of the columns you select. The service uses the input values as follows:

For this operation… The service…

Select Selects rows that have columns that match the input values.

Insert Populates the columns of the inserted rows using the inputvalues. If you want to populate all columns in the row, select

all column names.Delete Selects rows that have the columns that match the input

values, and deletes the selected rows.

Update Selects rows and updates them.

You identify the criteria to use to select rows by checkingcolumn names in the Criteria column. The service expectsinput values for each column name you check. The serviceselects rows that have columns that match the input values.If you want to select all rows, do not check any Criteriacolumns.

To identify the columns to update in the selected rows, usethe Set column. The service expects input values for each

column name you check. The service sets the value of thechecked column names (for all selected rows) to the inputvalues specified.

12 Click Generate SQL.



Creating Database Services with Java, C/C++, or VB


If you selected any columns for input variables, the server displays a Bind

parameters section of the screen. There is one Parameter n field for

each input variable you specified in the SQL statement.

13 Use this section of the screen to indicate additional information about the

input parameters. For each Parameter n field in the Bind parameters setthe associated parameters as follows:

For this parameter Specify…

name: Name you want the service to use for the input value.By default the server uses the database column name.If you want to use a different name, type the new name

in the name: field.

type: Data type of the input value. By default, the server usesthe data type that is associated with the databasecolumn. If you want to use a different data type, selectthe data type from the drop down list.

14 Click Generate.

Output from the Flow Service

The following describes the output from a flow service that you generate from a database

table based on the database operation that the service performs:

Database Operation Output

Select Number of rows that the service retrieved and the columns from

those rows that the service requested.

Insert Update count the database returned in response to the SQL

command.

Delete Update count the database returned in response to the SQLcommand.

Update Update count the database returned in response to the SQL

command.

Creat ing Database Services wi th Java, C/C++, or VB

You can code services that access databases in Java, C/C++, or Visual Basic. Code your

own services if you need a service that performs more complex database operations than

a flow service can provide.





To assist you in coding the service, you can use built-database services to perform basic

database operations and test SQL statements before you add them to your services.

If you want your service to access a database that has nonstandard features (for example,

data types that are not supported by SQL), use other database connection APIs. For

example, you can make direct calls to JDBC or use other connection libraries, such as

ADO.

Built-in Database Services

webMethods B2B provides several built-in database services that perform basic database

operations. These services use JDBC to connect to the database to perform the specific

database operation. You can invoke the built-in database services from:

Java, C/C++, and Visual Basic services

Any flow service that you create using the B2B Developer by using the INVOKE

flow operation

Clients

Appendix C contains a list of built-in database services and shows input and output

information for each. Your service or client must invoke the built-in database service that

opens a connection to a database before it can invoke any of the other built-in database

services.

Testing SQL Statements

You can use the Server Administrator to test an SQL statement that you want to execute

using the built-in database service, pub.db:execSQL, or that you want to invoke directly

using a JDBC call.Before you can use the Server Administrator to test an SQL statement, the server must

have a configured database alias for the database that you want to access. For more

information about how to configure a database alias, refer to the B2B Server

Administrator’s Guide.

To test a SQL statement


webMethods B2B Server Administrator’s Guide if you need procedures for

this step.



4 Select the database for which you want to issue a SQL statement from the

Source Alias drop down list.



Creating Clients that Access Databases


5 Select any package from the Package drop down list, and type an

interface name in the Interface field and a service name in the Service

field. It does not matter what you specify for in these fields because you

will not be creating a service.

6 Click Generate from table.7 If you are accessing a large database, you might want to restrict your

search to the tables with which you want to work.

— To restrict your search, fill in one or more fields in the Restrictions

section of the screen, and then click Connect. For more information

about how to restrict the search, refer to “Restricting the List of

Database Tables” on page 158.

— To search all database tables, click Connect.

8 In the Test SQL Queries section of the screen, type the SQL statement

you want to test.

9 Click Execute query.

The server displays a screen that lists the results from your SQL query.

Error Handling

All services return a $dbMessage output value, which contains a text message that

describes the results of the service. If the service results in an error, the service also

returns standard webMethods B2B error output values.

Creat ing Cl ients that Access DatabasesYou can access the databases from all types of clients:

Browser-based clients

Clients coded in Java, C/C++, or Visual Basic.

Invoking a Database Service from a Browser-Based Client

Several of the database services can accept input from a browser-based client. (The

descriptions of the database services in Appendix C indicate whether you can invoke a

built-in database service from a browser-based client.)

When a browser-based client submits input variables containing row information, theseservices automatically convert the row information into a nested Values object. The

service determines which variables to convert based on their names. All variables except

those whose names begin with _ or $db are converted into nested Values objects.

For example, if a browser user submits the following name-value pairs:





Variable Name Contents

$dbTable Table Name

Name Joe B

Company Widgets, Inc.

The pub.db:insert service converts the inputs as follows:

Variable Name Contents

$dbTable Table Name

$data Variable Name Contents

Name Joe B

Company Widgets, Inc.



Creating Clients that Access Databases


Invoking a Built-in Service from a Java, C/C++, or VB Cli ent

You can create client applications in Java, C/C, or Visual Basic. The client applications

can use the built-in database services to perform database operations. For information

about these built-in services, see Appendix C.

If you want your client to access a database that has nonstandard features (for example,

data types that are not supported by SQL), you use other database APIs. For example, you

can make direct calls to JDBC or use other connection libraries, such as ADO.

Sample Code

The following shows a sample Java client that accesses a database.

import com.wm.util.Values;import com.wm.app.b2b.client.Context;

public class DBClient{

public static void main (String [] args) throws Exception{

Values in = null, out = null;Values criteria = null, set = null;

//// connect to your B2B server using an appropriate user// name and password (doesn't have to be Administrator)//Context ctx = new Context();ctx.connect ("localhost:5555", "Administrator", "manage");

//// (1) request a DB connection by DB alias (if the DB

// changes location or something, we won't have to change// this client code)//in = new Values();in.put ("$dbAlias", "Employees");out = ctx.invoke ("wm.util.db", "connect", in);

//// (2) update the Identification table to set Fonz's ID// to 6500. note that we couldn't do this from a web// browser because we couldn't build up the complex// nested Values structures//in = new Values();in.put ("$dbAlias", "Employees");

in.put ("$dbTable", "Identification");criteria = new Values();

criteria.put ("name", "fonzie");in.put ("$criteria", criteria);

set = new Values();set.put ("ID", "6500");in.put ("$set", set);





out = ctx.invoke ("wm.util.db", "update", in);

//// (3) look at the return values (updateCount is the// most important in this case)//try {

int uc = Integer.parseInt ((String)out.get("updateCount"));System.err.println ("Update count: "+uc);} catch (Exception e) {

// maybe something went wrong with the DB access; we// can get more information hereSystem.err.println ("Error: "+out.get("$error"));System.err.println ("Error type: "+out.get("$errorType"));

}

}

}




C H A P T E R

Using Guaranteed Del ivery

What is Guaranteed Delivery? .................................................168

How Transactions are Managed ..............................................168

Identifying Transactions ...........................................................170

Specifying How Long Transactions are Active.........................170

Handling Failures .....................................................................171

Coding Client Applications and Services..................................172



C H A P T E R 1 0 U s i n g G u a r a n t e e d D e l i v e r y


What is Guaranteed Del ivery?

Guaranteed delivery is a facility of the B2B Integration Server that ensures guaranteed,

one-time execution of B2B services. It protects transactional requests from transient

failures that might occur on the network, in the client, or on the server.

A transient failure is a failure that can correct itself within a specified period of time. If a

request cannot be delivered to the server due to a transient failure, the request is

resubmitted. If the problem has corrected itself, the request is successfully delivered on a

subsequent attempt. You can determine what constitutes a transient error by specifying a

time-to-live (TTL) period for a guaranteed delivery transaction and, optionally, the

number of times a transaction should be retried. If you do not specify the TTL or retry

value, the configured defaults are used.

You can use guaranteed delivery when you invoke a B2B service from a client or from

within another B2B service.

!You can only use the guaranteed delivery capabilities with stateless (i.e., atomic) transactions. As aresult, guaranteed delivery capabilities cannot be used with multi-request conversational services.

Indicat ing You Want to Use Guaranteed Del ivery

To invoke B2B services using guaranteed delivery from either a client application or

another service use the class watt.client.TContext (TContext) that is a part of the Client

API. Similar to the standard class watt.client.Context (Context), you use TContext to

request that the B2B Integration Server execute a service. However, the server performsguaranteed delivery functions when a client application or service requests services

through TContext.

How Transact ions are Managed

Guaranteed delivery transactions are managed by Job Managers. For client applications,

the Job Manager runs on the client. For services, the Job Manager runs in the server.

The Job Managers manage all guaranteed delivery transactions that a process creates

using TContext. The Job managers maintain a job store of the guaranteed delivery

transactions. The job store contains a record for each transaction. In addition, the JobManagers maintain a log that tracks the progress of all transaction operations.

The Job Manager handles the invocation of the service using background threads, which

the Job Manager allocates from a configurable pool of threads. The Job Manager sends

the service requests to a B2B Integration Server and accepts the results on behalf of the



How Transactions are Managed


client applications or services that use TContext. If the Job Manager does not receive a

result for a transaction in its job store, it resubmits that request to execute the service. It

continues to resubmit requests until it either receives a result or the transaction expires.

For client applications, a single Job Manager runs in the client process and is shared by multiple

TContext instances. For services, a single Job Manager runs in the server process and is shared byall TContext instances.

Customizing the Job Managers

You can customize how the Job Manager manages guaranteed delivery transactions

programmatically or through system properties. To specify programmatically, your client

application specifies the setting with parameters of TContext methods. To specify

through system parameters, specify the setting on the Java command line.

If a setting is specified both with a parameter of TContext and through a system property,

the Job Manager uses the setting specified through the system property.

Location of the Job Store. Specify the directory in which the Job Manager maintains its

job store.

Client apps Specify using a parameter with the init method.TContext Method:

Services Cannot specify using a TContext method.

System Property: Use the –Dwatt.tx.jobdir=directory option.

The default for a client application is: ./jobs

The default for a service is: webmethods/server/logs/jobsout

Location of the transaction Log. Specify the file in which the Job Manager maintains itsaudit-trail log of all the guaranteed delivery transaction operations it processes.

Client apps Specify using a parameter with the init method.TContext Method:

Services Cannot specify using a TContext method.

System Property: Use the –Dwatt.tx.logfile =filename option.

The for a client application is default is: ./txout.log

The for a service is default is: webmethods/server/logs/tx.log

Submission interval for the Job Store. Specify the number of seconds between sweeps of

the job store. The Job Manager sweeps the job store to submit transactions to a B2BIntegration Server.

TContext Method: Cannot specify using a TContext method.

System Property: Use the –Dwatt.tx.sweepTime=seconds option.





The default is: 60 seconds

Time to Retry Interval. Specify the number of seconds to wait after a service request

failure before the Job Manager resubmits the request to the B2B Integration Server.


System Property: Use the –Dwatt.tx.retryBackoffTime=seconds option.

The default is: 60 seconds

Number of Client Threads in Thread Pool. Specify the number of threads you want to make

available in a thread pool to service pending requests.


System Property: Use the –Dwatt.tx.jobThreads.

The default is: 5 threads

Ident i fy ing Transact ions

It is the responsibility of the client application or service to obtain a transaction id (tid)

for each guaranteed delivery request and to specify the transaction id with each

subsequent request for the transaction.

The client application or service obtains the transaction id from the B2B Integration

Server using the startTx( ) method, which is used to start a guaranteed delivery

transaction. See “Coding Client Applications and Services” on page 172 for additional

instructions and sample code.

Speci fy ing How Long Transact ions are Act ive

A guaranteed delivery transaction has two attributes that determine how long it stays

active. These are the time-to-live (TTL) and the retry limit. The TTL specifies the number

of minutes that a transaction is to remain active. The retry limit specifies the maximum

number of times that the Job Manager is to resubmit a request. A transaction becomes

inactive when the TTL or the retry limit (if specified) is reached, whichever comes first.

When a transaction becomes inactive, it remains in the job store, but the Job Manager no

longer attempts to submit the request.

The client application or service sets the TTL, and optionally, the retry limit with thestartTx () method, which it uses to start a guaranteed delivery transaction. See “Coding

Client Applications and Services” on page 172 for additional instructions and sample

code.



Handling Failures


These values determine the degree of tolerance the client application or service has

towards transient network and server errors that occur at run time. Specifically, they

determine the length of the outage that the client application or service considers

transient. An outage that exceeds these limits will be deemed unrecoverable by the Job

Manager and will cause the Job Manager to return an error for the request.

Handl ing Fai lures

If a non-transient error prevents your client application or service from receiving the

results from a B2B service request, your application will receive an error message.

Records remain in the job store for a transaction until the client application or service

explicitly ends the transaction. To avoid exhausting the job store, a client application or

service must make sure to complete all the transactions it starts, or a site must establish

administrative procedures to address failed jobs.

TContext can return the following types of errors:

AccessException. The client application or service either supplied invalid credentials or

is denied access to the requested service.

ServiceException. The service encountered an execution error.

DeliveryException. The Job Manager failed and became disabled. An administrator

should be notified to correct this problem. For client applications, code your client

application to notify an administrator when this type of error occurs. After the

problem is corrected, re-enable the Job Manager using the TContext.resetJobMgr( )

method.

For services, guaranteed delivery notifies the administrator identified by thewatt.server.txMail configuration setting. After the problem is corrected, re-enable the

Job Manger by executing the wm.server.tx.resetOutbound service.

IllegalRequestException. The client application or service made an invalid request, for

example, supplied an invalid transaction id (tid) or other invalid parameter.





TXException. A failure occurred with the transaction. The transaction timed out, hit the

retry limit, or encountered a heuristic error. Typically, this type of error indicates that

the transaction became inactive either because the time-to-live (TTL) value elapsed

or the retry limit was met. To distinguish between these two errors, use the

isExceededRetries( ) method.

Heuristic errors will only occur if you altered the default configuration of the B2B

Integration Server to fail PENDING requests when the B2B Integration Server is

restarted after a failure. Use the isHeuristicFailure( ) method to determine if a

heuristic error occurred.

A heuristic error does not guarantee that your transaction was not executed, only that its

results could not be returned. Keep this in mind if you are processing transactions that must

be executed once and only once (for example, an application that enters purchase orders or

pays invoices). You might also need to implement additional mechanisms in your client

application or service to ensure that a transaction does not get posted twice.

Coding Cl ient Appl icat ions and Services

When using guaranteed delivery for a client application, you must initialize TContext

when a process starts. The server handles this function when a service uses guaranteed

delivery.

Create TContext instances for different connection attributes. If you are only connecting

to one host with a single set of credentials, you need only one TContext regardless of how

many threads share the TContext.

The main difference between Context (the standard class) and TContext is that your client

application or service is responsible for obtaining a transaction id (tid) and associating it

with each request you make for the same transaction. You receive a transaction id (tid)when you start a guaranteed delivery transaction.

After a transaction is started and a transaction id is received, you can invoke a service

using guaranteed delivery. You must supply the transaction id when you invoke the

service.

When the transaction completes, you must end the transaction to clear the record for the

transaction from the Job Manager’s job store.

You can chain transactions in a sequence so that each transaction in a sequence waits

until the preceding transaction executes. To chain transactions, supply the transaction id

(tid) from the previous transaction when starting a new transaction.

When you are done executing guaranteed delivery transactions for a specific instance,

disconnect to end the instance of TContext. When you disconnect, TContext unregisters

the instance with the Job Manager.



Coding Client Applications and Services


After a client application disconnects all TContext instances, it should shutdown

guaranteed delivery for the process. The server handles this function when a service uses

guaranteed delivery. If your client application or service has active TContext instances

when the shut down occurs, the server throws an exception (unless the shutdown was

performed with the force option).

Sample Code

The code sample in this section is for a client application. Code for a service would be the

same, except omit the call to TContext.init to initialize guaranteed delivery and the call to

TContext.shutdown to shutdown guaranteed delivery; the server handles these functions

for a service.

The following table describes the steps you must include in a guaranteed delivery

application. The table is followed by sample code that shows the steps in a Java client.

# Step Description

1. Declare TContext Declare TContext as a variable.

2. Initialize TContext. Initialize TContext and specify the job store directory and audit-trail log. The Job Manager starts.

3. Instantiate TContext. Create a new TContext object.

4. Establish connectionattributes for theTContext instance.

Execute connect() to specify the B2B Integration Server on

which you want to invoke services using this context.

Note: Multiple threads can share an instance of TContext aslong as they use the same connection attributes—i.e. they usethe same B2B Integration Server and user ID/passwordestablished by that instance of TContext.

Use methods in the class Context to set other connection

attributes, such as, the protocol to use (HTTP or HTTPS) andthe proxy to use.

5. Start the transaction. Execute startTx() to obtain a transaction ID (tid) and specify

the transaction time-to-live (TTL).

6. Invoke the B2B service. Execute invokeTx() to invoke a B2B service.

Note that you pass the transaction id (tid) as the first parameter to this method.

7. End the transaction. Execute endTx() to end the transaction. This method clears

the record for this transaction from the Job Manager's job store.

8 Check for errors. Check for the different types of errors. Always check for ServiceExceptions last.

9. Disconnect from B2BServer.

Execute disconnect to end the use of this instance of

TContext. The application should not perform this step until it isdone because disconnect unregisters TContext with the Job

Manager.

10. Shutdown The Job Manager ends.





TContext tc = null;

// initialize TContext and establish connection attributestry {

TContext.init("./jobs", "./tx.log");

tc = new TContext();tc.connect("localhost:5555", null, null);

} catch (ServiceException e) {System.err.println("Error: "+e.getMessage());System.exit(-1);

}

// do work with TContext - get tid, call service, end tidtry {

String tid = tc.startTx(3);Values out = tc.invokeTx(tid, "wm.server", "ping", new

Values());System.out.println("out="+out.toString());tc.endTx(tid);

} catch (TXException e) {System.err.println("Job Failed: "+e.getMessage());System.exit(-1);

} catch (DeliveryException e) {System.err.println("JobMgr Disabled: "+e.getMessage());System.exit(-1);

} catch (AccessException e) {System.err.println("Access Denied: "+e.getMessage());System.exit(-1);


}

// release connection and shutdowntry {

tc.disconnect();TContext.shutdown();


2

34

56

7

910

1

8

For additional information about TContext and its methods, see the TContext class in the

online Java API at webmethods\developer3\doc\api\index.html.




C H A P T E R

Using WebTap

What is WebTap?.....................................................................176

Components of a WebTap Application.....................................176

How Does a WebTap Service Work?.......................................176

Creating a WebTap Service .....................................................178

Defining WebTap Rules ...........................................................179

Creating Before and After Services..........................................181

Creating a Customized WebTap Service.................................184

Invoking a WebTap Service from a Browser............................186



C H A P T E R 1 1 U s i n g W e b T a p


What is WebTap?

WebTap is a facility that acts as an intermediary between a browser-based client and a

Web server. You use it to build services that monitor HTTP requests and conditionally

execute a prescribed set of actions based on a URL requested by a client. WebTap allowsyou to build flexible, browser-based applications that combine manual and automated

interactions, by letting you filter HTTP requests—letting some requests “pass through” to

the target server and intercepting others for special handling.

When a browser makes a request for a WebTap service, all follow-on requests from that

client are channeled through the WebTap service. In this capacity, the WebTap service

serves as an agent, submitting HTTP requests on the client’s behalf. (To the target server,

WebTap appears as the client, not the original requestor).

Using WebTap provides the following benefits:

It allows you to intercept a request and take some action based on the URL or data for

that request.

It facilitates data-aggregation applications by routing all follow-on requests through a

single service, reusing the authentication and cookie context established during the

initial request.

It provides a vehicle through which multiple users can access a protected resource

through a common user account.

!One of the primary differences between a WebTap service and other B2B services is that a WebTapservice passes the requested HTML document (modified slightly to ensure that follow-on requestsget directed through the WebTap service) back to the client. It does not load and bind the documentto convert it to a Values object as regular B2B services do.

Components of a WebTap Application

A basic WebTap application consists of:

A browser-based client that invokes a WebTap service and passes a single variable

(reqUrl ) containing the URL of the requested resource. (Note that WebTap only

works with browser-based clients).

A WebTap service (constructed from the RelayHandler class) that optionally has a set

of “rules” associated with it defining URLs that, when submitted in reqUrl , triggers a

specified action.

How Does a WebTap Service Work?

The following describes the process that takes place when a WebTap service executes:



What is WebTap?


Step Description

1 WebTap receives the request and compares the URL (in reqUrl ) to the

“rules” associated with the service.

2 If the URL matches the criteria defined in a rule, the server checks to see

whether the rule specifies a “before” action (often one or more services). If so, that action is executed.

3 WebTap submits the request for the specified URL (note—if a before

action was executed, this URL may be different than the one originally

submitted by the client).

4 WebTap receives the response and remaps the hypertext links within it

(this ensures that all follow-on requests are routed back through the

WebTap service). For example, if the response contained the following

reference:

HREF="http://www.abc.com"

WebTap would replace that reference with:HREF="/invoke/Interface/Service?reqUrl=MapNum "

Where Interface/Service is the name of the WebTap service and MapNum

is an alias (dynamically generated by WebTap) for the actual URL

assigned to this reference.

5 WebTap checks to see whether the rule defines an “after” action (usually

one or more services) for reqUrl . If there is, that action is executed.

6 WebTap returns the HTML page (which could have been altered in the

previous step) to the client.

Guidelines for Using WebTapWhen creating WebTap services, keep the following points in mind:

If you want to build a pass-through service (i.e., one that simply relays HTTP

requests between a client application and a target server for the purpose of using

a common user account or maintaining a single B2B context), create a WebTap

service that contains no rules.

If you want to build an intercept service, (one that takes some action when it

receives a URL), create a WebTap service that includes a set of rules defining

what action you want WebTap to take when the client submits a particular URL.

WebTap allows you to specify the action you want the server to take before itsubmits the request to the target server and/or before it returns the response to

the client. You can interject an action (or a series of actions) at none, one, or

both of these points.





You can build a rule around a URL and/or a particular value in a name=value

argument.

You can use a standard pattern-matching string or a regular-expression to define a

URL and/or name=value argument that will trigger an action.

Creat ing a WebTap Service

A WebTap service is a Java service built around the RelayHandler class. The service calls

the “rules engine,” which processes the rules file (if there is one) associated with the

service. The rules file defines the criteria (triggers) that will cause specified services to

execute at run time.

You build WebTap services using the Developer. It provides the interface you use to

specify the rules for the service (i.e., it builds the rules file for the service) and generates a

source-code stub that makes up the body of the service.

Depending on what you want to do, the Developer allows you to start with:

A standard framework, which allows you to create a basic WebTap service based on

standard rules (i.e., rules that you can define using the Rules tab in the Developer).

Start with this framework when you want to create a service that does nothing more

than relay messages between the client and a target server and/or intercept requests

based on URL pattern-matching rules. (Note-you cannot disable the rules engine in

this type of service.)

A custom framework that lets you insert your own code in the service. Use this

framework when you want to incorporate custom logic directly in the WebTap

service and/or you need a finer level of control than the standard framework provides.

For example, you would use the custom framework if you needed to execute a block of code before applying the standard rules to a request (e.g., logging a transaction),

you wanted to apply a complex rule that could not be described using standard

WebTap rules (e.g., a condition that requires pattern matching and Boolean logic, for

example), or you wanted to selectively disable the rules engine.

The following procedure describes how to create a WebTap application using either

framework.

To create a standard WebTap application


10 Select WebTap Service and then click Next.



Next.



Defining WebTap Rules


12 Select the type WebTap service you want to create, then click Finish.

Set this option To create…

Standard A basic service that relays messages between abrowser and a target server and optionally intercepts

requests based on standard WebTap rules.Custom A custom WebTap service in which you can insert

your own Java code and define complex triggers.

13 If you want to trigger specific services before and/or after WebTap submits

a request to the target service, use the Rules tab to define a rule for each

reqUrl value that will trigger an action. See “Defining WebTap Rules” on

page 179 if you need procedures for this step.

14 If you selected Custom in step 4, add your code on the Source tab and

the Shared tab as needed. For additional information about creating

custom code, see “Creating a Customized WebTap Service” on page 184.

15 To test your service, select Run in Browser from the Test menu. The

Developer will prompt you for the value of reqUrl , launch your browser and

invoke the service.

!Although the Developer displays a Settings tab for a WebTap service, only a few of its

options should be used with WebTap. (The caching and stateless options must never be

used .) The following describes how to use the Settings options with a WebTap service

Option Description

Template Use this option only when a before service, an after service, or custom

code returns a Values object to the client instead of an HTML

document. See the rspVals variable in “Creating Before and After Services” on page 181 for information about returning a Values object

instead of HTML.

Runtime Do not use these options. Make sure they are all disabled.

Comment Use this option to provide comment information as needed.

Defin ing WebTap Rules

When you create a WebTap service, you can optionally define a set of “rules” specifying

actions you want the service to take if it receives a URL matching certain criteria.

A rule is comprised of:

− A pattern-matching string that describes a URL and/or a set of name=value

arguments.





− The name of the service you want WebTap to execute before it submits the request to

the target server, and/or…

− The name of the service you want WebTap to execute after it receives a response

from the target server.

You may define any number of rules for a WebTap service. If you define multiple rules,WebTap executes all rules matching the submitted URL.

The following procedure describes how to define a rule for a WebTap service. To use this

procedure, you must first open your WebTap service in the Developer and display the

Rules tab.

To define a WebTap Rule

1 In the Rules tab, click to add a new, unnamed rule to the rule list.

2 Select the new, unnamed rule in the list.

3 In the Rule Name field, type a name for the rule.

4 In the URL Match field, type a pattern-matching string describing the URL

that will trigger a before or after service.

− You can specify a pattern-matching string using standard wild-card

characters (see page 205 for allowed wildcards). The following

example would match requests for any resource on the www.rubicon

server.

Example: http://www.rubicon.*

–OR–

− Using a regular expression. When you use a regular expression, you

must enclose the entire pattern-matching string in / characters. The

following example would match any URL in which the string “rubicon”

appears anywhere.

Example: /.*rubicon.*/

See Appendix E for a description of the regular expression syntax.

5 If you want to match a particular set of name=value arguments for the

specified URL, use the following steps to describe the criteria for each

argument that you want to test.

1 Click to create an empty row in the Input Match list.

2 In the Input For dialog box, type the following information:


Name The name of the argument (i.e., the name portionof the name=value pair) that you want to test.



Creating Before and After Services


Pattern A pattern-matching string describing the valuethat will satisfy this rule.

3 Click OK.

4 Repeat steps 1-3 for each argument that you want to specifically

match. Keep the following points in mind when matching onarguments:

− When you specify multiple arguments in Input Match, the rule is

not satisfied unless all of them are true. (A Boolean AND is

implied.)

− If you specify an argument in Input Match, the rule is not

satisfied unless that argument appears in the request and it

meets the specified criteria.

− If you do not specify an argument in the Input Match list, any

form of the argument will satisfy the rule.

6 If you want this rule, when true, to trigger the execution of a service before

the requested URL is submitted, specify the name of that service in the

Service Before field.

7 If you want this rule, when true, to trigger the execution of a service after it

receives a request from the target server, specify the name of that service

in the Service After field.

Creat ing Before and After Services

Before and after services are triggered when a WebTap application receives a URL

matching a designated pattern. If the pattern (as specified in a WebTap rule) has a beforeservice associated with it, WebTap executes that service before submitting the request to

the target server. If the pattern has an after service associated with it, WebTap executes

that service after it receives a response from the target server but before returning the

response to the client. (See page 176 for an overview of the stages in the execution of a

WebTap service).

Any type of B2B service can be used as a before or after service—a flow service, a Java

service, a C/C++ service and so forth. In most cases, you will want the service to act upon

information available to the WebTap service at runtime. To do this, you must assign the

pub.webtap:triggerSpec specification to your service (this specification resides in the

WmPublic package). It defines the variables that WebTap makes available to before and

after services. You use these variables to read and/or modify data that is passed betweenthe client and the target server and to control the behavior of WebTap at run time.

For example, you can change the reqUrl variable in a before service, to reroute the

client’s original request to a different resource. (See “A Simple Rerouting Example” on

page 183 for an example of this technique.) You can also use the rspVals or rspTxt





control variable to “short-circuit” the WebTap process, and return a predefined set of

outputs to the client instead of passing the request to the target server.

The following table describes the specification of a WebTap service. Note that it is made

up of two records. WebtapData holds the data that passes between the client and the

target server. WebtapControl contains a set of control variables that you use to direct the

run time behavior of the WebTap service.


WebtapData A Values object containing the inputs to the service, including

reqUrl and data posted by the requestor or passed via a query string.

This object will contain one element for each argument submitted

with the request.

WebtapControl Contains the following elements that you use to control the run-time

behavior of WebTap.


reqUrl Specifies the URL of the requested resource

(as specified in pub.webtap:getPage). You can

modify this value in a before service to

redirect a request.

reqVals Specifies the set of substitute inputs to use

when redirecting request to a different URL.

rspUrl Set on response (read-only) if request was

redirected to indicate URL of returned page.

rspVals Contains a Values object to return to the

client. Setting this value will interrupt thenormal WebTap sequence and return this

Values object instead of the requested page

(if you set rspVals in a before service, the

client’s original request will not be

submitted to the target server by WebTap).

rspTemplate Specifies the name of the template to use to

format contents of rspVals. (This setting

overrides the template setting associated

with the service.)

rspTxt Contains an HTML document to return to

the client. Setting this value will interruptthe normal WebTap sequence and return this

document instead of the requested page (if

you set rspTxt in a before service, the

client’s original request will not be

submitted to the target server by WebTap).



Creating Before and After Services


authUser Specifies the HTTP authentication user

name that the service will use when

requesting a protected resource.

authPwd Specifies the HTTP authentication password

that the service will use when requesting a

protected resource.

authUrl Specifies the HTTP authentication url the

service will use when requesting a protected

resource.

mapImages Contains the string true or false,

specifying whether WebTap should map

URLs associated with images in the returned

document. (Set to false if images are not

password-protected).

Default is true.

mapPage Contains the string true or false,


URLs in the returned document. You may

set this element to false to exit a WebTap

service.

Default is true.

mapJavascript Contains the string true or false,


URLs embedded in javascript in the returned

document. (Note that this mapping handles

many common cases of dynamic javascript

url creation; however, it does not handledocument.write( ) and eval( ) blocks that

involve url definition.)

Default is false.

A Simple Rerouting Example

The following procedure describes the steps you would take to build a WebTap

application that intercepts requests for a particular URL and routes them to another URL.

Step Description

1. Create a new, empty flow service and assign the pub.webtap:triggerSpec specification to it(this specification resides in the WmPublic package). See “To assign an external

specification to a service” on page 50 if you need procedures for this step.

2. In the Flow Pane, insert a single MAP operation.





3. On the Pipeline Tab, use the modifier to set the value of WebtapControl/reqUrl in

Service In to the URL that you want to reroute the client request to.

4. Save the flow service.

5. Create a standard WebTap service.

6. Define one rule that matches the URL the client will request, and designate the flow

service you created in step 1–4 as the before service for that rule. See “To define a

WebTap Rule” on page 180 if you need procedures for this step.

7. Test this service and type a URL that matches the rule you specified in step 6. WebTap

will automatically reroute you to the URL specified in step 3.

Creat ing a Customized WebTap Service

If you want to build a WebTap service that executes a standard block of code before

applying any rules to the request or that requires trigger conditions that cannot be

described using WebTap’s pattern-matching rules, you can build a custom WebTap

service.

When you choose to start with the custom framework, the Developer gives you a source-

code stub that looks as follows. (Shaded areas show where the rules engine is called.

Rules associated with the service are evaluated at these points, and the appropriate before

and/or after services are executed.)



Creating a Customized WebTap Service


RelayIf WebTapCustom__ = new RelayIf(){

RelayHandler handler = new RelayHandler(this);NSName svcName = Service.getServiceEntry().getNSName();public Values relay(Session session, Values in)

{return handler.relay(session, in);

}

// Request Callback - Add your request triggers herepublic boolean relayRequest(Session session, Values in, String reqUrl)

throws Exception{

// your triggers

// rules engine (optional)if (handler.processRequestRules(svcName) == RelayHandler.DONT_CONTINUE)return false;

return true;}

// Response Callback - Add your response triggers herepublic boolean relayResponse(Session session, String doctxt, String rspUrl)

throws Exception{

// your triggers

// rules engine (optional)

if (handler.processResponseRules(svcName) == RelayHandler.DONT_CONTINUE)return false;

return true;}

};

out = WebTapCustom__.relay(Service.getSession(), in);

Example

The following code segment shows a WebTap service that logs an incoming request

before passing it to the rules engine.

RelayIf logApp__ = new RelayIf(){

RelayHandler handler = new RelayHandler(this);NSName svcName = Service.getServiceEntry().getNSName();

public Values relay(Session session, Values in){

return handler.relay(session, in);}

// Request Callback - Add your request triggers herepublic boolean relayRequest(Session session, Values in, String reqUrl)

throws Exception{

logRequest(svcName, handler, reqUrl);

// your triggers

// rules engine (optional)if (handler.processRequestRules(svcName) == RelayHandler.DONT_CONTINUE)return false;

return true;

}...

You can also use the custom framework to define your own set of rules (i.e., test for

certain conditions in the URL or user data) by inserting code at the appropriate trigger

points.

Add custom code and“before” tests here

Add custom code and“after” tests here

Code inserted to call alogging method





Example

The following code fragment shows a WebTap service that contains a custom trigger

(shaded) that executes a special block of code if reqUrl contains a specified string.

RelayIf WebTapCustom__ = new RelayIf(){

RelayHandler handler = new RelayHandler(this);NSName svcName = Service.getServiceEntry().getNSName();

.

.

.// Response Callback - Add your response triggers here

public boolean relayResponse(Session session, String doctxt, String rspUrl)throws Exception

{// checkout triggerif (reqUrl.indexOf(“secure_checkout.asp?chkout=yes”) > 0){

// intercept request and return contents to callert ry {

// invoke flow to extract contents and set alternate responsehandler.setAltResponse(Service.doInvoke(“sample.webtap”,”getcart”,

session,in),Compuse_retrieve”);} catch (Exception e) {

throw(e);}// return alternate response to callerreturn false;

}

// rules engine (optional)

if (handler.processResponseRules(svcName) == RelayHandler.DONT_CONTINUE)return false;

return true;}

};out = WebTapCustom__.relay(Service.getSession(), in);

For additional information about the WebTap API, see the RelayHandler class in the B2B

API located in webmethods/developer3/doc/api/index.html.

Invoking a WebTap Service f rom a Browser

You use the following URL to invoke a WebTap application from a browser.

http://serverName/invoke/Interface/Service?reqUrl=RequestedUrl

Where:

− ServerName is the name of the B2B Integration Server on which the service resides.

− Interface is the name of the interface in which the service resides.

− Service is the name of the WebTap service.

− RequestedUrl is the URL of the requested resource. This part of the string must be

URL-encoded!

Example

http://rubicon/invoke/Admin/Orders?reqUrl=http%3A%2F%2Fwww.ABCSupplies.com



Invoking a WebTap Service from a Browser





A P P E N D I X

webMethods Flow Operations

BRANCH .................................................................................190

EXIT.........................................................................................192

INVOKE...................................................................................194

LOOP ......................................................................................195

MAP.........................................................................................197

REPEAT ..................................................................................198

SEQUENCE ............................................................................201



APPENDIX A webMethods Flow Operations


BRANCH

The BRANCH flow operation selects and executes a child operation based on the value of

a specified field (referred to as the switch field) in the pipeline. You specify the switch

field in the Switch property of the BRANCH operation.

The BRANCH flow operation executes the child operation that has the same label as the

value of the Switch property.

If you want to execute a child operation when the value of the Switch property is an empty

string, leave the label property of the child operation blank. If you want to execute a child

operation when the Switch property is a null or unmatched string, set the label of the child

operation to $null or $default.

BRANCH Flow Operation

Name of theswitch field is

choice

if the value of choice is 'Name1'Name1

∙

∙

∙

Otherwise

Name2

NameN

*

if the value of choice is 'Name2'

if the value of choice is 'NameN'

Properties

The BRANCH operation has the following properties.

comment

Optional. Specifies a descriptive comment for the operation.

scope

Optional. Specifies the name of a record in the pipeline to which you want to restrict this

operation. If you want this operation to have access to the entire pipeline, leave this field

blank.

timeout

Optional. Specifies the maximum number of seconds that the operation should run. When

the time is exceeded, the operation stops and raises an exception. However, if this

operation contains an INVOKE operation, the INVOKE operation is not interrupted when

the timeout value is exceeded. Instead, the exception is raised after the INVOKE is

complete.



BRANCH


If you do not want to specify a timeout period, set timeout to zero or leave it blank.

label

Optional. (Required if you are using this BRANCH operation as a target for another

BRANCH or EXIT operation.) Specifies a name for this instance of the BRANCH

operation, or a null, unmatched, or empty string ($null, $default, blank).

switch

Required. Specifies the name of the string variable in the pipeline that the BRANCH

operation uses as the switch field to determine which child operation is executed at run

time.

Conditions That Will Cause a BRANCH Operation to Fail

— The switch field is not in the pipeline.

— The matching child operation fails.

— The BRANCH flow operation does not complete before the timeout period expires.





EXIT

The EXIT operation exits the entire flow service or a single flow operation. Specifically, it

may exit from the nearest ancestor loop operation, a specified ancestor operation, the

parent operation, or the entire flow service.

The EXIT operation can throw an exception if the exit is considered a failure. When an

exception is thrown, user-specified error message text is displayed.

Properties

The EXIT operation has the following properties.

comment


scope



blank.

timeout





complete.


label

Optional. (Required if you are using this EXIT operation as a target for a BRANCH

operation.) Specifies a name for this specific operation, or a null, unmatched, or empty

string ($null, $default, blank).

from

Required. Specifies the flow operation that you want to exit from.

This value… Specifies to exit the…

$loop Nearest ancestor LOOP or REPEAT flow operation.

$parent Parent flow operation, regardless of the type of operation.

$flow Entire flow.



EXIT


This value… Specifies to exit the…

label Nearest ancestor flow operation that has a label thatmatches this value.

Note If the label you specify does not match the labelof an ancestor flow operation, the flow will exit with anexception.

signal

Required. Specifies whether the exit is to be considered a success or a failure. A SUCCESS

condition exits the flow service or operation. A FAILURE condition exits the flow service

or operation and throws an exception. The text of the exception message is contained in

the failure-message property.

failure-message

Optional. Specifies the text of the exception message that is displayed when signal is set to

FAILURE.

Examples of When to Use

— Exit an entire flow service from within a series of deeply nested operations.

— Throw an exception when you exit a flow or a flow operation without having to write

a Java service to call Service.throwError( ).

— Exit a LOOP or REPEAT flow operation without throwing an exception.





INVOKE

The INVOKE flow operation invokes another service. You can use it to invoke any type

of B2B service, including another flow service.

Properties

The INVOKE operation has the following properties.

comment


scope



blank.

timeout


the time is exceeded, the operation stops and raises an exception. However, the INVOKE

operation is not interrupted when the timeout value is exceeded. Instead, the exception is

raised after the INVOKE is complete.


label

Optional. (Required if you are using this operation as a target for a BRANCH or EXIT



service

Required. Specifies the fully-qualified name of the service to invoke.

Conditions That Will Cause an INVOKE Operation to Fail

— The service that is invoked fails.

— The specified service does not exist.

— The specified service is disabled.



LOOP


LOOP

The LOOP flow operation takes as input an array variable that is in the pipeline. It loops

over the members of an input array, executing its child operations each time through the

loop. For example, you have a service that takes a string as input and a string list in the pipeline. Use the LOOP operation 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 flow operation. You can also designate a single variable for output. The LOOP

flow operation 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 record that contains the fields you want to collect for the output

variable.

The LOOP Operation

No

Yes

more inputarray

members?

get nextmember of input array

input isan array

child∙∙∙

child child

Properties

The LOOP operation has the following properties.

comment


scope



blank.

timeout





complete.






label




in-array

Required. Specifies the input array over which to loop. You must specify a variable in the

pipeline that has an array data-type; that is, string list, string table, record list, or object

list.

out-array

Optional. Specifies the name of the output variable. The value of this variable is collected

each time through the loop and placed in an output array of this name. You do not need to

specify this property if the loop does not produce output values.

Conditions That Cause Failure

— The pipeline does not contain the input array.

— The input variable is not an array variable.

— A child operation of the LOOP operation fails during any iteration of the loop.

— The LOOP flow operation does not complete before the timeout period expires.



MAP


MAP

The MAP flow operation adjusts the pipeline at any point in a flow . It makes pipeline

modifications that are independent of an INVOKE operation.

Within the MAP operation, you can:

— Map (copy) the value of a pipeline input variable to a new or existing pipeline output

variable.

— Drop an existing pipeline input variable. (Keep in mind that once you drop a variable

from the pipeline, it is no longer available to subsequent services in the flow.)

— Assign a value to a pipeline output variable.

Properties

The MAP operation has the following properties.comment

Optional. Specifies a descriptive comment for this operation.

scope



blank.

timeout

Optional. Specifies the maximum number of seconds that this operation should run. When




complete.


label




Example of When to Use

You want to assign an initial set of input values in a flow service (i.e., initialize variables).

You insert the MAP operation at the beginning of the flow, and then use the Set Value

modifier to assign values to the appropriate variables in Pipeline Out.

REPEAT

The REPEAT flow operation repeatedly executes its child operations up to a maximum

number of that you specify. It determines whether to re-execute the child operations based

on a repeat on condition. You can set the repeat condition to one of the following:

— Repeat if any one of the child operations fail

— Repeat if all of the elements succeed

You can also specify a back-off time period that you want the REPEAT flow operation to

wait before it re-executes its child operations.

The REPEAT Operation

child ···

count < max.retries?

Waitback-off

time Yes No

count = count + 1

REPEAT fails

repeatcondition

met?Yes

childchild

No

count = 0count < max.

retries?REPEAT fails

Properties

The REPEAT operation has the following properties.

comment


scope


operation. If you want this operation to have access to the entire pipeline, leave this field blank.

timeout

Optional. Specifies the maximum number of seconds that this operation should run. When



REPEAT



complete.


labelOptional. (Required if you are using this operation as a target for a BRANCH or EXIT



count

Required. Specifies the number of times the REPEAT operation will re-execute its child

operations. A REPEAT flow operation is most useful when you specify a number that is

two (2) or greater. If you specify zero (0), the REPEAT flow operation does not execute

its child operations at all. If you specify one (1), the REPEAT operation executes its child

operations only one time; this is equivalent to a SEQUENCE operation.

If you want the children re-executed as long as the specified repeat-on condition remains

true (i.e., no maximum limit), set this value to –1.

backoff

Optional. Specifies the number of seconds to wait between attempts to execute the child

operations. Specify zero (0) to re-execute the child operations without a delay.

repeat-on

Required. Specifies the condition that causes the REPEAT flow operation to re-execute its

child operations. Specify one of the following:

FAILURE The REPEAT flow operation re-executes the child operations if any of the child operations fail. This is the default.

SUCCESS The REPEAT flow operation re-executes the child operations if allof the child operations succeed.


— After looping the maximum number of times, the repeat-on condition still indicates that

the child operations need to be re-executed.

— The REPEAT flow operation does not complete before the timeout period expires.

Examples of When to Use

• Repeat-on condition set to FAILURE

You have a service that attempts to access a Web site. The service might fail because

the Web site is too busy, but if you continue to retry, it might eventually succeed. You

make the service that accesses the Web site a child element of a REPEAT flow





operation. You then set the repeat-on condition to FAILURE. If the service attempts to

access the Web site and it fails, the REPEAT flow operation attempts to retry the

service again. You also set a back-off time that causes the REPEAT flow condition to

wait a period of time before invoking the service again.

• Repeat-on condition set to SUCCESS

In a Web-automation service, you want to repeat a load and query operation as long as

a “Next Page” button exists in the current document, indicating that there are

additional pages to be processed. You implement a REPEAT flow operation, ending

the loop when the query operation “fails” to retrieve a “Next Page” button in the

current document.



SEQUENCE


SEQUENCE

The SEQUENCE operation forms a collection of child operations that execute

sequentially. This is useful when you want to group a set of operations as a target for a

BRANCH operation.

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 operation fails. Use this condition when you want to ensure

that all child operations are completed successfully. If any child operation fails, the

sequence ends prematurely and the sequence fails.

Exit the sequence when a child operation 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

operation succeeds, the sequence ends prematurely and the sequence succeeds.

Exit the sequence after executing all child operations. Use this condition when you want to

execute all of the child operations regardless of their outcome. The sequence does not

end prematurely.

The SEQUENCE Operation

child ∙∙∙ childchild

First…If exit conditionis not met…

If exit conditionis not met…

Properties

The SEQUENCE operation has the following properties.

comment


scope



blank.

timeoutOptional. Specifies the maximum number of seconds that this operation should run. When




complete.






label




exit-on

Required. Indicates whether the SEQUENCE flow operation should exit the sequence

prematurely, and if so, under what condition it should exit. Specify one of the following:

FAILURE Exit the sequence when a child operation fails.

The SEQUENCE operation executes its child operations until either one fails or until it executes all its child operations. This is the default.

SUCCESS Exit the sequence when a child operation succeeds.

The SEQUENCE operation executes its child operations until either one succeeds or until it executes all its child operations.

DONE Exit the sequence after executing all child operations.

The SEQUENCE operation executes all of its child operationsregardless of whether they succeed or fail.


This section describes the conditions that cause failure based on the exit condition for the

sequence.

If exit-on is set to FAILURE, conditions that will cause a failure include:

— One of the child operations fails.

— The SEQUENCE flow operation does not complete before the timeout period expires.

If exit-on is set to SUCCESS, conditions that will cause a failure include:

— All the child operations fail.


If exit-on is set to DONE, conditions that will cause a failure include:





A P P E N D I X

webMethods Query Language

Object References...................................................................204

Object Properties .....................................................................207

Property Masking.....................................................................207

APPENDIX B webMethods Query Language



The webMethods Query Language (WQL) provides the primary mechanism for mapping

data from Web documents. When a Web document is read by webMethods, the XML or

HTML markup within the document is used to parse the contents of the document into theobject model.

XML and HTML markup both consist of tag elements enclosed in angle brackets: < >. In

the process of parsing, tag elements are transformed into arrays of objects; the attributes of

tag elements become object properties. XML and HTML markup both implement

containing elements and empty elements. Containing elements have open and close tags.

Empty elements are single tags.

When a Web document is parsed, the text contained within containing elements becomes

the text property of the corresponding document object.

Data parsed from Web documents is accessed with WQL queries, which consist of one or

more indexed element arrays and an object property.

Object ReferencesFor the following object references, x and y represent numerical indexes.

doc.element [ x ]. property

An absolute reference uses a numerical index into an element array.

doc.element [ x ].element [ x ]. property

Nested element arrays scope the object reference to children elements.

doc.element [ x ].line[ x ]. property

An array of lines is fabricated when the text property of a document object contains line

breaks.

doc.element [ x ].^. property

The parent of an element is referenced with ^.

doc.element [x].?[x]. property

A ? matches any type of element array.

doc.element []. property

Empty brackets signify that all members of an element array are to be returned.

doc.element |element []. property

The | is used to signify a logical 'OR'. The contents of two or more element arrays can be

returned.

doc.element [ x-y ]. property

Returns a range of elements from an array.

doc.element[x-end].property





end is a reserved word that returns the final element of an array.

doc.element [ x,y,z ]. property

Returns items x, y, and z where x, y, and z represent numerical indexes into an element

array.

doc.element [ x+y ]. property

Returns element x and every y element thereafter.

doc.element ['match']. property

Returns an array of elements whose text property matches the match string, which can

contain the following wildcard characters:

Use this Character… To…

* Match any sequence of zero or more characters

? Match any single character.

% Matches a single word, where word is defined to be any sequence of non-whitespace characters

\ Escape any of the above wildcards characters.

Match strings are compared with the .text property of the indexed object. The .text property contains the text of all child objects.

doc.element [/RegularExpression /]. property

Returns an array of elements whose text property matches the specified regular expression.

For information about how to construct a regular expression, see “Regular Expressions”

on page 287.

doc.element ( property ='match' ). property

Matches on the value of a specific element property.





Sibling Operators

WQL provides the following set of operators to refer to siblings of a specified element.

The examples shown in these descriptions refer to the following HTML structure:

TABLE

TR

TD

B

I

B

TD

I

B

B

Siblings (elements belonging to the same parent)

Bold 0

Italic 0

Bold 1

B Bold 2

I

Bold 3

Italic 1

Bold 4Italic 2

The sibling operators are constrained by the current parent. If an operator exceeds the

boundaries of the current parent, a null value is produced for that reference.

doc.element [x].@n. property

References the nth sibling after element [ x], regardless of type. Compare with

doc.element [x].+n. property, below.

Example Result

doc.td[0].b[0][email protected] Italic 0

doc.td[0].i[0][email protected] Bold 1

doc.td[0].b[0][email protected] Null

doc.element [x].@-n. property

References the nth sibling prior to element [ x], regardless of type. Compare with

doc.element [x].-n. property, below.

Example Result

doc.td[1].b[end][email protected] Bold 3

doc.td[1].i[end][email protected] Bold 4

doc.td[1].b[end][email protected] Null

doc.element [x].+n. property

References the nth sibling after element [ x] that is of the same type as element [ x]. Compare

with doc.element [x].@n. property, above.





Example Result

doc.td[0].b[0].+1.text Bold 1

doc.td[0].i[0].+1.text Null

doc.td[0].b[0].+3.text Null

doc.element [x].-n. property

References the nth sibling before element [ x] that is of the same type as element [ x].

Compare with doc.element [x].@-n. property, above.

Example Result

doc.td[1].b[end].-2.text Null

doc.td[1].i[end].-1.text Italic 1

doc.td[1].b[end].-3.text Null

Object PropertiesIn addition to the properties derived from the attributes of a parsed XML or HTML tag

element, the following properties are available for all objects:

.text/.txt

Returns the text of an object.

.value/.val

Returns the value of an object. (Equivalent to the text of the object if the element has no

VALUE attribute.)

.source/.src

Returns the XML or HTML source of an object.

.index/.idx

Returns the numerical index of an object.

.reference/.ref

Returns a complete object reference.

Property MaskingProperty masking allows for the stripping away of unwanted text from the value of an

object property.doc.element [ x ]. property [ x-y]

Returns a range of characters from position x to y.

doc.element [ x ]. property ['mask ']

Uses wildcard matching and token collecting to extract desired data from the value of an

object property.





doc.element [ x ]. property [/RegularExpression /]

Uses a regular expression to extract desired data from the value of an object property. For

information about how to construct a regular expression, see “Regular Expressions” on

page 287.




A P P E N D I X

Built- In Services

Client Services......................................................................... 210

Date Services .......................................................................... 220

Database Services .................................................................. 224

Flow Services .......................................................................... 236

Ldap Services..........................................................................240

Math Services..........................................................................247

Record Services ......................................................................251

Remote....................................................................................254

Report Services.......................................................................256

String Services ........................................................................259

Table Services.........................................................................266

Web Services ..........................................................................268

WebTap Services and Specifications ......................................282



APPENDIX C Built-In Services


Cl ient Services

You use the client services to formulate and submit requests to HTTP, FTP and SMTP servers.

pub.cl ient:ftp

Description Executes the following sequence of FTP actions:

1. Logs on to an FTP server

2. Changes to a specified working directory

3. Performs one of the following FTP commands: ls, put or get

4. Logs off the FTP server.

Input Variable Name Description

serverhost Name or IP address of the FTP server.

Example ftp.netscape.com

serverport Port number of the FTP server.

Example 4566

username Valid FTP user of the remote FTP server.

Example anonymous

password Valid password of the FTP user.

command One of the following FTP commands: ls, put or get.

dirpath Working directory of the FTP server.

Example pub

transfertype One of the following FTP data transfer modes. passive or active

transfermode One of the following FTP file transfer modes: ascii or binary

content Data to be transferred when command is set to put.

localfile When command is set to put, this value specifies the name of the local file you

want to transfer. (If the content is not null, this field is ignored.)

When command is set to get, this variable specifies the name of the local file

in which you want to the retrieved content saved.

remotefile When command is set to put, this value specifies the name of the remote file in

which you want the save the data you are sending.

When command is set to get, this variable specifies the name of the remote file

that you want to retrieve.Output Variable Name Description

command The FTP command that was executed (ls, get or put).

localfile The name of the local file used for a get or put operation.

remotefile The name of remote file name used for a get or put operation.



Client Services


content If localfile was not specified, this variable will contain the Content object sent to

the remote server (if a put command was executed) or received from the remote

server (if a get command was executed).

dirlist A String array containing the list of file names returned by the ls command.

returncode Standard FTP protocol return code.

returnmsg Standard FTP protocol return message.

logmsg FTP log messages.

pub.cl ient:http

Description Issues an HTTP request that you specify and returns the HTTP response (headers and data).

Input Variable Type Description

url String Specifies the URL of the document you want to access. This string

must begin with http: or https:


method String Specifies the HTTP method you want to use. You must set method toeither get or post.

auth

(optional)

Values Specifies authorization information that the http service will submit if

the resource specified in url is protected.

Element Type Description

type String Type of authentication you want the http

service to use when it submits this

request.

Currently, only basic authentication is

supported. If you are accessing a

protected resource, set auth to Basic.

user String The user name loadDocument willsubmit when requesting a protected

resource.

pass String The password associated with user .

headers

(optional)

Values Specifies fields that you want to explicitly override in the HTTP

request header issued by the http service.

Specify one element in the headers Values object for each header field

that you want to set, where:

− The element’s name represents the name of the header field, and…

− The element’s value represents the value of that header field.

If you do not set headers, the http service will use its default header

values.

data

(optional)

Values Specifies data that you want the http service to submit with the HTTP

request.

Specify your data in one of the following elements.

Name Type Description





args Values Specifies name=value pairs that you want

the http service to submit to the resource

in url.

You can use args to submit data via either

the POST or GET method.

To specify data using args, create oneelement for each name=value pair that

you want to submit, where:

− The element’s name represents the

name portion of the pair, and…

− The element’s value represents the

value portion of the pair.

Note that when you use args, the http

service will:

− automatically url-encode

name=value pair, so you do not need

to url-encode the values you specify

in args.

− automatically insert the “&”

character between pairs, so you do

not need to include it in args.

− automatically prefix the entire query

string with the “?” character if it

submits the data in args via a GET.

You do not need to include this

character in args.

string String Specifies a string of text that you want


in url.

You can use string to submit data via

either the POST or GET method.

If you use string to submit data, make

sure that you specify the string exactly as

you want it presented in the HTTP

request. (If you are using the GET

method, make sure you url-encode the

contents of string )

bytes bytes[ ] Specifies an array of bytes that you want


in url .

You can only use bytes to submit data via

the POST method.



Client Services


table String[ ][ ] Specifies data that the http service will

use to construct a query string to submit

to the resource specified in url.

table is similar to args, but it allows you

to submit unnamed values in a query

string, not just name=value pairs.To specify data using table, create one

row for each value that you want to

submit, where:

− The contents of column 0 represents

the name portion of the pair (leave

this column null to submit an

unnamed value, and…


the value portion of the pair.

Note that when you use table, the http

service will:




in table.


character between the pairs (or

unnamed values) that it constructs,

so you do not need to include it in

table.



submits the data in table via the

GET method. You do not need to

include this character in table.

loadAs String Specifies the form in which you want the http service to store the

returned document.

Set loadAs to… To…

bytes Store the returned document as a byte array.

Use this option if the document will be used

as input to a service that operates on whole

documents (for example, queryDocument).

stream Store the returned document as an input

stream.Use this option if the document will be used

as input to a service that can process a

document incrementally (for example,

getNodeIterator).

Output Variable Type Description

header Values Contains a Values object that represents the HTTP response header.





Variable Type Description

lines Values Each entry of the Values object

represents a field (line) of the response

header. The entry’s name is the field

name, and the entry’s value is the value

of the field. status String Status code of the response.

statusMessage String Status message of the response.

body byte[ ] Contains the HTTP response data.

pub.cl ient:smtp

Description Sends a MIME-type email message. You may attach one or more content objects or files to the

message.


to Receiver’s email address. If you specify multiple addresses, separate them with

commas.

cc Additional receiver’s email addresses. If you specify multiple addresses,

separate them with commas.

bcc Additional receiver’s email addresses. If you specify multiple addresses,

separate them with commas.

subject Subject of the message.

from Sender’s email address.

mailhost The SMTP host name for outbound messages (e.g. smtp.webMethods.com).

body Comments (text string) about the content.

attachments Attachments of the message. Each attachment is defined as a message part in a

multi-part message.


contenttype MIME type of the message, e.g. application/x-edi-

message

content Content of the message of type byte[ ], String, or

java.io.InputStream.

encoding Encoding of the message, e.g. base64 or 7bit.

filename Name of a local file to be attached to the message. Used

only when content is null.

Output Variable Name Description

status List of files being deleted in the format of a String array.

pub.cl ient. ftp:cd

Description Changes the current working directory during an FTP session (corresponding to the standard FTP user

command cd dirpath). Variables in the input and the output Values object are type String.


dirpath The working directory of the FTP server, e.g., pub.



Client Services





logmsg FTP log messages for the entire user session.

pub.cl ient. ftp:cdls

Description Changes the current working directory and retrieves the file list during an FTP session (corresponding

to the standard FTP user commands cd dirpath and ls namepattern). All fields in the input

and the output Values object are type String, except dirlist , which is type String[].


dirpath The working directory of the FTP server, e.g., public.

filenamepattern A pattern that specifies the file names of the files to retrieve, e.g., *.txt.


dirlist The list of file names in the format of a String array.



logmsg FTP log messages.

pub.cl ient. ftp:delete

Description Deletes a file in the current working directory on an FTP server (corresponding to the standard FTP

user command delete somefile). All fields in both input and output Values object are type

String.


filename The names of the files to be deleted from the current working directory, e.g.,

text.txt. If you use pattern-matching characters in filename, multiple files

will be deleted.





pub.cl ient. ftp:get

Description Retrieves a file from a remote ftp server (corresponding to the standard FTP user command get). All

fields in the input and output Values object are type String, except content , which is type byte[].


transfermode The FTP file transfer mode; specify either ascii or binary.

localfile The name of a local file where the content is saved. This field is optional.

remotefile The name of the remote file.









content The data content that was retrieved by the get command.

pub.cl ient. ftp:login

Description Connects to a remote FTP server and logs in with a specified user name and password. You must usethis service to initiate an FTP session before you can use other services within pub.client.ftp.

All fields in the input and the output Values objects are type String.


serverhost The name or IP address of the FTP server, e.g., ftp.netscape.com.

serverport The port number on which the FTP server listens for requests, e.g., 4566. The

default is 21.

dataport Optionally, the listener port number of the data transfer channel, e.g., 3345. If

you do not specify dataport, the B2B Integration Server will choose the listener

port number. This value is only used when transfertype is active.

username A valid FTP user on the remote FTP server, e.g., anonymous.

password A valid password for the FTP user specified in username, e.g.,someone@somewhere.

transfertype The type of the FTP data transfer mode. Specify either passive or active.





pub.cl ient. ftp:logout

Description Logs out of the current FTP session.


name Reserved





pub.cl ient. ftp:ls

Description Retrieves the file list during an FTP session (corresponding to the standard FTP user command ls

namepattern). All fields in the input and the output Values object are type String, except dirlist ,

which is type String[].


filenamepattern A pattern that specifies the file names of the files to retrieve, e.g., *.txt.


dirlist The list of file names in String array format.




Client Services




pub.cl ient. ftp:mdelete

Description Deletes multiple files in the current working directory on an FTP server (corresponding to the standardFTP user command mdelete pattern). All fields in both input and output Values object are type

String.


filenamepattern A pattern that specifies the file names of the files to be deleted from the current

working directory, e.g., *.txt. If you do not specify a value for

filenamepattern, all files in the current working directory are deleted.





pub.cl ient. ftp:mget

Description Transfers multiple files from the remote FTP server (corresponding to the standard FTP user command

mget). All fields in the input and output Values object are type String, except filenames which is type

String[].



localdirpath The directory in the local file system where you want the remote files to be

saved, e.g., c:\temp\ftpfiles.

filenamepattern A pattern that specifies the file names of the files to be transferred, e.g., *.txt.

Output Variable Name Description filenames The list of files being transferred from the remote FTP server.




pub.cl ient. ftp:mput

Description Transfers multiple files to a remote ftp server from the local B2B Integration Server (corresponding to

the standard FTP user command mput). All fields in the input and output Values object are type

String, except filenames is type String[].


transfermode The FTP file transfer mode, either “ascii” or “binary”.

localdirpath The directory in the local file system that contains the files you want to transfer

to the remote FTP server, e.g., c:\temp\ftpfiles.

filenamepattern A pattern that specifies the file names of the files to be transferred, e.g., *.txt.


filenames The list of files being transferred to or from remote FTP server.








pub.cl ient. ftp:put

Description Transfers a file to a remote ftp server from the local B2B Integration Server (corresponding to the

standard FTP user command put). All fields in the input and output Values object are type String,

except content , which is type byte[].



content The data content to be transferred with the put command.

localfile The name of a local file that you want transferred with the put command when

you do not specify a value for content; that is, if content is null. If you specify a

value for content, this field is ignored.

remotefile The name of the remote file.







Client Services






Date Services

You use the date services to generate and format date values.

Many of these services require you to specify pattern strings describing the data’s current format and/or the format to

which you want it converted. For services that require a pattern string, you use the following symbols in the

following table to describe the format of your data.

For example, to describe the format of a date in January 15, 1999 format, you would use the pattern string MMMMM dd,

yyyy.

To describe the format of a date in 01/15/99 format, you would use the pattern string MM/dd/yy.

Symbol Meaning Presentation Example

G era designator Text AD

y year Number 1996

M month in year Text & Number July & 07

d day in month Number 10

h hour in am/pm (1-12) Number 12

H hour in day (0-23) Number 0

m minute in hour Number 30

s second in minute Number 55

S millisecond Number 978

E day in week Text Tuesday

D day in year Number 189

F day of week in month Number 2 (2nd Wed in July)

w week in year Number 27

W week in month Number 2

a am/pm marker Text PM

k hour in day (1-24) Number 24

K hour in am/pm (0-11) Number 0

z time zone Text Pacific StandardTime

' escape for text Delimiter

' ' single quote Literal '



Date Services


pub.date:currentDate

Description Returns the current date in a specified format.


pattern A pattern string representing the format in which you want the date returned.Output Variable Name Description

value The current date in the format of pattern.

pub.date:dateBuild

Description Builds a date/time string using the specified pattern and the specified date elements.


pattern A pattern string representing the format in which you want the date returned.

year String representation of an integer year, yyyy or yy.

month String representation of an integer month. month value is 1-based, e.g., “1” for

January.dayofmonth String representation of an integer day of month. dayofmonth value is 1-based.


value A string that represents the date specified by year , month, and dayofmonth, in

the format of pattern.

Usage Notes If pattern is null, dateBuild returns null.

If a date element is null or invalid, dateBuild uses the element value at the time the service is invoked

pub.date:dateTimeBuild

Description Builds a date/time string using the specified pattern and the specified date elements.


pattern A pattern string representing the format in which you want the time returned.

year String representation of an integer year, yyyy or yy.

month String representation of an integer month. month value is 1-based, e.g., “1” for

January.

dayofmonth String representation of an integer day of month. dayofmonth value is 1-based.

hour String representation of the hour, based on a 24-hour clock.

minute String representation of the minute.

second String representation of the second.

millis String representation of the milliseconds.


value A string that represents the date specified by the date and time elements in the

format of pattern.





Usage Notes If pattern is null, dateTimeBuild returns null.

If a date element is null or invalid, dateTimeBuild uses the element value at the time the service is

invoked.

If a time element is null or invalid, dateTimeBuild uses “0”.

pub.date:dateTimeFormat

Description Converts a date/time string from one format to another.


inString String containing a date or time.

currentPattern Current format of inString , using time formatting syntax.

newPattern Desired format for inString , using time formatting syntax.


value A string representing the date/time given by inString , in the format of

newPattern



Date Services






Database Services

You use the database services to access JDBC-enabled databases.

pub.db:cal l

Description Invokes a stored procedure on a target database.


$dbAlias The alias of the database on which you want to execute the stored procedure.

$dbProc The name of the stored procedure.

$data Optionally, parameter values for the stored procedure.


updateCount The update count (if any) from the stored procedure.

results The result set (if any) from the procedure (class is com.wm.util.Table).

rowCount The number of rows in the result set.

Usage Notes The output will also contain output parameters and procedure return values, keyed name (the returnvalue is called RETURN_VALUE).

pub.db:clearTransaction

Description Clears transactional state within a database connection.


$dbAlias The alias of the database connection on which you want to clear transactional

state.


$dbMessage A message indicating the success or failure of the operation.

Usage Notes On some databases, exceptional conditions within transactions will automatically abort the entiretransaction. When this happens, the standard commit/rollback operations are meaningless because

there is no current transaction. If this occurs, use the clearTransaction service to clear the transactional

state and prepare for a new transaction. You should only use this service if you have begun a

transaction and cannot end it with a standard commit or rollback.

The clearTransaction service does not involve a database operation; it is entirely internal to the B2B

Integration Server.

pub.db:close

Description Closes a specified database connection.

Input You may specify the connection parameters in one of the following ways:

$dbAlias – OR –

$dbURL, $dbUser , $dbPass, $dbDriver

– OR –

$dbConnection


$dbAlias A database alias.



Database Services


$dbURL JDBC URL that identifies the database resource.

$dbUser User name to use to log into the database.

$dbPass Password for the user.

$dbDriver Name of JDBC driver to use (optional).

$dbConnection The connection object.Output Variable Name Description


pub.db:closeAll

Description Closes all database connections that the session has opened.

Input none



pub.db:commitDescription Commits changes to a database


$dbAlias The alias of the database on which you want to commit changes.



Usage Notes This service returns an exception if an error occurs when committing changes to the database. The

most common reason for this error is that no transaction has been started (see pub.db.startTransaction).

pub.db:connect

Description Creates a connection to the database using the supplied JDBC URL, user name, and password. You

can also specify a JDBC driver specific to the database.


$dbAlias

– OR –









$dbConnection The connection object.





pub.db:delete

Description Removes all rows in the specified table that meet the given criteria.


$dbAlias

– OR –


– OR –

$dbConnection








$dbCatalog Name of the database’s system catalog. Include this parameter if your DBMS

supports distributed databases and you want to delete rows from a table that is

not in the database to which you are connected.

If you are not using a distributed database system or if you want to delete rows

from the database to which you are connected, you do not need to specify this

parameter.

If you are running against DB2, use this parameter to specify the database

location.

$dbSchemaPattern Name of the schema to which the table belongs.

If your database supports pattern-matching on schemas, you may specify the

schema name with a pattern-matching string, where _ represents a single

character and % represents any string of characters. For example, the value

HR% would represent any schema beginning with the characters HR.

If you are running against DB2, you use this parameter to specify the table’s

AuthID.

$dbTable Name of table to remove rows from.

$data Values object with criteria that the rows to delete must meet.

! If no criteria are provided, all rows are deleted from the table.


$updateCount Number of rows deleted.

pub.db:execSQL

Description Executes the specified SQL statement. The service does not perform any parsing on the SQL

statement.






$dbCatalog The name of the database’s system catalog. Include this parameter if your

DBMS supports distributed databases and you want to retrieve a list of

stored procedures from a database other than the one to which you are

connected.

If you are not using a distributed database system, you do not need tospecify this parameter.


location.

$dbSchemaPattern The name of the schema to which the stored procedures belong.





If you are running against DB2, you use this parameter to specify the stored

procedure’s AuthID.

$dbTable The name of the table to which the procedures belong.

$dbProcNamePattern A pattern-matching string that specifies the procedures that you want

included in the returned list, where _ represents a single character and %

represents any string of characters. For example, the value DATE% would

represent any procedure beginning with the characters DATE.

Output A Values object containing a set of variables whose keys represent the names of stored procedures

matching the input criteria. Each element in the Values object is itself a Values object that contains

information about the stored procedure. For specific information about what information is supplied by

your database, see java.sql.DatabaseMetaData.getProcedures in your JDBC documentation.

pub.db:getProcInfo

Description Retrieves information about one or more stored procedures.Input Variable Name Description

$dbCatalog Name of the database’s system catalog. Include this parameter if your

DBMS supports distributed databases and you want to retrieve information

about a stored procedure that is not in the database to which you are

currently connected.

If you are not using a distributed database system, you do not need to

specify this parameter.


location.


If your database supports pattern-matching on schemas, you may specify theschema name with a pattern-matching string, where _ represents a single




AuthID.

$dbTable The name of the table to which the procedure belongs.



Database Services


$dbProcNamePattern The name of the procedure about which you want information.

Output A Values object containing a set of variables whose keys represent items in the stored procedure’s

signature. Each element is a Values object containing additional information about that signature item.

For specific information about what this service will return for your database, see

java.sql.DatabaseMetaData.getProcedureColumns in your JDBC documentation.

pub.db:getTableInfo

Description Retrieves information about columns in the specified table.


$dbAlias

– OR –


– OR –

$dbConnection









DBMS supports distributed databases and you want information about a

table that is not in the database to which you are connected.

If you are not using a distributed database system or you want information

about a table in the database to which you are connected, you do not needto specify this parameter.


location.


If your database supports pattern-matching on schemas, you may specify

a pattern-matching string for the schema name, where _ represents a

single character and % represents any string of characters. For example,

the value HR% would represent any schema beginning with the characters

HR.

If you are running against DB2, you use this parameter to specify the

table’s AuthID.

$dbTable Name of table to query.

$dbColumnNamePattern Pattern-matching string that specifies the column names about which you

want information, where _ represents a single character and % represents

any string of characters. For example, the value ADDR% would represent

any column name beginning with the characters ADDR.

Output A Values object with variable names that are the column names of the table. Each element in the

output is a Values object that contains information for each column.





Usage Notes This service will accept input from a web browser or HTML form.

pub.db:getTables

Description Retrieves the names of tables in the specified database and schema.

Input You may specify the connection parameters in one of the following ways:$dbAlias

– OR –


– OR –

$dbConnection









DBMS supports distributed databases and you want information about a

database that is not the one to which you are connected.

If you are not using a distributed database system or you want information

about the database to which you are connected, you do not need to specify

this parameter.


location.

$dbSchemaPattern Name of the schema for which you want the names of tables.

If your database supports pattern-matching on schemas, you may specify a

pattern-matching string for the schema name, where _ represents a single



If you want the table names from all schemas, set $dbSchemaPattern to null.


AuthID.

$dbTableNamePattern Pattern string describing the tables whose names you want to retrieve.

If your database supports pattern-matching on schemas, you may specify a

pattern-matching string, where _ represents a single character and %

represents any string of characters. For example, the value HR% wouldrepresent any table name beginning with the characters HR.

If you want a table names, set $dbTableNamePattern to null.

$dbTypeListe A String [ ] specifying the types of tables whose names you want to retrieve.

Common JDBC table types include: TABLE, VIEW, SYSTEM TABLE,

ALIAS, and SYNONYM. Check your driver documentation for others.



Database Services


Output A Values object with variable names that are the table names in the database. Each element in the

output is a Values object that contains information for each table.


pub.db:insert

Description Inserts one or more rows into the specified table.


$dbAlias

– OR –


– OR –

$dbConnection









supports distributed databases and you want to insert rows into a table that is


If you are not using a distributed database system or if you want to insert rows

into the database to which you are connected, you do not need to specify this

parameter.


location.







AuthID.

$dbTable Name of table into which you want to insert rows.

$data Values object containing the data to insert. This object can be of the type

Values or Values[].

$dbRollbackOnFail A String that determine whether changes are committed if a failure occurs

while processing multiple inserts.

Set to.. To…

true Undo changes on failure.

false Commit changes on failure.






$insertCount Number of rows the service inserted.

$failCount Number of rows that the service failed to insert.

$errors An array of strings containing any error messages.


pub.db:query

Description Retrieves all rows from the specified table that meet the given criteria.



supports distributed databases and you want to query a table that is not in the

database to which you are connected.

If you are not using a distributed database system or if you want to query a table

in the database to which you are connected, you do not need to specify this

parameter.


location.




character and % represents any string of characters. For example, the value HR%

would represent any schema beginning with the characters HR.


AuthID.

$dbTable Name of table to query.

$data Values object with criteria that the rows to retrieve must meet.


$results Values object that contains results of the query.


pub.db:rol lback

Description Discards changes to a database.


$dbAlias The alias of the database on which you want to discard changes.


$dbMessage A message indicating the success or failure of the operation.Usage Notes This service returns an exception if there an error occurs when discarding changes to the database. The

most common reason for this error is that no transaction has been started (see startTransaction).

pub.db:startTransaction

Description Begins a transaction on a database connection.




Database Services


$dbAlias The alias of the database on which you want to start the transaction.



Usage Note This service returns an exception if an error occurs when starting the new transaction. Common

reasons for an error when starting a new transaction are:

— A transaction is already in progress (see pub.db:commit, pub.db:rollback or

pub.db:clearTransaction)

— The target database does not support transactions

After a transaction has been started, it must be terminated with either a commit (to save all changes to

the database) or a rollback (to discard changes).

pub.db:update

Description Updates all rows in the specified table that meet the given criteria. The rows are updated with the

supplied new data.


$dbAlias

– OR –


– OR –

$dbConnection









supports distributed databases and you want to update rows in a table that is


If you are not using a distributed database system or if you want to update rows

in the database to which you are connected, you do not need to specify this

parameter.

If you are running against DB2, you use this parameter to specify the database

location.







AuthID.

$dbTable Name of table to update.





$criteria Values object with criteria that the rows to update must meet.

! If no criteria are provided, all rows are updated.

$set Values object containing the new data to update rows with.

OutputVariable Name Description

$updateCount Number of rows updated.



Database Services






Flow Services

You use the flow services to perform utility-type tasks in a flow service.

pub.flow:clearPipel ine

Description Remove all fields from the pipeline.


preserve String list containing field names that should not be cleared from the pipeline.

Output none

pub.flow:debugLog

Description Write a message to the server log (server\logs\server.log). Each log message contains a line number,

function name, and message field.

Example 000002 WMTXMG9999V message


message Text of the message to write to the log.

function Optional. Function name, typically an abbreviation used to identify the source

of the message.

level Optional. Debug level at which to display this message. Defaults to 4. If the

debug level on the Server is set to a value less than this parameter, the message

will not be written.

Output none

pub.flow:getSession

Description Insert the Session object into the pipeline as a record named $session. Session is useful for associating

values with particular clients or users. Once $session is added to the pipeline, it can be used like anyother record within flow operations. This permits more powerful flows that perform work spanning

several user requests.

Input none


$session A record containing fields associated with the current user session. Setting,

copying, or dropping fields within $session are effectively manipulating the

Session object on the Server.

pub.flow:restorePipel ine

Description Restore a pipeline previously saved by pub.flow:savePipeline. Pipelines are identified by $name, and an

exception will be raised if the name is not known. After a successful invocation of pub.flow:restorePipeline, all fields present immediately before the respective invocation to

pub.flow:savePipeline will be contained in the pipeline. Existing pipeline values are cleared during this

invocation unless the optional $merge field is specified.




Flow Services


$name Name of the saved pipeline. Since the multiple pipelines can be saved, this is

necessary to identify the pipeline in memory. An exception will be raised if this

value is left null or the name is unknown.

$merge Optional. Indicates how the existing pipeline will be treated during this

invocation.

FALSE (default): The existing pipeline will be cleared before restoring thesaved pipeline.

TRUE: The saved pipeline will be merged with the existing pipeline. In

situations where a field exists in both the saved and existing pipelines, the saved

field takes precedence.

$remove Optional. Indicates whether or not the saved pipeline will remain in memory

after this service is executed.

FALSE (default): The saved pipeline will remain in memory, so future calls to

restorePipeline with the same $name will still return the pipeline.

TRUE: The saved pipeline will be removed from memory.

Output Note The output is dynamic based on the fields within the saved and existing pipelines.

pub.flow:savePipel ine

Description Saves a pipeline into memory, for later retrieval by a call to pub.flow:restorePipeline. Pipelines are

identified by $name, and an exception will be raised if the name is not provided. After a successful

invocation of pub.flow:savePipeline, a snapshot of all pipeline fields will be saved in memory under

the key provided by $name. Note that since pipelines are saved to memory, they will not be available

after a server restart.

The main purpose of the save/restorePipeline services is to allow interactive development or debugging

of flows. For example, if a client process posts data asynchronously to your flow, there is no way to

visually step through the flow with the B2B Developer. But if your client calls pub.flow:savePipeline,

you can develop a flow by calling pub.flow:restorePipeline as the first service in your flow. From

there, you have access to the snapshot of the data sent by the client and can interactively develop anddebug. When the flow is ready for production, remove the call to pub.flow:restorePipeline and ask the

client to call your flow directly.


$name Name to identify the pipeline in memory. An exception will be raised if this

value is left null.

Output none

pub.flow:setResponse

Description Force a specific response string to be returned by B2B Server to a calling process (such as a browser or

application server). Formatting of the response is normally handled by templates, which format values

from the pipeline. If templates are not appropriate for a particular integration scenario, a response

message can be created within flow and returned to the caller using this service.

Typical usage of this service is to create an XML response to an XML request. A flow that creates an

XML document by calling pub.web:recordToDocument can add pub.flow:setResponse and map the

xmldata field (output of recordToDocument) to response (input to setResponse). Instead of processing

the entire pipeline through a template to return a response, the template is ignored and the xmldata

(response) is returned.






response String body of the response to be returned to the caller.

contentType Optional. String specifying the MIME type of the response data. By default the

server's response will match the MIME type of the request. This field allows this

behavior to be overridden.

Preset values are text/XML and text/HTML, but user-defined values are also

permitted.

Output none

pub.flow:tracePipel ine

Description Write the names and values of all fields in the pipeline to the server log (server\logs\server.log). This

can be useful for debugging flows invoked by clients other than the B2B Developer and thus cannot be

debugged interactively.


level Optional. Debug level at which to display the pipeline. Defaults to 4. If the

debug level on the B2B Integration Server is set to a value less than this

parameter, the pipeline will not be written.

Output none



Flow Services






Ldap Services

You use the ldap services to access and update information on an ldap directory server.

pub.ldap:bind

Description Adds an entry into the LDAP server.

Input Variabl e Name Description

ldapConnectionKey The key for the connection on the B2B Integration Server; this is the key

returned from the execution of pub.ldap:connect

ldapTargetName The name of the entry that you want to add.

For example, to add a user entry for Joe Krebbs in the ou=People context,

specify cn=Joe Krebbs, ou=People for ldapTargetName.

ldapTargetObject Optionally, an object you want to store into this entry. Some LDAP servers

restrict the kinds of objects you can store (some do not even support storage

of Java objects). Typically, the objects must implement the java.io.Serializable

interface. The default value for ldapTargetObject is null

ldapTargetAttributes A record containing the attributes to assign to the new entry. The following

shows an example of inputs you might use to add the user Joe Krebbs:

Example

Variable Value

objectclass organizationalPerson

cn Joe

sn Krebbs

uid jkrebbs

mail [email protected]


ldapMessage A message indicating the success or failure of the operation.

Usage Notes You must have the appropriate permissions to add entries into an LDAP directory. For most simple

insertions, you should not need to supply a Java object value for the ldapTargetObject input parameter.

Refer to the schema of the target server to determine the attributes that are required. For example,

typically an “objectclass” attribute is required.

pub.ldap:connect

Description Connect to an LDAP server.


ldapUrl The URL of the ldap server to connect with (e.g., ldap://bigfoot.com).

ldapUser Optional. The user name to use on the LDAP server.ldapPass Optional. The password to use on the LDAP server.


ldapConnectionKey Key for this connection on the B2B server.



Ldap Services


Usage Notes Use this service to connect to an LDAP server and get a valid connection key. Use the returned

connection key to invoke the rest of the pub.ldap services (including pub.ldap:disconnect). Your

connection to the LDAP server remains open until the server shuts down or until the connection is

disconnected.

To connect to a subdirectory, specify the URL of the subtree for ldapUrl. For example, if your

directory starts at ldap://mydir.com and you only want to operate on the subtree rooted at ou=People,specify, ldap://mydir.com/ou=People for ldapUrl .

pub.ldap:delete

Description Delete an entry from the LDAP server.



returned from the execution of pub.ldap:connect.

ldapLookupName The name of the entry that you want to delete.

For example, to delete Joe Krebbs from the ou=People context, specify

cn=Joe Krebbs, ou=People for ldapLookupName.



Usage Notes You must have the appropriate permissions to delete entries in an LDAP directory.

pub.ldap:disconnect

Description Closes a connection to an LDAP server.




Usage Notes Use this service to disconnect from an LDAP server when you are done using the connection.

pub.ldap:getAttr ibuteDef

Description Get the definition of an attribute in the server’s schema.




ldapAttributeName The name of the attribute for which you want to get the definition.

For example, to get the definition of the “mail” class, specify mail for

ldapAttributeName.


ldapAttributeDef A record describing the named objectclass. It has the following structure:

Variable Value

NAME The name of the objectclass.

NUMERICOID The numeric OID of the objectclass.

SYNTAX The numeric OID of the syntax for the attribute

DESC A description of this objectclass.





The following shows an example of the returned output from looking up the

“mail” attribute:

Example

Variable Value

NAME mail

NUMERICOID 2.16.840.1.113730.3.2.2

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15

DESC Standard Attribute

Usage Notes This service has been tested for the Netscape Directory servers. If you use a different

LDAP server, test this service to ensure it works for your server.

pub.ldap:getClassDef

Description Get the definition of an objectclass in the server’s schema.


ldapConnectionKey The key for the connection on the B2B Integration Server; this is the keyreturned from the execution of pub.ldap:connect.

ldapObjectClass The name of the objectclass for which you want to retrieve the definition.

For example, to get the definition of the “organizationalPerson” class, specify

organizationalPerson for ldapObjectClass.


ldapAttributeDef A record describing the named objectclass. It has the following structure:

Variable Value

NAME The name of the objectclass.

NUMERICOID The numeric OID of the objectclass.

MUST An array of names of required attributes. MAY An array of names of optional attributes.

SUP The superclass of this objectclass.

DESC A description of this objectclass

Example

The following shows an example of the returned output from looking up the

“inetOrgPerson” class

Variable Value

NAME inetOrgPerson

NUMERICOID 2.16.840.1.113730.3.2.2

MUST objectclasssn

cn

MAY aci

description

ssealso

etc.



Ldap Services


SUP organizationalPerson

DESC Standard ObjectClass

Usage Notes This service has been tested for the Netscape Directory servers. If you use a different LDAP server,

test this service to ensure it works for your server.

pub.ldap:ini t

Description Do not use. This service performs initialization routines that are used by the B2B Integration Server. It

is not meant to be invoked by a user.

pub.ldap:l ist

Description List the bindings within a particular directory context.




ldapListRoot Optionally, the relative name of the context to list. If you do not specify a

value for ldapListRoot , the default is "", which indicates the root context for the directory server.

ldapReturnAttributes Optionally, a comma-separated list of attribute names to return for each of the

listed bindings. For example, to return only the “mail” and “uid” attributes,

set this parameter to mail,uid. If you do not specify a value for

ldapReturnAttributes, all attributes are returned.

ldapReturnObjects Optionally, whether you want the directory to return objects from the

bindings or just the attributes. Specify the string true to have the objects

returned; specify the string false to have just the attributes returned. For

example, if your directory contains persisted Java objects, set this attribute to

true to have the objects returned. If you do not specify a value for

ldapReturnObjects, false is used and just attributes are returned.


ldapListing A record array describing the objects bound within the specified directory

context; one record for each object. Each record contains the following keys:

— $name: the fully-qualified name of the binding.

— $object : the object bound to this name in the directory (only if you

specified true for ldapReturnObjects).

— one key for each returned attribute.

Usage Notes The directory server running on myCompany.com contains an ou=Users context, which contains an

entry (binding) for each user in the directory server. To list the userid and e-mail address of each user,

specify the following input parameters for the pub.ldap:list service:

Variable Value

ldapListRoot ou=Users

ldapReturnAttributes uid,mail

ldapReturnObjects false

The resulting record list might look like this (perhaps with more entries):

Variable Value





Variable Value

$name cn=Arthur Milberg, ou=People

uid amilberg


$name n=Dorothy Hadden, ou=Peopleuid dhadden


$name cn=Scott Treezak, ou=People

uid streezak

ldapListing


pub.ldap:lookup

Description Lookup a single entry in the directory server.




ldapLookupName The relative name of the context to look up, e.g., ou=People, cn=Arthur

Milberg.

ldapReturnAttributes Optionally, a comma-separated list of attribute names to return for each of the

listed bindings. For example, to return only the “mail” and “uid” attributes,

set this parameter to mail,uid. If you do not specify a value for

ldapReturnAttributes, all attributes are returned.

ldapReturnObject Optionally, whether you want the directory to return objects from the

bindings or just the attributes. Specify the string true to have the objects

returned; specify the string false to have just the attributes returned. For

example, if your directory contains persisted Java objects, set this attribute totrue to have the objects returned. If you do not specify a value for

ldapReturnObjects, false is used and just attributes are returned.


ldapSearchResults A record array describing the objects bound within the specified directory

context; one record for each object. Each record contains the following keys:

Key Value

$name The fully-qualified name of the binding.

$object The object bound to this name in the directory (only if

you specified true for ldapReturnObjects).

And one key for each returned attribute.

Usage Notes To avoid returning unnecessary data, use searches that are as specific as possible. This reduces

network traffic and speeds up searches. Also, note that different servers respond to search filters in

different ways based on their schema. For instance, the (uid=a*) filter might be rejected on a server

that does not allow substring searches on the uid attribute.

pub.ldap:search

Description Search the directory for entries matching a set of criteria



Ldap Services



ldapConnectionKey Key for the connection on the B2B Server

ldapSearchFilter A filter describing which entries to return. For instance, to retrieve all entries

with the objectClass groupOfNames and cn of Engineers, you might use:

(&(objectclass=groupOfNames)(cn=Engineers))

For more information about LDAP search filters, consult your server

documentation or look for RFC 1558.

ldapSearchRoot The name of the context in which to start the search (optional, defaults to the

root entry). The search will be recursive unless you specify the

ldapSearchOneLevel parameter (see below).

For example, to search only the “ou=Engineers” subcontext, set this

parameter to “ou=Engineers”.

ldapReturnObjects Should the directory return an object from the matching entries (as opposed

to just attributes)? This should be either the string “true” or the string

“false”. (optional, defaults to “false”)

For example, if your directory contains persisted Java objects, set this

attribute to “true” to get back the objects themselves.

ldapReturnAttributes A comma-separated list of attribute names to return for each of the returned

entries (optional, defaults to all attributes)

For example, to return only the “mail” and “uid” attributes, set this

parameter to “mail, uid”


ldapSearchResults A record array describing objects matching the search filter; one record for

each object. Each record contains the following keys:

Key Value

$name The fully-qualified name of the binding.

$object The object bound to this name in the directory. (Only if ldapReturnObjects is true.)

And one key for each returned attribute.

Usage Notes Use searches that are as specific as possible, to avoid returning additional unnecessary data. This

reduces network traffic and speeds up searches. Also, note that different servers respond to search

filters in different ways based on their schema. For instance, the “(uid=a*)” filter might be rejected on

a server which doesn’t allow substring searches on the uid attribute.

pub.ldap:shutdown

Description Do not use. This service performs shutdown routines that are used by the B2B Integration Server. It is

not meant to be invoked by a user.

pub.ldap:update

Description Modifies attributes of an entry in the LDAP directory.







returned from the execution of pub.ldap:connect

ldapLookupName The name of the entry that you want to modify.

For example, to modify the entry for Joe Krebbs in the ou=People context,

specify cn=Joe Krebbs, ou=People for ldapLookupName.

ldapTargetMods An array of records that describe the changes you want to make to this entry.

Each of these records has the following structure:

Variable Value

$name The name of the attribute to modify.

$modtype Optionally, the action to take. Specify remove,

replace, or add. The default is add.

$value Optionally, the new value to assign, if applicable.

The following shows an example of the inputs you might specify to change

Joe Krebbs’ e-mail address:

Example

Variable Value

$name mail

$modtype replace

$value [email protected]



Usage Notes You must have the appropriate permissions to modify entries in an LDAP directory. You cannot use

this service to change the value of an entry itself (i.e., if you have bound Java objects in your directory,

you must delete them and rebind the name to a different Java object).



Math Services


Math Services

You use the arithmetic services to add, subtract, multiply, or divide string-based numeric values.

pub.math:addFloatList

Description Adds the numeric values in numList and returns the sum as value.

Variable Name DescriptionInput

numList String array containing a list of string-based float values.

Variable Name DescriptionOutput

value A string that represents the sum of the numeric values contained in numList .

pub.math:addFloats

Description Adds the numeric values of num1 and num2 and returns the sum as value.


num1 String representation of a float.

Input



value A string that represents the sum of the numeric values of num1 and num2.

pub.math:addIntList

Description Adds the numeric values in numList and returns the sum as value.


numList String array containing a list of string-based integer values.


value A string that represents the sum of the numeric values contained in numList .

pub.math:addInts

Description Adds the numeric values of num1 and num2 and returns the sum as value.


num1 String representation of an integer.

Input



value A string that represents the sum of the numeric values of num1 and num2.

pub.math:divideFloats

Description Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns the

quotient as value.



Input







value A string that represents num1 / num2.

pub.math:divideInts

Description Divides the numeric value of num1 by the numeric value of num2 (num1 / num2) and returns thequotient as value.



Input



value A string that represents num1 / num2.

pub.math:multiplyFloatList

Description Multiplies the numeric values in numList and returns the product as value.

Variable Name DescriptionInputnumList String array containing a list of string-based float values.


value Product of the numeric values contained in numList .

pub.math:multiplyFloats

Description Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.



Input



value A string that represents the product of num1 and num2.

pub.math:multiplyIntList

Description Multiplies the numeric values in numList and returns the product as value.


numList String array containing a list of string-based integer values.


value Product of the numeric values contained in numList .

pub.math:multiplyInts

Description Multiplies the numeric value of num1 by the numeric value of num2 and returns the product as value.



Input





Math Services


value A string that represents the product of num1 and num2.

pub.math:subtractFloats

Description Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the

difference as value.



Input



value A string that represents num1 – num2.

pub.math:subtractInts

Description Subtracts the numeric value of num2 from the numeric value of num1 (num1 – num2) and returns the

difference as value.



Input



value A string that represents num1 – num2.



Record Services


Record Services

You use the record services to perform operations on Records in the pipeline.

pub.record:length

Description Returns the number of records in a record list.


recordList Record list for which a length calculation is needed.


length Number of records in the input record list. If the input record list is null, this key

is not added to the pipeline.

pub.record:recordListToRecord

Description Construct a record from a list of records. Two constant fields (name, value) are retrieved from every

record in the input record list. The name field is then placed into the output record, its value equal to

the value field.


recordList Target record list to transform into a record.

name Constant name to retrieve from recordList and serve as the name of a new field

in the output record.

value Constant name to retrieve from recordList and serve as the value of a new field

in the output record.

pub.record:recordToRecordList

Description Expand the contents of a record into a list of records. Each name/value pair in the target record will

become a new record in a record list with constant keys for name and value.Input Variable Name Description

record Target record to transform.

name Constant name to use for the keys of the target record.

value Constant name to use for the values of the target record.


recordList Resulting record list, length equal to the number of fields in the input record.

Each of its records will have two fields (name and value).

pub.record:recordToXMLValues

Description Convert a record in the pipeline to a String by encoding it as webMethods XMLValues format. Todecode the String back into a record, use pub.record:XMLValuesToRecord.


record Target record to convert. This record can contain any number of other fields,

lists, and other records.






xmlvalues XML document containing encoded representation of input record. The XML

format is webMethods XMLValues. No other formats can be generated.

pub.record:XMLValuesToRecord

Description Convert a String containing XMLValues to a record by decoding the webMethods XMLValues

format.


xmlvalues XML document containing encoded representation of a record. The XML

format is webMethods XMLValues. No other formats will be accepted.


record Record resulting from the decoding of xmlvalues.



Record Services




Remote






Report Services

The report services allow you to apply an output template to a Values object. Each service requires an output

template and a Values object. They can be used within order to generate any type of dynamic XML, EDI, or HTML

document. Basically, there are three services that have two versions. One version needs a Values object to be passed

in as input in order to bind the template against. The second version uses the input to itself (Pipeline) as the Valuesobject to bind the template against.

pub.report:runFi leTemplate

Description This service will apply a template available in a File object on a Values object specified.


$template A File object (java.io.File) which points to a physical template file.

$values The values object to be bind against the template.


$txt The resulting string from applying the template.

Usage Notes If a template is not available in a templates directory of any of the packages on the server, you can use

this service by passing in a File object representing the template.

pub.report:runFi leTemplateOnPipe

Description A replica of the pub.report:runFileTemplate, only the Values object to bind against is the input Values

object to the service (Pipeline).


$template A File object (java.io.File) which points to a physical template file.



Usage Notes If a template is not available in a templates directory of any of the packages on the server you can use

this service by passing in a File object representing the template.

pub.report:runStringTemplate

Description This service provides added flexibility by allowing to use a template from a string object. The template

does not have to be known and saved to file before hand.


$template The String object containing the template to be used.




Usage Notes This service is typically invoked from other services that already have a template in a String object and

a Values object that will be used to bind against the template.

pub.report:runStringTemplateOnPipe

Description A replica of the pub.report:runStringTemplate, only the Values object to bind against is the input

Values object to the service(Pipeline).



Report Services



$template The String object containing the template to be used.



Usage Notes This service is typically invoked from other services that already have a template in a String object andneed the template to be bind against the Pipeline.

pub.report:runTemplate

Description Generates dynamic text by binding an output template to a Values object. The output template is

located by its file name and the package where is resides on the server. The Values object is passed in

as input to the service.


$template The filename for a template. Ex. mytemp.html or mytemp.xml

$package The package where the template is. Ex. “Default”




Usage Notes To apply a template which resides under webmethods\server3\package\Defaul\templates\mytemp.xml,

invoke the service with the following values.

$template: mytemp.xml

$package: Default

$values: Make sure that the Values object you want to bind against is pointed to by this key.

pub.report:runTemplateOnPipe

Description A replica of the pub.report:runTemplate, only the Values object to bind against is the input Values

object to the service (Pipeline).


$template The filename for a template. Ex. mytemp.html or mytemp.xml

$package The package where the template is. Ex. “Default”



Usage Notes To apply a template which resides under webmethods\server3\package\Defaul\templates\mytemp.xml,

invoke the service with the following values.

$template: mytemp.xml

$package: Default

String Services


Str ing Services

You use the string services to perform string manipulation and substitution operations.

pub.string:bytesToString

Description Converts a byte array to a String.


bytes A byte array (byte[]).


string A string containing the bytes in bytes.

pub.string:concat

Description Concatenates two strings.


inString1 A string.

Input

inString2 A string.


value A string that represents inString1 concatenated with inString2 (inString1 +

inString2).

pub.string:HTMLDecode

Description Replaces HTML character entities in inString with native characters.


inString A string.

Variable Name DescriptionOutputvalue A string containing the characters in inString with the HTML character entities

replaced by equivalent native characters.

pub.string:HTMLEncode

Description Replaces HTML-sensitive characters [“&<>] in inString with equivalent HTML character entities.

These translations are useful when displaying text in an HTML context.


inString A string.


value A string containing the characters in inString with occurrences of thecharacters above replaced by their equivalent HTML character entities.

pub.string:indexOf

Description Returns the index of the first occurrence of subString in inString , starting at fromIndex.


inString A string.





subString The string containing the sequence of characters to look for.

fromIndex A string representing the index of inString to start the search from. If null or

empty, uses “0.”


value A string representing the index of the first occurrence of subString in inString,

or “-1” if no occurrence is found.

pub.string:length

Description Returns the length of a string.


inString A string.


value A string representing the length of inString .

pub.string:lookupDictionary

Description Looks up a key string in a Hashtable and returns the corresponding string to which the specified key is

mapped (case-sensitive).


hashtable A Hashtable that uses String objects for keys and values.

Input

key The string to look up.


value The string to which key is mapped; if key is null or if key is not mapped to any

value in hashtable, returns null.

pub.string:lookupTable

Description Looks up a key string in a String table (String[][]) and returns the corresponding string to which the

specified key is mapped.


lookupTable A multi-row, multi-column table of strings.

keyColumnIndex String representation of the index of the key column.

valueColumnIndex String representation of the index of the value column.

key The string to look up.

ignoreCase Set this string to “true” to perform a case-insensitive lookup.

Input

useRegex Set this string to “true” to have the key column values interpreted as regular

expressions.


value The string in the value column of the first row whose key column matches key.

If no match is found, returns null.



String Services


pub.string:makeString

Description Builds a single string by concatenating an array of strings while concatenating an optional separator

between each string.


stringList An array of strings to concatenate.

Input

separator The string to insert between each non-null element in stringList .


value A string that contains all the strings in stringtList concatenated with separator

between each string.

pub.string:messageFormat

Description Formats an array of strings into a given message pattern.


stringList An array of strings to format into a single string.

Input

pattern A string that contains the desired message pattern. Use {n} as a placeholder for the nth string in stringList . Example: “Test results: {0} items passed, {1}

items failed.”


value A string that contains the elements in stringList substituted into pattern.

pub.string:numericFormat

Description Formats a number into a given numeric pattern.


num A string representation of a number.

Input

pattern A string that contains the desired number pattern.Variable Name DescriptionOutput

value A string that represents num formatted according to pattern.

pub.string:padLeft

Description Pads a string to a certain length. Padded characters are added to the beginning of the string.


inString A string.

padString String to use as padding.

Input

length Desired length of resulting string.






value A string of length length, containing inString preceded by multiple occurrences

of padString .

If padString is longer than one character and padString does not fit an exact

number of times into the resulting string, the beginning of padString will be

aligned with the beginning of the resulting string.

If inString is longer than length characters, the first length characters will bereturned.

pub.string:padRight

Description Pads a string to a certain length. Padded characters are added to the end of the string.


inString A string.

padString String to use as padding.

Input

length Desired length of resulting string.


value A string of length length, containing inString followed by multiple occurrences

of padString .

If padString is longer than one character and padString does not fit an exact

number of times into the resulting string, the end of padString will be aligned

with the end of the resulting string.

If inString is longer than length characters, the first length characters will be

returned.

pub.string:replace

Description Replaces all occurrences of a specified substring with a substitute string.


inString A string.

searchString String to search for within inString .

replaceString String to substitute in place of searchString . If null or empty, occurrences of

searchString will simply be removed.

Input

useRegex Set this string to “true” to have searchString interpreted as a regular

expression. replaceString may also contain interpolation variables, e.g., “$1”,

that match parenthesized subexpressions in searchString .


value A string that represents inString , with all occurrences of substrings matching

searchString replaced by replaceString .

pub.string:stringToBytes

Description Converts a String to a byte array.


string A string.






inString A string.

delim A string containing the delimiter characters. If null or empty, uses " \t\n\r"

(white space characters).


valueList An array of strings containing the tokens in inString .

pub.string:tr im

Description Trims white space from a string.


inString A string.


value A string containing inString with white space trimmed from both ends.

pub.string:URLDecode

Description Decodes a url-encoded string.Variable Name DescriptionInput

inString A url-encoded string.


value A string containing the decoded form of inString. Converts plus (+) signs to

spaces, and converts any %xx encoding to the character equivalent of the hex

value.

pub.string:URLEncode

Description Url-encodes a string. Encodes characters the same way that posted data from a WWW form is

encoded, that is, the application/x-www-form-urlencoded mime type.


inString A string.


value A string in which all non-alphanumeric characters except [-_.*@] have been

replaced with a percent (%) sign followed by two hex digits and spaces

encoded as plus (+) signs.



String Services






Table Services

You use the table services to convert instances of com.wm.util.Table to other data types.

pub.table:recordListToTable

Description Turn a list of records into an instance of com.wm.util.Table.


recordList Data for the new table. Each record represents a row for the new table. The keys

columnNames An array of strings representing the column names for the new table. Each

record/row will be queried for a value for each column.

tableName A name for the new table (optional)


table The resulting table

pub.table:stringTableToTable

Description Turn a string table (Java array) into an instance of com.wm.util.Table.


columnNames A string array of column names for the table.

stringTable A multi-dimensional string array of table data.

tableName Optional. A name for the new table.


table An instance of com.wm.util.Table with the supplied data.

Usage Notes For example, to create a two-column table which maps id numbers to names, you might use the

following parameters:

columnNames = { “id”, “name” } stringTable = { { “1099”, “arthur” }, { “3000”, “dorothy” }, { “2068”, “scott” } }

tableName = “idTable”

pub.table:tableToRecordList

Description Turn an instance of com.wm.util.Table into a list of records.


table The table to convert.


recordList Data from the table. Each record represents a row from the table. The keys of

the record are the column names, and their values are the corresponding valuesin that row.

pub.table:tableToStringTable

Description Decompose an instance of com.wm.util.Table into Java arrays.


table The table to convert.



Table Services



columnNames An array of column names from the table.

stringTable A multi-dimensional array of string data from the table.

Usage Notes Having just used pub.db:select to query your database for a table of all transactions with an ID higher

than 3000, you could turn the resulting instance of com.wm.util.Table into a multi-dimensional string

array with this service.





Web Services

You use the Web automation services to perform operations on XML and HTML documents.

pub.web:createRegions

Description Generates regions output parameters.


node Node

Document

Region

The node from which you want to create regions. (A node is produced

by loadDocument, stringToDocument, createRegions or one the B2B

Server content handlers.)

nsDecls

optional

Values

Values[ ]

Vector

String[ ][2]

XML namespace declarations to use with the XQL queries specified

with the regions input. When nsDecls is a Values[ ], each Values object

provides a namespace declaration that is defined as follows:

Element Type Description prefix String Prefix that represents the URI in queries.

uri String URL identifying the XML namespace.

− When nsDecls is a single Values object, the key identifies the

prefix, and the value identifies the URL.

− When it is a Vector, nsDecls contains a collection of Values

objects as defined above.

− When it is a String[ ][2], the first column is the prefix and the

second is the URL.

regions Values A set of parameters defining a region. A region is a portion of a

document between two delimiting nodes, possibly including either or

both delimiting nodes. Each region is defined as follows:


name Values[ ] Name to assign to resulting region.

structured

optional

String Not used. Reserved for future use.

start

optional

Values Identifies the starting node of the region.

When start is not specified, the region starts

with the first node and includes the first

node. Specify start as follows:

Variable Description

queryType A String specifying the querylanguage in which the query

for the starting node is

expressed. Valid values are

WQL and XQL.



Web Services


query A String specifying the query

identifying the starting node.

If the identified node cannot

be found, the region cannot be

found.

include A String specifying whether to include the starting node in

the region. Valid values are

true and false.

end

optional

String Identifies the ending node of the region.

When end is not specified, the region ends

with the last node and includes the last

node. Specify end as follows:


queryType A string specifying the query

language in which the query

for the ending node is

expressed. Valid values areWQL and XQL.

query A String specifying a query

identifying the ending node. If

the identified node cannot be

found, the region cannot be

found

include A String specifying whether

to include the ending node in

the region. Valid values are

"true" and "false".

Pattern is not

currently

implemented

pattern

optional

String List of element type names and asterisks

delimited by spaces. Provides a way to

identify a region by giving the pattern of

nodes that defines the region. Asterisks

represent zero or more nodes. When you

specify pattern, the query fields are ignored.

onnull String Specifies what you want createRegion to do

when either the region or the queries

defining the region are null:

continue —All result values are legal.

fail —If the result of the query is null, the

service fails. If the result of the query or

region is not-null, the service continues.

succeed —If the result of the query is null,

the service continues. If the result of the

query or region is not-null, the service fails.

Output Values retrieved by the regions input specifications. There will be one output parameter for each region,

which will go directly into the Values object passed to the service (usually the pipeline).

pub.web:documentToRecord

Description Converts a parsed document to a Values object. The Values object can be arbitrarily complex, reflecting

the complexity of the document. All attributes are put into their corresponding Values objects. Because

the conversion is performed using data as the input (i.e. a single instance of a document), the parameters

(arrays, records, collections) are used to define the order and format of the Values object to create. For

example, the list items of a purchase order should be created as a Values[] even if the input documentonly contains a single item. Forcing certain items to be Values[] makes the code that transforms the

Values object simpler.

makeArrays parameter automatically generates arrays based on the data of the input document. If there

are multiple instances of any element name, it will be collected in a Values array. Note that when

elements are made into an array the order of the elements is not preserved. For example:

<x>

<y>one</y>

<z>two</z>

<y>three</y>

<z>four</z>

</x>

When collected into arrays y and z, will look like:

boundNode x

y[0]one

y[1]three

z[0]two

z[1]four

Elements that only occur once in the input document will not be put into arrays unless specified in the

arrays parameter or if makeArrays is true. If the elements are not put into an array, all but the last

element value is lost.

If order is important, collection rules should be defined.

Certain XML data is lost when an XML file is converted to a Record using documentToRecord:

− Comments

− namespace xmlns declarations

− pi nodes (such as DOCTYPE)

− any elements that contain more than one entry that are not put in arrays (all but the last is lost)

− elements put into arrays are collected, i.e. the order is lost


node Object Parse tree (returned by loadDocument, stringToDocument).

attrPrefix

optional

String String that allows for a customized attribute prefix.

The default is "@".

nsDecls

optional

Values,

Values[ ],

Vector,

String[ ][2]

XML namespace declarations to use with the element type names

found in arrays and collections. When nsDecls is a Values[ ], each

Values object provides a namespace declaration and is defined as

follows:


prefix String Prefix that represents the URI in queries.

uri String URL identifying the XML namespace.



Web Services



prefix, and the value identifies the URI.



− When it is a String[][2], the first column is the prefix and the

second is the URL.

arrays

optional

String[ ] Array of XML element type names. Element type names may

optionally be preceded by a namespace prefix. All matching tags in the

document will be defined with dimension array.

records

optional

String[ ] Array of XML element type names. Element type names may

optionally be preceded by a namespace prefix. All matching tags in the

document will be defined as a Record type.

makeArrays

optional

String Whether to create arrays for every element that appears in the

document multiple times. Set to true or false.

Default is false.

collections Values[ ] Array of Values objects used to retain the element order

optional Element Type Description

name String Name of the collection.

members String[ ] Array of the element type names for

elements that are to appear as peers in a

collection. Element type names can

optionally be preceded by a namespace

prefix.

A field can only appear in a single

collection. If it appears in multiple

collections only the last instance will be

used.


boundNode Values Values objects that include all the nodes and attributes of the document

organized based on the array, record and collection rules.

pub.web:freeDocument

Description Frees the resources allocated to the given document. When using a NodeIterator to iterate over a

document, the client may decide to stop reading the document before the entire document is read. The

client can call web.pub:freeDocument to explicitly free the resources held by the document instead of

waiting for Java garbage collection to occur. It is not necessary to call this method, but doing so can

boost server performance. The document is left in an unfinished state and should not be used

subsequently.


doc Document Document whose resources you want to release.

Output none

pub.web:getDocumentType

Description Returns document type information about a document.



Web Services


pub.web:getNodeIterator

Description Creates and returns a NodeIterator. A NodeIterator iterates over the element node descendants of a given

node and returns the element nodes that satisfy the indicated criteria. The client application or flow

service uses the service getNextNode() to get each node in turn. NodeIterators can only be created for

XML nodes (not for HTML nodes). getNodeIterator is useful for loading and parsing documents on-

demand. Large or slow documents need only be loaded as far as is needed to get the desired data. NodeIterators are also useful for providing service as the pertinent information in the document arrives

rather than first having to wait for the entire document to load. This service is primarily intended to deal

with large documents or documents that arrive slowly.

NodeIterator provides a moving window mode, in which the only node that is ever resident in memory is

the last node returned by getNextNode(). In this mode, when getNextNode() is called, all nodes

preceding the newly returned node become invalid, including all nodes previously returned by

getNextNode(). The client must fully complete processing of preceding nodes before advancing the

window by calling getNextNode() again. In moving window mode the document will consume at least

enough memory to hold the most recently returned node.

Moving window mode allows the server to process multi-megabyte XML documents using very little

memory. Moving window mode may only be used on a node that represents an entire XML document

and not on any descendant node.


node Object Node over which to iterate. The node must represent either an XML

document or an element of an XML document. The parameter is

constrained to be of type Document when used in moving window

mode. This is because moving window mode is only meaningful for

managing the loading process of a document, and to operate on a

node, is to have already loaded the node.

nsDecls

optional

Values

Values[ ]

Vector

String[ ][2]

XML namespace declarations for use with the XML element names

found in criteria.

− When nsDecls is a Values[ ], each Values object provides a

namespace declaration and is defined as follows:



uri String URI identifying the XML namespace.


prefix, and the value at that key identifies the URI.




second is the URI.

criteria String[ ] This input parameter is a String[] of patterns identifying the nodes

that the iterator is to return. A pattern may take either the form

"<localName>" or the form "<prefix>:<localName>".

When a pattern takes the first form, it identifies an element whose

local name is <localName> and that belongs to the default XML

namespace. When a pattern takes the second form, it identifies anelement whose local name is <localName> and whose XML

namespace is given by the prefix <prefix>. If the input parameter

nsDecls declares this prefix, the namespace URI of the element must

match the URI declared for the prefix. If the prefix is not declared in

nsDecls, the prefix is matched against prefixes found in the XML.

<prefix> and <localName> can each optionally take the value '*'

(asterisk) to match any namespace or local name. A '*' prefix also

matches elements residing in the default namespace.

If the criteria is not specified, all element node children of the root

element are returned.

movingWindow

optional

String Whether the NodeIterator is to iterate using a moving window, as

described above. In moving window mode, the entire document preceding the node most recently returned by GetNextNode is

discarded. Subsequent attempts to return preceding portions of the

document will return either the repeating text "*PURGED*" or the

proper data, depending on whether the data falls within an area that

the server was able to discard. When iterating with a moving window,

the current node should be queried and completely examined prior to

requesting the next node. Valid values are "true" and "false". When

absent, a value of "false" is assumed.


iterator NodeIterator A NodeIterator for use with the service getNextNode.



Web Services


pub.web:loadDocument

Description Retrieves a specified XML or HTML document via HTTP or HTTPS and returns a parsed Document

object that can be used as input to any service that accepts a node.


url String Specifies the URI of the document you want to load. This string must

begin with http: or https:


method String Specifies the HTTP method you want loadDocument to use.

You must set method to either get or post.

auth

optional

Values Specifies authorization information that loadDocument will

submit if the resource specified in url is protected.


type String Type of authentication you want

loadDocument to use to submit this

request.

Currently, only basic authentication is

supported. If you are accessing a

protected resource, set auth to Basic.

user String The user name that loadDocument will

submit when it requests a protected

resource.

pass String The password associated with user .

headers

optional

Values Specifies fields that you want to explicitly override in the HTTP

request header issued by loadDocument.

Specify one element in the headers Values object for each header field

that you want to set, where:

− The element’s name represents the name of the header field, and…

− The element’s value represents the value of that header field.

If you do not set headers, loadDocument will use its default header

values.

encoding String The character set in which the returned document is encoded. The

parser requires this value in order to interpret a document correctly.

Set encoding to… To…

autoDetect Determine the document’s character set

based on document type, where:

—

ISO-8859-1 is used for HTML

— UTF-8 is used for XML

The name of a

registered, IANA

character set

Decode the document using that character

set.

Example ISO-8859-1

If you do not specify an encoding value, loadDocument decodes the

returned document using the following defaults:





If the document is… It is decoded using…

HTML ISO-8859-1

XML UTF-8

data

optional

Values Specifies data that you want loadDocument to submit with the HTTP

request.

Specify your data in one of the following elements.

Name Type Description

args Values Specifies name=value pairs that you want

loadDocument to submit to the resource

in url.

You can use args to submit data via either

the POST or GET method.

To specify data using args, create one

element for each name=value pair that

you want to submit, where:

− The element’s name represents the

name portion of the pair, and…

− The element’s value represents the

value portion of the pair.

Note that when you use args,

loadDocument will:




in args.


character between pairs, so you do

not need to include it in args.



submits the data in args via a GET.

You do not need to include this

character in args.

string String Specifies a string of text that you want


in url .

You can use string to submit data via

either the POST or GET method.

If you use string to specify data you wantloadDocument to submit, make sure that

you specify the string exactly as you want

it presented in the HTTP request. (If you

are using the GET method, make sure

you url-encode the contents of string )



Web Services


bytes bytes[ ] Specifies an array of bytes that you want


in url .

You can only use bytes to submit data via

the POST method.

table String[ ][ ] Specifies data that loadDocument willuse to construct a query string to submit

to the resource specified in url .

table is similar to args, but it allows you

to submit unnamed values in a query

string, not just name=value pairs.

To specify data using table, create one

row for each value that you want to

submit, where:


the name portion of the pair (leave

this column null to submit an

unnamed value, and…


the value portion of the pair.

Note that when you use table,

loadDocument will:




in table.


character between the pairs (or

unnamed values) that it constructs,so you do not need to include it in

table.



submits the data in table via the

GET method. You do not need to

include this character in table.

expandDTD String Determines whether or not loadDocument processes references to

parameter entities in the returned document’s DTD.

Set expandDTD to… To…

true Expand references to parameter entities to

their full definition.

false Ignore references to parameter entities in the

document’s DTD.

The default value is false.

isXML String Specifies whether the returned document is XML or HTML.

loadDocument must know this in order to parse a document correctly.

Set isXML to… To…

autoDetect Parse the document based on its type.

When you use this option, loadDocument

senses the document’s type based on its

<!DOCTYPE…> or <?XML…> tag. If it cannot

determine a document’s type, it parses it asHTML.

true Parse the document as XML.

false Parse the document as HTML.

The default value is autoDetect

loadAs String Specifies the form in which you want loadDocument to make the

parsed document available to subsequent services.

Set loadAs to… To…

bytes Pass the parsed document as a byte array.


as input to a service that operates on wholedocuments (for example, queryDocument).

stream Pass the parsed document as an input stream.


as input to a service that can process a

document incrementally (for example,

getNodeIterator).


node Document Document object containing the parsed HTML or XML document. This

object can be used as input to any service that accepts a node.

pub.web:makeArraysDescription Produces a String[ ] array that can be sent to pub.web:DocumentToRecord based on the values in the

document's DTD.


node Object Any node in a parsed Document object (node can be produced by

loadDocument, stringToDocument or XML content handlers).


arrays String[ ] Array of element names for each repeating element in the document.

This variable will be null if the document's DTD is not found or if

there is no DTD references in the document specified by node.



Web Services


pub.web:queryDocument

Description Executes queries on a document, region or node to generate output variables. Each field specifies how

data is extracted from the document to yield an output variable. This output variable may be called a

binding , because the field parameter binds a certain part of the document to an output variable. An

invocation must include at least one field entry.

− The fields parameter can contain nested definitions of fields, which will produce a nested binding as

the result.

− If a fields parameter is to create an instance of each of the children for each result, it should have

resultType Record[].

− If a fields parameter is to create only a set of children for the first result value, it should be defined

with resultType Record.

− If a fields parameter has any children, it's query must return a node object and be defined as

resultType Record or return a node array and be defined as resultType Record[].

− If a parent has no query, the children query the same node that the parent would have, allowing you

to group child results into a Record or Record [].

− If the parent returns a node, each child queries that node (and only that node) once and fills the

Values object. In this case, the parent must be defined as returning a Record (not an Object).

If the parent returns a node array, each child queries each node once and fills the Values[ ] object. In this

case, the parent must be defined as returning Record[] (not an Object[]).The result of each root field (top

level parent) is put into the pipeline in a variable named for the field name. Child fields cannot reference

a region unless the parent node has no query and the input node is set to a region.


node Node

Document

Region

The node that you want to query. (A node is produced by

loadDocument, stringToDocument, createRegions or one the B2B

Server content handlers.)

nsDecls

optional

Values

Values[ ]Vector

String[ ][2]

XML namespace declarations to use with the XQL queries specified

with the fields input. When nsDecls is a Values[], each Values object provides a namespace declaration and is defined as follows:


Prefix String Prefix that represents the URI in queries.

Uri String URL identifying the XML namespace.






second is the URI.

fields Values[ ] Each field defines how a value is extracted from a document. This

parameter defines fields for the values that are to be extracted. Each

field is defined as follows:


Name String Name to assign to resulting value.

resultType String Primitive type of the value or values that

the query is to yield. Valid values are

Object, Object[], Object[][], String,

String[], and String[][].

queryType String Query language in which the query for

the value is expressed. Valid values areWQL and XQL.

query String Query identifying the value to return.

onnull String Specifies what you want queryDocument

to do when the result is null:

continue —All result values are legal.

fail —If the result of the query is null,

the service fails. If the result of the query

is not-null, the service continues.

succeed —If the result of the query is

null, the service continues. If the result of

the query is not-null, the service fails.

Fields Values A nested set of fields parameters that

support recursive execution of bindings.

Each array of fields records define

bindings for one level of the output with

the top level being the pipeline and the

first level down being contents of a

Values or Values[] object that is in the

pipeline.

Output Values object defined by the fields input specifications. There will be one output variable for each field

specified with nested Values objects for the results of the child fields.

pub.web:recordToDocument

Description Converts a Values object into an XML string. Recurses through the given Values object building an

XML String from the values. Values object keys are turned into tag names and the Values object values

are turned into the body of each tag. Key names starting with the attribute prefix are turned into attributes

of the parent Values object.


boundNode Values Values objects that include all the nodes and attributes of the document

organized based on the array and collection rules.

attrPrefix

optional

String String that allows for a customized attribute prefix.

The default is "@".

addHeader optional

String Specifies whether the header <?xml version=”1.0”?> should beadded to the output XML string. Set to true or false.

Setting to false will allow for the caller to build an XML file using

repeated calls to recordToDocument and allow the caller to add a

custom header to the document.

Default is true.



Web Services


nsDecls

optional

Values,

Values[ ],

Vector,

String[ ][2]

XML namespace declarations to use with the element type names

found in arrays and collections.

When nsDecls is a Values[ ], each Values object provides a namespace

declaration and is defined as follows:



uri String URI identifying the XML namespace.





When it is a String[ ][2], the first column is the prefix and the second is

the URL.


xmldata String An XML document.

pub.web:stringToDocument

Description Converts a text string representing an XML document into a Document object.


xmldata String Text string to convert to a document.

encoding

optional

String Character encoding in which text is represented to use when parsing the

document. Specify UTF-8 for XML files and ISO-8859-1 for HTML

files. To have the parser attempt to detect the type of encoding, specify

autoDetect.


node Document Document object representing the parsed document. The output can by

input into any service that accepts a node.





WebTap Services and Speci f icat ions

You use the WebTap services and specification to develop

pub.webtap:getPage

Description Maps all URLs of the supplied page so that subsequent requests go back through this service.

This service can be used to test WebTap’s url-mapping abilities on a particular site. It may also be

sufficient for some applications that only need WebTap in order to utilize HTTP authentication

information in order to access links from protected web pages.

This service is only for use by Browser clients. Also, customized WebTap capabilities, such as rules

engine or custom triggers, are only available via user-generated WebTap services.


reqUrl Web page URL that will be retrieved and mapped before being returned to the

caller’s browser.

mapJS Optional. Specify “true” to have Javascript-manipulated URLs mapped. Notethat this feature handles many common cases; however, it does not handle URLs

defined in document.write() or eval() blocks.

Output none

Usage Notes If you invoke this service from the Browser’s command line rather than the Developer make sure

to URL encode any prohibited characters within the reqUrl argument.

Example:

http://localhost:5555/invoke/wm.pub/getPage?reqUrl=http%3A%2F%2Fquote.yahoo.com%2F

pub.webtap:tr iggerSpec

Description Provides the signature for ‘trigger’ services invoked by the WebTap rules engine. Use thisspecification when you create such services in B2B Developer.

The signature provides identical inputs and outputs so that the data and the control options are

available for one service or a sequence of services.


WebtapData Values object (record) containing all inputs to WebTap service (e.g. reqUrl and

other variables in query string or cgi post data. The elements of this record are

unspecified as they vary for each WebTap request.

WebtapControl Values object (record) containing control variables that identify current request

and can be used to redirect the flow of the WebTap request. The variables are

specified below.

reqUrl Corresponds to requested web page – e.g. as specified in pub.webtap:getPage.Modify to redirect request.

reqVals Null. Set to provide substitute inputs when redirecting to a different url.

rspUrl Null. Set on response (read-only) if request was redirected to indicate url of

returned page.

rspVals Null. Set to Values object (record) to interrupt normal WebTap sequence and

force return of alternate data either on request or response.




A P P E N D I X

Supported Data Types



APPENDIX D Supported Data Types


Data is passed in and out of a B2B service through a Values object. The Values object

stores individual data items in a hash table which the service retrieves the data that it needs

using the get method.

The following data types are used by B2B services.

B2B Data Type Java Data Type

String java.lang.String

String List java.lang.String[ ]

String Table 2-dimensional String: java.lang.String[ ][ ]

Record An extended version of the Java hashtable. See com.pub.Values.

Record List Same as above, but an array of them (Values[ ]). com.pub.Table

will also appear as a Record List in the GUI (since it can be

transformed into one). Table is used by the database and SAP

packages.

Object Any data type that does not fall into the above list will be shown

as an object. Example: java.util.Vector

Object List Same as above, but array type. Example: java.util.Vector[ ]




A P P E N D I X

Regular Expressions

What is a Regular Expression? ...............................................288

Using a Regular Expression in a Mask....................................288

Regular Expression Operators ................................................289



APPENDIX E Regular Expressions


What is a Regular Expression?

A regular expression is a pattern-matching technique used extensively in UNIX

environments. webMethods B2B lets you use regular expressions to specify pattern-

matching strings for some of its functions. For example, you can use a regular expressionto specify an index, a property, or a mask in a webMethods Query Language (WQL)

statement. You can also use a regular expression to specify the switch value for a

BRANCH operation or to describe a URL in a WebTap rule.

To specify a regular expression, you must enclose the expression between / symbols.

When the server encounters this symbol, it knows to interpret the characters between these

symbols as a pattern-matching string (i.e., a regular expression).

A simple pattern-matching string such as /string / matches any element that contains

string. So, for example, the regular expression /webMethods/ would match all of the

following strings:

“webMethods”

“You use webMethods B2B Server to execute services”

“Exchanging data with XML is easy using webMethods”

“webMethods B2B Integration Server”

! Characters in regular expressions are case-sensitive.

Using a Regular Expression in a Mask

When you use a regular expression as a mask, you use parenthesis to specify which

characters you want to collect. For example, the object reference:

doc.p[].text[/(.{30}).*/]

retains the first 30 characters in each matching element and discards the rest.



Regular Expression Operators



The following documents the operators supported in webMethod’s implementation of

regular expressions.

Use this symbol… To…

. Match any single character except a new line.

Example: doc.p[/web.ethods/].text

This example would return any paragraph containing the string ‘web’

followed by any single character and the string ‘ethods’. It would match

both ‘webMethods’ and ‘webmethods’.

^ Match the beginning of the string or line.

Example: doc.p[/^webMethods/].text

This example would return any paragraph containing the string‘webMethods’ at the beginning of the element or at the beginning of any

line within that element.

$ Match the end of the string or line.

Example: doc.p[/webMethods$/].text

This example would return any paragraph containing the string

‘webMethods’ at the end of the paragraph element or at the end of any


* Match the preceding item zero or more times.

Example: doc.p[/part *555-A/].textThis example would return any paragraph containing the string ‘part’

followed by zero or more spaces and then the characters ‘555-A’.

+ Match the preceding item 1 or more times.

Example: doc.p[/part number +555-A/].text

This example would return any paragraph containing the string ‘part’

followed by one or more spaces and then the characters ‘555-A’.

? Match the preceding item 0 or 1 times.

Example: doc.p[/part ?555-A/].text

This example would return any paragraph containing the string ‘partnumber’ followed by zero or one space and then the characters ‘555-A’.

( ) When used in an index, these characters group an item within the regular

expression.

Example: doc.p[/part(,0)May+/].text

This example would return any paragraph containing the string ‘part’






followed by one or more occurrences of the characters ‘,0’ and then the

characters ‘May”.

When used in a mask, they specify characters that you want to retain.

Example: doc.p[].text[(^.{25}).*]

This example would keep the first 25 characters within each paragraph

and discard the rest.

{n } Match the preceding item exactly n times.

Example: doc.p[/^.{24}webmethods/].text

This example would return any paragraph in which the word

‘webmethods’ started in the 25th character position of the paragraph.

{n ,} Match the preceding item n or more times.

Example: doc.p[/^.{10,}webmethods/].text


‘webmethods’ appeared anywhere after the 10th character position of the

paragraph.

{,m } Match the preceding item none or at most m times.

Example: doc.p[/^.{,4}webmethods/].text


‘webmethods’ started in any of the first 5 character positions of the

paragraph.

{n ,m } Match the preceding item at least n times, but not more than m times.

Example: doc.p[/^.{1,4}webmethods/].text


‘webmethods’ started in character position 2 through 5 of the paragraph.

| Match the expression that precedes or follows this character.

Example: doc.p[/webmethods|webMethods/].text

This example would return any paragraph that contained either

‘webmethods’ or ‘webMethods’.

\b Match a word boundary.

Example: doc.p[/\bport\b/].text

This example would return any paragraph that contained the word ‘port’,

but not paragraphs that contained these characters as part of a larger

word, such as ‘import’, ‘support’, ‘ports’ or ‘ported’.

\B Match a boundary that isn’t a word boundary.

Example: doc.p[/\B555-A/].text

This example would return any paragraph that contained the characters






‘555-A’ as part of a larger word such as AZ555-A, or Dept555-A, but

not ‘555-A’ alone.

\A Match only at the beginning of a string (equivalent to ̂ ).

Example: doc.p[/\AwebMethods/].text


‘webMethods’ at the beginning of the element or at the beginning of any


\Z Match only at the end of a string (or before a new line at the end).

Example: doc.p[/webMethods\Z/].text


‘webMethods’ at the end of the paragraph element or at the end of any


\n Match a new lineExample: doc.p[/webMethods\n/].text


‘webMethods’ followed by the new line character.

\r Match a carriage return

Example: doc.p[/webMethods\r/].text


‘webMethods’ followed by a carriage return.

\t Match a tab character

Example: doc.p[/\twebMethods/].text


‘webMethods’ preceded by a tab character.

\f Match a form feed character

Example: doc.p[/webMethods\f/].text


‘webMethods’ followed by a form feed character.

\d Match any digit. Same as [0-9]

Example: doc.p[/part \d555-A/].text

This example would return any paragraph containing a part number that

starts with any digit 0 through 9, and is followed by the characters 555-

A. Therefore, it would match ‘part 1555-A’ but not ‘part A555-A’ or

‘part #555-A’.

\D Match any non-digit. Same as [^0-9]

Example: doc.p[/part \D555-A/].text







starts with any character other than 0 through 9, and is followed by the

characters 555-A. Therefore, it would match ‘part A555-A’ and ‘part

#555-A’, but not ‘part 1555-A’.

\w Match any word character. Same as [0-9a-z_A-Z]

Example: doc.p[/part \w4555-A/].text


starts with a letter or digit and is followed by the characters 555-A.

Therefore, it would match ‘part A555-A’ and ‘part 1555-A’, but not

‘part #555-A’.

\W Match any nonword character. Same as [^0-9a-z_A-Z]

Example: doc.p[/part \W4555-A/].text


starts with a character other than a letter or digit, and is followed by thecharacters 555-A. Therefore, it would match ‘part #555-A’ and ‘part -

555-A’, but not ‘part 1555-A’ or ‘part A555-A’.

\s Match any white-space character. Same as [\t\n\r\f]

Example: doc.p[/\swebMethods/].text


‘webMethods’ if it is preceded by a tab character, a new line character, a

carriage return, or a form-feed character.

\S Match any nonwhite-space character. Same as [^\t\n\r\f]

Example: doc.p[/\SwebMethods/].textThis example would return any paragraph containing the string

‘webMethods’, if that string is not preceded by a tab character, a new

line character, a carriage return, or a form-feed character.

\0 Match a null string

Example: doc.p[/[^\0]/].text

This example would return any paragraph that is not empty (null).

\xnn Match any character with the hexadecimal value nn.

Example: doc.p[/\x1FwebMethods/].text

This example would return any paragraph containing the ASCII unit-separator character (1F) followed by the characters ‘webMethods’.

[ ] Match any character within the brackets.

Example: doc.p[/part [023]555-A/].text


starts with the numbers 0, 2, or 3 and is followed by the characters 555-






A. Therefore, it would match ‘part 0555-A’ and ‘part 2555-A’, but not

‘part 4555-A’.

The following characters have special meaning when used within

brackets:

Use this char… To…

^ Exclude characters from the pattern.

Example: doc.p[/part 4555-[^023]/].text

This example would return any paragraph containing a

part number that does not start with the numbers 0, 2,

or 3, but is followed by the characters 555-A.

Therefore, it would match ‘part 4555-A’ and ‘part

A555-A’, but not ‘part 0555-A’.

- Specify a range of allowed characters.

Example: doc.p[/part 4555-[A-M]/].text

This example would return any paragraph containing a

part number that starts with any letter A through M

and is followed by the characters 555-A. Therefore, it

would match ‘part A555-A’ and ‘part J555-A’, but not

‘part N555-A’.




A P P E N D I X

Output Template Tags

%comment% ...........................................................................298

%ifvar% ...................................................................................299

%include%...............................................................................301

%loop% ...................................................................................302

%nl% .......................................................................................304

%rename%..............................................................................305

%scope% ................................................................................306

%switch% ................................................................................309

%value% .................................................................................310



APPENDIX F Output Template Tags


Overview

This appendix describes the syntax for B2B tags that you use to insert variable information

into output templates.

!B2B tags are case-sensitive and must be typed into an output template exactly as described in thisappendix. Also, all text between %…% symbols in a tag must appear on one line (i.e., no line breaks).

The examples shown in this appendix assume a Values object that looks as follows:

Values Object

Variable Name Value

submittor Mark Asante

shipNum 991015-00104

shipDate 10/15/99

carrier UPS

serviceLevel Ground

arrivalDate 10/18/99

itemsVariable Name Value

qty 10

stockNum BK-XS160

description Extreme Spline 160 Snowboard- Black

orderNum GSG-99401088

status Partial Order

qty 15

stockNum WT-XS160

description Extreme Spline 160 Snowboard- White

orderNum GSG-99401088

status Complete

supplierInfo Variable Name Value

companyName Bitterroot Boards, LLC

streetAddr1 1290 Antelope Drive

streeAddr2city Missoula

state MT

postalCode 59801

supplierID BRB-950817-001

phoneNum 406-721-5000

faxNum 406-721-5001

email [email protected]

buyerInfo Variable Name Value

companyName Global Sporting Goods, Inc.

accountNum

phoneNum (216) 741-7566

faxNum (216) 741-7533

streetAddr1 10211 Brookpark Road

streeAddr2

city Cleveland

state OH

postalCode 22130

email [email protected]

backItems SL-XS170 Extreme Spline 170 Snowboard- Silver

BL-KZ111 Kazoo 111 Junior Board- Blue

BL-KZ121 Kazoo 121 Junior Board- Blue



Overview


%comment%

You use the %comment% tag to include remarks in your template. The server ignores all text (and tags)

between the %comment% and %end% tag.

Syntax %comment%

Block of Code

%end%

Example The following example contains a section of explanatory information about the

template.

%comment%Use this template to generate an order list from any Record containing apurchased item number, quantity, description, and PO number%end%<tr><td>%value stockNum%</td>

<td>%value qty%</td><td>%value description%</td><td>%value orderNum%</td></tr>



Overview


%ifvar%

You use the %ifvar% tag to conditionally include or exclude a block of code based on the existence or the

value of a specified variable.

Syntax %ifvar Variable [option option option…]%

Block of Code

[%else%

Block of Code]

%end%

Arguments Variable specifies the name of the variable that determines whether or not the

enclosed block of code is processed.

When %ifvar% is used with Variable alone (i.e., no switches or options) the

Options You may use any of the following options with this tag. To specify multiple options,separate them with spaces.

Options Description

-isnull Includes the enclosed segment of the template only if Variable

is null.

Example %ifvar –isnull backItems%

-notempty Includes the enclosed segment of the template only if Variable

contains one or more characters (for string variables) or has one

or more elements (for array variables).

Example %ifvar –notempty supplierInfo/email%

equals(' AnyString ') Includes the enclosed segment of the template only if the value

of Variable matches the string you specify in AnyString .

( AnyString is case-sensitive. 'FedEx' does not match 'Fedex' or

'FEDEX').

Example %ifvar carrier equals('FedEx')%

vequals( RefVar ) Includes the enclosed segment of the template only if the value

of Variable matches the value of the variable you specify in

RefVar .

Example %ifvar supplierInfo/state vequals(buyerInfo/state)%

Notes For readability, you can optionally use %endif% or %endifvar% instead of %end% to

denote the end of a %ifvar% block.

ExamplesThe following example inserts a paragraph if a variable named AuthCode exists.

...%ifvar AuthCode%

Authorization Code Received %value $date%: %value AuthCode%%endif%

.

..

The following example generates a line for each element in the backItems String List

only if there are items in backItems....

%ifvar –notempty backitems%The following items are backordered%loop backItems%

%value% %endloop%

%endif%

...

The following example generates a line for each element in the backItems String List

only if there are items in backItems, otherwise it prints a standard message.

...%ifvar –notempty backitems%

The following items are backordered%loop backItems%

%value% %endloop%

%else%

There are no backordered items pending for your account%end%

..

.

Overview


%include%

You use the %include% tag to reference an external template file from within a template. When you

%include% an external template, the server inserts the contents of the specified file (processing any tags it

may contain) at run time. If you use output templates extensively, you may want to build a library of

standard template “fragments” that you reference through %include% tags as needed.

Syntax %include FileName%

Arguments FileName specifies the name of the file containing the external template. If the

external template is not in the same directory as the referencing template, FileName

must include path information that defines the file’s location relative to the

referencing template.

Notes The inserted template inherits the scope that is in effect at the point it is called.

Examples The following example inserts a file called “TMPL_ShipToBlock.html” into the

template. Since path information is not provided, the server will expect to find this

file in the same directory as the referencing template....

%scope buyerInfo%Shipped To: 

%include TMPL_ShipToBlock.html%%end%

...

The following example inserts a file called “TMPL_ShipToBlock.html” into the

template. At run time, the server will expect to find this file in a subdirectory called

“StandardTemplates” beneath the location of the referencing template....


%include StandardTemplates/TMPL_ShipToBlock.html%%end%

...

The following example inserts a file called “TMPL_ShipToBlock.html” into the

template. At run time, the server will expect to find this file in the parent directory

of the referencing template....

%scope buyerInfo%

Shipped To: %include ../TMPL_ShipToBlock.html%%end%

...





%loop%

You use the %loop% tag to repeat a block of code once for each element in a specified array (String List or

Record List) or for each key in a Record.

Syntax %loop [Variable] [option option option…] %

Block of Code

%end%

Arguments Variable specifies the name of the array variable over which you want the enclosed

section of the template to iterate. You may optionally omit Variable and specify the

–struct option to loop over each element in the current scope.

If Variable is a… The loop is applied to…

String List Each String in the list.

Record List Each Record in the Record List.Record Each key in the Record (Values object). (Include the –struct option

when you use %loop% with a Record.)

Options You may use any of the following options with this tag. To specify multiple options,

separate them with spaces.

Option Description

-struct Specifies that Variable is a Record (Values object) and

instructs the server to apply the loop to key in that Record.

-eol Ends the body of the loop at the next end-of-line (EOL)character in the template. When you use –eol, you can omit the

%end% tag, since the server will use an EOL to signal the end

of the loop block.

Notes You may optionally omit the variable name from a %values% tag in the body of a

loop for a String table or a Record. When you omit the variable name, the server

automatically inserts the current element into the template.

For readability, you can optionally use %endloop% instead of %end% to denote the

end of a %loop% block.

Overview


Examples The following example generates a paragraph for each record in the items Record

List....

This shipment contains the following items:%loop items%

%value qty% %value stockNum% %value description% value status%%end%...

The following example generates a line for each element in the backItems String

List....

The following items are backordered%loop backItems%

%value% %end%

...

The following example shows how you can nest %loop% tags to process the

individual Record elements in a Record list....

<This shipment contains the following items:<table>%loop items%<tr>

%loop –struct%<td>%value%</td>%end%

</tr>%end%

...

%nl%

You use the %nl% tag to generate a blank line (a line containing only an end-of-line character). This tag is

useful for generating white space in your output, since the server does not pass blank lines from your

template into the output stream. (The server eliminates blank lines to create a compact and efficient output

stream, but the result can often be difficult to read for debugging purposes.) If you want to blank lines to

appear in your output stream, you must insert a %nl% tag at those points where you want a blank line to

appear.

Syntax %newline%

ExamplesThe following example, the server will insert three blank lines to preserve the

vertical space between the two blocks of code.

...<hr>Departure Information: Ship Date: %value shipDate% Carrier: %value carrier% Shipment Number: %value shipNum%%nl%%nl%%nl%<hr>Arrival Information: FOB: %value companyName% %value streetAddr1%%value streetAddr%2%value city%, %value state%

...

Overview


%rename%

You use the %rename% tag to rename a variable in the current scope or to copy it to another key.

Syntax %rename SourceVar TargetVar [option option option…]

Arguments SourceVar is the name of the variable that you want to rename or copy.

TargetVar specifies the name that you want to assign to SourceVar (if you are

renaming it) or to which want to copy SourceVar (if you are copying it).

Options You may use he following option with this tag.

Option Description

-copy Copies SourceVar to TargetVar instead of moving

(renaming) SourceVar . When you use the –copy option, you

can refer to the variable by it original name or its new name.

Notes You can only copy (or rename) one variable to another in the same scope.

Examples The following example renames the state variable in the buyerInfo Record to ST ....

%scope buyerInfo%%rename state ST%

%include TMPL_ShipToBlock.html%%end%

...

The following example copies the copies the stockNum variable in the items RecordList to SKU .

...%rename items/stockNum items/SKU% -copy%

%include TMPL_ItemList.html%...





%scope%

You use the %scope% tag to restrict a specified block of the template to a particular Record in the Values

object. You can also use the %scope% tag to define a completely new Record and switch the scope to that

record.

Syntax %scope [ RecordName] [option option option…]%

Block of Code

%end%

Arguments RecordName specifies the name of a Record within the current scope. If you do not

specify RecordName, the param and rparam options will extend the current scope.

If you specify a new RecordName, that record becomes the current scope.

Options You may use any of the following options to add elements to the scope specified by

RecordName.

When you specify multiple options, separate them with spaces.

! If you specify the name of an existing variable when you use the following

parameters, the value you specify will replace that variable's current value.

Option Description

param( Name='Value') Defines a new String or String array with the

name you specify in Name and assigns to it, the

string you specify in Value.

If Name is a String, specify one Value and enclose

it in single quotes.

Example %scope param(buyerClass='Gold')

If Name is a String array:

— Include a set of empty brackets at the end of

the name to indicate that you are defining an

array

— Enclose each element Value in single quotes.

— Separate elements with commas.

Example %scope param(shipPoints[]='BWI','LAX',

'ORD','MSP',DFW')

Overview


rparam( Name={ Key='Value';

Key='Value'; Key='Value'})

Defines a new Record (Values object) or Record

List (Values array) with the name you specify in

Name, and assigns to it, values that you provide in

a list of Key=Value pairs.

If Name is a Record: — Enclose its list of elements in braces { }

— Separate the elements with semi-colons

— Enclose Value strings in single quotes

Example %scope rparam(custServiceInfo=

{csClass='Gold';csPhone='800-444-2300';

csRep='Lauren Chueng'})%

If Name is a Record List:

— Enclose each Record in the list with braces { }

— Separate Records with vertical bars |. — Separate elements within each Record with

semi-colons

— Enclose Value strings in single quotes.

Example %scope rparam(custServiceCtrs[]=

{csName='Memphis';csPhone='800-444-2300';}|

{csName='Troy';csPhone='800-444-3300';}|

{csName='Austin';csPhone='800-444-4300';})%

Notes The specified scope remains in effect until the next %scope% tag is encountered

(which declares a new scope) or the next, non-nested %end% tag is encountered(which reverts to the prior scope).

For readability, you may use %endscope% instead of %end% to denote the end of a

%scope% structure.

Examples The following example sets the scope to the record named buyerInfo....


%value companyName% %value streetAddr1% %value streetAddr2% %value city%, %value state% %value postalCode%

%end%...

The following example sets the scope to Record buyerInfo and then uses the param

option to add variables called buyerClass and shippingPoint to that Record.....

%scope buyerInfo param(buyerClass='Gold') param(shipPoint='BWI Hub')%

Shipped To: %value companyName% %value streetAddr1% %value streetAddr2% %value city%, %value state% %value postalCode%

<hr>Point of Departure: %value shipPoint% Customer Class: %value buyerClass%

%end%...

The following example sets the scope to Record buyerInfo and then uses the rparam

option to add a Record called custServiceInfo to it.....

%scope buyerInfo% rparam(custServiceInfo={csCtr=Memphis;csPhone=800-444-2300;csRep=Lauren Chueng})%Shipped To: 

%value companyName% %value streetAddr1% %value streetAddr2% %value city%, %value state% %value postalCode%

<hr>%scope custServiceInfo%

For questions or issues about this shipment, contact our CustomerServices Center in %value csCtr% at %value csPhone%. Your accountrepresentative is %value csRep%.

%endscope%%endscope%

...

Overview


%switch%

You use the %switch% tag to insert one block from a set of predefined alternatives based on the value of a

specified variable at run time. In many instances, the %switch% tag is an easy-to-build alternative to the

%ifvar% tag.

Syntax %switch Variable%

%case 'SwitchValue'%

Block of Code

%case 'SwitchValue'%

Block of Code...

[%case%

Default Block of Code]

%end%

Arguments Variable specifies the name of the variable whose value will determine which case

is inserted into the output stream at run time. SwitchValue is a string that specifies

the value that will cause the associated case to be processed at run time.

Notes To select a case, SwitchValue must match the value of Variable exactly.

(SwithValue is case-sensitive. 'FedEx' does not match 'Fedex' or 'FEDEX').

The server evaluates %case% tags in the order they appear in the template. When it

finds a “true” case, it processes the associated block of code and then exits the

%switch%…%end% structure.

You can specify a default case by using the %case% tag without a SwitchValue. The

block of code associated with the default case is processed only if none of the other

cases are true.

If you use %case% without SwitchValue, it must appear as the last %case% in the

%switch%…%end% structure.

For readability, you can optionally use %endswitch% instead of %end% to denote

the end of a %switch% structure.

Examples The following example inserts a specified paragraph in the output stream depending

on the value in carrier ..

..%switch carrier%

%case 'FedEx'%Shipped via Federal Express %value serviceLevel% %value trackNum%

%case 'UPS'%Shipped via UPS %value serviceLevel%

%case 'Freight'%Shipped via %transCompany% 

FOB: %value buyerInfo/streetAddr1% %value buyerInfo/streetAddr2% %value city%, %value state% %postalCode%

%end%

...

%value%

You use this tag to insert the value of a specified variable in the output stream.

Syntax %value Variable [option option option…]%

Arguments Variable specifies the name of the variable whose value you want to insert into the

template. Variable can specify any String or String element in the Values object or

one of the following system variables:


$host Inserts the name of the server that produced the output stream.

$date Inserts the current date in “Weekday Month Day HH:MM:SS

Locale Year” format (e.g. Fri Aug 12 04:15:30 Pacific 1999).

$key Inserts the value of the current key. For use with the %loop%

tags which repeats a section of a template once for each

element in a specified array variable. See %loop% on page

302.

$lastmod Inserts the date and time that the template file was last

modified in “Weekday Month Day HH:MM:SS Locale Year”

format (e.g. Fri Aug 12 04:15:30 Pacific 1999).

When you specify a Variable name, the server retrieves the variable from the

current scope. To select a variable outside the current scope, use the followingsymbols to address it. For example,

You would use… To…

/Variable Insert Variable from the root Values object.

.. /Variable Insert Variable from the parent container of the current scope.

Options You may use any of the following options with this tag. To specify multiple options,

separate the options with spaces.

Option Description

null=' AnyString ' Specifies the string that you want the server to insert into theoutput template when Variable is null. You specify the string

in AnyString .

Example %value carrier null='No Carrier Assigned'%



Overview


empty= AnyString Specifies the string that you want the server to insert into the

output template when Variable contains an empty string. You

specify the string in AnyString .

Example %value description empty='Description Not Found'%

index= IndexNum Specifies the index of a Sting List element that you want to

insert into the output template. Specify an integer that

represents the element’s position in the array (all arrays in a

Values object are zero-based)

Example %value backItems index=1%

encode=(Code) Encodes the contents of Variable before inserting it into the

output template, where Code specifies the encoding system

you want the server to apply to the string.

set Code to… To encode the value using…

xml XML encoding.

b64 Base-64 encoding.

url URL encoding.

decode=(Code) Decodes the contents of Variable before inserting it into the

output template, where Code specifies the way in which

Variable is currently encoded.

set Code to… To encode the value using…

b64 Base-64 encoding.

url URL encoding.

Examples The following example inserts the contents of carrier . If carrier is null, the string

“UPS” is inserted. If carrier is empty, the string “UPS” is also inserted.

%value carrier null=UPS empty=UPS%




A P P E N D I X

jcode tags

jcode Template........................................................................314

jcode Example......................................................................... 315

APPENDIX G 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 B2B jcode utility.*/

// --- <<B2B-START-IMPORTS>> ---import com.wm.util.Values;// --- <<B2B-END-IMPORTS>> ---

public class Interface2{

public static Values Service1 (Values in){

Values out = in;

// --- <<B2B-START(Service1)>> ---// --- <<B2B-END>> ---return out;

}

public static Values Service2 (Values in){

Values out = in;// --- <<B2B-START(Service2)>> ---// --- <<B2B-END>> ---return out;

}

// --- <<B2B-START-SHARED>> ---// --- <<B2B-END-SHARED>> ---

}

jcode Example


jcode Example

The following is a complete example of a properly commented Java service.

package recording;

/**

* This is an example of Java source code properly annotated* for use with the B2B 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.*/

// --- <<B2B-START-IMPORTS>> ---import com.wm.util.Values;import java.util.*;// --- <<B2B-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 record. 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)* record (corresponds to instances of com.wm.util.Values)* 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 Values createAccount (Values in){

Values out = in;// --- <<B2B-START(createAccount)>> ---

APPENDIX G jcode tags


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

String name = (String) in.get ("name");String [] refs = (String[]) in.get ("references");Values data = (Values) in.get ("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 the Developer.)

out.put ("message", "createAccount not fully implemented");out.put ("id", "00000000");

// --- <<B2B-END>> ---return out;

}

/**

* == 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 Values getAccount (Values in){

Values out = in;// --- <<B2B-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

String id = (String) in.get ("id");Values data = getAccountInformation(id);out.put ("account", data);

// --- <<B2B-END>> ---return out;

}

/*** == SHARED SOURCE ==* This is where the shared code lives. This includes both* global data structures and non-public functions that aren't* exposed as B2B Services. Note the tags delimiting the start* and end of the shared code section.*/

// --- <<B2B-START-SHARED>> ---

private static Vector accounts = new Vector();

private static Values getAccountInformation (String id) {throw new RuntimeException ("this service is not implemented yet");

}

// --- <<B2B-END-SHARED>> ---

}



jcode Example




INDEX


I N D E X

$

$xmldata 149A

access to B2B Integration Server 6 ACL

definition of 6requirements 6

adding a variable to a pipeline map 62addressing document nodes 118adjusting the pipeline 55after service for WebTap 181annotating source code for jcode 83

API 4 API, for Java services 79, 83

arithemetic services 247arithmetic services 65assigning a default value to a variable 60assigning a value to the pipeline 59, 60assigning a variable to a variable 60

B

B2B Integration Server access requirements for 6connecting to 7, 14disconnecting from 14logging on to 7

B2B Wizard

for load-and-query services 127, 129before service for WebTap 181binding options for COM objects 92BRANCH operation

creating a multi-step child for 30definition of 18, 190procedure for building 31specifying the default operation 29specifying the label value 28specifying the switch variable 28use of regular expressions with 28using in a flow 27using SEQUENCE as a target of 30

br owser clientcreating 141for WebTap 186invoking db services from 163invoking services from 142, 143

Browser Recorder for load-and-query service 129procedure for using 130

built-in services 26

for arithemetic operations 65, 247for calling remove services 254for client operations 210for database operations 224for date/time transformations 65for ldap operations 240

for pipeline operations 236for record operations 251for string manipulation 65, 259for table conversions 266for time/date transformations 220for using output templates 256for WebTap 282for working with XML and HTML documents 268

C

C/C+ servicescreating 87procedure for creating 87

C/C++using with B2B 87

C/C++ clientcreating 135for database service 165procedure for creating 136

C/C++ servicesaccessing databases through 161

children of a flow operation 24class files, location of 84client code

creating in browser 141creating in Excel 139creating with C/C++ 135

creating with Java 134creating with Visual Basic 137definition of 134for database services 163, 165what is 134

COM objectsinvoking as services 96using with B2B 91

COM service, invoking 92, 94COM-based services

creating 91comment property 25comments for jcode 83

compiling services in C/C++ 90compiling services in Visual Basic 92compiling services with Developer 80compiling services with jcode 85, 86composite mode (jcode) 86comwrap utility 94connecting to B2B Integration Server 7, 14conventions used in this document 2, 3converting date formats 65



INDEX

B2B Developer’s Guide Version 3.0

converting time formats 65creating

a flow service 18, 20, 21a Java service in C/C++ 87a Java service with Developer 75a Java service with own IDE 82

a Java service with Visual Basic 91a new package 21, 76, 87a specification for a C/C++ service 87a specification f or a Java service 80an interface 21, 76, 87

creating new elements 12

D

data types 286mapping with Pipeline Editor 58

database servicebuilding in Java, C/C++ or VB 161converting db rows to Values 163creating 154creating from a table 159error handling 163flow services 155generating from a SQL statement 156generating from a table 158invoking from a browser 163invoking from a client app 165procedure for creating 157, 159

database services 224date conversion services 65date transformation services 65date-conversion services 220default value, assigning to a pipeline variable 60

directories for Java services 84dispatch

createObject 96dispatch services for COM 96Document object 104Document View tab 120documentation

conventions used in 2printing 4related manuals 3using effectively 2

Drop modifier 64DROP modifier 55, 61

dropping a value to the pipeline 61E

early binding 92, 94editing a flow service 18Editor pane 11elements

creating 12displayed in Service Browser 9

saving 13error handling

for a flow service 38Excel client

creating 139procedure for creating 140

exit condition, specifying 38exit on property 38EXIT operation

definition of 18, 192using in a flow 42

extending the Java class 78extends Java keyword 78external records

assigning to a Record or Record List 51assigning to a specification 51benefits of 51creating 51procedure for assigning to a Record or Record List 53

procedure for assigning to a specification 52procedure for creating 51external specification

assigning to a service 50benefits of 48creating 48definition of 20procedure for creating 49

F

failure of a flow operation 38flow control operations

BRANCH 18, 27definition of 17

EXIT 18, 42LOOP 18, 39REPEAT 18, 33SEQUENCE 18, 38using in a flow 27

flow operationsBRANCH 18, 27definition of 18EXIT 18, 42failure of 38hierarchical order of 24inserting into a flow service 22INVOKE 18, 25

LOOP 18, 39MAP 19MAP operation 63moving within a flow service 23, 24parent/child relationships 24properties 25REPEAT 18, 33SEQUENCE 18, 38

Flow Pane



INDEX


inserting operations into 23flow service

creating 18definition of 16editing 18inserting operations into 23

relationship to WIDL 17, 104response to failure 38stages of creating 20

frag mode (jcode) 86FTPing XML to a service 151

G

Generate Code command 134, 136, 138generating code for Java services 81getting started 3grouping flow operations 38guaranteed delivery

creating client code for 172error handling 171heuristic errors 172Job Manager 168sample code 173server properties 169TTL 170using 168what is 168

H

hailmary mode (jcode) 86help

getting help 14using 14

heuristic errors 172hierarchical order of flow operations 24HTML documents

retrieving 105

I

IDEassigning a super class with 78defining private methods with 78implementing interfaces with 78importing Java packages 78provided by B2B Developer 74, 76using other IDEs 82

using the Shared tab 77using the Source tab 76implementing interfaces in Java services 78implements Java keywor d 78import Java keyword 78, 83importing Java packages 78, 83in-array property 40input variables

declaring in a record 51

declaring in a specification 46mapping from the Pipeline 56

Input/Output tab 45, 80inputs and outputs, declaring 45installing java services 84Integrated Development Environment See IDE

interfaces, implementing in Java service 78INVOKE operation

definition of 18, 194invoking built-in services 26service property 26using in a flow 25

invoking a Visual Basic service 92invoking db services from a browser 163, 165invoking remote services 254invoking service from a browser 142invoking services from a browser 143invoking Webtap services 186

J

Javausing with B2B 74, 75, 82

Java clientcreating 134for database service 165procedure for creating 135

Java servicesaccessing databases through 161adding private methods to 78annotating for jcode 83class file location 84compiling with jcode 85creating with Developer 75

creating with own IDE 82extending the class of 78generating code for 81implementing interfaces in 78importing packages into 78, 83installing manually 84procedure for building 78required code 83setting run-time options 82source file location 84specifications for 80stages of development 75

Java Virtual Machine

requirements for COM objects 91 jcode

examples 314 jcode utility

composite mode 86frag mode 86hailmary mode 86make mode 85purpose of 84



INDEX


source code tags 83update mode 86

Job Manager 168Jview configuration setting 91Jview requirements 91

Llabel propertyfor general use 25for specifying the default BRANCH operation 29for targeting BRANCH operations 28

late binding 92libs directory 87load-and-query services

creating from URL 127creating with B2B Wizard 127, 129creating with Browser Recorder 129loadDocument 105procedure for creating 105, 121, 128relationship to WIDL 104shortcuts for 127what are 104

loadDocumentcreating from URL 127creating with Browser Recorder 129data variable 108description of 275encoding variable 114error handling 117expandDTD variable 115headers variable 112inputs 107is XML variable 115

loadAs variable 116method variable 108outputs 117procedure for using 105, 128shortcuts 127url variable 107

logging on to B2B Integration Server 7, 14LOOP operation

creating nested loops 39definition of 18, 195procedure for building 41setting in-array 40setting out-array 41

using in a flow 39M

make filecreating 87, 89using to compile 90

make mode (jcode) 85Map modifier 64MAP modifier 55, 56, 57, 58

MAP operationdefinition of 19, 197using in a flow 63using to initialize variables in a flow 64

mapping different data types 58mapping the pipeline 53, 59

masksdescription of 207

methods, adding to a Java service 78modifying the pipeline 55moving an operation within a flow 23, 24

N

namespace informationbuilding source file from 86location of 84updating with jcode 86

nodeaddressing elements in 118extracting information from 118passing to queryDocument 118what is 105

node iterator freeDocument 271getNextNode 272getNodeIterator 273

ns directory 84

O

ob ject referencesdescriptions of 204sibling operators 206

online Help

accessing from B2B Developer 14out-array property 41output templates

applying to Values object 256tag descriptions 296using for non-browser clients 256

output variablesdeclaring in a record 51declaring in a specification 47mapping from the Pipeline 57

Overwrite Pipeline Value option 60

P

packages, importing in Java service 78, 83packages, required by Java services 83panes

behavior and operation 12general layout 9resizing 13Service Browser 9zooming 13

parent/child relationships in a flow 24



INDEX


parsing documents 104passing XML to a service 148Perform Variable Substitution option 60pipeline

adding variables to 62adjusting 55

assigning value to 59definition of 19DROP modifier 61dropping variables from 61MAP operation 63mapping different data types 58mapping input variables 56mapping output variables 57mapping variables 53Overwrite Pipeline Value option 60Perform Variable Substitution option 60Pipeline In 54Pipeline Out 54

procedure for mapping 59Service In 54Service Out 54SET VALUE modifier 59stages of 54

Pipeline Editor 54Pipeline In 54pipeline modifiers

definition of 55DROP 55MAP 55SET VALUE 55

Pipeline Out 54Pipeline tab 54

posting XML to a service 150printing this guide 4private methods, defining in Java service 78programming languages

creating B2B services with 74supported 74

properties 207comment property 25common to all operations 25definition of 25exit on 38in-array 40label (for BRANCH operations) 28, 29

label property 25out-array 41repeat-on 34service property 26switch 28timeout property 32, 35, 41

Properties tab 25pub.client:ftp 210pub.client:http 211

pub.client:smtp 214pub.client.ftp:cd 214pub.client.ftp:cdls 215pub.client.ftp:delete 215pub.client.ftp:get 215pub.client.ftp:login 216

pub.client.ftp:logout 216pub.client.ftp:ls 216pub.client.ftp:mdelete 217pub.client.ftp:mget 217pub.client.ftp:mput 217pub.client.ftp:put 218pub.date:currentDate 221pub.date:dateBuild 221pub.date:dateTimeBuild 221pub.date:dateTimeFormat 222pub.db:call 224pub.db:clearTransaction 224pub.db:close 224

pub.db:

closeAll 225pub.db:commit 225pub.db:connect 225pub.db:delete 226pub.db:execSQL 226pub.db:getProcInfo 228pub.db:getProcs 227pub.db:getTableInfo 229pub.db:getTables 230pub.db:insert 231pub.db:query 232pub.db:rollback 232pub.db:startTransaction 232pub.db:update 233

pub.flow:clearPipeline 236pub.flow:debugLog 236pub.flow:getSession 236pub.flow:restorePipeline 236pub.flow:savePipeline 237pub.flow:setResponse 237pub.flow:tracePipeline 238pub.ldap:bind 240pub.ldap:connect 240pub.ldap:delete 241pub.ldap:disconnect 241pub.ldap:getAttributeDef 241pub.ldap:getClassDef 242

pub.ldap:init 243pub.ldap:list 243pub.ldap:lookup 244pub.ldap:search 244pub.ldap:shutdown 245pub.ldap:update 245pub.math:addFloatList 247pub.math:addFloats 247pub.math:addIntList 247



INDEX


pub.math:addInts 247pub.math:divideFloats 247pub.math:divideInts 248pub.math:multiplyFloatList 248pub.math:multiplyFloats 248pub.math:multiplyIntList 248

pub.math:multiplyInts 248pub.math:subtractFloats 249pub.math:subtractInts 249pub.record:length 251pub.record:recordListToRecord 251pub.record:recordToRecordList 251pub.record:recordToXMLValues 251pub.record:XMLValuesToRecord 252pub.remote:invoke 254pub.report:runFileTemplate 256pub.report:runFileTemplateOnPipe 256pub.report:runStringTemplate 256pub.report:runStringTemplateOnPipe 256

pub.report:

runTemplate 257pub.report:runTemplateOnPipe 257pub.string:bytesToString 259pub.string:concat 259pub.string:HTMLDecode 259pub.string:HTMLEncode 259pub.string:indexOf 259pub.string:length 260pub.string:lookupDictionary 260pub.string:lookupTable 260pub.string:makeString 261pub.string:messageFormat 261pub.string:numericFormat 261pub.string:padLeft 261

pub.string:padRight 262pub.string:replace 262pub.string:stringToBytes 262pub.string:substring 263pub.string:tokenize 263pub.string:toLower 263pub.string:toUpper 263pub.string:trim 264pub.string:URLDecode 264pub.string:URLEncode 264pub.table:recordListToTable 266pub.table:stringTableToTable 266pub.table:tableToRecordList 266

pub.table:tableToStringTable 266pub.web:createRegions 268pub.web:documentToRecord 117, 270pub.web:freeDocument 271pub.web:getDocumentType 271pub.web:getNextNode 272pub.web:getNodeIterator 273pub.web:loadDocument 105, 275pub.web:makeArrays 278

pub.web:queryDocument 118, 279pub.web:recordToDocument 280pub.web:stringToDocument 281pub.webtap:getPage 282pub.webtap:triggerSpec 181, 282

Qqueryprocedure to create 124, 125specifying by pointing 125specifying manually 123what is 105

queryDocumentcreating from URL 127creating with Browser Recorder 129description of 279error handling 126inputs 118output 125procedure for using 121, 128shortcuts 127using WQL with 118using XQL with 118

R

record-conversion services 251records See external recordsrefreshing the Service Browser 10regions, creating 268regular expressions 288

using as BRANCH label 28RelayHandler class 176remote servers, invoking services of 254

removing a value from the pipeline 61REPEAT operation

definition of 18, 198procedure for building (on failure) 35procedure for building (on success) 37specifying the repeat condition 34using in a flow 33using to repeat a successful operation 36using to retry a failed operation 34

repeat-on property 34report services 256resizing window panes 13retrieving documents from the Web 105

retry a flow operations 33rules engine for WebTap 178Rules tab 180run-time settings 82

S

Sample View tab 120saving your work 13sending XML documents via FTP 151



INDEX


sending XML documents via HTTP 150sending XML to a service 148SEQUENCE operation

as target for a BRANCH 30definition of 18, 201setting exit condition of 38

using in a flow 38server See B2B Integration Server Server Administrator’s Guide 3Service Browser 9

icons 9updating contents of 10

Service In 54Service Out 54service property 26services

creating with Visual Basic 91services provided by B2B Integration Server 26Set Value modifier 64

SET VALUE modifier 55, 59setting the value of a variable 59Settings tab 82Shared tab 77sibling operators 206signature of a B2B service 74source code

auto-generating for Java service 81building from namespace information 86compiling with C/C++ make file 90compiling with jcode 85, 86compiling with Visual Basic 92location of 84procedure for building (Java) 81

tagging for jcode 83writing in C/C++ 89writing in Developer 76writing in own Java IDE 82

Source field on Shared tab 78Source tab 76specification

benefits of 45creating 45defining externally 48definition of 20for a Java service 80generating Java code from 81

procedure for creating 47specification for WebTap 181, 282SQL

generating service from 156specifying dynamic SQL 156testing 162

starting the Developer 7startTx method 170

string transformation services 65, 259string, converting to Values object 281structural transformations 58subordinate flow operations See children of a flow

operationsuper class, defining in IDE 78

switch property 28

T

table services 266tabs

general layout 9Properties tab 25selecting 12

tagging source code for jcode 83tags for output templates 296TContext 168template tags 296time conversion services 65time transformation services 65time-conversion services 220timeout property 32, 35, 41time-to-live period See TTLtransaction ids 170transforming data values 65transforming date formats 65transforming time formats 65trigger specification for WebTap 282TTL

specifying 170what is 168

typographical conventions 2, 3

Uupdate mode (jcode) 86URL

for invoking B2B service 142, 143USE JVIEW options 91user account on B2B Integration Server 6

V

value transformationdefinition of 65services provided by webMethods 65

valuesassigning to pipeline variables 60

Values object 74convert to XML Document 280using in a Java service 82

variablesadding to a pipeline map 62declaring in a record 51declaring in a specification 45, 46, 47mapping to and from the pipeline 53mapping to and from the Pipeline 55



INDEX


using as Set Value 60Variables tab 119VB client

for database service 165viewing assigned value of a variable 60Visual Basic

accessing databases through 161procedure for creating 138

Visual Basic clientcreating 137

Visual Basic servicewrapping as a COM object 94

Visual Basic servicescreating 91early binding 92, 94late binding 92procedure to invoke (early binding) 95procedure to invoke (late binding) 92win32.COM

invoke 92, 94invokeLate 92

W

web services 268webMethods API, for Java 83webMethods Query Language

mask descriptions 207object reference descriptions 204overview 204property descriptions 207sibling operators 206wildcard characters 205

WebTap

after services 181before services 181built-in services 282components of 176creating a custom service 184creating a standard service 178creating the service 178custom framework 178, 184invoking from a browser 186procedure for creating standard service 178procedure for defining rules 180process overview 176rerouting example 183rules engine 178rules, creating 179standard framework 178trigger specification 282what is 176

WIDL, and 3.0 104WIDL, using in 3.0 17wildcard characters 205win32.COM

invoke 92, 94invokeLate 92

window layout 9wizard See B2B WizardWmPublic package

definition of 27

WmVDDemo.vpd 91WmWin32 package 91WQL 105, 118

X

XML documentconverting to Values object 270create from Values object 280creating regions in 268

XML documentsand $xmldata 149converting to Values object 148, 281passing to a service 148posting via HTTP 150retrieving 105

XQL 105, 118

Z

zooming a window 13



INDEX




B 2 B I N T E G R A T I O N

B2B Developer’s Guide

VER SIO N 3 .0



Copyright © 1999 by webMethods, Inc. All rights reserved.

B2B Developer and B2B Integration Server are trademarks of webMethods, Inc. webMethods and the webMethods logo areregistered trademarks of webMethods, Inc. All other marks are the property of their respective owners.

webM-DEV-DG-991015



B2B Developer’s Guide Version 3.0 iii

C O N T E N T S

Introduction .............................................................................................................................. 1

Welcome! ........................................................................................................................................................ 2

Typographical Conventions............................................................................................................................. 2

Program Code Conventions..................................................................................................................... 3

Related Documentation................................................................................................................................... 3

Printing this Guide........................................................................................................................................... 4

Getting Started with B2B Developer....................................................................................... 5

What is B2B Developer? ................................................................................................................................. 6

Before You Use B2B Developer...................................................................................................................... 6

Starting B2B Developer................................................................................................................................... 7

The B2B Developer Window........................................................................................................................... 9

Basic Operations........................................................................................................................................... 12

Working in a Pane.................................................................................................................................. 12

Multiple Panes and Tabs ....................................................................................................................... 12

Creating New Elements ......................................................................................................................... 12

Saving Your Work .................................................................................................................................. 13

Resizing Panes ...................................................................................................................................... 13

Connecting and Disconnecting from a Server........................................................................................ 14

Using Online Help .................................................................................................................................. 14

Building Flow Services.......................................................................................................... 15

Basic Concepts ............................................................................................................................................. 16

What is a Flow Service? ........................................................................................................................ 16

What is a Flow Operation?..................................................................................................................... 18

What is the Pipeline? ............................................................................................................................. 19

What is a Specification?......................................................................................................................... 20

A Pr ocess Overview...................................................................................................................................... 20

Creating a New Flow Service........................................................................................................................ 21

Package and Interface Requirements.................................................................................................... 21

Using the Default Logic Options ............................................................................................................ 22

Inserting Flow Operations ............................................................................................................................. 22



iv B2B Developer’s Guide Version 3.0

Changing the Position of an Operation .................................................................................................. 23

Changing the Level of an Operation ...................................................................................................... 24

Setting the Properties of a Flow Operation ............................................................................................ 25

Invoking Services from a Flow ............................................................................................................... 25

Invoking a Built-In Service...................................................................................................................... 26

Using the Flow Control Operations ........................................................................................................ 27

The BRANCH Operation ........................................................................................................................ 27

The REPEAT Operation......................................................................................................................... 33

The SEQUENCE Operation ................................................................................................................... 38

The LOOP Operation ............................................................................................................................. 39

The EXIT Operation ............................................................................................................................... 42

Creating a Specification for a Service ........................................................................................................... 45

Completing the Input/Output Tab ........................................................................................................... 45

Creating an External Specification ......................................................................................................... 48

Creating an External Record Definition.................................................................................................. 51Mapping the Pipeline..................................................................................................................................... 53

What is the Pipeline Editor? ................................................................................................................... 54

Pipeline Modifiers................................................................................................................................... 55

Mapping Pipeline Variables to Service Inputs and Outputs ................................................................... 55

Assigning Values to Pipeline Variables.................................................................................................. 59

Dropping Variables from the Pipeline..................................................................................................... 61

Adding Variables with the Pipeline Editor............................................................................................... 62

Working with the MAP Operation ........................................................................................................... 63

Performing Value Transformations on Pipeline Variables ...................................................................... 65Specifying Run Time Parameters.................................................................................................................. 67

Maintaining the State of a Service ......................................................................................................... 67

Configuring a Service’s Use of Cache.................................................................................................... 68

Building B2B Services with a Programming Language ...................................................... 73

Basic Concepts ............................................................................................................................................. 74

The Values object .................................................................................................................................. 74

Building B2B Services Using Java ................................................................................................................ 74

How Java Services are Organized on the Server.......................................................................................... 75Building a Java Service with the B2B Developer........................................................................................... 75

Using the Developer IDE........................................................................................................................ 76

Creating a Java Service with the Developer’s IDE................................................................................. 78

Creating the Input/Output Specification for a Java Service .................................................................... 80

Setting Run-time Options for a Java Service ......................................................................................... 82



B2B Developer’s Guide Version 3.0 v

Building a Java Service with Your Own IDE.................................................................................................. 82

Writing the Source Code for a Service................................................................................................... 82

Publishing Java Services on the B2B Integration Server....................................................................... 84

Using the jcode Utility ............................................................................................................................ 85

Building a B2B Service Using C/C++ ............................................................................................................ 87

Generating Files for a C/C++ Service .................................................................................................... 87

The Java Code for a C Service.............................................................................................................. 88

Building the C/C++ Source Code........................................................................................................... 89

Building B2B Services Using COM ............................................................................................................... 91

Requirements......................................................................................................................................... 91

Writing a Visual Basic Service ...................................................................................................................... 91

Compiling a Visual Basic Service........................................................................................................... 92

Invoking a Visual Basic Service .................................................................................................................... 92

Invoking Methods from Existing COM Objects.............................................................................................. 96

Creating Output Templates ................................................................................................... 97What is an Output Template? ....................................................................................................................... 98

What Does a Template Look Like? ............................................................................................................... 98

How do You Assign a Template to a Service? .............................................................................................. 99

When Does the B2B Server Use a Template?.............................................................................................. 99

Using Templates to Return Output to a Browser-Based Client .............................................................. 99

Using Templates to Return Output to Other Types of Clients .............................................................. 100

Creating an Output Template...................................................................................................................... 101

Using the Load and Query Services................................................................................... 103

What are the Load and Query Services? .................................................................................................... 104

Basic Concepts ........................................................................................................................................... 104

Using the loadDocument Service................................................................................................................ 105

Adding loadDocument to a Flow Service ............................................................................................. 105

Input and Output Values for loadDocument ......................................................................................... 106

Inputs for loadDocument...................................................................................................................... 107

Output Values from loadDocument...................................................................................................... 117

Error Handling With loadDocument...................................................................................................... 117

Using the queryDocument Service.............................................................................................................. 118Passing a node to queryDocument...................................................................................................... 118

Addressing Information in a node ........................................................................................................ 118

Working with a Sample Document ....................................................................................................... 119

Adding queryDocument to a Flow Service........................................................................................... 121

Specifying a Query............................................................................................................................... 123



B2B Developer’s Guide Version 3.0 vii

Sending an XML Document via FTP ........................................................................................................... 151

Accessing Databases with B2B Services........................................................................... 153

The Types of Services You Can Create...................................................................................................... 154

Deciding What Type of Service to Create ............................................................................................ 154

Creating Database Flow Services............................................................................................................... 155

Generating a Service from a SQL Statement....................................................................................... 156Generating a Service from a Table ...................................................................................................... 158

Creating Database Services with Java, C/C++, or VB ................................................................................ 161

Built-in Database Services................................................................................................................... 162

Testing SQL Statements...................................................................................................................... 162

Error Handling...................................................................................................................................... 163

Creating Clients that Access Databases..................................................................................................... 163

Invoking a Database Service from a Browser-Based Client................................................................. 163

Invoking a Built-in Service from a Java, C/C++, or VB Client............................................................... 165

Using Guaranteed Delivery ................................................................................................. 167

What is Guaranteed Delivery? .................................................................................................................... 168

Indicating You Want to Use Guaranteed Delivery ....................................................................................... 168

How Transactions are Managed ................................................................................................................. 168

Customizing the Job Managers ........................................................................................................... 169

Identifying Transactions .............................................................................................................................. 170

Specifying How Long Transactions are Active ............................................................................................ 170

Handling Failures ........................................................................................................................................ 171

Coding Client Applications and Services..................................................................................................... 172

Sample Code ....................................................................................................................................... 173

Using WebTap ...................................................................................................................... 175

What is WebTap?........................................................................................................................................ 176

Components of a WebTap Application................................................................................................. 176

How Does a WebTap Service Work?................................................................................................... 176

Guidelines for Using WebTap .............................................................................................................. 177

Creating a WebTap Service ........................................................................................................................ 178

Defining WebTap Rules .............................................................................................................................. 179

Creating Before and After Services............................................................................................................. 181

A Simple Rerouting Example............................................................................................................... 183

Creating a Customized WebTap Service .................................................................................................... 184

Invoking a WebTap Service from a Browser ............................................................................................... 186

webMethods Flow Operations............................................................................................. 189



viii B2B Developer’s Guide Version 3.0

BRANCH ..................................................................................................................................................... 190

Properties............................................................................................................................................. 190

Conditions That Will Cause a BRANCH Operation to Fail ................................................................... 191

EXIT ............................................................................................................................................................ 192

Properties............................................................................................................................................. 192

Examples of When to Use.................................................................................................................... 193

INVOKE....................................................................................................................................................... 194

Properties............................................................................................................................................. 194

Conditions That Will Cause an INVOKE Operation to Fail................................................................... 194

LOOP .......................................................................................................................................................... 195

Properties............................................................................................................................................. 195

Conditions That Cause Failure............................................................................................................. 196

MAP ............................................................................................................................................................ 197

Properties............................................................................................................................................. 197

Example of When to Use ..................................................................................................................... 197REPEAT...................................................................................................................................................... 198

Properties............................................................................................................................................. 198


Examples of When to Use.................................................................................................................... 199

SEQUENCE ................................................................................................................................................ 201

Properties............................................................................................................................................. 201


webMethods Query Language ............................................................................................ 203

webMethods Query Language .................................................................................................................... 204

Object References ............................................................................................................................... 204

Object Properties ................................................................................................................................. 207

Property Masking ................................................................................................................................. 207

Built-In Services ................................................................................................................... 209

Client Services ............................................................................................................................................ 210

Date Services.............................................................................................................................................. 220

Database Services ...................................................................................................................................... 224

Flow Services.............................................................................................................................................. 236Ldap Services ............................................................................................................................................. 240

Math Services ............................................................................................................................................. 247

Record Services.......................................................................................................................................... 251

Remote........................................................................................................................................................ 254

Report Services........................................................................................................................................... 256



B2B Developer’s Guide Version 3.0 ix

String Services............................................................................................................................................ 259

Table Services ............................................................................................................................................ 266

Web Services.............................................................................................................................................. 268

WebTap Services and Specifications.......................................................................................................... 282

Supported Data Types ......................................................................................................... 285

Regular Expressions............................................................................................................ 287What is a Regular Expression?................................................................................................................... 288

Regular Expression Operators.................................................................................................................... 289

Output Template Tags ......................................................................................................... 295

Overview ..................................................................................................................................................... 296

%comment%........................................................................................................................................ 298

%ifvar%................................................................................................................................................ 299

%include% ........................................................................................................................................... 301

%loop%................................................................................................................................................ 302

%nl%.................................................................................................................................................... 304

%rename% .......................................................................................................................................... 305

%scope%............................................................................................................................................. 306

%switch% ............................................................................................................................................ 309

%value%.............................................................................................................................................. 310

jcode tags ............................................................................................................................. 313

jcode Template............................................................................................................................................ 314

jcode Example............................................................................................................................................. 315



x B2B Developer’s Guide Version 3 0