PRPC52 Integrating With External Systems [PDF Library]

(1)

Integrating with External Systems

PegaRULES Process Commander 5.2

(2)

© Copyright 2006

Pegasystems Inc., Cambridge, MA

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

(3)

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

(4)

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

(5)

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

(6)

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:

(7)

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.

(8)

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

(9)

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:

(10)

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 SmartBuildprovides 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.

(11)

■ 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.

(12)

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

(13)

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.

(14)

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.

(15)

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.

Client Service

Tax rate = 4% Tax rate?

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.

(16)

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).

(17)

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.

External System

Workflow Connector

Process Commander

Price for x?

Price for x = 10

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

(18)

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).

(19)

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.”

(20)

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

(21)

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:

(22)

■ 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.

(23)

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.

(24)

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.

(25)

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.

(26)

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.”

(27)

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.

(28)

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 ■ Service Testing Features ■ Summary: Creating Service

(29)

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.

(30)

Services Overview — Introduction 3-3

Process

Commander

Clipboard Service Package External System or Client request response Service Rule Service Activity property property

Process

Commander

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).

(31)

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

(32)

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.

(33)

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.

(34)

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

(35)

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.

(36)

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

(37)

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.

(38)

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.

(39)

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.

(40)

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.

(41)

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.

(42)

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.

(43)

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.

(44)

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.

(45)

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.”

(46)

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.

(47)

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

(48)

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.