Professional Documents
Culture Documents
PRPC52 Integrating With External Systems
PRPC52 Integrating With External Systems
PRPC52 Integrating With External Systems
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.
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
Contents
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:
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.
1-2
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.
1-3
Chapter Overview
The following is a list of the remaining chapters in this book:
Chapter 5, Data Mapping Overview describes how to correlate the data inside
Process Commander with the appropriate properties or fields in the external
system.
1-4
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp
1-5
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.
1-6
Using the Performance Tools describes how to use the performance analyzer
(PAL) tool.
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.
Release Notes (located on the installation media) lists known issues regarding
the Process Commander release.
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
2-2
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:
Introduction Overview
2-3
Import and export mechanisms, rules that parse incoming text or files, and rules
that assemble messages or requests to be sent to external systems
2-4
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
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).
2-5
2-6
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
External System
Connector
Process Commander
Price for x = 10
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).
2-8
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.
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.
Java class
For more information, see Using the Connector Accelerator, available on the PDN.
2-10
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
2-11
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.
2-12
2-13
2-14
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.
2-15
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 a connector, you should also know enough about flow design so that
you can attach the connector and test it from within the flow.
2-16
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.
This chapter contains the following sections:
Introduction
Parts of a Service
3-2
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.
2.
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.
3-3
External System or
Client
response
request
Process
Commander
Service Package
Process
Commander
Service Rule
property
Clipboard
property
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).
3-4
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.
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.
3-5
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.
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.
3-6
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.
3-7
3-8
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 MQ and Email services, a server data object that holds connection
information.
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.
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
3-10
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.
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.
3-11
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.
3-12
Service Type
SOAP
.wsdl
.Net
.wsdl
Portlet
.war
Java
.jar
EJB
.jar
COM
.dll
CORBA
.idl
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.
3-13
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:
Information about whether to keep the requestor session open or to close it after
the service rule is finished.
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 RuleObj-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 RuleMethod. 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.
3-14
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.
3-15
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.
3-16
For File services, create an instance of one of the following parse rules to assess the
incoming data:
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.
3-17
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.
3-18
3-19
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.
3-20
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.
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.
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.
3-22
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.
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.
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.
3.
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.
3-24
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.
9.
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.
This chapter contains the following sections:
Introduction
Parts of a Connector
4-2
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.
2.
The Integrator task calls the connector activity and passes it the appropriate
properties from the clipboard.
3.
4.
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 propertyvalue pairs on the clipboard. The connector then returns control to the
Integrator task, and the flow resumes.
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).
4-3
4-4
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.
Java connectors call the Java methods and constructors of Java classes or .jar
files that are located in Process Commanders classpath.
HTTP connectors send message data to external systems through HTTP GET or
POST requests and process the response data.
.Net connectors are Microsoft .NET clients that call Web services on external
systems based on the Microsoft .NET Framework.
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.
4-5
4-6
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)
4-7
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.
4-8
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 JCA connector, create a JCA adapter data object that identifies the
location of the resource adapter the connector will communicate with.
4-10
After creating the connector, you integrate it into your application with an
Integrator task in a workflow.
When you use the Connector Accelerator to generate the connector, create an
abstract 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.
4-11
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 Workbase 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 beans 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.
4-12
The RuleSet.
With the exception of the SQL connector, a connector rule has two key parts:
Service name, which holds the name of the external service or method that it
connects to
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
Name of the request type, a string that you enter to describe the purpose of the
connector
4-13
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.
A JNDI server object that identifies the application server that manages the
message queue
A JMS producer model that identifies message processing settings
4-14
4-15
Compensating actions
Connector simulation
ConnectionProblem flow
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
4-16
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 DataAdmin-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.
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.
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.
4-18
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.
4-19
2.
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.
4-20
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.
This chapter contains the following sections:
Introduction
5-2
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.
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
External System
from
Process Commander
from
External System
to
5-3
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
Service
External System
Map From = response
5-4
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
Connector
External System
Map To = response
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.
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:
Special default parameters, based on the kind of service or connector you are
creating
HTML PostData
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.
5-6
Properties of mode Page or Page List create embedded pages on the clipboard:
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.
5-7
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.
5-8
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.
The clipboard
HTML stream
HTML frame
XML stream
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).
5-9
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
Option
Constant
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
parameter
None. You specify the name of the parameter in the Map From field,
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
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.
5-10
Map From
Option
Name of a custom
Map From function
Figure 5-4. Details for Map From and Map From Key Fields
The clipboard
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.
5-11
Map To Option
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
parameter
None. You specify the name of the property in the Map To field.
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.
Delimited Parse
Rule
5-12
Map To Option
Structured Parse
Rule
Name of a custom
Map To function
A string that identifies the name of a clipboard property that will hold
the results of the custom function.
See Map To and the Structured Parse Rule Option on page 5-22.
5-13
For services, they are the primary and parameter pages of the service activity
that the service calls. This activity is the service activity.
5-14
For connectors, they are the primary and parameter pages of the activity that
calls the connector. This activity is the connector activity.
Syntax Example
Description
.myproperty
mypage.myproperty
.mylistproperty(5)
Green.mygroupproperty(LOW)
param.radius
5-15
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.
5-16
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.
Map To option When the incoming message is HTML, select HTML Post
Data.
5-17
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.
5-18
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
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.
5-19
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.
5-20
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.
5-21
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.
5-22
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.
5-23
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.
5-24
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.
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
Application Developer Help system.
5-25
5-26
Parameter Data
Type
Parameter Description
PublicAPI
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
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.
5-27
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.
5-28
PublicAPI
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
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 worldclass 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:
Chicago, Illinois
Sydney, Australia
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:
Page number
Note: This e-mail address is only for documentation feedback. For a product or
technical question, contact Pegasystems Global Services department.
A-4
Office Locations
Pegasystems maintains offices in these locations:
Alpharetta, Georgia
Chicago, Illinois
Irving, Texas
Melbourne, Australia
Sydney, Australia
Paris, France