PRPC52 Integrating With External Systems (PDF Library)

Integrating with External Systems
PegaRULES Process Commander 5.2

© Copyright 2006
Pegasystems Inc., Cambridge, MA
All rights reserved.
This document describes products and services of Pegasystems Inc. It may contain trade secrets and
proprietary information. The document and product are protected by copyright and distributed under
licenses restricting their use, copying, distribution, or transmittal in any form without prior written
authorization of Pegasystems Inc.
This document is current as of the date of publication only. Changes in the document may be made
from time to time at the discretion of Pegasystems. This document remains the property of
Pegasystems and must be returned to it upon request. This document does not imply any commitment
to offer or deliver the products or services described.
This document may include references to Pegasystems product features that have not been licensed by
your company. If you have questions about whether a particular capability is included in your
installation, please consult your Pegasystems service consultant.
For Pegasystems trademarks and registered trademarks, all rights are reserved. Other brand or product
names are trademarks of their respective holders.
Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain
inaccuracies or typographical errors. This document could contain technical inaccuracies or
typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may
make improvements and/or changes in the information described herein at any time.
This document is the property of:

Pegasystems Inc.
101 Main Street
Cambridge, MA 02142-1590
(617) 374-9600, fax: (617) 374-9620
www.pega.com
PegaRULES Process Commander

Document: Integrating with External Systems
Software Version: 5.2
Issue Date: December 2006
Order #: @DPCINTEG08
Contents
About This Document ...........................................................................................................1-1

Who Should Read This Document ...................................................................................1-2
Chapter Overview.............................................................................................................1-3
Integration Services Documentation on the PDN .............................................................1-4
PegaRULES Process Commander Documentation .........................................................1-5
Introduction ...........................................................................................................................2-1
Overview ..........................................................................................................................2-2
Services............................................................................................................................2-4
Connectors.......................................................................................................................2-6
Data Mapping ...................................................................................................................2-8
Integration Accelerators ...................................................................................................2-9
Create Connector Rules (Connector Accelerator).....................................................2-9
Create Service Rules (Service Accelerator)............................................................2-10
Import XSD/DTD .....................................................................................................2-10
Import JavaBeans ...................................................................................................2-11
Create EForm Rules (EForm Accelerator) ..............................................................2-12
Create External Data Table Rules...........................................................................2-13
Create Authentication Configuration .......................................................................2-13
Publish as Web Service Option...............................................................................2-14
Before You Begin ...........................................................................................................2-15
RuleSets..................................................................................................................2-16
Rule Resolution.......................................................................................................2-16
Services Overview.................................................................................................................3-1
Introduction.......................................................................................................................3-2
Service Rule Types ...................................................................................................3-4
Calling Process Commander with Java-Based Services...........................................3-6
Java-Based Services and Distributed Transactions..................................................3-7
Parts of a Service .............................................................................................................3-8
Service Package .......................................................................................................3-9
Service Rule............................................................................................................3-13
Classes and Properties ...........................................................................................3-14
Service Activity........................................................................................................3-15
Parse and Stream Rules .........................................................................................3-15
iv Contents
Listeners and Servers .............................................................................................3-17

Service Testing Features ...............................................................................................3-19
Unit Testing Service Rules......................................................................................3-19
Tracing Service Rules .............................................................................................3-19
Using PAL with Services .........................................................................................3-20
Summary: Creating Services..........................................................................................3-22
EJB, File, Java, JMS, MQ, .NET, SOAP .................................................................3-22
COM, CORBA, Email, HTTP, Portlet ......................................................................3-23
BPEL .......................................................................................................................3-24
Connectors Overview............................................................................................................4-1
Introduction.......................................................................................................................4-2
Connector Rule Types ..............................................................................................4-4
Java-Based Connectors vs. Other Ways to Use Existing Java Code .......................4-5
SQL Connectors vs. Activity Methods .......................................................................4-7
Connectors and Distributed Transactions .................................................................4-7
Parts of a Connector ........................................................................................................4-9
Classes and Properties ...........................................................................................4-10
Connector Activity ...................................................................................................4-11
Connector Rule .......................................................................................................4-11
Parse and Stream Rules .........................................................................................4-12
Databases, Servers, and Other Data Objects .........................................................4-13
Integrator Task for the Workflow .............................................................................4-13
Connectors and Flow Support........................................................................................4-14
Running Connectors in Parallel...............................................................................4-14
Compensating Actions ............................................................................................4-14
Connector Simulation..............................................................................................4-15
ConnectionProblem, the Standard Error Handler Flow ...........................................4-16
Summary: Creating Connectors .....................................................................................4-18
Data Mapping.........................................................................................................................5-1
Introduction.......................................................................................................................5-2
Map To vs. Map From ...............................................................................................5-2
Request vs. Response ..............................................................................................5-3
Mapping Options .......................................................................................................5-4
Properties..................................................................................................................5-5
Creating Data Maps .........................................................................................................5-7
Contents v
A Row in a Data Map ................................................................................................5-7

Map From and Map From Key Fields........................................................................5-8
Map To and Map To Key Fields ..............................................................................5-10
Sources and Targets for Mapped Data ..........................................................................5-13
Mapping to and from the Clipboard .........................................................................5-13
Mapping from a Constant........................................................................................5-15
Mapping to and from Special Default Parameters...................................................5-16
Mapping to and from HTML.....................................................................................5-16
Mapping XML ..........................................................................................................5-18
Mapping Incoming Files ..........................................................................................5-21
Building Custom Map To and Map From Functions .......................................................5-23
Requirements for the Library Rule ..........................................................................5-24
Requirements for the Functions ..............................................................................5-24
Contacting Pegasystems.....................................................................................................A-1
Customer Support ........................................................................................................... A-2
Education Services.......................................................................................................... A-2
Documentation Feedback ............................................................................................... A-3
Office Locations............................................................................................................... A-4
Chapter 1
About This Document
PegaRULES Process Commander provides a set of standard integration services for
creating interfaces to and from external systems. The documentation for these
integration services is presented as follows:
■ This guide, Integrating with External Systems, describes the Process

Commander integration features and presents general concepts and information
for integrating Process Commander applications with other systems.
■ The Integration Services section of the Pega Developer Network (PDN) presents
individual documents for individual types of services and connectors, along with
appropriate RuleSet and code examples for them.
The Pega Developer Network (PDN), located at http://pdn.pega.com, is the primary

technical resource for the Process Commander developer community. The PDN
contains a broad range of technical articles including troubleshooting and “How-To”
information and a comprehensive and searchable knowledgebase to help developers
speed their application development. Before you can use the Pega Developer
Network (PDN), you must register to obtain an account at the following URL:
http://pdn.pega.com
1-2 Integrating with External Systems — About This Document
Who Should Read This Document

If you plan to integrate your Process Commander application with other systems, you
need to read this document. Most likely your job function falls into one of the
following categories:
■ Developers (system architects) — an application developer who is responsible

for application design and architecture, database operations, security design, and
implementation; creates the class structure for the application with supporting
automation capabilities, and implements interfaces with external systems.
■ System administrators — a systems engineer who is responsible for installation

and setup, system-level security, database management, and other operational
functions such as control, tuning, and troubleshooting.
For access to certain integration features, you need administrator rights. That is, you
should have the SysAdmin role and the Developer portal assigned to your operator
ID record.
About This Document — Chapter Overview 1-3
Chapter Overview
The following is a list of the remaining chapters in this book:
■ Chapter 2, Introduction — presents an overview of services, connectors, and the

rule types and features that support them.
■ Chapter 3, Services Overview — describes the components and interactions of

Process Commander services.
■ Chapter 4, Connectors Overview — describes the components and interactions

of Process Commander connectors.
■ Chapter 5, Data Mapping Overview— describes how to correlate the data inside
Process Commander with the appropriate properties or fields in the external
system.
■ Appendix A, Contacting Pegasystems — provides information about how to

contact Pegasystems.
Integration Services Documentation on the PDN

As mentioned, information about building specific types of services and connectors
is presented in individual documents for the individual types of service or connector.
These documents, along with RuleSet and code samples, are posted on the
Integration Services section pages of the PDN.
After you read this book and have obtained a PDN account (from
http://pdn.pega.com), go to the Integration Services section of the PDN and
download the documents and samples for the service and connector types that you
plan to build
You can access the PDN site in the following ways:
■ When you have administrator rights in Process Commander, the dashboard

displays section called Monitor System. Click the Pega Developer Network link
in this section of the dashboard.
■ From a browser, go to:
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp
About This Document — PegaRULES Process Commander Documentation 1-5
PegaRULES Process Commander Documentation

Pegasystems provides the following documents for PegaRULES Process
Commander.
■ Introduction is an overview for business users, introducing concepts for and

insight into applications built on Process Commander.
For more technical users, the Introduction provides an overview of concepts,

architecture, processes, and features of Process Commander applications.
■ Quick Start is a tutorial for business users and technical users. For business
users, the Quick Start provides the experience of using an application — its look
and feel — with a walk through features in relation to a business solution.
For technical users, the Quick Start provides a tutorial with standard elements
used in configuring a Process Commander application, providing guidance in
using and modifying an application.
■ Designing Your Application with SmartBuild provides the design methodology

essential for systems and technical staff in developing applications according to
best practices.
■ Administration and Security provides information on system administration and

on setting up security of applications and systems. This guide is useful for both
system administrators and technical staff for initial startup, setup, and day-to-
day administration of Process Commander.
■ Integrating with External Systems supports IT professionals who plan, design,

build, and test the interfaces with other systems that can be used with a Process
Commander application. The document provides information on setting up
interfaces between systems, enabling connection to legacy systems and for
retrieval of information as part of application use. Additional documentation and
examples are available for various integration protocols.
■ Authentication in PegaRULES Process Commander supports application

developers by describing standard Process Commander authentication methods
and explaining how Process Commander interacts with external methods of
authentication.
■ Using the Performance Tools describes how to use the performance analyzer
(PAL) tool.
■ PegaRULES Process Commander System Management Reference describes the

features provided by and the information displayed by the System Management
application.
■ prconfig.xml File Settings Reference describes all the configuration settings

held in the prconfig.xml file.
■ PegaRULES Process Analyzer User Guide describes how to install and use
Process Analyzer, an optional component that provides online analytical
processing (OLAP) data for PegaRULES Process Commander.
■ PegaRULES Process Simulator User Guide describes how to install and use
Process Simulator, an optional component that provides simulation of
PegaRULES Process Commander business processes.
■ Application Developer Help is an extensive online help system that provides

information on concepts, forms, and functions of PegaRULES Process
Commander. Contextual information about Process Commander is available on
browser pages by selecting Help from the menu or clicking on the toolbar.
■ Installation Guide (located on the installation media) — describes how to install

Process Commander.
■ Upgrade Guide (located on the installation media) — describes how to upgrade

an existing Process Commander installation.
■ Release Notes (located on the installation media) — lists known issues regarding
the Process Commander release.
Documentation for a release is provided on the installation media. The core

documents for PegaRULES Process Commander are available through Application
Developer Help. The entire documentation library is available through the PDN
(located at http://pdn.pega.com). Selected documentation is available in hardcopy
form.
Chapter 2
Introduction
PegaRULES Process Commander applications are designed to complement other
systems and technologies that you already have in place for doing work. The
Process Commander integration services are based on industry-standard technologies
for external system integration. Whether you have information in Process
Commander that you want to make available to other systems, or there is information
in an external system that you need to access from within a Process Commander
workflow, you use the integration services features to accomplish your goal.
This chapter contains the following sections:
■ Overview
■ Services
■ Connectors
■ Data Mapping
■ Integration Accelerators
■ Before You Begin

2-2 Integrating with External Systems — Introduction
Overview
Process Commander provides integration facilities that support interactions between
its applications and external systems, databases, Web sites, e-mail servers, and so on.
By using these features, Process Commander can exchange information with many
kinds of external systems, including relational databases, Enterprise Information
Systems (EIS), e-mail servers, Excel spreadsheets, and even simple text files.
Process Commander interfaces support a wide range of technologies and standards,

including HTML, HTTP, Simple Object Access Protocol (SOAP), Microsoft .NET,
Sun Microsystems Enterprise JavaBeans™ (EJB), IBM WebSphere MQ® messaging,
Java Message Service (JMS), J2EE Connector Architecture (JCA), Business Process
Execution Language (BPEL), JSR 94, JSR 168, and others. These interfaces are
called integration services.
Integration services enable communications or exchanges between Process

Commander applications and external systems, whether an exchange is initiated from
a user interface or browser (by a user) or whether an exchange is initiated from a
server or a background process. In integration situations, a Process Commander
application can act as either the client or the server, communicating with both
back-end and front-end applications.
Integration services are grouped into the following categories:
■ Services — programmatic components that define and implement an interface

between an external application that acts as the client and a Process Commander
application that acts as the server.
Services respond to requests or messages sent from external systems to Process

Commander. The messages can request data, deliver data, or even deliver a
work object on behalf of the external system.
■ Connectors — programmatic components that implement an interface that is

defined by an external system. With connectors, your Process Commander
application acts as the client and the external system acts as the server.
Introduction — Overview 2-3
Connectors make requests or send messages to external systems, typically as

part of a workflow process. Do not confuse connector rules or interfaces with
flow connectors, the arrows on a Visio workflow diagram.
In addition, the following integration components support services and connectors:
■ Import and export mechanisms, rules that parse incoming text or files, and rules
that assemble messages or requests to be sent to external systems
■ Data mapping and transformation functions
■ Accelerators that generate rules and interfaces, automating certain integration

tasks
■ Testing and troubleshooting tools, especially the System Management client

application
A Process Commander application typically has multiple connectors and services

that make requests to and process requests from external systems.
Services
External systems can make requests to Process Commander applications; services
respond to those requests (Figure 2-1).
For example, suppose a Process Commander application contains data about sales
taxes in the USA and an activity that calculates the tax. An accounts payable
program located elsewhere in the enterprise needs to use the sales tax rate for
individual states on a regular basis. In this case, you would expose the activity as a
service to make it accessible to the accounts payable program. After you create the
service, the program can make calls to Process Commander when it needs to use the
current sales tax rate for a state.
Tax rate?
Client Service
Tax rate = 4%
External System Process Commander

Figure 2-1. External Clients Access Rules Through Process Commander Services
To define most services, use the Create Service Rules Accelerator (Service
Accelerator) to create the key rules and data objects, which is available from the
Wizards section of the Integration page. As the name implies, the accelerator
prompts you to enter information about the service that you want to create. Then the
accelerator generates the appropriate rules and data objects for the service.
A service package is a data object that describes how the services manage state. For
services of type Enterprise JavaBean™ (EJB), COM, CORBA, Java, Microsoft .Net,
Portlet, and SOAP, the service package form is also used to generate a deployment
file appropriate for that technology.
While the service package is the container for the service, the service rule itself holds
information about how the individual interactions with the external system. For
example, SOAP service rules govern a SOAP exchange. They parse SOAP requests
and assemble SOAP responses.
Introduction — Services 2-5
For more information about services, see Chapter 3, “Services Overview.” For
information about the Service Accelerator, see Using the Service Accelerator,
available on the Pega Developer Network (PDN).
Connectors
Connectors are the mechanism that Process Commander uses to send messages
to or make requests of external systems and then process the results or response
(Figure 2-2).
For example, suppose that for a task in a Process Commander workflow the user
needs the current price of a product. The enterprise has an ERP system that exposes
product prices as a Web service and a SOAP connector is used to obtain the
appropriate pricing information from the ERP system.
Price for x?
Workflow Connector External System
Price for x = 10
Process Commander
Figure 2-2. A Connector Enables a Workflow to Make Requests to an External Server
To create a connector of type EJB, Java, .NET, SOAP, or SQL, use the Create
Connector Rules Accelerator (Connector Accelerator), which is available from the
Wizards section of the Integration page. As the name implies, the accelerator
prompts you to enter information about the connector that you want to create. Then
the accelerator generates the appropriate rules, activities, classes, and properties that
the connector needs. (For connectors of type HTTP, JCA, JMS, MQ, and BPEL, you
must create the rules manually.)
After you create a connector, use Visio to insert an Integrator task into an existing
workflow rule. The Integrator task calls the connector through the activity that the
accelerator generated, and passes to the connector parameters from the workflow.
In the example in Figure 2-2, the Integrator task passes in the UPC code of a product
to an external SOAP service. As with the service rules, the connector rule holds
information about that protocol or technology and, in this case, converts the
parameters, their values, and other information into a valid SOAP request and calls
Introduction — Connectors 2-7
the pricing Web service on the EIS system. The connector parses the returned SOAP
response and writes the price into a Process Commander property that the workflow
can access.
For more information about connectors, see Chapter 4, “Connectors Overview.” For
information about the Connector Accelerator, see Using the Connector Accelerator,
available on the Pega Developer Network (PDN).
Data Mapping
When you configure a service or connector, you also match or correlate the
properties in the Process Commander application to the corresponding data fields or
properties in the external system. This is called data mapping. You map both the
data that comes in to Process Commander as well as the data sent from Process
Commander.
The service or connector can send and receive property values or an HTML or XML
stream to and from the external system. When you configure the data mapping for a
service or for a connector that is not created by a accelerator, you map the data
elements (values) that are used by the service or connector. If incoming data must be
parsed before it can be processed — the incoming data is in a delimited file, for
example — map the data using a parse rule. If outgoing data needs to be presented as
formatted HTML or XML, map the data using an XML or HTML stream rule.
When you use the Service Accelerator or the Connector Accelerator, the accelerator
configures the data mapping for the service or connector rule. The Service
Accelerator creates suggested lists of input and output parameters based on the
purpose of the service. The Connector Accelerator creates input and output lists
based on the source material it parses while generating the rules and also creates
properties in Process Commander that represent the data in the external system.
Other integration services accelerators also assist you in data mapping by creating
class and property rules that implement the data model of an external system. For
more information about data mapping, see Chapter 5, “Data Mapping.”
Introduction — Integration Accelerators 2-9
Integration Accelerators
Process Commander provides several rule generation and interface generation
accelerators that automate some of the integration tasks. The integration accelerators
are accessible from the Wizards section of the Integration page. Additionally, you
can use the Publish as Web Service option on the Process tab of a flow rule to
convert a flow into a SOAP or BPEL Web service.
Create Connector Rules (Connector Accelerator)

The Connector Accelerator creates connector rules for only those connectors that use
a protocol or technology that exposes its metadata. For example, because a SOAP
service has a Web Service Definition Language (WSDL) file that defines its
interface, the Connector Accelerator can create SOAP connectors.
To use this accelerator, first create an abstract class (typically one that inherits from
Data-) for the accelerator to use as the base for the generated rules, classes, and
properties for the connector. Then run the accelerator and identify the class name and
the file, URL, or database that defines the data structure of the external system.
The accelerator uses the Interface Generator tool to import the metadata of the
external system that you want connect to. It then parses and converts the information
into data classes and properties (subclasses of the class that you specified), connector
rules (instances of Rule-Connect-*), activities that call the connector rules.
You can use the Connector Accelerator to create the following kinds of connectors:
■ Enterprise JavaBean™ (EJB)
■ Java class
■ SQL (relational database)
■ SOAP Web service
■ Microsoft .NET Web service
For more information, see Using the Connector Accelerator, available on the PDN.
Create Service Rules (Service Accelerator)

The Service Accelerator creates service rules and data objects for several service
types. It creates services that do one of the following: create a work item and start the
flow for that item, perform a flow action on an existing work item, or call an activity
that you have created to do something else.
Run the accelerator, select the type of service you want to create, and fill out the
forms that the accelerator displays. Based on your selections, the accelerator creates
the appropriate rules and data objects for a service of that type. For services of type
SOAP and dotNET, the accelerator also generates a deployment file (a WSDL file).
For services of type EJB and Java, you open the generated service package and
generate the deployment file manually.
You can use the Service Accelerator to create the following kinds of services:
■ EJB
■ File
■ Java
■ JMS
■ JSR 94
■ MQ
■ .NET
■ SOAP
For more information, see Using the Service Accelerator, available on the PDN.
Import XSD/DTD
The Import XSD/DTD Accelerator implements in Process Commander the data
model described in an XSD or DTD file. This accelerator uploads and analyzes a
DTD or XSD file that you create or identify and then creates the following according
to the options you select:
■ Class rules that represent each element or type defined in the document and
properties that define each parameter
■ Model rules for each class rule
■ XML parse rules
■ XML stream rules
To use this accelerator, first create an abstract class for the accelerator to use as the
base for the generated rules, classes, and properties. Then run the accelerator and
make selections from the displayed forms.
For more information, see Data Mapping XML, available on the PDN. See also the
Application Developer Help system.
Import JavaBeans
Many organizations have pre-existing Java data models, instances of which represent
their business or work objects. If requests or responses to/from an external system
will include Java objects that are instances of JavaBeans, your applications can use
the Java Pages feature to interact with those objects as though they were pages and
properties on the clipboard.
You use the Import JavaBeans accelerator when a JavaBean instance will be sent
from an external system to a Process Commander Java-based service rule. The
accelerator creates class and Java property rules (properties of mode Java Property or
Java Property List) that reflect the data model described in a Java class file.
You start the accelerator and identify the source Java class. The accelerator imports
the Java class through introspection and then generates the appropriate class and
property rules. It also creates Java wrapper classes that implement the get and set
methods from the Java class through the PRObjectWrapper interface of the
Clipboard Java API. The Java wrapper classes provide you with a standard way to
access Java objects as clipboard pages from within Process Commander.
Note: When your Process Commander application needs to call a method in an

external Java class, you use the Connector Accelerator to generate a Java
connector. If the method invoked by the connector has arguments that are
themselves instances of JavaBeans, the Connector Accelerator will generate the
appropriate class and property rules and Java wrapper classes in addition to the
connector and activity rules.
For more information about using the Java Pages feature, see Working with Java
Objects in Process Commander, available on the PDN. For information about the
PRObjectWrapper interface, see the PublicAPI JavaDocs topics.
Create EForm Rules (EForm Accelerator)

The EForm Accelerator helps to implement the Process Commander SmartForms
feature, which automates the processing of and creation of PDF forms, eliminating
manual steps. This accelerator uses a flow to guide you through the process of
creating an eForm file rule and its corresponding eForm map rule.
The eForm Accelerator imports and parses a PDF form that you identify. Then it
displays a list of the names of the interactive form fields in the PDF form, making it
easier for you to match the fields to Process Commander properties. If you create the
rules yourself, you must manually enter the name of each form field in an eForm
map rule and verify that you made no data entry errors on your own.
Because the accelerator uses a flow rule, the data you enter is stored as a work object
until you finish the flow. When you resolve the work object, the eForm Accelerator
creates an eForm file rule for the uploaded PDF form and an eForm map rule that
specifies how the fields in a form like that one map to Process Commander
properties.
For information about using the SmartForms feature to process incoming PDF forms
or to generate a PDF form, see Working with PDF Forms and Documents, available
on the PDN.
Create External Data Table Rules

The Create External Data Table Rules wizard (External Table wizard) creates rules
and data objects that implement in Process Commander the data model of an external
database table. With these rules and data objects in place, you can use the Obj- series
of activity methods to interact with the data in an external table in the same way that
you use them to read and write data to the Process Commander database rather than
using a SQL connector rule.
Before you begin, obtain the appropriate JDBC database driver for the database and
a database user account for Process Commander. Then configure a data source that
points to the external table from the application server Process Commander is
running in and create an instance of Data-Admin-DB-Name that uses the data source
you configured.
You start the wizard and identify the Data-Admin-DB-Name that you created. The
wizard uses the data source to connect to the external database. You select a table,
and the wizard generates an instance of Data-Admin-DB-Table, a class rule that
represents the table, and property rules that represent the columns in the table. It also
generates a model rule for the class rule.
Create Authentication Configuration

The Create Authentication Configuration wizard helps you configure your Process
Commander system to use an LDAP-compliant directory server to authenticate users.
The wizard creates an authentication service data object (Data-Admin-AuthService)

that holds the connection information for the LDAP directory. It also specifies two
standard activities that use the connection information to bind to the directory server,
authenticate the users, and re-authenticate users if their sessions expire.
There are two parts to an authentication service: the data object itself and a servlet
definition in the Process Commander web.xml file that refers to the data object.
The web.xml file in Process Commander 5.1 has five default servlet definitions:
WebStandardLDAP1, WebStandardLDAP2, and so on, up to WebStandardLDAP5.
As long as the name you choose for an authentication service object matches one of
the default servlet definitions, you can implement up to five authentication service
configurations without having to edit the web.xml file. Note that editing a web.xml
file means undeploying and then redeploying Process Commander.
For more information, see Authentication in PegaRULES Process Commander 5.2,

which is available on the PDN.
Publish as Web Service Option

The Publish as Web Service option on the flow forms creates service and connector
rules that make a flow available as a BPEL process named PublishedFlows. To use
this option, you must first create and save a flow. Then, select the Process tab and
click the Publish button.
The Publish feature creates two SOAP service rules and packages them with three
SOAP connector rules to create a BPEL Web service. It also generates three WSDL
documents and one BPEL document.
Introduction — Before You Begin 2-15
Before You Begin

To create a service or connector, you must understand Process Commander terms,
forms, functions, and the SmartBuild design and development process. You must
have experience in defining Process Commander class rules, properties, models,
activities, and other types of rules.
You also need some knowledge of the technology or protocol for which you are
building the service or connector. For example:
■ To create a SOAP service, you need to know how to write a SOAP client so that
you can test the SOAP service.
■ To create a SQL connector, you need to know information about the database,
such as the database name, database host server, and the JDBC connection pool
name so that you can define the database with a Data-Admin-DB-Name data
object. Additionally, you need to know how to write SQL queries so that you
can test the connector.
■ To create Java-based services and connectors, you need to understand how

classes are included in the Process Commanders. For information, see PRKB-
20931 “About the Process Commander Version 5 Class Paths,” available on the
PDN.
■ To create a connector, you should also know enough about flow design so that
you can attach the connector and test it from within the flow.
For information about related documentation, see the listing of additional

publications and resources in Chapter 1, “About This Document.”
RuleSets
If the Process Commander application is designed to use more than one RuleSet,
consider how services and connectors interact with the Process Commander system
while determining the RuleSet to use for service and connector components:
■ Connectors typically run in the current requestor session — for example, the
session for the workflow. Assign the RuleSet for connectors to the access groups
of the users whose work will trigger connectors from a workflow process.
■ Services typically obtain a new, separate requestor ID and session and they use
the access group specified in the service package. Assign the RuleSet for
services to the access group you specify in the service package.
Additionally, the RuleSet lists of services and connectors and your RuleSet list must
include Pega-IntSvcs RuleSet — the standard RuleSet for integration services.
Rule Resolution
Many Process Commander rules have a multipart key that is used to identify the
correct rule to use in any situation. The rule that the system uses is based on the key
names that you provide when referring to the rule, and on elements such as
inheritance, versioning, and security.
The rules and data classes that you create for services and connectors are subject to
the same rule resolution algorithms as any other rules or data classes. This means, for
example, that you can design multiple versions of the same connector for use in
different versions of the same workflow.
Chapter 3
Services Overview
A service is a set of rules and data objects that reveals a function or data model of
your application to an external system. You use services to enable an external system
to access Process Commander data and processing. For example, the external system
delivers a work object to your Process Commander application. When you create a
service, you are defining how Process Commander interoperates with an external
system when the external system initiates an inbound request.
■ Introduction
■ Parts of a Service
■ Service Testing Features
■ Summary: Creating Service

3-2 Integrating with External Systems — Services Overview
Introduction
A service receives input from an external system and can respond in some way. For
example, a service can reply with data that the external system requested and it can
process the incoming data to determine that it needs to create a work object and
initiate a workflow.
The following is a high-level description of how a service works:
1. An external client or system assembles and delivers a message or request to a

Process Commander service. The message identifies the service package that
contains the service rule or method to invoke.
2. The service package locates a service rule.
3. The service rule, in turn, invokes the appropriate rules to map the incoming
parameters to Process Commander properties.
4. The service rule invokes an activity. The activity processes the input
properties and completes the task of the service. As mentioned, perhaps the
service extracts data from the Process Commander database or delivers a work
item to Process Commander. The data mapping for the service rule then maps
appropriate values into output properties.
5. The service assembles a response message from the output properties and
sends the response.
The architecture for this process is shown in Figure 3-1.

Services Overview — Introduction 3-3
External System or
Client
request response
Process
Process
Commander Service Package Commander
Service Rule
property property
Clipboard
Service Activity
Figure 3-1. Architecture for a Service
This description does not include lower-level processing details because they vary
for each type of service. For a more detailed description of the processing for a
specific type of service, see the documentation on the Integration Services section of
the Pega Developer Network (PDN).
Service Rule Types

The Process Commander services are based on industry-standard technologies.
Process Commander provides the following standard types of services:
■ EJB service rules expose functions in a Process Commander application as

though they were methods of an Enterprise JavaBean.
■ JSR 94 service rules receive and respond to requests from external applications
through JSR 94 invocations. A JSR 94 service is used when a part or all of a
Process Commander application is embedded in another Java-based application.
■ Java service rules expose functions in a Process Commander application as

though they were public methods of a Java class.
■ SOAP service rules provide Web services to SOAP (Simple Object Access
Protocol) clients.
■ .NET service rules provide Web services to Microsoft .NET clients (external
systems based on the Microsoft .NET Framework).
■ HTTP service rules process and respond to HTTP requests that contain XML or
other string data (text) or HTML POST data. Use HTTP rules when you want to
send XML or string data using a messaging protocol like SOAP.
■ JMS service rules respond to messages sent by Java Message Service clients
to a queue or topic. JMS services read messages from the queue or topic.
■ MQ service rules accept WebSphere MQ (formerly called IBM MQSeries)

messages from external systems and respond to them.
Note: When Process Commander is deployed as an enterprise application, you

use a message-driven bean (MDB) as the listener for message-based service
rules (JMS and MQ). This means that although you can use WebSphere MQ as a
JMS service provider, you must use JMS MDB listeners with JMS service rules
rather than MQ listeners with MQ service rules when Process Commander is
deployed as an enterprise application.
■ Portlet service rules provide the mechanism for displaying Process

Commander features and functions in JSR 168-compliant portlets that are
displayed by JSR 168-compliant portal servers. Defined by the Java

Community Process, JSR 168 describes a set of Portlet APIs.
■ BPEL service rules act as a container for the SOAP services and connectors that
communicate with the same external Business Process Execution Language
(BPEL) application when the external BPEL application starts a Process
Commander flow.
■ E-mail service rules import and evaluate e-mail messages, including their
headers and attachments.
■ File service rules evaluate the contents of files that are stored outside of Process
Commander.
■ COM service rules support the creation of a custom Windows ActiveX control
that you can integrate with external (desktop or server) Windows applications by
using Microsoft Visual Studio or similar Windows development tools. The
ActiveX control interacts with other parts of the Windows application using
Microsoft Component Object Model (COM) protocols.
■ CORBA service rules let external clients request services of Process

Commander through an Object Request Broker (ORB) that implements the
Object Management Group Common Request Broker Architecture (CORBA)
standard. Process Commander can automatically generate an Interface
Definition Language (IDL) file.
■ SnapStart is a lightweight data import facility that conveys data from one
desktop application into Process Commander under the control of a user.
Building a SnapStart interface requires skills in creating HTML forms and
writing short activities. Unlike the other services, the SnapStart service does not
rely on a subclass of Rule-Service.
You can use the Service Accelerator to create EJB, File, Java, JMS, JSR 94, MQ,
.NET, and SOAP services that deliver work items, perform flow actions on work
items, or call an activity that you have created.
Calling Process Commander with Java-Based Services

Process Commander provides three Java-based service interfaces (EJB, Java, and
JSR 94) that you can use to request services using either a signature-based or API
invocation-based communication:
■ Signature-based means the external application invokes the Process Commander

service rules through a proxy EJB or Java class generated by the service
package. The proxy publishes the method signatures of the service rules. A
client application sends the input to the service rule by calling a method in the
proxy — a method with parameters that match the service rule. The proxy
manages type validation, constructs the URI for the service rule, and so on.
■ API invocation-based means the external application communicates with the

Process Commander service rules either through a (generic) business delegate,
directly through the PRService EJBs, or through an instance of the PegaRULES
engine. The client application invokes the same Java method no matter which
service rule is targeted in Process Commander. The parameters provided in the
invocation identify the service rule and provide the input for the service rule.
Unlike the signature-based style, there is no compile-time validation of method
names and parameters because you are not using a proxy compiled by Process
Commander.
EJB and Java services support both invocation styles. JSR 94 services support the
engine API invocation style only, in accordance with the standards set by the JSR 94
specification.
The choice of service rule type and invocation style depends on the situation and
requirements. For example, if the application from which you want to call Process
Commander is an enterprise application, use an EJB service with a generated proxy.
If your organization is committed to complying with the JSR 94 specification, use
JSR 94. For a POJO (“plain old Java object”) interface to Process Commander, use
Java services with or without a generated proxy.
For more information, see Building EJB Services and Building JSR 94 Services,
available on the PDN.
Java-Based Services and Distributed Transactions

A distributed transaction is a set of operations that include more than one resource
manager and that must be treated as one operation. For example, updates to more
than one database in one transaction, or, a database operation and the sending or
receiving of a JMS message in the same transaction. When Process Commander is
deployed as an enterprise application, the processing performed by EJB, Java, and
JMS services can participate in distributed transactions that are either bean-managed
or container-managed.
For more information, see Designing Applications that Ensure Data Integrity and
Building EJB Services, both of which are posted on the Integration pages of the
PDN.
Parts of a Service
A service is made up of several rules and data objects; some types of services require
more parts than others. For EJB, File, Java, JMS, JSR 94, MQ, .NET, and SOAP
services, you can use the Service Accelerator to create the key parts. For COM,
CORBA, e-mail, or portlet services, you create all the rules and data objects yourself.
A service begins with a service package data object. A service package is similar to
a container class. A service package represents the service as an application and the
service rules represent individual functions or methods in that application.
The class rule that the service exposes is typically a direct or indirect subclass of
either the Data- or Work- base class. When creating the service, you determine the
appropriate class rule and the significant properties for the service.
A service has an activity that manipulates the values that are placed on a clipboard
page by the service that may start a work object in a flow. But it is the service rule
that assesses the incoming messages and writes input parameter values to the
clipboard. The service rule also assembles and sends the appropriate response after
the activity is finished with its task. Certain kinds of services typically have more
than one service rule (EJB, BPEL, Java, SOAP, .NET), while other kinds typically
have only one service rule (MQ, JMS, portlet).
Additionally, depending on its type, a service has some of the following components:
■ For File services and sometimes for SOAP, dotNet, or Email services, a parse
rule. For a SOAP, dotNet, or Email service, you may also need an XML stream
rule for assembling the response.
■ For Email, File, JMS, or MQ services, a listener. A listener is a background

process that monitors an inbox, a message queue, or a directory, routes messages
from those locations to the appropriate service rule and transmits the reply
messages.
■ For MQ and Email services, a server data object that holds connection
information.
■ For JMS services, a JNDI server data object.

Services Overview — Parts of a Service 3-9
Service Package
The central part of the service is the service package. As the name implies, the
service package instance acts as a package or container for the service rules that
make up the service. The first key in the three-part key to a service rule is the name
of a service package. Therefore, all the services that use the same service package
name as the first key belong to the same service package.
The service package represents the service as an application. As such, the service
package has global configuration settings for all the services that belong to it:
■ The access group that the service rules use when they run as unauthenticated
users. The service rules must belong to one of the RuleSets listed in the access
group.
■ Whether the services must run as authenticated users. If so, the incoming
message from the external client application must include the name and
password of a valid Process Commander operator.
■ Configuration information about the requestor pool when the service rules run
as unauthenticated users and session state is stateless.
■ Whether the service is stateless or not.

− If the service is stateful, you specify whether to keep the requestor session
open and when to close it in the service rules. (See “Requestors” on page
3-14 for more information.)
− If the service is stateless, the End Requestor option in the service rule does
not apply.
Additionally, for several service types, you use the service package form to generate
the deployment file that describes the functions in the service in a format that is
appropriate for that protocol or technology.
Authentication
Services can run as authenticated or unauthenticated users.
To specify that a service must run as an authenticated user, select the Requires
Authentication option on the Context tab of the service package. Typically, you
would also set the session state option in the Processing Mode field to Stateful,
although a service can run as an authenticated user in a stateless session.
The client application that sends messages must then pass in its authentication
credentials (a valid username and password) in the manner appropriate for the
technology.
Access Groups and RuleSets

The access group specified in the service package is consulted when a client
application sends a request to a Process Commander service. The request identifies
the service, which includes the service package. The service package uses its access
group to determine the correct version of the service rule through rule resolution.
The access group also determines the correct version of the service activity rule,
properties, and any parse, stream, or other rules.
■ If the service runs as an unauthenticated user, Process Commander continues to

use the access group specified in the service package to evaluate the rules.
■ If the service runs as an authenticated user, Process Commander uses the access
group associated with the user ID to evaluate the rules.
Requestor Pools
A requestor pool is a set of requestors that Process Commander reserves for use by
the services in a specific service package. Requestor pooling is available for
stateless, unauthenticated service requests only. Requestor pooling often improves
the performance of a service because requestors are reused, their allocated resources
are shared, and the service does not have to wait for a requestor to be created.
The first time a service from the service package runs, Process Commander creates a
requestor for it and creates the pool for the service package. When the service
completes processing, Process Commander puts the requestor in the pool. The next
time a service from that service package runs, Process Commander assigns the
service a requestor from the pool if one is available. Otherwise, Process Commander
creates and assigns a new requestor. Once again, when the service completes its task,
Process Commander returns the requestor to the pool.
There are two categories of requestors associated with a pool:
■ Idle requestors are currently in the pool, waiting for a service request.
■ Active requestors are currently out of the pool, managing service requests.
You specify how many requestors can be in the pool on the Pooling tab of the
service package form. The setting for the number of idle requestors defines the size
of the pool. The setting for the number of active requestors defines how many
concurrent requestors you want to allocate to the services in the service package.
When the pool has no idle requestors, Process Commander continues to create new
requestors for service requests until it reaches the limit specified for active
requestors. If a service request arrives after that limit is reached and no idle
requestors are waiting in the pool, Process Commander waits to manage the request
until an active requestor returns to the pool.
When an active requestor completes processing, Process Commander checks the

limit for idle requestors before returning that requestor to the pool. If the pool is
under the limit, the requestor becomes idle and Process Commander returns it to the
pool. If the pool is at the limit, Process Commander deletes the requestor instead.
When you are testing or monitoring a service, you can examine the status of the
requestor pool in the System Management application.
Deployment Components
For SOAP, dotNet, BPEL, EJB, Java, Portlet, COM, and CORBA services, you use
the service package form to generate deployment files. Process Commander
translates the functions and processing provided by the service rules in that service
package into the appropriate kind of deployment component for a service of that
type.
The service package can generate the items shown in Figure 3-2.
Service Type Deployment File Type

SOAP .wsdl
.Net .wsdl
Portlet .war
Java .jar
EJB .jar
COM .dll
CORBA .idl
Figure 3-2. Types of Deployment Files
Use the deployment files as appropriate for that technology. For example, for a
portlet service, deploy the portlet war file on a portal server. For an EJB service,
deploy the EJB jar file (which acts as a proxy EJB) in an EJB container. For SOAP
and .NET, use the WSDL files to help develop the client applications that
communicate with the service.
Note: For BPEL services, there are two ways to generate deployment files:
using the Publish option on a flow form or the Deployment tab in the BPEL
service rule form.
Service Rule
The service itself is defined by an instance of the appropriate Rule-Service- subclass.
The service rule handles the details for this kind of request; that is, the service rule
maps the input parameters into clipboard properties and then calls an activity to
process the request.
For example, a SOAP client sends a SOAP message, which a SOAP service rule
parses into clipboard properties. Similarly, the service rule also maps the appropriate
clipboard properties for the SOAP response.
The service rule holds the following types of information:
■ Class of the primary clipboard page that the service uses
■ Name of the primary clipboard page that the service uses
■ Name of the service activity
■ Information about whether to keep the requestor session open or to close it after
the service rule is finished.
■ Information about recognizing and reporting exceptions
■ The list of input and output parameters, their data types, and how their values
are mapped to and from clipboard pages
With the exception of the email service, a service rule has three key parts:
■ Name of the service package. The service package must exist before you can
create the service rule.
■ Name of the service class. This name is a string; it is not an instance of Rule-
Obj-Class. The service package name and service class name are used to group
service rules.
■ Name of the service method. This name is a string; it is not an instance of Rule-
Method. The service method name describes what the service rule does. This is
the only key for an email service rule.
An incoming message must identify the service by specifying all three parts of the
name (package, class, and method) in the message.
Requestors
Service rules and listeners are represented as Application requestors (requestors of
type Application) while they are processing a service request. Whether the service
runs in a stateless or stateful session is specified by the service package. However,
for stateful services, you specify whether to close the requestor session when a
service completes its processing or whether to keep the session open for subsequent
requests from other services in the package with the End Requestor option.
When a service is stateful, its requestor does not return to the pool unless the End
Requestor option is selected.
Sample Rule Instances

The Pega-IntSvcs RuleSet contains sample instances of each service rule type that
you can examine. They are not working samples. They are examples that show the
kind of information needed by a service rule of that type.
With the exception of the email service rule, the name of each sample rule is
CustomerPackage.CustomerClass.CustomerMethod. The email sample rule is named
CustomerMethod.
Classes and Properties

Because you use a service to reveal data or a function that exists in your Process
Commander application, it is likely that the class rule that your service will interact
with already exists. However, if you are developing the service at the same time that
you are developing the Process Commander application, you may need to create the
pertinent class and property rules. Typically, the pertinent class rule inherits from
either Data- or Work-.
Your task is to identify the pertinent class rule, properties, and data types for the
class rules that the service interacts with so that you or the Service Accelerator can
map data correctly. If the classes or properties do not exist, you create them. For
example, you may need to define additional properties to hold derived data,
depending on what the service will do with the incoming requests.
If you use one of the integration accelerators to create in Process Commander the
data model of the external system sending messages, the service may be interacting
with two separate class structures within Process Commander: the data structure
created to manage the messages, and the data structure of a work object. In this case,
the service activity can set property values from the class structure created for the
messages into work object properties that you create for this purpose.
Service Activity
A service activity evaluates the property values that are stored on clipboard pages
and takes an action.
For example, the action might be to deliver a work item and start the flow for it. Or
perhaps the activity performs a flow action on an existing work item. In other cases,
the service activity might call other Process Commander activities that can
manipulate a work item or perform other tasks. The service activity might write
values to the Process Commander database for permanent storage.
When you use the Service Accelerator, you create a service that does one of three
things: creates a work object and starts the workflow for it, performs a flow action on
an existing work object, or calls an activity that you specify. If you select either of
the first two options, the service calls one of two standard service activities. If you
select the third option or you are creating a service rule yourself (without the
accelerator), you must either identify or create the activity for the data class that the
service is exposing.
When you create a service rule yourself, you designate the service activity by
entering its name in the Activity Name field on the Service tab of the service rule.
Parse and Stream Rules

For some services, the service rule requires additional information to parse the
incoming data and/or assemble the response. For example, File services can evaluate
any kind of input file, but they need information about the structure of the incoming
files to parse them correctly. That information is provided with a parse rule.
For File services, create an instance of one of the following parse rules to assess the
incoming data:
■ Parse delimited — parses records in which the fields are separated by a

character delimiter such as a comma.
■ Parse structured — parses records in which the fields cover a specific range of
columns in an input string; for example, the first field occupies columns 1
through 5, the second field occupies columns 6 through 20, and so on.
Note: It is also possible to use a delimited or structured parse rule for the POST
data sent to an HTTP service rule.
The structure of the incoming message determines whether an HTTP, SOAP, .Net,
Java, EJB, JMS, or Email services needs an XML parse rule:
■ If the request contains parameters with simple string or numeric values, the
service rule can process it without a parse rule.
■ If the request includes a string parameter with XML code embedded in its value,
the service needs an XML parse rule to parse the string in that parameter.
■ For SOAP and .NET, if the request an XML object, the service needs a model
rule to use to interpret the schema of the object.
You can use the Import XSD/DTD accelerator to create XML parse, XML stream, or
model rules needed by the service rule. However, you must create structured and
delimited parse rules and HTML stream rules manually.
When a service needs a parse rule to process incoming data, specify the name of the
rule in the data map for the request. Conversely, if the response to the incoming
request is formatted as an HTML or XML stream, specify the name of the rule in the
data map for the response.
Note that parse and stream rules are also known as import and export rules in the
integration services accelerators.
Listeners and Servers

Some services establish a connection with a server or listen for certain client events;
this kind of information is stored as data objects rather than rules. Email, File, JMS,
or MQ services need listener and/or server data objects:
■ Email services require both an e-mail server and an e-mail listener
■ File services require a file listener.
■ MQ services require both an MQ server and an MQ listener
■ JMS services require either a JMS MDB listener, or, a JMS listener and a JNDI
server, depending on how Process Commander is deployed.
EJB, Java, Portlet, SOAP, and .Net services do not require a listener:
■ Requests to Portlet services are processed through the main Process Commander
servlet, PRServle). See Building Portlet Services, available on the PDN
■ SOAP requests to SOAP and .Net services are processed through a special
servlet named PRSOAPServlet that listens for SOAP requests. See Building
SOAP Services, available on the PDN
■ Requests to EJB and Java services are processed by the Process Commander
services EJBs, PRServiceStateless and PRServiceStateful. See Building EJB
Services, available on the PDN.
Listeners start running when Process Commander goes through its start up process.
When you add a new listener, you do not have to restart Process Commander,
however. You can start new listeners or stop and then restart existing listeners from
the System Management application.
For more information about listeners, see Testing Services and Connectors, available
on the PDN.
More about JMS Listeners

JMS listeners are implemented differently, based on how Process Commander is
deployed.
When Process Commander is deployed as a Web application, the listener runs as a

Java thread that is created when Process Commander starts up. The listener waits for
incoming messages on the JMS destination (queue or topic). At regular intervals (as
specified on the listener form), the listener checks to see if Process Commander has
issued a request for it to stop running. In this case, you create a JMS listener and a
JNDI server data object for your JMS services.
When Process Commander is deployed as an enterprise application, the listener is a

message-driven bean (MDB) deployed inside your Process Commander application.
The MDB routes messages to the Process Commander JMS service rule. In this case,
you create a JMS MDB listener data object for your services. You use the form to
generate a fragment of the EJB deployment descriptor file that describes the MDB.
Then you insert the fragment into the message-driven beans subsection of the
Process Commander EJB deployment descriptor file. For deployment instructions,
see the Pega Developer Network article PRKB-23106 “How to Deploy a JMS
Listener as a Message-Driven Bean.”
Services Overview — Service Testing Features 3-19
Service Testing Features

Several features enable you to test your services while you develop them. During the
design and development phase of your integration project, be sure to complete the
following testing tasks for your service rules:
■ Unit test service rules with the Run button.
■ Watch service rules run in the Tracer
■ Collect statistics about the processing that services perform with Performance
Analyzer (PAL)
This section provides brief descriptions of these features. For additional information
about them, see Testing Services and Connectors, which is available on the PDN.
Unit Testing Service Rules

Services start their processing in response to a request from an external application.
What happens if the external application that makes the requests is being built and
tested at the same time that you are creating your application in Process
Commander? In this case, you can verify that the service will process data
appropriately by manually providing it some representative data to process.
When you click the Run button in a service rule, a dialog box appears in which you
can provide test data. When you click the Execute button, Process Commander
invokes the service rule. The service rule maps the test data and invokes the service
activity. You can then determine whether the data mappings are configured correctly
and if the service activity runs correctly without having to wait for the client
application to be finished.
Tracing Service Rules

The Tracer tool monitors an individual requestor session, tracking the execution of
rules. You can set breakpoints, pause the processing while you examine the results of
an action, and review and/or set property values.
You can use the Tracer to monitor any active requestor session. However, a service
usually runs in a new requestor session with a requestor ID that is not created until
the service begins processing. At that point, the processing a service performs occurs
so quickly it can be hard to catch the event to trace it. Therefore, use the Trace Open
Rule option to trace service rules.
To use this option, open the service rule you want to trace and then select Run >
Trace Open Rule. You can select the following Tracer options for services:
■ Services – the Tracer adds steps for when the service invocation begins and
ends. Nested within those steps are entries that show when the inbound data
mapping begins and ends, and when the outbound data mapping begins and
ends.
■ Parse Rules – the Tracer adds steps for when parse rules (delimited, structured,
or XML) begin and end their processing.
■ Stream Rules – the Tracer adds steps for when HTML or XML stream rules
begin and end their processing.
Using PAL with Services

The Performance Analyzer tool (PAL) enables you to gather statistics about the
performance of your Process Commander system. This tool collects “snapshots” of
your requestor on demand as it executes. You use it to observe the rules cache and to
see how requests are resolved. You can examine summary, incremental, and detailed
data, and you can save the data in spreadsheet format.
PAL gathers the following statistics for service rules:
■ The elapsed time for the entire service processing event.
■ The elapsed time and the CPU time for the data mapping of the request message.
■ The elapsed time and the CPU time for the data mapping of the response
message.
■ If the data is mapped to a parse rule or from a stream rule, the elapsed time and
the CPU time for the parse or stream rule to process the data.
Services Overview — Service Testing Features 3-21
■ The number of parse rules that were called during the processing event.
■ The elapsed time and the CPU time it took to run the service activity.
■ For file services, the number of records contained in the file that was processed.
■ For file, e-mail, SOAP, MQ, and JMS services, the size of the data received in
the request, in kilobytes.
If a service request takes longer than your design team has determined it should, use
this information to determine if the problem is with a poorly designed activity, an
overly large request or response message, and so on.
Summary: Creating Services

The following procedures summarize the basic steps for creating services. For details
about creating specific types of services, see the individual documents on the
Integration Services section of the PDN.
EJB, File, Java, JMS, MQ, .NET, SOAP

The basic procedure for creating a service with the Service Accelerator is as follows:
1. Plan the service. Pick names for the service package, service class identifier,
and service method. Decide on an access group and RuleSet (including
version) for all the classes and rules. Determine the purpose of the service and
identify the class rules and properties that are pertinent.
2. If appropriate, run the Import XSD/DTD Accelerator or the Import Java Beans
Accelerator to implement in Process Commander the data model of the
external system that is to send requests to the service.
3. If you used one of the accelerators to implement a data model that represents
the external system, create properties to use to link that data model to the work
object class.
4. Run the Service Accelerator to generate the rules and data objects for the
service. See Using the Service Accelerator, which is available on the PDN.
5. Customize the generated rules and data objects as necessary, for example, by
configuring the requestor pool in the service package instance or fine-tuning
the data mapping settings in the service rule.
− For a File service, write or identify the appropriate structured or delimited
parse rule. Then specify the parse rule in the data map.
Services Overview — Summary: Creating Services 3-23
− For an SOAP or .NET service, assess the data that will be exchanged and
determine whether you need to provide an XML parse rule or an XML
stream rule for that data.
− For EJB and Java, open the service package and generate the deployment
files.
6. For an EJB, Java, NET, or SOAP service, copy the deployment file(s) to a
client computer and then use the appropriate software development tools to
develop the client application that communicates with this service. For more
information about this step for EJB and SOAP services, see the Integration
Services section of the PDN.
7. Test the service.
COM, CORBA, Email, HTTP, Portlet

The basic procedure for creating the rules and data objects for services of type COM,
CORBA, Email, HTTP, or portlet is as follows:
1. Plan the service. Pick names for the service package, service class identifier,
and service method. Decide on an access group and ruleset (including version)
for all the classes and rules.
2. Create a service package.
3. Create or identify the pertinent class rule and properties.
4. For an Email service, assess the data that will be exchanged and determine
whether you need to provide an XML parse rule or an XML stream rule for
that data.
5. For an HTTP service, assess the data that will be exchanged and determine
whether you need to provide an XML, structured, or delimited parse rule, or
an HTML or XML stream rule for the data.
6. For a Portlet service or if the service must respond to requests with an HTML
stream, write or identify the appropriate HTML stream rules.
7. Create a service activity and specify that it applies to the class rule you
identified in step 3.
8. Create the service rule.
9. For an Email service, create an e-mail listener and an e-mail server.
10. Return to the service package and identify the name of the service rule that
you created in step 8. For a COM, CORBA, or portlet service, generate the
deployment files.
11. Copy the deployment file(s) to a client computer and then use the appropriate
software development tools to develop the client application that
communicates with this service. For a portlet service, deploy the portlet.war
file on a portal server.
12. Test the service.
BPEL
To create a BPEL service, use the Publish Flow Accelerator. Create and save the
flow that you want to publish as a BPEL Web service. Then select the Process tab
and click Publish.
Chapter 4
Connectors Overview
A connector is a set of rules and data that enables Process Commander, as a client, to
send a message or a request for data to an external system. When you create a
connector, you are defining how Process Commander invokes a service that is
provided by an external system. After the processing or data retrieval is complete,
the external system returns the results to Process Commander.
■ Introduction
■ Parts of a Connector
■ Connectors and Flow Support
■ Summary: Creating Connector

4-2 Integrating with External Systems — Connectors Overview
Introduction
A connector is typically used within a workflow, a flow rule. Perhaps at some point
in a flow, the person who is assigned the work object needs information from an
external system — a price, an account number, a referral code, a tax rate, for
example — before the work object can move to the next step. In such a case, you
create a connector and attach it to the workflow with an Integrator task.
The following is a high-level description of how connectors work:
1. A work object triggers an Integrator task in a flow.
2. The Integrator task calls the connector activity and passes it the appropriate
properties from the clipboard.
3. The activity calls the connector.
4. The connector assembles and sends a message or request to the external

system.
5. The external system replies to the connector with the data the connector
requested.
6. The connector receives the reply, processes it, and places the data as property-
value pairs on the clipboard. The connector then returns control to the
Integrator task, and the flow resumes.
The architecture for this process is shown in Figure 4-1.

Connectors Overview — Introduction 4-3
Process Commander
Integrator
Integrator680
Task
page
Activity
Clipboard
Page
Connect Rule
request response
External Service
Figure 4-1. Architecture of a Connector
This description does not include lower-level processing details because they vary
for each type of connector. For a more detailed description of the processing for a
specific type of connector, see the documentation for that specific type on the
Integration Services section of the Pega Developer Network (PDN).
Connector Rule Types

As are services, connectors are based on industry-standard technologies. Process
Commander provides the following standard types of connectors:
■ EJB connectors access an Enterprise JavaBean™ (EJB) and call its remote
methods. You can also use them to communicate with WebSphere Business
Integration adaptors.
■ SOAP connectors are SOAP (Simple Object Access Protocol) clients that call
Web services.
■ SQL connectors send complex SQL statements to an external database.
■ Java connectors call the Java methods and constructors of Java classes or .jar
files that are located in Process Commander’s classpath.
■ HTTP connectors send message data to external systems through HTTP GET or
POST requests and process the response data.
■ JCA connectors send requests to external Enterprise Information Systems

through resource adapters that implement the Common Client Interface of the
J2EE Connector Architecture specification.
■ JMS connectors send request messages to an external system and process

responses through an intermediate server that hosts Java Message Service
middleware.
■ .Net connectors are Microsoft .NET clients that call Web services on external
systems based on the Microsoft .NET Framework.
■ MQ connectors send request messages to an external system and process

responses through an intermediate server that hosts IBM WebSphere MQ
middleware.
■ BPEL connectors act as a container for the SOAP services and connectors that
represent Process Commander as a partner of a Business Process Execution
Language (BPEL) process when Process Commander starts the process.
To create connectors of type EJB, Java, .NET, SOAP, or SQL, use the Connector
Accelerator.
Java-Based Connectors vs. Other Ways to Use Existing Java Code

There are several ways to take advantage of your existing Java code when
developing a Process Commander application. You can use EJB connectors and Java
connectors to invoke external Java applications; you can use Java activity steps in
those exceptional cases when none of the Process Commander rule types implement
the processing you need; and you can create utility function rules (Rule-Utility-
Function) to store reusable routines or procedural Java code.
This section describes when you might use each option.
EJB and Java Connectors

When your application must make requests to an external EJB application, use an
EJB connector.
When your application must make requests to an external Java-based application that
is not an EJB, or must interact with an external Java class that must be maintained
outside Process Commander, use a Java connector.
By using a connector rule to invoke an external Java class, you can reuse the
connector rule in multiple places while maintaining the Java code the connector
interacts with in one place. Additionally, when connector rules run, they set
Performance Analyzer timers for the external connections. If you have a
performance issue or question, you can determine how much time the external Java
class spends processing the connector's request. You can also track them in the
Tracer: the Tracer tracks the beginning and end of a connector’s operation when it
runs.
For Process Commander to access the external application or Java class, the jar or
class files must be in both the Process Commander compile time and runtime class
path. For information, see PRKB-20931 “About the Process Commander Version 5
Class Paths,” available on the Pega Developer Network (PDN).
Java Steps
While it is also possible to call external Java classes from Java steps in activities, it
is best practice to use Java connectors instead. The SmartBuild design and
development guardrails encourage you to use Java steps in activities sparingly. You
should never use Java in an activity step when you can use rules to accomplish your
processing goals.
However, there are some very specific and limited reasons why you may need to use
Java in an activity. In some cases, you must use a Java method from the Process
Commander public API that does not have an activity method equivalent. For
example, to create custom authentication activities, you use Java steps to invoke the
setSecurityProfile and setUserAuthenticated Java methods from the
PRAuthentication interface. (For information about writing custom authentication
activities, see Authentication in PegaRULES Process Commander, available on the
PDN)
Utility Function Rules

If the specific piece of the existing Java code that you want to use is a procedural
method or routine that does not use member variables, refer to other Java classes, or
maintain state, you can create a utility function rule and store the code in the rule.
That way you can maintain the code within the Process Commander database as a
rule that is subject to versioning, which means the correct version of the function rule
is selected at runtime based on the user’s RuleSet list. However, the SmartBuild
design and development guardrails encourage you to use custom Java sparingly,
even in function rules.
Utility function rules typically perform simple computations or transformations. You

can use them in activity preconditions and transitions, when rules, expressions, and
so on. You can update them and recompile them without having to stop and restart
Process Commander.
For information about utility function rules, see the Application Developer Help
system.
SQL Connectors vs. Activity Methods

There are two ways for your Process Commander application to interact with tables
in external databases: use the Obj- activity methods in activities or use SQL
connectors.
■ Use the Obj- activity methods for simple read/write interactions. To use these
methods with an external table, the appropriate class and property rules and data
objects must exist. Use the Create External Data Table Rules Wizard to generate
these items.
■ For stored procedures and for SQL queries that include joins or are more
complex than simple read/write interactions, use a SQL connector.
In either case, you must obtain the appropriate JDBC driver and a database account
for Process Commander and then configure a data source for the external database in
the application server hosting Process Commander. You must also create an instance
of Data-Admin-DB-Name that uses the data source to identify the external database.
Connectors and Distributed Transactions

A distributed transaction is a set of operations that include more than one resource
manager and that must be treated as one operation. For example, updates to more
than one database in one transaction, or, a database operation and the sending or
receiving of a JMS message in the same transaction.
When Process Commander is deployed as an enterprise application, it can participate

in distributed transactions. Whether the transactions connectors participate in are
bean-managed or container-managed depends on their requestor context.
■ Typically, connectors run in the requestor context of a user rather than as a

background process. Users create a work object and when the work object
reaches the Integrator task that invokes the connector, the connector runs in the
user’s requestor context. When users the connector runs in a human user’s
requestor context, transactions are bean-managed by Process Commander.
■ A service runs in the background, in a new requestor session. If the service

processing for an EJB, Java, or JMS service invokes a connector, the connector
runs in the service’s requestor context. Whether the connector participates in a

container-managed transaction depends on the transactional state of the service.
For more information about distributed transactions and the boundaries (scope) of
Process Commander’s bean-managed transactions, see the document Designing
Applications that Ensure Data Integrity, which is posted on the PDN.
Connectors Overview — Parts of a Connector 4-9
Parts of a Connector
A connector is made up of several rules and data objects; some types of connectors
require more parts than others. If you are creating a JCA, JMS, or MQ connector,
you create all the rules and data objects yourself. However, for any other connector
type, you use the Connector Accelerator to create the rules and activities.
First, you need a class rule that typically inherits from the Data- base class for the
connector or the Create Connectors Rules Accelerator. The accelerator uses this class
rule as the parent for any other classes and properties it needs to create.
The accelerator also creates the main component of the connector, the connector
rule, and an activity that calls the rule. The connector rule assembles the outgoing
message. This rule also receives and processes any response that the external service
sends back and performs any necessary data mapping.
The Connector Accelerator creates the class, model, activity, property, and connector
rules needed to implement the connector, using the abstract class that you specify as
the parent class when you run the accelerator.
Additionally, depending on its type, a connector might need some of the following
components:
■ Depending on the system the connector interacts with, connectors of type JMS
or MQ might require an XML stream rule to assemble the message.
Conversely, if the reply contains an XML file that must be parsed, the connector
must have an appropriate parse rule.
■ For a SQL connector, create an instance of Data-Admin-DB-Name that

identifies the external database. Create this data object before running the
Connector Accelerator.
■ For an EJB, JMS, or MQ connector, create a server data object.
■ For a JCA connector, create a JCA adapter data object that identifies the
location of the resource adapter the connector will communicate with.
■ For a JMS connector, create a JMS producer model to identify message

processing settings.
After creating the connector, you integrate it into your application with an
Integrator task in a workflow.
Classes and Properties

Whether or not you use the Connector Accelerator, you start by creating a parent
(base) class rule with the following difference:
■ When you use the Connector Accelerator to generate the connector, create an
abstract class.
■ When you create a JCA, JMS, or MQ connector, create or identify a concrete

class.
The class rule that you create is likely to inherit from Data- because typically
connectors request and retrieve data rather than work. However, depending on what
the connector does, it is possible that the class rule can inherit from Work- or another
appropriate class rule.
The class rule for the connector must have a property for each parameter that will be
used in the request or response. These properties are created as follows:
■ When you use the Create Connector Rules Accelerator, identify the source of
the metadata (the location of a .wsdl file, for example). The accelerator
examines that metadata and then creates, as subclasses of the parent class, the
properties and any additional data classes that it needs to implement the
connector.
■ When you create a JCA, JMS, or MQ connector, you create all the properties
yourself (or identify them).
When you use the Connector Accelerator, it implements in Process Commander the
data model of the external system to which the connector sends messages, and the
connector interacts with this class structure. To move property values from that class
structure to the work object class structure, the connector activity can set property
values from the class structure for the messages into work object properties that you
create for this purpose.
Connector Activity
The connector activity is the mechanism that starts the connector. A method in the
activity calls the connector rule. For example, if the connector is a SOAP connector,
the activity uses the Connect-SOAP method to call the connector rule.
Integrator tasks can call activities that apply to class rules that inherit from the Work-
base class rule only. Therefore, typically a connector activity applies to a class rule
that inherits from the Work- class so that you can call it directly from an Integrator
task in a workflow rule. If the connector activity does not apply to a class rule that
inherits from Work-, you must create another activity — known as a caller activity
— for the Integrator task to use to invoke the connector activity.
When you use the Connector Accelerator to create a connector, you specify two class
rules: one for the connector rule and its associated data class and property rules and
one for the connector activity. The field that specifies the class rule for the connector
activity defaults to the value of your current work pool, which is a subclass of the
Work- base class.
Connector Rule
The connector itself is defined by an instance of a Rule-Connect-* rule. When you
use the Connector Accelerator, the accelerator creates the appropriate connector
rules.
The connector rule types encapsulate the appropriate logic for communicating with a
service of that type. For example, a SOAP connector holds the URL of the SOAP
server. An EJB connector holds information about the EJB container that holds the
bean and which of the bean’s Java methods to use.
The connector rule handles the details for the request. The rule composes the
outgoing message from clipboard properties, sends the request, obtains a response,
and maps response data back into clipboard properties.
The connector rule holds the following kinds of information:
■ The RuleSet.
■ The number and type of output and input parameters.
■ Whether the system it communicates with accepts requests from authenticated

users only, and, if so, the username and password the connector is to use.
■ Technology-specific information about connecting to a service of that type. For

example, if the request is sent via HTTP (HTTP, SOAP, and dotNet connectors),
the connector rule specifies session and time-out information.
With the exception of the SQL connector, a connector rule has two key parts:
■ Name of the class rule it applies to
■ Service name, which holds the name of the external service or method that it
connects to
SQL connector rules have three key parts:
■ Name of the class rule it applies to, which also identifies the name of the
database table data object that represents the external table the connector queries
■ The package name, which is typically set to JDBC
■ Name of the request type, a string that you enter to describe the purpose of the
connector
Sample Rule Instances

The PegaSample-IntSvcs RuleSet contains sample instances of each Rule-Connect-*
type, each named CollectData. They are not working samples. They are examples
that show the kind of information needed by a connector rule of that type.
Parse and Stream Rules

For some connector types, the connector rule needs information to assemble the
request or to parse the response. Also known as import and export rules, parse rules
interpret or parse a response from an external service, and stream rules assemble the
XML or HTML stream that is sent in the connector request.
Depending on what the connector needs to do, you may need to map outgoing data
from a stream rule or incoming data to a parse rule.
Databases, Servers, and Other Data Objects

Some connectors need additional data objects to provide reference information, such
as port numbers, passwords, and hostnames.
■ Connectors of type SQL require a database name that identifies the external
database that it connects to. They also need a database table object that identifies
the table the connector queries.
■ Connectors of type EJB require a JNDI server data object to identify the EJB
container where the EJB of interest is deployed.
■ Connectors of type MQ require an MQ server data object to specify the location

of the server that manages the message queue it sends messages to.
■ Connectors of type JMS require the following additional data objects:

− A JNDI server object that identifies the application server that manages the
message queue
− A JMS producer model that identifies message processing settings
Integrator Task for the Workflow

The last step is to integrate the connector with your application. Typically, you add
an Integrator task to your workflow. Integrator tasks are objects in the Process
Commander Visio flow shape library. Figure 4-2 shows the standard Integrator task
shape.
Figure 4-2. Standard Integrator Task
When the processing of a flow rule reaches an Integrator flow shape, Process
Commander runs the activity associated with the task — either the work activity for
the connector or the extra caller activity that invokes the connector activity. The
connector sends its request while the workflow waits. When the system receives a
response, the flow resumes.
Connectors Overview — Connectors and Flow Support 4-15
Connectors and Flow Support

Because connectors are typically called from flows, several connector features
support flow design and development:
■ Run in parallel — asynchronous operation
■ Compensating actions
■ Connector simulation
■ ConnectionProblem flow
Running Connectors in Parallel

By default, when a connector is invoked it retains control of the requestor session
until it returns a response to the flow. However, when the RunInParallel parameter is
selected for the Connect-* method called by the activity, the connector returns
control of the session to the flow immediately after the request. This means that if
the flow has another connector with a subsequent task to accomplish, the next
connector can send its request immediately after the first makes its request — the
second connector does not have to wait for the first connector to return a response.
The RunInParallel parameter is typically used with SQL connectors because each
SQL statement (SQL connector) is invoked by a separate connector activity. As an
example, imagine that a work object reaches a point where the user needs both a
referral code and a doctor name for the work item, and these pieces of data are in
different tables in the same external database. As long as there are no dependencies
(that is, the referral code does not depend on which doctor you select, for example),
you can run these connectors in parallel, which speeds up the task.
Compensating Actions
An action in a flow can have dependencies on later events. For example, perhaps a
work object causes a bill to be sent to a customer, and the next step in the flow is a
process that updates the accounts receivable data in the accounting system. What
happens if the accounting system is offline? Do you need to cancel the bill and send
the work item back to the previous step until the accounting system is back online? If
that is the case, the process architect can program a compensating action that cancels
the bill (rolls back the preceding events).
Compensating actions are pertinent to connectors because connectors interact with

external systems that can be gating factors to the resolution of a work object. For
example, perhaps a flight reservation could not be booked so the hotel reservation
that was just booked is now unnecessary. In this case, you can use a compensating
action to cancel the hotel reservation.
Although the SOAP and dotNet connector rule forms enable you to create parts of
the logic for compensating actions directly in the connect rule, you create
compensating actions in the workflow. For more information, see Using
Compensating Actions, available on the PDN.
Connector Simulation
When you use a connector in a flow, you cannot test the flow completely until the
connector has an external working system to connect to. What happens if the
external component that you want to connect to is being built and tested at the same
time that you are creating your application in Process Commander? In this case, you
can create a connector simulator so that you can test the processing that occurs in the
rest of the workflow, the flow before the connector and the flow after the connector.
A connector simulator is an activity that bypasses the connector and returns static
test data to the Integrator task. The Integrator task returns the test data to the
workflow, and the workflow resumes.
To set up a connector simulator, create an activity that provides appropriate values.

Then create an instance of the Data-Admin-IS-Simulation class, include the
simulator activity, and select the Enable option for it.
To use the simulator activity while testing the flow, open the instance of the Data-
Admin-IS-Simulation class and click the Enable button at the bottom of the form.
This button sets the simulator flag for your requestor session only.
Connectors Overview — Connectors and Flow Support 4-17
When the work object reaches the Integrator task for your connector, the activity that
calls the connector checks for the simulator flag. It discovers that simulation mode is
enabled; rather than calling the connector, it calls the associated simulation activity.
The simulation activity responds by sending the simulated return values to the
connector activity, the connector activity returns to the Integrator task, and you can
continue testing the rest of the flow.
For more information, see Using Connector Simulators, available on the PDN.
ConnectionProblem, the Standard Error Handler Flow

Because connectors request information from external systems, there are external
factors that can cause a connector to fail to obtain the data it needs – the external
system could be offline, for example. Use the ConnectionProblem flow, a standard
Process Commander flow, to track and resolve issues when a connector fails.
To use this feature, you specify the ConnectionProblem flow in the Error Handler
Flow field of the connector rule. When the Integrator task in a flow calls that
connector, the following occurs if the connector fails:
1. The connector returns an error message (exception).

2. If the connector failed because it could not communicate with the external
system, the current flow starts the ConnectionProblem flow. The work object or
task is assigned to a workbasket named IncompleteConnections.
Note: If the connector failed because it is not configured correctly, the current
flow starts the standard Process Commander flow named FlowProblems and
reassigns the work object or task to an administrator user.
3. The Service Unavailable SLA goes into effect. This SLA tries the Integrator
task again five times.
− If the connector succeeds, the ConnectionProblem flow ends, the
ConnectionProblem flow assignment is cancelled, and the original flow
resumes.
− If the connector fails for a new reason, the ConnectionProblem flow ends,
the FlowProblems flow starts, and the assignment is reassigned to the
FlowProblems flow.
− If the connector fails to connect to the external system after four attempts,
the SLA stops trying. The assignment stays in the IncompleteConnections
work basket until a user either restarts the flow or cancels the assignment.
When you create a new connector rule or use the Connector Accelerator to generate
a connector rule, the ConnectionProblem flow is set in the Error Handler Flow field,
which means that this feature is enabled by default. You can customize the standard
ConnectionProblem flow by creating your own version of it or any of its parts in a
separate ruleset.
If you do not want to use this feature, delete the name of the ConnectionProblem
flow from the Error Handler Flow field. When this field is blank, the feature is
disabled.
For more information, see Using Error Handler Flows, available on the PDN.
Connectors Overview — Summary: Creating Connectors 4-19
Summary: Creating Connectors

The following procedure describes the basic procedure that you use to create
connectors. For details about creating specific types of connectors, see the
individual documents on the Integration Services section of the PDN.
The basic procedure for creating a connector is as follows:
1. Perform the appropriate system administration or setup tasks on the external

system or service. For example, to create a SQL connector, a DBA must create
an account for the connector on the external database. If you set up the service
or system before you create the connector, you can use the Create Connector
Accelerator to run validation tests against the actual service or system.
2. Perform the appropriate system administration or setup tasks on the Process

Commander system. For information, see Using the Connector Accelerator
and Creating JMS and MQ Connectors, which are available on the PDN.
3. If you plan to use the Connector Accelerator, create an abstract class, typically
one that inherits from Data-. The Connector Accelerator writes properties and
activities into this class. Depending on the connector type, the Connector
Accelerator might also create subclasses of the data class. Additionally, create
properties for the work object class that will link the data from the generated
class structure to the work object.
4. If the connector is of type HTTP, BPEL, JCA, JMS, or MQ, create the
connector rules. Otherwise, Run the Connector Accelerator to generate the
rules for the connector.
5. Click the Test Connectivity button to test the connection to the external
system.
6. Edit the generated rules as necessary, for example, by adding security

constraints or fine-tuning the data mapping settings.
7. Add an Integrator task to the appropriate flow rule. Associate the connector
work activity with the Integrator task.
8. Test the workflow. If the system that the connector needs to connect with is
not online yet, create a connector simulator so that you can test the rest of the
workflow.
Chapter 5
Data Mapping
Services and connectors communicate with external systems. Data maps define the
relationships between field-value pairs in external systems and property-value pairs
on Process Commander clipboard pages.
This chapter describes the basic concepts of data mapping for all types of service and
connector rules. The documents Using the Service Accelerator and Using the
Connector Accelerator, available on the Pega Developer Network (PDN), describe
how the accelerators configure data mapping in the rules that they generate. The
individual documents on the Integration Services section of the PDN provide more
specific information about data mapping for services and connectors of individual
types.
■ Introduction
■ Creating Data Maps
■ Sources and Targets for Mapped Data
■ Building Custom Map To and Map From Functions

5-2 Integrating with External Systems — Data Mapping
Introduction
A data map controls how Process Commander selects, converts, and copies data
between the formats that are used by an external system and the properties that are
used by Process Commander. Data maps specify the correlation between external
variables and Process Commander properties. For example, you can specify that
when an external system passes in an integer named “x,” Process Commander will
map the value of x to a property named “xtra” on the primary page of the clipboard.
Each service rule and each connector rule contain two data mappings, one for the
request and one for the response. In Process Commander terminology, these data
maps are called Map To and Map From data maps.
Map To vs. Map From

When you think about the flow of data for a service or a connector, remember that
data mapping is always from the perspective of the Process Commander system:
■ A Map To data map describes data that is being sent to Process Commander.
Data is mapped to Process Commander from the other system.
■ A Map From data map describes data that Process Commander is sending to an
external system. Data is mapped from Process Commander to the other system.
to from
External System Process Commander External System
from to
Figure 5-1. Data Flows to and from Process Commander

Data Mapping — Introduction 5-3
Request vs. Response

To configure data maps, you create the request and/or response in a service or
connector rule. To determine which tab (Request or Response) configures which
kind of data map, consider this question: Is the primary role of the Process
Commander application that of the client (requestor) or that of the server
(responder)?
Services: the Responders

For a service, the primary role of Process Commander is that of the responder:
■ Because the Request tab defines the request from the other system to the Process
Commander service, the data map on the Request tab for a service is a Map To
data map.
■ Because the Response tab defines the response from the service to the external
request, the data map on the Response tab is a Map From data map.
Map To = request
Process Commander
External System Service
Map From = response
Figure 5-2. Data Mapping to and from a Service
In some Process Commander forms, these tabs are not named Request and Response.
For example, the response for a service of type EJB or COM is defined on the
Parameters tab.
Connectors: the Requestors

For a connector, the primary role of Process Commander is that of the requester:
■ Because the Request tab defines the request or message that the connector sends
from Process Commander to the other system, the data map on the Request tab
for a service is a Map From data map.
■ Because the Response tab defines the response from the other system response
to the connector request, the data map on the Response tab is a Map To data
map.
Map From = request
Process Commander External System

Connector
Map To = response
Figure 5-3. Data Mapping From and To a Connector
In some Process Commander forms, these tabs are not named Request and Response.
For example, the request for a connector of type EJB is configured on the Create tab,
and the response is configured on the Remote tab.
Mapping Options
The goal of the data map is for properties and their values to be identified by the
source system and to be recognizable to the target system. When the data is simple or
is similar between systems, the data map is also simple — you can usually map data
directly to and from properties on the clipboard. However, if a message must be
assembled before it is sent out, or parsed before it can be processed, you map it using
a rule.
Data Mapping — Introduction 5-5
The following is a list of the general categories of constructs that you can map data
to or from in a data map:
■ A property on the clipboard
■ A constant, fixed value
■ Special default parameters, based on the kind of service or connector you are
creating
■ HTML PostData
■ Parse rules that parse XML, structured files, or delimited files
■ Stream rules that create HTML or XML
■ Custom MapTo and MapFrom functions that you create.
Each of these options is described in more detail later in this chapter.
Properties
Before you can create a data map, you must identify the key properties and their
property modes (data types) so that you can map them correctly:
■ When you create a connector, you usually create the class rule that it needs. In
this case, you know the definitions (modes) of the properties that will participate
in the data maps because you created them.
■ When you create a service, however, your task is usually to expose a class rule
that already exists. In this case, you must investigate the class rule to determine
the property modes of the properties that will participate in the data map.
Data maps can handle properties of any of the following Process Commander
property modes: Single Value, Value List, Value Group, Page, Page List, Java
Property, Java Property List, Java Object, and Java Object List. All but the single
value mode define aggregate or complex properties that store arrays and repeating
groups.
Properties of mode Page or Page List create embedded pages on the clipboard:
■ A property of mode Page can contain other properties of any mode.
■ A property of mode Page List can contain an indexed array of pages.
As you define data maps for aggregate properties, remember that in Process
Commander, ordered collections (lists) are 1-based, not 0-based. When specifying
the first item in a list, you identify it with a 1 rather than a 0; you identify the second
item in a list with a 2 rather than a 1; and so on.
For example, assume that you are mapping the first value of a Value List property
named My Children, and the MyChildren property is located on the first page of a
PageList property named Employee. In this case you use the following syntax:
.Employee(1).MyChildren(1)
Top-level clipboard pages cannot be PageList. Use the period character (.) to specify
an embedded PageList, such as the one in the example above.
For additional information about properties and property modes, see Working with
Java Objects in Process Commander and Designing Your Application with
SmartBuild, available on the PDN. See also the Application Developer Help system.
Data Mapping — Creating Data Maps 5-7
Creating Data Maps

The process of creating a data map is the same for Map To and Map From data
maps. However, the options that you can configure are different. This section
describes a row in a data map, especially the Map To, Map To Key, Map From, and
Map From Key fields. The next section, “Sources and Targets for Mapped Data,”
presents a more detailed description of each of the individual mapping options.
A Row in a Data Map

Each row in a data map explains how to process a value. You provide the following
information for the value in both a Map To and a Map From data mapping:
■ Data Type — the data type of the external value you are mapping.
■ Name — the name of the property used by the external system; that is, the name
that Process Commander uses to identify the value in the request to or response
from the external system.
■ Description — an optional description of the value you are mapping. This text
is for information only; it is displayed in the Process Commander Portal, but it is
not evaluated during processing.
Then, for a Map From data mapping, you also provide values for the following
fields:
■ Map From — the source, or in some cases the type of source, of the value in
Process Commander, for example, the clipboard, a rule type, or a custom
function. The list of options in the selection box depends on the data type that is
selected in the Data Type field.
■ Map From Key — the key to locating the property in the source. For example,
if the source of the property is the clipboard, the key is the name of the property.
If the source of the property is a rule, the key is the name of the rule.
Conversely, for a Map To data mapping, you also provide values for the following
fields:
■ Map To — the destination or the type of destination for the value in Process
Commander, for example, the clipboard, a rule type, or a custom function. The
list of options in the selection box depends on the data type selected in the Data
Type field.
■ Map To Key — the key to locating the property in the destination. For example,
if the destination of the property is the clipboard, the key is the name of the
property. If the destination of the property is a rule, the key is the name of the
rule.
Map From and Map From Key Fields

A Map From data map describes the information in Process Commander to send to
an external system and how to assemble it into the appropriate format or message
that the external system needs.
The value that you specify in the Map From Key field depends on the option that you
selected in the Map From field. The Map From field presents the following options:
■ A constant, a fixed value that does not change
■ The clipboard
■ HTML stream
■ HTML frame
■ XML stream
■ Custom Map From functions (Rule-Utility-Function), if any are appropriate for

the mapping
In addition, depending on the kind of service or connector you are creating, you can
enter certain default parameters manually (the parameters do not appear in the Map
From selection box).
Figure 5-4 describes how to provide the value for the Map From Key field for each
option available in the Map From field.
Map From Value in Map From Key

Option
Constant A string that specifies the literal value of the constant.
See “Mapping from a Constant” on page 5-15.
Clipboard The name of the property with a value to be sent. The name can
include the name of the clipboard page or a keyword that specifies
the clipboard page.
See “Mapping to and from the Clipboard” on page 5-13.
Name of a default None. You specify the name of the parameter in the Map From field,
parameter instead.
Several service and connector types can pass special parameters.

The names of those parameters depend on the type of service or
connector. For example, MQ services can pass values for parameters
called Requestor ID, Username, and Password. The class the service
or connector interacts with does not need these parameters to be
defined as properties because Process Commander can process
these values by default.
See “Mapping to and from Special Default Parameters” on page 5-16.
HTML Stream The stream name of a rule that produces an HTML stream.
See “Map From and the HTML Stream Option” on page 5-16.
HTML Frame None. Use this option to specify the HTML that has already been
generated by a Show-HTML method in a previous activity.
See “Map From and the HTML Frame Option” on page 5-17.
XML Stream The stream name of the appropriate XML rule. See “Mappping From
XML Stream Rules” on page 5-18.
Map From Value in Map From Key

Option
Name of a custom The name of a clipboard property. The value of this property is
Map From function passed to the custom function.
See “Building Custom Map To and Map From Functions” on

page 5-23.
Figure 5-4. Details for Map From and Map From Key Fields
Map To and Map To Key Fields

A Map To data map describes how Process Commander processes an incoming
message. The data map specifies how to extract values from the message and into
which properties to put the values.
The value that you specify in the Map To Key field depends on the option that you
select in the Map To field. The Map To field includes the following options:
■ The clipboard
■ HTML Post Data
■ XML parse rule
■ Delimited parse rule
■ Structured parse rule
■ Custom Map To functions, if any are appropriate
In addition, depending on the kind of service or connector you are creating, you can
enter certain default parameters manually (the parameters do not appear in the Map
To selection box).
Figure 5-5 describes how you provide the value for the Map To Key field for each
option available in the Map To field.
Map To Option Value for Map To Key

Clipboard A string that specifies the name of the property to hold the incoming
data. The string can also include the name of the clipboard page or a
keyword that specifies the clipboard page.
See “Mapping to and from the Clipboard” on page 5-13.
Name of a default None. You specify the name of the property in the Map To field.
parameter
Several service and connector types can pass special parameters.
The names of these default parameters depend on the type of service
or connector. For example, MQ services can pass values for
parameters named Requestor ID, Username, and Password. The
class that the service or connector interacts with does not need these
parameters to be defined as properties because Process Commander
can process these values by default.
See “Mapping to and from Special Default Parameters” on page 5-16.
HTML Post Data None. The incoming URL provides (identifies) the property/value
pairs. If the class that the service or connector interacts with has
properties with the same names as those provided by the URL,
Process Commander can put the data in the correct place.
See on “Map To and the HTML Post Data Option” page 5-17.
XML Parse Rule The name of the rule.
See “Mapping To XML Parse Rules” on page 5-19.
Delimited Parse The name of the rule.

Rule
See “Map To and the Delimited Parse Rule Option” on page 5-21.
Map To Option Value for Map To Key

Structured Parse The name of the rule.
Rule
See “Map To and the Structured Parse Rule Option” on page 5-22.
Name of a custom A string that identifies the name of a clipboard property that will hold
Map To function the results of the custom function.
See “Building Custom Map To and Map From Functions” on

page 5-23.
Figure 5-5. Details for Map To and Map To Key Fields

Data Mapping — Sources and Targets for Mapped Data 5-13
Sources and Targets for Mapped Data

The data mapping options that appear in the Map From and Map To fields are both
data sources and data targets. This section describes the data mapping options and
presents information about how you identify and/or create them.
Mapping to and from the Clipboard

When you select the Clipboard option in the Map To or Map From field, specify a
property in the Map To Key or Map From Key field. If you enter the name of the
property by itself (that is, .propertyName), it means that the property is located on
the primary page of the service or connector activity.
Figure 5-6 shows the data mapping for a string property named
“pySearchResponse.” pySearchResponse is located on the primary page of the
service, and its value is passed to the external system as a property-value pair for a
property named “Result.”
Figure 5-6. Data Map for a Property on the Clipboard
If you know that when a service or connector rule is invoked, a specific named page
is on the clipboard, you can specify a property on that named page. Specify the page
with a prefix to the property name. You can specify either the page name or the
keyword param, which means that the property is on the parameter page of the
service or connector activity.
Primary Page and Parameter Page

The primary page and parameter page are as those of the following activities:
■ For services, they are the primary and parameter pages of the service activity
that the service calls. This activity is the service activity.
■ For connectors, they are the primary and parameter pages of the activity that
calls the connector. This activity is the connector activity.
Syntax for Property References

Figure 5-7 shows examples of the syntax used to refer to properties in the Map From
Key and Map To Key fields for data mapping to or from the clipboard.
Syntax Example Description

.myproperty The value of the property named
myproperty located on the primary page of
the activity.
mypage.myproperty The value of the property named
myproperty located on a top-level user
page named mypage.
.mylistproperty(5) The value of the fifth element of the Value
List property named mylistproperty located
on the primary page.
Green.mygroupproperty(“LOW”) For the Value Group property named
mygroupproperty located on a top-level
page named Green, the value of the
element indexed by the literal value LOW.
param.radius The value of the property named radius
located on the parameter page of the
activity.
Figure 5-7. Syntax Examples for Property References
To provide an indirect property reference, use curly braces. For example, consider
the following property reference:
{Green.overthere}
In this case, a property named overthere, located on the top-level page named
Green, holds a text string that is a property reference. The system applies the
property reference algorithm again to find the value.
While you can specify an explicit page name (as shown in the examples in this
section), doing so decreases the flexibility and reusability of the service or connector
rule. The best practice is to use the page keyword param to refer to a parameter
page.
For information about additional ways to reference properties, see the Application
Developer Help system.
Mapping from a Constant

A constant is a fixed, known value that remains the same no matter when the
connector or service runs. For example, assume that a connector identifies itself to
the external system through a user ID or a license key that does not change. You can
map that value as a constant so the user who triggers the connector does not have to
enter a value each time.
To use a constant, enter the name of the constant in the Name field, select Constant
from the Map From field, and enter the value of the constant surrounded by double
quote characters in the Map From Key field. For example, Figure 5-8 shows a
constant named Foo with the value Bar.
Figure 5-8. Mapping a Value as a Constant

Mapping to and from Special Default Parameters

Several service and connector types include a set of default parameters that are used
for security, or session management.
■ Inbound SOAP, JMS, and MQ messages can contain parameter-value pairs for
properties named “Username,” “Password,” and “RequestorID.”
■ Inbound .NET messages can contain parameter-value pairs for “Username” and
“Password.”
Process Commander processes these parameters automatically, without requiring that

the primary page class have properties that match these parameters.
To map one of these special default parameters, set the Data Type value to String,
then select the appropriate parameter from the selection list in the Map To or Map
From field, and leave the Map To Key or Map From Key blank.
Mapping to and from HTML

Three HTML options are available for data mapping, two for Map From data maps
and one for Map To data maps:
■ Map From options — When the message to be sent to an external system is

HTML, select HTML Stream or HTML Frame, as appropriate.
■ Map To option — When the incoming message is HTML, select HTML Post
Data.
Map From and the HTML Stream Option

Use the Map From option of HTML Stream when the HTML message to be sent to
the external system must be created.
You must first create an HTML rule before you can select the HTML Stream option.
The rule can reference clipboard properties and use directives, which are assembly
instructions for stream processing used to produce final HTML. The key to the rule
name has two parts: the Applies To class and Stream Name.
To use this option, select HTML Stream in the Map From field, and then specify the
stream name of the HTML stream rule in the Map From Key field.
The data for the HTML stream can be on a page other than the primary page. When
this is the case, enter pagename.StreamName in the Map From Key field rather than
the stream name.
For example, Figure 5-9 shows a reference to an HTML stream rule on the Response
tab of a SOAP service rule. Process Commander determines the identity of the
appropriate HTML stream rule at runtime as follows: the Applies To key is on the
clipboard page named pyWorkPage, and the Stream Name key specified as
WorkAssign.
Figure 5-9. Sample Reference to HTML Rule
For information about how to create HTML stream rules (Rule-Obj-HTML), see the
Map From and the HTML Frame Option

Use the HTML Frame option when the HTML data for the outbound message has
already been created by an activity that uses the Show-HTML method. In this case,
the HTML is already created and is waiting on the thread page (pxThread) on the
clipboard for the service or connector activity. Select the HTML Frame option in the
Map From field, and leave the Map From Key field blank.
The service package form includes an option to suppress HTML. If Show-HTML is

suppressed for a service package, do not select this option for a data mapping in the
service rule.
Map To and the HTML Post Data Option

An incoming message originating from a Web browser (forwarded by a client) is
assembled in a specially formatted text stream (CGI format) and sent using the
HTTP POST method from a form. When a service receives HTTP POST data, select
the HTML Post Data option in the Map To field of the data map.
The property values are presented in the URL that is streamed from the browser to
Process Commander. The values are appended as field-value pairs to the URL and
must include clipboard page names. For example, the following URL passes the
field-value pairs “field1=foo” and “field2=bar”:
http://servername?page1.field1=foo&page1.field2=bar
Process Commander automatically interprets the field-value pairs appended to a

URL as property-value pairs and writes them to the clipboard. Therefore, you do not
map them in the data map for the service or connector. Instead, when you select the
HTTP Post Data option in the Map To field, you leave the Map To Key field blank.
Be sure that the properties are defined — that there is a matching property (Rule-
Obj-Property) in the data class associated with the connector or service for each
value that is submitted in the URL.
Mapping XML
When you are building SOAP, .NET, EJB, JMS, and MQ services or connectors, you
may need to specify data mapping for messages that contain XML.
When the message contains scalar arguments that match Process Commander
properties or activity parameters and the data in the argument is to be treated as a
single value, you can create simple argument-property mappings. However, if the
message contains scalar arguments and the data in the argument is XML data, or if
the message contains an XML object, you map the values and from the rules
described in this section.
Mappping From XML Stream Rules

XML stream rules describe how to assemble an XML document from property
values. Use the XML Stream option if the message that your service or connector is
sending is an assembled XML document.
Before you can select the XML Stream option in a Map From field, you must have
an XML stream rule to use. The easiest way to create XML stream rules is to use the
Create Import/Export Rules Accelerator. XML stream rules have three key parts:
applies to class, stream name, and XML type (which must be set to the literal string
“MapFrom”).
To use this Map From option, select XML Stream in the Map From field, and then
enter the stream name of the XML rule in the Map From Key field. The first key –
the Applies To class – is assumed to be that of either the class specified as the Page
Class for the service rule or the Applies To class of the connector rule (depending on
which kind of rule you are creating), unless you also specify the name of a clipboard
page. When the data for the XML stream is on a page other than the primary page,
enter pagename.StreamName in the Map From Key field, where pagename is the
name of a clipboard page that you know exists when the service or connector is
invoked.
For a service or connector of type SOAP or dotNET, do not select XML Stream as
the Map From option if the Data Type of the value is set to XMLPage. See
“Mapping To and From Model Rules” on page 5-20.
For information about how to create XML stream rules, see Data Mapping XML,
available on the PDN. See also the Application Developer Help system.
Mapping To XML Parse Rules

XML parse rules, instances of Rule-Parse-XML, describe how to interpret XML
embedded in a string argument into property-value pairs in Process Commander. Use
the XML Parse Rule option when the incoming data includes XML that is held in a
scalar argument.
When processing an XML parse rule, Process Commander scans the incoming XML
text, parses it into an internal tree structure, and then traverses the structure as
instructed by the XML parse rule. Process Commander extracts specific element
values and places them onto a clipboard page. An XML parse rule can perform
searches, accept repeating groups by creating embedded pages, and navigate through
the XML structure.
Before you can select the XML Parse Rule option, you must have an XML parse rule
to use. The easiest way to create XML parse rules is to use the Create Import/Export
Rules Accelerator. After they are generated, open them and use the Validate tab to
specify when Process Commander should validate the incoming XML stream against
a published definition (XSD or DTD) before attempting to parse it.
XML parse rules have three parts: class name, namespace, and element name. To use
this Map To option, select XML Parse Rule in the Map To field, and then specify the
namespace and element name of the appropriate XML parse rule in the Map To Key
field using the syntax NamespaceName.ElementName.
For services and connectors of type SOAP or dotNET, do not select the XML Parse
Rule option if the Data Type of the value is XML Page. See “Mapping To and From
Model Rules” on page 5-20.
For information about how to create XML parse rules, see Data Mapping XML,
available on the PDN. See also the Application Developer Help system.
Mapping To and From Model Rules

The primary purpose for model rules, instances of Rule-Obj-Model, is to define
initial property values for instances of a class rule. For services and connectors of
type SOAP and .NET only, model rules can also be used as a schema description for
XML documents when an incoming or outgoing SOAP message contains an XML
object.
Both the Import XSD/DTD Accelerator and the Create Connector Rules Accelerator
generate model rules in addition to the other rules they generate.
When a model rule is used as a schema description, it specifies the subset of

properties that are significant for the XML document, specifies their default values,
if appropriate, and determines their order. SOAP and .NET services and connectors
can use a model rule to map an XML object’s property values to and from pages and
properties on the clipboard.
For services, mapping an argument to or from a model rule (and specified as an

XML Page data type) means that you want schema definitions for complex
properties to be included in the WSDL generated in the service package. That is, the
SOAP operation style for the service is document-literal, not RPC-encoded.
For connectors, the Connector Accelerator identifies arguments as XML Page types
and maps the arguments to and from models when the WSDL you connect to defines
its own complex types. Typically, but not always, this means the Web service uses
the document-literal SOAP message style.
To map an XML object to or from a model rule, you create an entry on the XML
Page tab of a connector or the Schema tab of a service that provides a page name for
a class rule and specifies the model to use from that class. In the data mapping for
the request or response, specify that the data type of the argument is XML Page, map
it to or from the Clipboard, and specify the page name in the Map To Key or Map
From Key field.
For more information, see Data Mapping XML, available on the PDN.
Mapping Incoming Files

For a service of type File, map the incoming files to a parse rule that provides
processing logic for files of that type. Use either a structured parse rule or a
delimited parse rule, as appropriate.
Map To and the Delimited Parse Rule Option

Use this option when the incoming data is in delimited files, that is, files that have a
comma, colon, or tab space that delimits each information type.
You must create a delimited parse rule before you can use this option. The rule
defines the delimiting character that separates the pertinent data in the incoming files
(for example, comma, tab, or quote marks) and describes where to store the values
— in a property value or in a special Value List property as one value. If necessary,
the parse rule can use processing that is defined in other delimited or XML parse
rules.
To use this option, select Delimited Parse Rule in the Map To field, and then specify
the appropriate rule by name in the Map To Key field.
For information about creating delimited parse rules, see the Application Developer
Help system.
Map To and the Structured Parse Rule Option

Use this option when the incoming data is in flat files that have a fixed format with
fields that have a fixed length.
You must create a structured parse rule before you can use this option. The rule
instructs Process Commander how to process the input file or input file record. To
use this option, select Structured Parse Rule in the Map To field, and then specify the
name of the appropriate rule by name in the Map To Key field.
For information about creating structured parse rules, see the Application Developer
Help system.
Data Mapping — Building Custom Map To and Map From Functions 5-23
Building Custom Map To and Map From Functions

Even when the data types of a property at the source and a property at the target are
compatible, the definitions of the data types can differ in length, number of
characters allowed, range, special values allowed, and other ways. If the data
mapping you need to express is not available from any of the default rules, you can
use your own custom Java code to clean up or transform the data.
For example, assume that you are mapping a double to a decimal. The incoming
value carries three digits to the right of the decimal point, but the property you are
mapping to can accept only two digits to the right of the decimal point. In this case,
write a custom Map To function that rounds the value up before placing the
property-value pair on the clipboard.
To create a custom function, create a custom library and add the custom functions to
it. Libraries are instances of Rule-Utility-Library and functions are instances of Rule-
Utility-Function. A library rule associates a library name with a RuleSet. Each
function rule in a library must have a unique name.
A custom function must meet the following requirements before it will appear in the
selection box for a Map To or Map From field:
■ The custom library that the function belongs to must be named, literally, MapTo
or MapFrom (as appropriate).
■ The method signature of the function must reflect a specific parameter list, as
described in “Requirements for the Functions” on page 5-24.
■ The data type of the return parameter must match the data type of the property
being mapped.
In Figure 5-10, for example, the last three options displayed in the Map To selection
box are custom Map To functions that return string values.
Figure 5-10. Custom Functions Listed in the Map From Field
Requirements for the Library Rule

Before you can create a custom function, you must first create a custom library rule.
A library rule associates a library name with a RuleSet name. The library rule must
be named, literally, either MapFrom or MapTo, as appropriate:
■ For a custom function for a Map From data map, name the library “MapFrom.”
■ For a custom function for a Map To data map, name the library “MapTo.”
Create the library in a RuleSet that the service or connector can access. For
additional information about creating a library rule, see the appropriate topics in the
Requirements for the Functions

When creating a custom function rule, designate whether it is a Map To or a Map
From function by entering the appropriate name (MapTo or MapFrom) in the Library
Name field. Additionally, the custom function must have a specific method
signature, as described in the following sections.
Parameters for Custom Map To Functions

All Map To functions accept three method parameters of three specific data types, a
fourth parameter that represents the data being mapped, and a Boolean return value
to indicate that the function either succeeded or failed. For example, Figure 5-11
shows the Parameters tab for a function named MapTo.parseCsvDetail.
Figure 5-11. Custom Map To Function
The first three parameters in the list in the Input Parameters section demonstrate the
required method signature for a custom Map To function. The parameter names can
be anything meaningful for your function rule, but the data type of the parameters
must be those listed in Figure 5-12 and in the order listed.
Parameter Data Parameter Description

Type
PublicAPI Specifies the name of a Java object that provides access to the
methods and objects in the Process Commander PublicAPI,
including the thread context.
For information about the Process Commander PublicAPI, see

the Process Commander Javadocs.
ClipboardPage Identifies the name of the clipboard page that holds the property
that is the target for the data provided by the function. Typically it
is the primary page of the service or connector activity.
String Identifies a variable that holds the name of the property that is
the target of the resulting data from this function. In data
mapping, the value of this string (the name of the specific
property) is passed from the Map To Key field.
Figure 5-12. Parameter List of Method Signature for Custom Map To Functions
The fourth parameter for the function identifies a variable that holds the input value
that is passed by the external system. Therefore, the third and fourth parameters
represent the name-value pair for setting a clipboard property value: the third
parameter represents the name, and the fourth parameter represents the value.
In the data mapping form, Process Commander compares the data type of the value
that is being mapped to the data type of the fourth parameter in the custom function
to determine whether the custom function can be listed as an option in the Map To
selection box.
In the Output section, specify that the Return Type is “boolean” (with a lower-case
“b”). You must program your custom function to return a value of true or false to
inform Process Commander whether or not the value could be processed. If the
function returns a value of “false,” the data mapping stops.
Parameters for Custom Map From Functions

All Map From functions accept three method parameters of three specific types, and
return an output value that is sent to the external system. For example, Figure 5-13
shows the Parameters tab for a function named MapFrom.conditionalError.
Figure 5-13. Custom MapFrom Function
The list of parameters in the Input Parameters section demonstrates the required
method signature for a custom MapFrom function. The names of the parameters can
be any string that is meaningful for the function rule, but the Java data types of the
parameters must be those listed in Figure 5-14 and in the order listed.
Java Data Type Purpose of the Parameter

PublicAPI Specifies the name of a Java object that provides access to the
methods and objects in the Process Commander PublicAPI,
including the thread context.
For information about the Process Commander PublicAPI, see the

Process Commander Javadocs.
ClipboardPage Identifies the name of the clipboard page that holds the property that
is the source of the data provided to be processed by the function.
Typically, it is the primary page of the service or connector activity.
String Identifies the name of the property that holds the source of the data
that will be processed by this custom function. When this function is
used in a data mapping, the value of this string (the name of the
specific property) is passed from the Map From Key field.
Figure 5-14. Parameter List of Method Signature for Custom Map From Functions
The parameter that represents the return value is defined in the Output section. The
third parameter in the list and the output parameter represent the name-value pair that
is returned by the function: the third parameter represents the name, and the output
parameter represents the value.
In the data mapping form, Process Commander compares the data type of the value
that is being mapped to the data type of the output parameter of the custom function
to determine whether the custom function can be listed as an option in the Map From
selection box.
Appendix A
Contacting Pegasystems
This appendix describes how to contact Pegasystems for the following:
■ Customer support
■ Education services
■ Documentation feedback
■ Office locations
For more information about our company and products, visit our Web site at
www.pega.com.
A-2 Introduction — Contacting Pegasystems
Customer Support
Pegasystems Global Services has a dedicated team of support engineers and product
specialists ready to respond with support and consulting services. Pegasystems offers
a choice of customer support programs to meet your business requirements. Global
Services is committed to working in partnership with our customers to deliver world-
class support and service.
To contact Pegasystems, go to www.pega.com.
Education Services
Pegasystems Education department offers a wide range of courses for our customers.
For course descriptions and contact information, go to www.pega.com. Courses can
be presented at customer sites. Courses are given at these locations:
■ Headquarters in Cambridge, Massachusetts
■ Chicago, Illinois
■ San Francisco, California
■ Reading, United Kingdom
■ Sydney, Australia
Pegasystems Certified Professional Program

The Pegasystems Certified Professional Program is an important part of Education
Services. The program provides certification examinations for System Architects on
the aspects of PegaRULES Process Commander essential to implementing successful
applications. For more information, go to www.pega.com.
Contacting Pegasystems — Documentation Feedback A-3
Documentation Feedback
Pegasystems strives to produce high-quality documentation. If you have comments
or suggestions, please send us a fax or e-mail with the following information:
■ Document name, version number, and order number (located on the

copyright page)
■ Page number
■ Brief description of the problem — for example, what instructions are

inaccurate, or what information requires clarification
Send faxes to: 617-374-9620, attention Technical Communications.
Send e-mail to: docteam@pega.com.
Note: This e-mail address is only for documentation feedback. For a product or
technical question, contact Pegasystems Global Services department.
A-4 Introduction — Contacting Pegasystems
Office Locations
Pegasystems maintains offices in these locations:
■ Cambridge, Massachusetts (Headquarters)
■ Alpharetta, Georgia
■ Chicago, Illinois
■ Concord, New Hampshire
■ New York, New York
■ Irving, Texas
■ Toronto, Ontario, Canada
■ Melbourne, Australia
■ Sydney, Australia
■ Paris, France
■ Reading, United Kingdom
For more information, contact your Pegasystems Sales Representative or go to

www.pega.com.

PRPC52 Integrating With External Systems (PDF Library)

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PRPC52 Integrating With External Systems (PDF Library)

Uploaded by

Copyright:

Available Formats

Integrating with External Systems

PegaRULES Process Commander 5.2

This document is the property of:

PegaRULES Process Commander

About This Document ...........................................................................................................1-1

Listeners and Servers .............................................................................................3-17

A Row in a Data Map ................................................................................................5-7

■ This guide, Integrating with External Systems, describes the Process

The Pega Developer Network (PDN), located at http://pdn.pega.com, is the primary

Who Should Read This Document

■ Developers (system architects) — an application developer who is responsible

■ System administrators — a systems engineer who is responsible for installation

■ Chapter 2, Introduction — presents an overview of services, connectors, and the

■ Chapter 3, Services Overview — describes the components and interactions of

■ Chapter 4, Connectors Overview — describes the components and interactions

■ Appendix A, Contacting Pegasystems — provides information about how to

Integration Services Documentation on the PDN

You can access the PDN site in the following ways:

■ When you have administrator rights in Process Commander, the dashboard

■ From a browser, go to:

PegaRULES Process Commander Documentation

■ Introduction is an overview for business users, introducing concepts for and

For more technical users, the Introduction provides an overview of concepts,

■ Designing Your Application with SmartBuild provides the design methodology

■ Administration and Security provides information on system administration and

■ Integrating with External Systems supports IT professionals who plan, design,

■ Authentication in PegaRULES Process Commander supports application

■ PegaRULES Process Commander System Management Reference describes the

■ prconfig.xml File Settings Reference describes all the configuration settings

■ Application Developer Help is an extensive online help system that provides

■ Installation Guide (located on the installation media) — describes how to install

■ Upgrade Guide (located on the installation media) — describes how to upgrade

Documentation for a release is provided on the installation media. The core

This chapter contains the following sections:

■ Before You Begin

Process Commander interfaces support a wide range of technologies and standards,

Integration services enable communications or exchanges between Process

Integration services are grouped into the following categories:

■ Services — programmatic components that define and implement an interface

Services respond to requests or messages sent from external systems to Process

■ Connectors — programmatic components that implement an interface that is

Connectors make requests or send messages to external systems, typically as

In addition, the following integration components support services and connectors:

■ Data mapping and transformation functions

■ Accelerators that generate rules and interfaces, automating certain integration

■ Testing and troubleshooting tools, especially the System Management client

A Process Commander application typically has multiple connectors and services

External System Process Commander

Workflow Connector External System

Figure 2-2. A Connector Enables a Workflow to Make Requests to an External Server

Create Connector Rules (Connector Accelerator)

■ Enterprise JavaBean™ (EJB)

■ SQL (relational database)

■ SOAP Web service

■ Microsoft .NET Web service

Create Service Rules (Service Accelerator)

■ Model rules for each class rule

■ XML parse rules

■ XML stream rules

Note: When your Process Commander application needs to call a method in an

Create EForm Rules (EForm Accelerator)

Create External Data Table Rules