Download - 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 2/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 3/338
Related Documentation
B2B Developer’s Guide Version 3.0 3
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 4/338
C H A P T E R 1 I n t r o d u c t i o n
4 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 5/338
B2B Developer’s Guide Version 3.0 5
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 6/338
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
6 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 7/338
Starting B2B Developer
B2B Developer’s Guide Version 3.0 7
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 8/338
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
8 B2B Developer’s Guide Version 3.0
In this field… Specify…
!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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 9/338
The B2B Developer Window
B2B Developer’s Guide Version 3.0 9
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 10/338
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
10 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 11/338
The B2B Developer Window
B2B Developer’s Guide Version 3.0 11
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 12/338
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
12 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 13/338
Basic Operations
B2B Developer’s Guide Version 3.0 13
!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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 14/338
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
14 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 15/338
B2B Developer’s Guide Version 3.0 15
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 16/338
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
16 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 17/338
Basic Concepts
B2B Developer’s Guide Version 3.0 17
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:CreditAuth
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 18/338
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
18 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 19/338
Basic Concepts
B2B Developer’s Guide Version 3.0 19
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
INVOKE Purch:CreditAuth
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 20/338
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
20 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 21/338
Creating a New Flow Service
B2B Developer’s Guide Version 3.0 21
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 22/338
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
22 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 23/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 23
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”
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 24/338
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
24 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 25/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 25
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 26/338
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
26 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 27/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 27
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 28/338
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
28 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 29/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 29
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 30/338
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
30 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 31/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 31
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 32/338
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
32 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 33/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 33
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 34/338
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
34 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 35/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 35
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,
display that service in the Flow Pane and highlight the operation
immediately above where you want the REPEAT operation inserted.
2 Click on the Flow Pane toolbar and select REPEAT from the list.
3 Complete the following fields on the Properties tab:
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,
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 36/338
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
36 B2B Developer’s Guide Version 3.0
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
in the label field. See “The BRANCH Operation” on
page 27 or “The EXIT Operation” on page 42 for
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:
1 Insert a flow operation using or on the Flow Pane
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 37/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 37
— 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,
display that service in the Flow Pane and highlight the operation
immediately above where you want the REPEAT operation inserted.
2 Click on the Flow Pane toolbar and select REPEAT from the list.
3 Complete the following fields on the Properties tab:
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 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 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).
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.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 38/338
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
38 B2B Developer’s Guide Version 3.0
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:
1 Insert a flow operation using or on the Flow Pane
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.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 39/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 39
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 40/338
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
40 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 41/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 41
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.
3 Complete the following fields on the Properties tab:
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 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 is
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 42/338
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
42 B2B Developer’s Guide Version 3.0
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).
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.
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:
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 LOOP operation.)
3 Set the properties for the child operation as needed.
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 43/338
Inserting Flow Operations
B2B Developer’s Guide Version 3.0 43
— 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.
3 Complete the following fields on the Properties tab:
For this property… Specify…
comment An optional descriptive comment for thisoperation.
label An optional name for this specific operation, or anull, unmatched, or empty string ($null, $default,blank).
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.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 44/338
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
44 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 45/338
Creating a Specification for a Service
B2B Developer’s Guide Version 3.0 45
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 46/338
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
46 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 47/338
Creating a Specification for a Service
B2B Developer’s Guide Version 3.0 47
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 48/338
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
48 B2B Developer’s Guide Version 3.0
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 49/338
Creating a Specification for a Service
B2B Developer’s Guide Version 3.0 49
— 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 50/338
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
50 B2B Developer’s Guide Version 3.0
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.
2 Click on the toolbar and select the type of variable that you
want to specify.
3 Type the name of the variable and then 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.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 51/338
Creating a Specification for a Service
B2B Developer’s Guide Version 3.0 51
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 52/338
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
52 B2B Developer’s Guide Version 3.0
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:
1 Click on the toolbar and select the type of variable that you
want to specify.
2 Type the name of the variable and then press ENTER.
3 If the variable is a Record or a Record List, repeat steps 1 and 2 to
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 53/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 53
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 54/338
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
54 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 55/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 55
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 56/338
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
56 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 57/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 57
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 58/338
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
58 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 59/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 59
— 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.
3 Click on the toolbar.
!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).
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 60/338
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
60 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 61/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 61
The Input For dialog box
To assign a value to a variable in the Pipeline
1 In the Flow Pane, select the INVOKE or MAP operation whose
variable you want to alter.
2 Click the Pipeline tab.
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.
4 Click on the toolbar.
5 In the Input For dialog box, specify the value you want to assign to
this variable.
— If you want to assign a literal value to the variable, type that value.
— 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 62/338
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
62 B2B Developer’s Guide Version 3.0
!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
1 In the Flow Pane, select the INVOKE or MAP operation whose
pipeline variables you want to drop.
2 Click the Pipeline tab.
3 Select the variable that you want to drop.
! You can only drop variables from Pipeline In and Pipeline Out.
4 Click on the toolbar.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 63/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 63
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.
2 Click the Pipeline tab.
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.
6 If the variable is a Record or a Record List, repeat steps 1 and 2 to
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 64/338
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
64 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 65/338
Mapping the Pipeline
B2B Developer’s Guide Version 3.0 65
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 66/338
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
66 B2B Developer’s Guide Version 3.0
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.
2 Click on the toolbar.
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.
2 Click on the toolbar.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 67/338
Specifying Run Time Parameters
B2B Developer’s Guide Version 3.0 67
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 68/338
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
68 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 69/338
Specifying Run Time Parameters
B2B Developer’s Guide Version 3.0 69
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 70/338
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
70 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 71/338
Specifying Run Time Parameters
B2B Developer’s Guide Version 3.0 71
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 72/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 73/338
B2B Developer’s Guide Version 3.0 73
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 74/338
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
74 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 75/338
How Java Services are Organized on the Server
B2B Developer’s Guide Version 3.0 75
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 76/338
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
76 B2B Developer’s Guide Version 3.0
— 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 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 77/338
Building a Java Service with the B2B Developer
B2B Developer’s Guide Version 3.0 77
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 78/338
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
78 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 79/338
Building a Java Service with the B2B Developer
B2B Developer’s Guide Version 3.0 79
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 80/338
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
80 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 81/338
Building a Java Service with the B2B Developer
B2B Developer’s Guide Version 3.0 81
!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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 82/338
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
82 B2B Developer’s Guide Version 3.0
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 83/338
Building a Java Service with Your Own IDE
B2B Developer’s Guide Version 3.0 83
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>> ---
.
.
.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 84/338
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
84 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 85/338
Building a Java Service with Your Own IDE
B2B Developer’s Guide Version 3.0 85
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 86/338
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
86 B2B Developer’s Guide Version 3.0
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
following on the command line:
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
following on the command line:
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 87/338
Building a B2B Service Using C/C++
B2B Developer’s Guide Version 3.0 87
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
privileges on the B2B Integration Server, ask your server administrator to do this.)
Make sure the directory for this package contains a “code/libs” directory. When you compile
your C/C++ service, the make file places the compiled service (a DLL) in this
directory. If the package does not already have a code/libs directory, create one
before you begin building the service.
Make sure the 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
1 Select the New command from the File menu.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 88/338
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
88 B2B Developer’s Guide Version 3.0
2 Select C Service and then click Next.
3 In the Interface tree, select the interface into which you want to save this
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 89/338
Building a B2B Service Using C/C++
B2B Developer’s Guide Version 3.0 89
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 90/338
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
90 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 91/338
Building B2B Services Using COM
B2B Developer’s Guide Version 3.0 91
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 92/338
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
92 B2B Developer’s Guide Version 3.0
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 93/338
Invoking a Visual Basic Service
B2B Developer’s Guide Version 3.0 93
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.
The following example shows the value you woulduse for the “Hello World” example:
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 94/338
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
94 B2B Developer’s Guide Version 3.0
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 “_”
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 95/338
Invoking a Visual Basic Service
B2B Developer’s Guide Version 3.0 95
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.
The following example shows the value you woulduse for the “Hello World” example:
Example: wmVBDemo
$methodName The name of the method you want to invoke.
The following example shows the value you woulduse for the “Hello World” example:
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 96/338
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
96 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 97/338
B2B Developer’s Guide Version 3.0 97
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 98/338
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
98 B2B Developer’s Guide Version 3.0
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><P>Contact information for account %value AccountNum% is:</P>
<TABLE><TR><TD><B>Account Name</B></TD><TD>%value CompanyNum%</TD></TR>
<TR><TD><B>Contact Name</B></TD><TD>%value ContactName%</TD></TR><TR><TD><B>Phone Number</B></TD><TD>%value PhoneNum%</TD></TR>
</TABLE></BODY></HTML>
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 99/338
How do You Assign a Template to a Service?
B2B Developer’s Guide Version 3.0 99
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 100/338
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
100 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 101/338
Creating an Output Template
B2B Developer’s Guide Version 3.0 101
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 102/338
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
102 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 103/338
B2B Developer’s Guide Version 3.0 103
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 104/338
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
104 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 105/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 105
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.)
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 106/338
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
106 B2B Developer’s Guide Version 3.0
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 .
2 Click on the toolbar.
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 107/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 107
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 108/338
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
108 B2B Developer’s Guide Version 3.0
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
Do one of the following:
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 109/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 109
Use this element… If you want to…
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
include this character in the values you specify.
! 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 110/338
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
110 B2B Developer’s Guide Version 3.0
Use this element… If you want to…
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 111/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 111
Use this element… If you want to…
− 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
include this character in the values you specify.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 112/338
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
112 B2B Developer’s Guide Version 3.0
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
Do one of the following:
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 113/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 113
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 114/338
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
114 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 115/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 115
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
Do one of the following:
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 116/338
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
116 B2B Developer’s Guide Version 3.0
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
Do one of the following:
Use the Set Value modifier in the Pipeline Editor to select the
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
Do one of the following:
Use the Set Value modifier in the Pipeline Editor to select the
value of loadAs from the drop-down list.
—OR—
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 117/338
Using the loadDocument Service
B2B Developer’s Guide Version 3.0 117
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 118/338
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
118 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 119/338
Using the queryDocument Service
B2B Developer’s Guide Version 3.0 119
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.)
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 120/338
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
120 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 121/338
Using the queryDocument Service
B2B Developer’s Guide Version 3.0 121
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 122/338
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
122 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 123/338
Using the queryDocument Service
B2B Developer’s Guide Version 3.0 123
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 124/338
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
124 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 125/338
Using the queryDocument Service
B2B Developer’s Guide Version 3.0 125
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 126/338
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
126 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 127/338
Load and Query Shortcuts
B2B Developer’s Guide Version 3.0 127
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., <p>, <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 <p> 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,
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 128/338
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
128 B2B Developer’s Guide Version 3.0
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
1 Select the New command from the File menu.
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:.)
Example: http://www.rubicon.com/orders/orders.html
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 129/338
Load and Query Shortcuts
B2B Developer’s Guide Version 3.0 129
Select… To create…
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 130/338
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
130 B2B Developer’s Guide Version 3.0
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
1 Select the New command from the File menu.
2 Select Flow Service and then click Next.
3 In the Interface tree, select the interface into which you want to save this
service, type a name for the service in the Name field, and then click
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/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 131/338
Load and Query Shortcuts
B2B Developer’s Guide Version 3.0 131
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.
Select… To create…
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 132/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 133/338
B2B Developer’s Guide Version 3.0 133
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 134/338
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
134 B2B Developer’s Guide Version 3.0
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 135/338
Building a C/C++ Client
B2B Developer’s Guide Version 3.0 135
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 136/338
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
136 B2B Developer’s Guide Version 3.0
Assumptions
— The B2B Integration Server is running.
— 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
invokes a B2B service:
To generate C/C++ 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; 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.
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 C client code
(ServiceName.c), a file that contains compiling settings
(ServiceName.make), and a CReadme.txt file.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 137/338
Building a Visual Basic Client
B2B Developer’s Guide Version 3.0 137
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.
Files That Are Generated
This section describes the files that B2B Developer generates for a C/C++ client
application.
File Name Description
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
— The B2B Integration Server is running.
— 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 138/338
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
138 B2B Developer’s Guide Version 3.0
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
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; then click Next.
4 In the Language field, select Visual Basic 5/6; 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 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.
Files That Are Generated
This section describes the files that B2B Developer generates for a Visual Basic client
application.
General Fi les
File Name Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 139/338
Building an Excel Client
B2B Developer’s Guide Version 3.0 139
Files for the User Interface
The following files are the same for all Visual Basic client code you generate.
File Name Description
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
File Name Description
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
intended for use as-is in custom applications.
ServiceName.cls The service object. You include this object into your own
project.
File Containing the Code that Interacts with the B2B Integration Server
File Name Description
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
— The B2B Integration Server is running.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 140/338
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
140 B2B Developer’s Guide Version 3.0
— 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
invokes a B2B service:
To generate Excel 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; then click Next.
4 In the Language field, select Excel 97/2000; 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 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 141/338
Building a Browser-Based Client
B2B Developer’s Guide Version 3.0 141
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.
Files That Are Generated
This section describes the files that B2B Developer generates for an Excel client
application.
File Name Description
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
intended for use as-is in custom applications.
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 B2B Integration Server is running.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 142/338
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
142 B2B Developer’s Guide Version 3.0
— 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 143/338
Building a Browser-Based Client
B2B Developer’s Guide Version 3.0 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 144/338
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
144 B2B Developer’s Guide Version 3.0
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<BR>
<INPUT TYPE="checkbox" NAME="Color" VALUE="green">Green<BR>
<INPUT TYPE="checkbox" NAME="Color" VALUE="red">Red<BR>
If the browser user selects all check boxes, the document that is posted to 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 145/338
Building a Browser-Based Client
B2B Developer’s Guide Version 3.0 145
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 146/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 147/338
B2B Developer’s Guide Version 3.0 147
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 148/338
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
148 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 149/338
Submitting an XML Document in $xmldata
B2B Developer’s Guide Version 3.0 149
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 150/338
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
150 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 151/338
Sending an XML Document via FTP
B2B Developer’s Guide Version 3.0 151
! 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 152/338
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
152 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 153/338
B2B Developer’s Guide Version 3.0 153
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 154/338
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
154 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 155/338
Creating Database Flow Services
B2B Developer’s Guide Version 3.0 155
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 156/338
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
156 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 157/338
Creating Database Flow Services
B2B Developer’s Guide Version 3.0 157
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 158/338
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
158 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 159/338
Creating Database Flow Services
B2B Developer’s Guide Version 3.0 159
— 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
1 Open the Server Administrator if it is not already open. See the
webMethods B2B Server Administrator’s Guide if you need help with 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 160/338
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
160 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 161/338
Creating Database Services with Java, C/C++, or VB
B2B Developer’s Guide Version 3.0 161
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 162/338
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
162 B2B Developer’s Guide Version 3.0
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
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 for which you want to issue a SQL statement from the
Source Alias drop down list.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 163/338
Creating Clients that Access Databases
B2B Developer’s Guide Version 3.0 163
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 164/338
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
164 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 165/338
Creating Clients that Access Databases
B2B Developer’s Guide Version 3.0 165
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);
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 166/338
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
166 B2B Developer’s Guide Version 3.0
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"));
}
}
}
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 167/338
B2B Developer’s Guide Version 3.0 167
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 168/338
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
168 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 169/338
How Transactions are Managed
B2B Developer’s Guide Version 3.0 169
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 170/338
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
170 B2B Developer’s Guide Version 3.0
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.
TContext Method: Cannot specify using a TContext method.
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.
TContext Method: Cannot specify using a TContext method.
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 171/338
Handling Failures
B2B Developer’s Guide Version 3.0 171
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 172/338
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
172 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 173/338
Coding Client Applications and Services
B2B Developer’s Guide Version 3.0 173
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 174/338
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
174 B2B Developer’s Guide Version 3.0
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);
} catch (ServiceException e) {System.err.println("Error: "+e.getMessage());System.exit(-1);
}
// release connection and shutdowntry {
tc.disconnect();TContext.shutdown();
} catch (ServiceException e) {System.err.println("Error: "+e.getMessage());System.exit(-1);
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 175/338
B2B Developer’s Guide Version 3.0 175
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 176/338
C H A P T E R 1 1 U s i n g W e b T a p
176 B2B Developer’s Guide Version 3.0
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 177/338
What is WebTap?
B2B Developer’s Guide Version 3.0 177
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 178/338
C H A P T E R 1 1 U s i n g W e b T a p
178 B2B Developer’s Guide Version 3.0
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
9 Select the New command from the File menu.
10 Select WebTap Service and then click Next.
11 In the Interface tree, select the interface into which you want to save this
service, type a name for the service in the Name field, and then click
Next.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 179/338
Defining WebTap Rules
B2B Developer’s Guide Version 3.0 179
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 180/338
C H A P T E R 1 1 U s i n g W e b T a p
180 B2B Developer’s Guide Version 3.0
− 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:
In this field… Specify…
Name The name of the argument (i.e., the name portionof the name=value pair) that you want to test.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 181/338
Creating Before and After Services
B2B Developer’s Guide Version 3.0 181
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 182/338
C H A P T E R 1 1 U s i n g W e b T a p
182 B2B Developer’s Guide Version 3.0
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.
Variable Name Description
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.
Variable Name Description
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).
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 183/338
Creating Before and After Services
B2B Developer’s Guide Version 3.0 183
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,
specifying whether WebTap should map
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,
specifying whether WebTap should map
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 184/338
C H A P T E R 1 1 U s i n g W e b T a p
184 B2B Developer’s Guide Version 3.0
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.)
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 185/338
Creating a Customized WebTap Service
B2B Developer’s Guide Version 3.0 185
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 186/338
C H A P T E R 1 1 U s i n g W e b T a p
186 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 187/338
Invoking a WebTap Service from a Browser
B2B Developer’s Guide Version 3.0 187
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 188/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 189/338
B2B Developer’s Guide Version 3.0 189
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 190/338
APPENDIX A webMethods Flow Operations
190 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 191/338
BRANCH
B2B Developer’s Guide Version 3.0 191
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 192/338
APPENDIX A webMethods Flow Operations
192 B2B Developer’s Guide Version 3.0
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
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.
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 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 193/338
EXIT
B2B Developer’s Guide Version 3.0 193
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 194/338
APPENDIX A webMethods Flow Operations
194 B2B Developer’s Guide Version 3.0
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
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, the INVOKE
operation is not interrupted when the timeout value is exceeded. Instead, the exception is
raised after the INVOKE is complete.
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 operation as a target for a BRANCH or EXIT
operation.) Specifies a name for this specific operation, or a null, unmatched, or empty
string ($null, $default, blank).
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 195/338
LOOP
B2B Developer’s Guide Version 3.0 195
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
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 196/338
APPENDIX A webMethods Flow Operations
196 B2B Developer’s Guide Version 3.0
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 operation as a target for a BRANCH or EXIT
operation.) Specifies a name for this specific operation, or a null, unmatched, or empty
string ($null, $default, blank).
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 197/338
MAP
B2B Developer’s Guide Version 3.0 197
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
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 this 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.
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 operation as a target for a BRANCH or EXIT
operation.) Specifies a name for this specific operation, or a null, unmatched, or empty
string ($null, $default, blank).
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 198/338
APPENDIX A webMethods Flow Operations
198 B2B Developer’s Guide Version 3.0
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
Optional. Specifies a descriptive comment for this 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 this 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 199/338
REPEAT
B2B Developer’s Guide Version 3.0 199
the timeout value is exceeded. Instead, the exception is raised after the INVOKE is
complete.
If you do not want to specify a timeout period, set timeout to zero or leave it blank.
labelOptional. (Required if you are using this operation as a target for a BRANCH or EXIT
operation.) Specifies a name for this specific operation, or a null, unmatched, or empty
string ($null, $default, blank).
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.
Conditions That Cause Failure
— 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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 200/338
APPENDIX A webMethods Flow Operations
200 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 201/338
SEQUENCE
B2B Developer’s Guide Version 3.0 201
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
Optional. Specifies a descriptive comment for this 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.
timeoutOptional. Specifies the maximum number of seconds that this 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 202/338
APPENDIX A webMethods Flow Operations
202 B2B Developer’s Guide Version 3.0
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 operation as a target for a BRANCH or EXIT
operation.) Specifies a name for this specific operation, or a null, unmatched, or empty
string ($null, $default, blank).
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.
Conditions That Cause Failure
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.
— The SEQUENCE flow operation does not complete before the timeout period expires.
If exit-on is set to DONE, conditions that will cause a failure include:
— The SEQUENCE flow operation does not complete before the timeout period expires.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 203/338
B2B Developer’s Guide Version 3.0 203
A P P E N D I X
webMethods Query Language
Object References...................................................................204
Object Properties .....................................................................207
Property Masking.....................................................................207
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 204/338
APPENDIX B webMethods Query Language
204 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 205/338
webMethods Query Language
B2B Developer’s Guide Version 3.0 205
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 206/338
APPENDIX B webMethods Query Language
206 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 207/338
webMethods Query Language
B2B Developer’s Guide Version 3.0 207
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 208/338
APPENDIX B webMethods Query Language
208 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 209/338
B2B Developer’s Guide Version 3.0 209
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 210/338
APPENDIX C Built-In Services
210 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 211/338
Client Services
B2B Developer’s Guide Version 3.0 211
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:
Example: http://www.rubicon.com/orders/orders.html
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 212/338
APPENDIX C Built-In Services
212 B2B Developer’s Guide Version 3.0
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
the http service to submit to the resource
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
the http service to submit to the resource
in url .
You can only use bytes to submit data via
the POST method.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 213/338
Client Services
B2B Developer’s Guide Version 3.0 213
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 contents of column 1 represents
the value portion of the pair.
Note that when you use table, the http
service will:
− automatically url-encode
name=value pair, so you do not need
to url-encode the values you specify
in table.
− automatically insert the “&”
character between the pairs (or
unnamed values) that it constructs,
so you do not need to include it in
table.
− automatically prefix the entire query
string with the “?” character if it
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 214/338
APPENDIX C Built-In Services
214 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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.
Variable Name Description
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.
Input Variable Name Description
dirpath The working directory of the FTP server, e.g., pub.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 215/338
Client Services
B2B Developer’s Guide Version 3.0 215
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
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[].
Input Variable Name Description
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.
Output Variable Name Description
dirlist The list of file names in the format of a String array.
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
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.
Input Variable Name Description
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.
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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[].
Input Variable Name Description
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.
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 216/338
APPENDIX C Built-In Services
216 B2B Developer’s Guide Version 3.0
logmsg FTP log messages for the entire user session.
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.
Input Variable Name Description
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.
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
pub.cl ient. ftp:logout
Description Logs out of the current FTP session.
Input Variable Name Description
name Reserved
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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[].
Input Variable Name Description
filenamepattern A pattern that specifies the file names of the files to retrieve, e.g., *.txt.
Output Variable Name Description
dirlist The list of file names in String array format.
returncode Standard FTP protocol return code.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 217/338
Client Services
B2B Developer’s Guide Version 3.0 217
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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.
Input Variable Name Description
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.
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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[].
Input Variable Name Description
transfermode The FTP file transfer mode; specify either ascii or binary.
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.
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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[].
Input Variable Name Description
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.
Output Variable Name Description
filenames The list of files being transferred to or from remote FTP server.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 218/338
APPENDIX C Built-In Services
218 B2B Developer’s Guide Version 3.0
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
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[].
Input Variable Name Description
transfermode The FTP file transfer mode; specify either ascii or binary.
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.
Output Variable Name Description
returncode Standard FTP protocol return code.
returnmsg Standard FTP protocol return message.
logmsg FTP log messages for the entire user session.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 219/338
Client Services
B2B Developer’s Guide Version 3.0 219
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 220/338
APPENDIX C Built-In Services
220 B2B Developer’s Guide Version 3.0
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 '
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 221/338
Date Services
B2B Developer’s Guide Version 3.0 221
pub.date:currentDate
Description Returns the current date in a specified format.
Input Variable Name Description
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.
Input Variable Name Description
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.
Output Variable Name Description
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.
Input Variable Name Description
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.
Output Variable Name Description
value A string that represents the date specified by the date and time elements in the
format of pattern.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 222/338
APPENDIX C Built-In Services
222 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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.
Output Variable Name Description
value A string representing the date/time given by inString , in the format of
newPattern
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 223/338
Date Services
B2B Developer’s Guide Version 3.0 223
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 224/338
APPENDIX C Built-In Services
224 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
$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.
Output Variable Name Description
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.
Input Variable Name Description
$dbAlias The alias of the database connection on which you want to clear transactional
state.
Output Variable Name Description
$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
Variable Name Description
$dbAlias A database alias.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 225/338
Database Services
B2B Developer’s Guide Version 3.0 225
$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
$dbMessage A message indicating the success or failure of the operation.
pub.db:closeAll
Description Closes all database connections that the session has opened.
Input none
Output Variable Name Description
$dbMessage A message indicating the success or failure of the operation.
pub.db:commitDescription Commits changes to a database
Input Variable Name Description
$dbAlias The alias of the database on which you want to commit changes.
Output Variable Name Description
$dbMessage A message indicating the success or failure of the operation.
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.
Input You may specify the connection parameters in one of the following ways:
$dbAlias
– OR –
$dbURL, $dbUser , $dbPass, $dbDriver
Variable Name Description
$dbAlias A database alias.
$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).
Output Variable Name Description
$dbConnection The connection object.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 226/338
APPENDIX C Built-In Services
226 B2B Developer’s Guide Version 3.0
pub.db:delete
Description Removes all rows in the specified table that meet the given criteria.
Input You may specify the connection parameters in one of the following ways:
$dbAlias
– OR –
$dbURL, $dbUser , $dbPass, $dbDriver
– OR –
$dbConnection
Variable Name Description
$dbAlias A database alias.
$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.
$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.
Output Variable Name Description
$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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 227/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 228/338
APPENDIX C Built-In Services
228 B2B Developer’s Guide Version 3.0
Input Variable Name Description
$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.
If you are running against DB2, use this parameter to specify the database
location.
$dbSchemaPattern The name of the schema to which the stored procedures belong.
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 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.
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 theschema 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 The name of the table to which the procedure belongs.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 229/338
Database Services
B2B Developer’s Guide Version 3.0 229
$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.
Input You may specify the connection parameters in one of the following ways:
$dbAlias
– OR –
$dbURL, $dbUser , $dbPass, $dbDriver
– OR –
$dbConnection
Variable Name Description
$dbAlias A database alias.
$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.
$dbCatalog Name of the database’s system catalog. Include this parameter if your
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.
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
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 230/338
APPENDIX C Built-In Services
230 B2B Developer’s Guide Version 3.0
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 –
$dbURL, $dbUser , $dbPass, $dbDriver
– OR –
$dbConnection
Variable Name Description
$dbAlias A database alias.
$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.
$dbCatalog Name of the database’s system catalog. Include this parameter if your
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.
If you are running against DB2, use this parameter to specify the database
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
character and % represents any string of characters. For example, the value
HR% would represent any schema beginning with the characters HR.
If you want the table names from all schemas, set $dbSchemaPattern to null.
If you are running against DB2, you use this parameter to specify the table’s
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 231/338
Database Services
B2B Developer’s Guide Version 3.0 231
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.
Usage Notes This service will accept input from a web browser or HTML form.
pub.db:insert
Description Inserts one or more rows into the specified table.
Input You may specify the connection parameters in one of the following ways:
$dbAlias
– OR –
$dbURL, $dbUser , $dbPass, $dbDriver
– OR –
$dbConnection
Variable Name Description
$dbAlias A database alias.
$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.
$dbCatalog Name of the database’s system catalog. Include this parameter if your DBMS
supports distributed databases and you want to insert rows into 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 insert rows
into 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 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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 232/338
APPENDIX C Built-In Services
232 B2B Developer’s Guide Version 3.0
Output Variable Name Description
$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.
Usage Notes This service will accept input from a web browser or HTML form.
pub.db:query
Description Retrieves all rows from the specified table that meet the given criteria.
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 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.
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 query.
$data Values object with criteria that the rows to retrieve must meet.
Output Variable Name Description
$results Values object that contains results of the query.
Usage Notes This service will accept input from a web browser or HTML form.
pub.db:rol lback
Description Discards changes to a database.
Input Variable Name Description
$dbAlias The alias of the database on which you want to discard changes.
Output Variable Name Description
$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.
Input Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 233/338
Database Services
B2B Developer’s Guide Version 3.0 233
$dbAlias The alias of the database on which you want to start the transaction.
Output Variable Name Description
$dbMessage A message indicating the success or failure of the operation.
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.
Input You may specify the connection parameters in one of the following ways:
$dbAlias
– OR –
$dbURL, $dbUser , $dbPass, $dbDriver
– OR –
$dbConnection
Variable Name Description
$dbAlias A database alias.
$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.
$dbCatalog Name of the database’s system catalog. Include this parameter if your DBMS
supports distributed databases and you want to update rows in 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 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.
$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 update.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 234/338
APPENDIX C Built-In Services
234 B2B Developer’s Guide Version 3.0
$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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 235/338
Database Services
B2B Developer’s Guide Version 3.0 235
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 236/338
APPENDIX C Built-In Services
236 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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
Input Variable Name Description
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
Output Variable Name Description
$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.
Input Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 237/338
Flow Services
B2B Developer’s Guide Version 3.0 237
$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.
Input Variable Name Description
$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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 238/338
APPENDIX C Built-In Services
238 B2B Developer’s Guide Version 3.0
Input Variable Name Description
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.
Input Variable Name Description
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 239/338
Flow Services
B2B Developer’s Guide Version 3.0 239
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 240/338
APPENDIX C Built-In Services
240 B2B Developer’s Guide Version 3.0
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]
Output Variable Name Description
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.
Input Variable Name Description
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.
Output Variable Name Description
ldapConnectionKey Key for this connection on the B2B server.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 241/338
Ldap Services
B2B Developer’s Guide Version 3.0 241
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.
Input Variable 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.
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.
Output Variable Name Description
ldapMessage A message indicating the success or failure of the operation.
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.
Input Variable 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.
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.
Input Variable 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.
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.
Output Variable Name Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 242/338
APPENDIX C Built-In Services
242 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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.
Output Variable Name Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 243/338
Ldap Services
B2B Developer’s Guide Version 3.0 243
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.
Input Variable 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.
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.
Output Variable Name Description
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 244/338
APPENDIX C Built-In Services
244 B2B Developer’s Guide Version 3.0
Variable Value
$name cn=Arthur Milberg, ou=People
uid amilberg
mail [email protected]
$name n=Dorothy Hadden, ou=Peopleuid dhadden
mail [email protected]
$name cn=Scott Treezak, ou=People
uid streezak
ldapListing
mail [email protected]
pub.ldap:lookup
Description Lookup a single entry in the directory server.
Input Variable 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.
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.
Output Variable Name Description
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 245/338
Ldap Services
B2B Developer’s Guide Version 3.0 245
Input Variable Name Description
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”
Output Variable Name Description
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.
Input Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 246/338
APPENDIX C Built-In Services
246 B2B Developer’s Guide Version 3.0
ldapConnectionKey The key for the connection on the B2B Integration Server; this is the key
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]
Output Variable Name Description
ldapMessage A message indicating the success or failure of the operation.
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).
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 247/338
Math Services
B2B Developer’s Guide Version 3.0 247
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.
Variable Name Description
num1 String representation of a float.
Input
num2 String representation of a float.
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
numList String array containing a list of string-based integer values.
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of an integer.
Input
num2 String representation of an integer.
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of a float.
Input
num2 String representation of a float.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 248/338
APPENDIX C Built-In Services
248 B2B Developer’s Guide Version 3.0
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of an integer.
Input
num2 String representation of an integer.
Variable Name DescriptionOutput
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.
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of a float.
Input
num2 String representation of a float.
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
numList String array containing a list of string-based integer values.
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of an integer.
Input
num2 String representation of an integer.
Output Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 249/338
Math Services
B2B Developer’s Guide Version 3.0 249
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.
Variable Name Description
num1 String representation of a float.
Input
num2 String representation of a float.
Variable Name DescriptionOutput
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.
Variable Name Description
num1 String representation of an integer.
Input
num2 String representation of an integer.
Variable Name DescriptionOutput
value A string that represents num1 – num2.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 250/338
APPENDIX C Built-In Services
250 B2B Developer’s Guide Version 3.0
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 251/338
Record Services
B2B Developer’s Guide Version 3.0 251
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.
Input Variable Name Description
recordList Record list for which a length calculation is needed.
Output Variable Name Description
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.
Input Variable Name Description
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.
Output Variable Name Description
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.
Input Variable Name Description
record Target record to convert. This record can contain any number of other fields,
lists, and other records.
Output Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 252/338
APPENDIX C Built-In Services
252 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
xmlvalues XML document containing encoded representation of a record. The XML
format is webMethods XMLValues. No other formats will be accepted.
Output Variable Name Description
record Record resulting from the decoding of xmlvalues.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 253/338
Record Services
B2B Developer’s Guide Version 3.0 253
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 254/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 255/338
Remote
B2B Developer’s Guide Version 3.0 255
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 256/338
APPENDIX C Built-In Services
256 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
$template A File object (java.io.File) which points to a physical template file.
$values The values object to be bind against the template.
Output Variable Name Description
$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).
Input Variable Name Description
$template A File object (java.io.File) which points to a physical template file.
Output Variable Name Description
$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: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.
Input Variable Name Description
$template The String object containing the template to be used.
$values The values object to be bind against the template.
Output Variable Name Description
$txt The resulting string from applying the template.
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).
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 257/338
Report Services
B2B Developer’s Guide Version 3.0 257
Input Variable Name Description
$template The String object containing the template to be used.
Output Variable Name Description
$txt The resulting string from applying the template.
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.
Input Variable Name Description
$template The filename for a template. Ex. mytemp.html or mytemp.xml
$package The package where the template is. Ex. “Default”
$values The values object to be bind against the template.
Output Variable Name Description
$txt The resulting string from applying the template.
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).
Input Variable Name Description
$template The filename for a template. Ex. mytemp.html or mytemp.xml
$package The package where the template is. Ex. “Default”
Output Variable Name Description
$txt The resulting string from applying the template.
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 258/338
APPENDIX C Built-In Services
258 B2B Developer’s Guide Version 3.0
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 259/338
String Services
B2B Developer’s Guide Version 3.0 259
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.
Variable Name DescriptionInput
bytes A byte array (byte[]).
Variable Name DescriptionOutput
string A string containing the bytes in bytes.
pub.string:concat
Description Concatenates two strings.
Variable Name Description
inString1 A string.
Input
inString2 A string.
Variable Name DescriptionOutput
value A string that represents inString1 concatenated with inString2 (inString1 +
inString2).
pub.string:HTMLDecode
Description Replaces HTML character entities in inString with native characters.
Variable Name DescriptionInput
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.
Variable Name DescriptionInput
inString A string.
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
inString A string.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 260/338
APPENDIX C Built-In Services
260 B2B Developer’s Guide Version 3.0
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.”
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
inString A string.
Variable Name DescriptionOutput
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).
Variable Name Description
hashtable A Hashtable that uses String objects for keys and values.
Input
key The string to look up.
Variable Name DescriptionOutput
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.
Variable Name Description
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.
Variable Name DescriptionOutput
value The string in the value column of the first row whose key column matches key.
If no match is found, returns null.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 261/338
String Services
B2B Developer’s Guide Version 3.0 261
pub.string:makeString
Description Builds a single string by concatenating an array of strings while concatenating an optional separator
between each string.
Variable Name Description
stringList An array of strings to concatenate.
Input
separator The string to insert between each non-null element in stringList .
Variable Name DescriptionOutput
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.
Variable Name Description
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.”
Variable Name DescriptionOutput
value A string that contains the elements in stringList substituted into pattern.
pub.string:numericFormat
Description Formats a number into a given numeric pattern.
Variable Name Description
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.
Variable Name Description
inString A string.
padString String to use as padding.
Input
length Desired length of resulting string.
Output Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 262/338
APPENDIX C Built-In Services
262 B2B Developer’s Guide Version 3.0
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.
Variable Name Description
inString A string.
padString String to use as padding.
Input
length Desired length of resulting string.
Variable Name DescriptionOutput
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.
Variable Name Description
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 .
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
string A string.
Output Variable Name Description
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 263/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 264/338
APPENDIX C Built-In Services
264 B2B Developer’s Guide Version 3.0
inString A string.
delim A string containing the delimiter characters. If null or empty, uses " \t\n\r"
(white space characters).
Variable Name DescriptionOutput
valueList An array of strings containing the tokens in inString .
pub.string:tr im
Description Trims white space from a string.
Variable Name DescriptionInput
inString A string.
Variable Name DescriptionOutput
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.
Variable Name DescriptionOutput
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.
Variable Name DescriptionInput
inString A string.
Variable Name DescriptionOutput
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 265/338
String Services
B2B Developer’s Guide Version 3.0 265
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 266/338
APPENDIX C Built-In Services
266 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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)
Output Variable Name Description
table The resulting table
pub.table:stringTableToTable
Description Turn a string table (Java array) into an instance of com.wm.util.Table.
Input Variable Name Description
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.
Output Variable Name Description
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.
Input Variable Name Description
table The table to convert.
Output Variable Name Description
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.
Input Variable Name Description
table The table to convert.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 267/338
Table Services
B2B Developer’s Guide Version 3.0 267
Output Variable Name Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 268/338
APPENDIX C Built-In Services
268 B2B Developer’s Guide Version 3.0
Web Services
You use the Web automation services to perform operations on XML and HTML documents.
pub.web:createRegions
Description Generates regions output parameters.
Input Variable Type Description
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:
Element Type Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 269/338
Web Services
B2B Developer’s Guide Version 3.0 269
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:
Variable Description
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).
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 270/338
APPENDIX C Built-In Services
270 B2B Developer’s Guide Version 3.0
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
Input Variable Type Description
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:
Element Type Description
prefix String Prefix that represents the URI in queries.
uri String URL identifying the XML namespace.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 271/338
Web Services
B2B Developer’s Guide Version 3.0 271
− When nsDecls is a single Values object, the key identifies the
prefix, and the value identifies the URI.
− 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.
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.
Output Variable Type Description
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.
Input Variable Type Description
doc Document Document whose resources you want to release.
Output none
pub.web:getDocumentType
Description Returns document type information about a document.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 272/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 273/338
Web Services
B2B Developer’s Guide Version 3.0 273
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.
Input Variable Type Description
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:
Element Type Description
prefix String Prefix that represents the URI in queries.
uri String URI identifying the XML namespace.
− When nsDecls is a single Values object, the key identifies the
prefix, and the value at that key identifies the URI.
− 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 URI.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 274/338
APPENDIX C Built-In Services
274 B2B Developer’s Guide Version 3.0
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.
Output Variable Type Description
iterator NodeIterator A NodeIterator for use with the service getNextNode.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 275/338
Web Services
B2B Developer’s Guide Version 3.0 275
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.
Input Variable Type Description
url String Specifies the URI of the document you want to load. This string must
begin with http: or https:
Example: http://www.rubicon.com/orders/orders.html
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.
Element Type Description
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:
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 276/338
APPENDIX C Built-In Services
276 B2B Developer’s Guide Version 3.0
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:
− 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
loadDocument to submit to the resource
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 )
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 277/338
Web Services
B2B Developer’s Guide Version 3.0 277
bytes bytes[ ] Specifies an array of bytes that you want
loadDocument to submit to the resource
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 contents of column 0 represents
the name portion of the pair (leave
this column null to submit an
unnamed value, and…
− The contents of column 1 represents
the value portion of the pair.
Note that when you use table,
loadDocument will:
− automatically url-encode
name=value pair, so you do not need
to url-encode the values you specify
in table.
− automatically insert the “&”
character between the pairs (or
unnamed values) that it constructs,so you do not need to include it in
table.
− automatically prefix the entire query
string with the “?” character if it
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 278/338
APPENDIX C Built-In Services
278 B2B Developer’s Guide Version 3.0
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.
Use this option if the document will be used
as input to a service that operates on wholedocuments (for example, queryDocument).
stream Pass the parsed 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
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.
Input Variable Type Description
node Object Any node in a parsed Document object (node can be produced by
loadDocument, stringToDocument or XML content handlers).
Output Variable Type Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 279/338
Web Services
B2B Developer’s Guide Version 3.0 279
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.
Input Variable Type Description
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:
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 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:
Element Type Description
Name String Name to assign to resulting value.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 280/338
APPENDIX C Built-In Services
280 B2B Developer’s Guide Version 3.0
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.
Input Variable Type Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 281/338
Web Services
B2B Developer’s Guide Version 3.0 281
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:
Element Type Description
prefix String Prefix that represents the URI in queries.
uri String URI 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.
Output Variable Type Description
xmldata String An XML document.
pub.web:stringToDocument
Description Converts a text string representing an XML document into a Document object.
Input Variable Type Description
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.
Output Variable Type Description
node Document Document object representing the parsed document. The output can by
input into any service that accepts a node.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 282/338
APPENDIX C Built-In Services
282 B2B Developer’s Guide Version 3.0
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.
Input Variable Name Description
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.
Variable Name Description
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 283/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 284/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 285/338
B2B Developer’s Guide Version 3.0 285
A P P E N D I X
Supported Data Types
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 286/338
APPENDIX D Supported Data Types
286 B2B Developer’s Guide Version 3.0
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[ ]
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 287/338
B2B Developer’s Guide Version 3.0 287
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 288/338
APPENDIX E Regular Expressions
288 B2B Developer’s Guide Version 3.0
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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 289/338
Regular Expression Operators
B2B Developer’s Guide Version 3.0 289
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
line within that element.
* 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’
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 290/338
APPENDIX E Regular Expressions
290 B2B Developer’s Guide Version 3.0
Use this symbol… To…
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
This example would return any paragraph in which the word
‘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
This example would return any paragraph in which the word
‘webmethods’ started in any of the first 5 character positions of the
paragraph.
{n ,m } Match the preceding item at least n times, but not more than m times.
Example: doc.p[/^.{1,4}webmethods/].text
This example would return any paragraph in which the word
‘webmethods’ started in character position 2 through 5 of the paragraph.
| Match the expression that precedes or follows this character.
Example: doc.p[/webmethods|webMethods/].text
This example would return any paragraph that contained either
‘webmethods’ or ‘webMethods’.
\b Match a word boundary.
Example: doc.p[/\bport\b/].text
This example would return any paragraph that contained the word ‘port’,
but not paragraphs that contained these characters as part of a larger
word, such as ‘import’, ‘support’, ‘ports’ or ‘ported’.
\B Match a boundary that isn’t a word boundary.
Example: doc.p[/\B555-A/].text
This example would return any paragraph that contained the characters
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 291/338
Regular Expression Operators
B2B Developer’s Guide Version 3.0 291
Use this symbol… To…
‘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
This example would return any paragraph containing the string
‘webMethods’ at the beginning of the element or at the beginning of any
line within that element.
\Z Match only at the end of a string (or before a new line at the end).
Example: doc.p[/webMethods\Z/].text
This example would return any paragraph containing the string
‘webMethods’ at the end of the paragraph element or at the end of any
line within that element.
\n Match a new lineExample: doc.p[/webMethods\n/].text
This example would return any paragraph containing the string
‘webMethods’ followed by the new line character.
\r Match a carriage return
Example: doc.p[/webMethods\r/].text
This example would return any paragraph containing the string
‘webMethods’ followed by a carriage return.
\t Match a tab character
Example: doc.p[/\twebMethods/].text
This example would return any paragraph containing the string
‘webMethods’ preceded by a tab character.
\f Match a form feed character
Example: doc.p[/webMethods\f/].text
This example would return any paragraph containing the string
‘webMethods’ followed by a form feed character.
\d Match any digit. Same as [0-9]
Example: doc.p[/part \d555-A/].text
This example would return any paragraph containing a part number that
starts with any digit 0 through 9, and is followed by the characters 555-
A. Therefore, it would match ‘part 1555-A’ but not ‘part A555-A’ or
‘part #555-A’.
\D Match any non-digit. Same as [^0-9]
Example: doc.p[/part \D555-A/].text
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 292/338
APPENDIX E Regular Expressions
292 B2B Developer’s Guide Version 3.0
Use this symbol… To…
This example would return any paragraph containing a part number that
starts with any character other than 0 through 9, and is followed by the
characters 555-A. Therefore, it would match ‘part A555-A’ and ‘part
#555-A’, but not ‘part 1555-A’.
\w Match any word character. Same as [0-9a-z_A-Z]
Example: doc.p[/part \w4555-A/].text
This example would return any paragraph containing a part number that
starts with a letter or digit and is followed by the characters 555-A.
Therefore, it would match ‘part A555-A’ and ‘part 1555-A’, but not
‘part #555-A’.
\W Match any nonword character. Same as [^0-9a-z_A-Z]
Example: doc.p[/part \W4555-A/].text
This example would return any paragraph containing a part number that
starts with a character other than a letter or digit, and is followed by 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
This example would return any paragraph containing the string
‘webMethods’ if it is preceded by a tab character, a new line character, a
carriage return, or a form-feed character.
\S Match any nonwhite-space character. Same as [^\t\n\r\f]
Example: doc.p[/\SwebMethods/].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
This example would return any paragraph containing a part number that
starts with the numbers 0, 2, or 3 and is followed by the characters 555-
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 293/338
Regular Expression Operators
B2B Developer’s Guide Version 3.0 293
Use this symbol… To…
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’.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 294/338
APPENDIX E Regular Expressions
294 B2B Developer’s Guide Version 3.0
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 295/338
B2B Developer’s Guide Version 3.0 295
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 296/338
APPENDIX F Output Template Tags
296 B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 297/338
Overview
B2B Developer’s Guide Version 3.0 297
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 298/338
APPENDIX F Output Template Tags
298 B2B Developer’s Guide Version 3.0
%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>
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 299/338
Overview
B2B Developer’s Guide Version 3.0 299
%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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 300/338
APPENDIX F Output Template Tags
300 B2B Developer’s Guide Version 3.0
ExamplesThe following example inserts a paragraph if a variable named AuthCode exists.
...%ifvar AuthCode%
<p>Authorization Code Received %value $date%: %value AuthCode%</p>%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%<p>The following items are backordered</p><p>%loop backItems%
%value%<BR>%endloop%
</p>%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%
<p>The following items are backordered</p><p>%loop backItems%
%value%<BR>%endloop%
</p>%else%
<p>There are no backordered items pending for your account</p>%end%
..
.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 301/338
Overview
B2B Developer’s Guide Version 3.0 301
%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%<p>Shipped To:<br>
%include TMPL_ShipToBlock.html%</p>%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....
%scope buyerInfo%<p>Shipped To:<br>
%include StandardTemplates/TMPL_ShipToBlock.html%</p>%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%
<p>Shipped To:<br>%include ../TMPL_ShipToBlock.html%</p>%end%
...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 302/338
APPENDIX F Output Template Tags
302 B2B Developer’s Guide Version 3.0
%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.
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 303/338
Overview
B2B Developer’s Guide Version 3.0 303
Examples The following example generates a paragraph for each record in the items Record
List....
<p>This shipment contains the following items:</p>%loop items%
<p>%value qty% %value stockNum% %value description% value status%</p>%end%...
The following example generates a line for each element in the backItems String
List....
<p>The following items are backordered</p><p>%loop backItems%
%value%<BR>%end%</p>
...
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:</p><table>%loop items%<tr>
%loop –struct%<td>%value%</td>%end%
</tr>%end%
...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 304/338
APPENDIX F Output Template Tags
304 B2B Developer’s Guide Version 3.0
%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><p>Departure Information:<br>Ship Date: %value shipDate%<br>Carrier: %value carrier%<br>Shipment Number: %value shipNum%</p>%nl%%nl%%nl%<hr><p>Arrival Information:<br>FOB: %value companyName%<br>%value streetAddr1%%value streetAddr%2%value city%, %value state%
...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 305/338
Overview
B2B Developer’s Guide Version 3.0 305
%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%</p>%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%</p>...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 306/338
APPENDIX F Output Template Tags
306 B2B Developer’s Guide Version 3.0
%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')
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 307/338
Overview
B2B Developer’s Guide Version 3.0 307
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....
%scope buyerInfo%<p>Shipped To:<br>
%value companyName%<br>%value streetAddr1%<br>%value streetAddr2%<br>%value city%, %value state% %value postalCode%
%end%...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 308/338
APPENDIX F Output Template Tags
308 B2B Developer’s Guide Version 3.0
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')%
<p>Shipped To:<br>%value companyName%<br>%value streetAddr1%<br>%value streetAddr2%<br>%value city%, %value state% %value postalCode%</p>
<hr><p>Point of Departure: %value shipPoint%<br>Customer Class: %value buyerClass%</p>
%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})%<p>Shipped To:<br>
%value companyName%<br>%value streetAddr1%<br>%value streetAddr2%<br>%value city%, %value state% %value postalCode%
<hr>%scope custServiceInfo%
<p>For questions or issues about this shipment, contact our CustomerServices Center in %value csCtr% at %value csPhone%. Your accountrepresentative is %value csRep%.</p>
%endscope%%endscope%
...
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 309/338
Overview
B2B Developer’s Guide Version 3.0 309
%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'%<p>Shipped via Federal Express %value serviceLevel% %value trackNum%
%case 'UPS'%<p>Shipped via UPS %value serviceLevel%
%case 'Freight'%<p>Shipped via %transCompany%<br>
FOB: %value buyerInfo/streetAddr1%<br>%value buyerInfo/streetAddr2%<br>%value city%, %value state% %postalCode%
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 310/338
APPENDIX F Output Template Tags
310 B2B Developer’s Guide Version 3.0
%end%</p>
...
%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:
Variable Description
$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'%
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 311/338
Overview
B2B Developer’s Guide Version 3.0 311
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%
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 312/338
APPENDIX F Output Template Tags
312 B2B Developer’s Guide Version 3.0
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 313/338
B2B Developer’s Guide Version 3.0 313
A P P E N D I X
jcode tags
jcode Template........................................................................314
jcode Example......................................................................... 315
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 314/338
APPENDIX G jcode tags
314 B2B Developer’s Guide Version 3.0
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>> ---
}
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 315/338
jcode Example
B2B Developer’s Guide Version 3.0 315
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)>> ---
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 316/338
APPENDIX G jcode tags
316 B2B Developer’s Guide Version 3.0
// [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>> ---
}
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 317/338
jcode Example
B2B Developer’s Guide Version 3.0 317
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 318/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 319/338
INDEX
B2B Developer’s Guide Version 3.0 319
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 320/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 321/338
INDEX
B2B Developer’s Guide Version 3.0 321
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 322/338
INDEX
B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 323/338
INDEX
B2B Developer’s Guide Version 3.0 323
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 324/338
INDEX
B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 325/338
INDEX
B2B Developer’s Guide Version 3.0 325
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 326/338
INDEX
B2B Developer’s Guide Version 3.0
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 327/338
INDEX
B2B Developer’s Guide Version 3.0 327
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 328/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 329/338
B 2 B I N T E G R A T I O N
B2B Developer’s Guide
VER SIO N 3 .0
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 330/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 331/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 332/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 333/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 334/338
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 335/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 336/338
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
Conditions That Cause Failure............................................................................................................. 199
Examples of When to Use.................................................................................................................... 199
SEQUENCE ................................................................................................................................................ 201
Properties............................................................................................................................................. 201
Conditions That Cause Failure............................................................................................................. 202
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 337/338
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
7/23/2019 Sap Bc Developers Guide
http://slidepdf.com/reader/full/sap-bc-developers-guide 338/338
x B2B Developer’s Guide Version 3 0