Integrating with External Systems PegaRULES Process Commander 5.2
© Copyright 2006 Pegasystems Inc., Cambridge, MA All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying, distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights are reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time.
This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 (617) 374-9600, fax: (617) 374-9620 www.pega.com PegaRULES Process Commander Document: Integrating with External Systems Software Version: 5.2 Issue Date: December 2006 Order #: @DPCINTEG08
Contents About This Document ...........................................................................................................1-1 Who Should Read This Document ...................................................................................1-2 Chapter Overview.............................................................................................................1-3 Integration Services Documentation on the PDN .............................................................1-4 PegaRULES Process Commander Documentation .........................................................1-5 Introduction ...........................................................................................................................2-1 Overview ..........................................................................................................................2-2 Services............................................................................................................................2-4 Connectors.......................................................................................................................2-6 Data Mapping ...................................................................................................................2-8 Integration Accelerators ...................................................................................................2-9 Create Connector Rules (Connector Accelerator).....................................................2-9 Create Service Rules (Service Accelerator)............................................................2-10 Import XSD/DTD .....................................................................................................2-10 Import JavaBeans ...................................................................................................2-11 Create EForm Rules (EForm Accelerator) ..............................................................2-12 Create External Data Table Rules...........................................................................2-13 Create Authentication Configuration .......................................................................2-13 Publish as Web Service Option...............................................................................2-14 Before You Begin ...........................................................................................................2-15 RuleSets..................................................................................................................2-16 Rule Resolution.......................................................................................................2-16 Services Overview.................................................................................................................3-1 Introduction.......................................................................................................................3-2 Service Rule Types ...................................................................................................3-4 Calling Process Commander with Java-Based Services...........................................3-6 Java-Based Services and Distributed Transactions..................................................3-7 Parts of a Service .............................................................................................................3-8 Service Package .......................................................................................................3-9 Service Rule............................................................................................................3-13 Classes and Properties ...........................................................................................3-14 Service Activity........................................................................................................3-15 Parse and Stream Rules .........................................................................................3-15
iv
Contents
Listeners and Servers .............................................................................................3-17 Service Testing Features ...............................................................................................3-19 Unit Testing Service Rules......................................................................................3-19 Tracing Service Rules .............................................................................................3-19 Using PAL with Services .........................................................................................3-20 Summary: Creating Services..........................................................................................3-22 EJB, File, Java, JMS, MQ, .NET, SOAP .................................................................3-22 COM, CORBA, Email, HTTP, Portlet ......................................................................3-23 BPEL .......................................................................................................................3-24 Connectors Overview............................................................................................................4-1 Introduction.......................................................................................................................4-2 Connector Rule Types ..............................................................................................4-4 Java-Based Connectors vs. Other Ways to Use Existing Java Code .......................4-5 SQL Connectors vs. Activity Methods .......................................................................4-7 Connectors and Distributed Transactions .................................................................4-7 Parts of a Connector ........................................................................................................4-9 Classes and Properties ...........................................................................................4-10 Connector Activity ...................................................................................................4-11 Connector Rule .......................................................................................................4-11 Parse and Stream Rules .........................................................................................4-12 Databases, Servers, and Other Data Objects .........................................................4-13 Integrator Task for the Workflow .............................................................................4-13 Connectors and Flow Support........................................................................................4-14 Running Connectors in Parallel...............................................................................4-14 Compensating Actions ............................................................................................4-14 Connector Simulation..............................................................................................4-15 ConnectionProblem, the Standard Error Handler Flow ...........................................4-16 Summary: Creating Connectors .....................................................................................4-18 Data Mapping.........................................................................................................................5-1 Introduction.......................................................................................................................5-2 Map To vs. Map From ...............................................................................................5-2 Request vs. Response ..............................................................................................5-3 Mapping Options .......................................................................................................5-4 Properties..................................................................................................................5-5 Creating Data Maps .........................................................................................................5-7
Contents
v
A Row in a Data Map ................................................................................................5-7 Map From and Map From Key Fields........................................................................5-8 Map To and Map To Key Fields ..............................................................................5-10 Sources and Targets for Mapped Data ..........................................................................5-13 Mapping to and from the Clipboard .........................................................................5-13 Mapping from a Constant........................................................................................5-15 Mapping to and from Special Default Parameters...................................................5-16 Mapping to and from HTML.....................................................................................5-16 Mapping XML ..........................................................................................................5-18 Mapping Incoming Files ..........................................................................................5-21 Building Custom Map To and Map From Functions .......................................................5-23 Requirements for the Library Rule ..........................................................................5-24 Requirements for the Functions ..............................................................................5-24 Contacting Pegasystems.....................................................................................................A-1 Customer Support ........................................................................................................... A-2 Education Services.......................................................................................................... A-2 Documentation Feedback ............................................................................................... A-3 Office Locations............................................................................................................... A-4
Chapter 1 About This Document PegaRULES Process Commander provides a set of standard integration services for creating interfaces to and from external systems. The documentation for these integration services is presented as follows: ■
This guide, Integrating with External Systems, describes the Process Commander integration features and presents general concepts and information for integrating Process Commander applications with other systems.
■
The Integration Services section of the Pega Developer Network (PDN) presents individual documents for individual types of services and connectors, along with appropriate RuleSet and code examples for them.
The Pega Developer Network (PDN), located at http://pdn.pega.com, is the primary technical resource for the Process Commander developer community. The PDN contains a broad range of technical articles including troubleshooting and “How-To” information and a comprehensive and searchable knowledgebase to help developers speed their application development. Before you can use the Pega Developer Network (PDN), you must register to obtain an account at the following URL: http://pdn.pega.com
1-2
Integrating with External Systems — About This Document
Who Should Read This Document If you plan to integrate your Process Commander application with other systems, you need to read this document. Most likely your job function falls into one of the following categories: ■
Developers (system architects) — an application developer who is responsible for application design and architecture, database operations, security design, and implementation; creates the class structure for the application with supporting automation capabilities, and implements interfaces with external systems.
■
System administrators — a systems engineer who is responsible for installation and setup, system-level security, database management, and other operational functions such as control, tuning, and troubleshooting.
For access to certain integration features, you need administrator rights. That is, you should have the SysAdmin role and the Developer portal assigned to your operator ID record.
About This Document — Chapter Overview
1-3
Chapter Overview The following is a list of the remaining chapters in this book: ■
Chapter 2, Introduction — presents an overview of services, connectors, and the rule types and features that support them.
■
Chapter 3, Services Overview — describes the components and interactions of Process Commander services.
■
Chapter 4, Connectors Overview — describes the components and interactions of Process Commander connectors.
■
Chapter 5, Data Mapping Overview— describes how to correlate the data inside Process Commander with the appropriate properties or fields in the external system.
■
Appendix A, Contacting Pegasystems — provides information about how to contact Pegasystems.
1-4
Integrating with External Systems — About This Document
Integration Services Documentation on the PDN As mentioned, information about building specific types of services and connectors is presented in individual documents for the individual types of service or connector. These documents, along with RuleSet and code samples, are posted on the Integration Services section pages of the PDN. After you read this book and have obtained a PDN account (from http://pdn.pega.com), go to the Integration Services section of the PDN and download the documents and samples for the service and connector types that you plan to build You can access the PDN site in the following ways: ■
When you have administrator rights in Process Commander, the dashboard displays section called Monitor System. Click the Pega Developer Network link in this section of the dashboard.
■
From a browser, go to:
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp
About This Document — PegaRULES Process Commander Documentation
1-5
PegaRULES Process Commander Documentation Pegasystems provides the following documents for PegaRULES Process Commander. ■
Introduction is an overview for business users, introducing concepts for and insight into applications built on Process Commander. For more technical users, the Introduction provides an overview of concepts, architecture, processes, and features of Process Commander applications.
■
Quick Start is a tutorial for business users and technical users. For business users, the Quick Start provides the experience of using an application — its look and feel — with a walk through features in relation to a business solution. For technical users, the Quick Start provides a tutorial with standard elements used in configuring a Process Commander application, providing guidance in using and modifying an application.
■
Designing Your Application with SmartBuild provides the design methodology essential for systems and technical staff in developing applications according to best practices.
■
Administration and Security provides information on system administration and on setting up security of applications and systems. This guide is useful for both system administrators and technical staff for initial startup, setup, and day-today 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.
1-6
Integrating with External Systems — About This Document
■
Using the Performance Tools describes how to use the performance analyzer (PAL) tool.
■
PegaRULES Process Commander System Management Reference describes the features provided by and the information displayed by the System Management application.
■
prconfig.xml File Settings Reference describes all the configuration settings held in the prconfig.xml file.
■
PegaRULES Process Analyzer User Guide describes how to install and use Process Analyzer, an optional component that provides online analytical processing (OLAP) data for PegaRULES Process Commander.
■
PegaRULES Process Simulator User Guide describes how to install and use Process Simulator, an optional component that provides simulation of PegaRULES Process Commander business processes.
■
Application Developer Help is an extensive online help system that provides information on concepts, forms, and functions of PegaRULES Process Commander. Contextual information about Process Commander is available on browser pages by selecting Help from the menu or clicking on the toolbar.
■
Installation Guide (located on the installation media) — describes how to install Process Commander.
■
Upgrade Guide (located on the installation media) — describes how to upgrade an existing Process Commander installation.
■
Release Notes (located on the installation media) — lists known issues regarding the Process Commander release.
Documentation for a release is provided on the installation media. The core documents for PegaRULES Process Commander are available through Application Developer Help. The entire documentation library is available through the PDN (located at http://pdn.pega.com). Selected documentation is available in hardcopy form.
Chapter 2 Introduction PegaRULES Process Commander applications are designed to complement other systems and technologies that you already have in place for doing work. The Process Commander integration services are based on industry-standard technologies for external system integration. Whether you have information in Process Commander that you want to make available to other systems, or there is information in an external system that you need to access from within a Process Commander workflow, you use the integration services features to accomplish your goal. This chapter contains the following sections: ■
Overview
■
Services
■
Connectors
■
Data Mapping
■
Integration Accelerators
■
Before You Begin
2-2
Integrating with External Systems — Introduction
Overview Process Commander provides integration facilities that support interactions between its applications and external systems, databases, Web sites, e-mail servers, and so on. By using these features, Process Commander can exchange information with many kinds of external systems, including relational databases, Enterprise Information Systems (EIS), e-mail servers, Excel spreadsheets, and even simple text files. Process Commander interfaces support a wide range of technologies and standards, including HTML, HTTP, Simple Object Access Protocol (SOAP), Microsoft .NET, Sun Microsystems Enterprise JavaBeans™ (EJB), IBM WebSphere MQ® messaging, Java Message Service (JMS), J2EE Connector Architecture (JCA), Business Process Execution Language (BPEL), JSR 94, JSR 168, and others. These interfaces are called integration services. Integration services enable communications or exchanges between Process Commander applications and external systems, whether an exchange is initiated from a user interface or browser (by a user) or whether an exchange is initiated from a server or a background process. In integration situations, a Process Commander application can act as either the client or the server, communicating with both back-end and front-end applications. Integration services are grouped into the following categories: ■
Services — programmatic components that define and implement an interface between an external application that acts as the client and a Process Commander application that acts as the server. Services respond to requests or messages sent from external systems to Process Commander. The messages can request data, deliver data, or even deliver a work object on behalf of the external system.
■
Connectors — programmatic components that implement an interface that is defined by an external system. With connectors, your Process Commander application acts as the client and the external system acts as the server.
Introduction — Overview
2-3
Connectors make requests or send messages to external systems, typically as part of a workflow process. Do not confuse connector rules or interfaces with flow connectors, the arrows on a Visio workflow diagram. In addition, the following integration components support services and connectors: ■
Import and export mechanisms, rules that parse incoming text or files, and rules that assemble messages or requests to be sent to external systems
■
Data mapping and transformation functions
■
Accelerators that generate rules and interfaces, automating certain integration tasks
■
Testing and troubleshooting tools, especially the System Management client application
A Process Commander application typically has multiple connectors and services that make requests to and process requests from external systems.
2-4
Integrating with External Systems — Introduction
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
Integrating with External Systems — Introduction
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
Figure 2-2. A Connector Enables a Workflow to Make Requests to an External Server To create a connector of type EJB, Java, .NET, SOAP, or SQL, use the Create Connector Rules Accelerator (Connector Accelerator), which is available from the Wizards section of the Integration page. As the name implies, the accelerator prompts you to enter information about the connector that you want to create. Then the accelerator generates the appropriate rules, activities, classes, and properties that the connector needs. (For connectors of type HTTP, JCA, JMS, MQ, and BPEL, you must create the rules manually.) After you create a connector, use Visio to insert an Integrator task into an existing workflow rule. The Integrator task calls the connector through the activity that the accelerator generated, and passes to the connector parameters from the workflow. In the example in Figure 2-2, the Integrator task passes in the UPC code of a product to an external SOAP service. As with the service rules, the connector rule holds information about that protocol or technology and, in this case, converts the parameters, their values, and other information into a valid SOAP request and calls
Introduction — Connectors
2-7
the pricing Web service on the EIS system. The connector parses the returned SOAP response and writes the price into a Process Commander property that the workflow can access. For more information about connectors, see Chapter 4, “Connectors Overview.” For information about the Connector Accelerator, see Using the Connector Accelerator, available on the Pega Developer Network (PDN).
2-8
Integrating with External Systems — Introduction
Data Mapping When you configure a service or connector, you also match or correlate the properties in the Process Commander application to the corresponding data fields or properties in the external system. This is called data mapping. You map both the data that comes in to Process Commander as well as the data sent from Process Commander. The service or connector can send and receive property values or an HTML or XML stream to and from the external system. When you configure the data mapping for a service or for a connector that is not created by a accelerator, you map the data elements (values) that are used by the service or connector. If incoming data must be parsed before it can be processed — the incoming data is in a delimited file, for example — map the data using a parse rule. If outgoing data needs to be presented as formatted HTML or XML, map the data using an XML or HTML stream rule. When you use the Service Accelerator or the Connector Accelerator, the accelerator configures the data mapping for the service or connector rule. The Service Accelerator creates suggested lists of input and output parameters based on the purpose of the service. The Connector Accelerator creates input and output lists based on the source material it parses while generating the rules and also creates properties in Process Commander that represent the data in the external system. Other integration services accelerators also assist you in data mapping by creating class and property rules that implement the data model of an external system. For more information about data mapping, see Chapter 5, “Data Mapping.”
Introduction — Integration Accelerators
2-9
Integration Accelerators Process Commander provides several rule generation and interface generation accelerators that automate some of the integration tasks. The integration accelerators are accessible from the Wizards section of the Integration page. Additionally, you can use the Publish as Web Service option on the Process tab of a flow rule to convert a flow into a SOAP or BPEL Web service.
Create Connector Rules (Connector Accelerator) The Connector Accelerator creates connector rules for only those connectors that use a protocol or technology that exposes its metadata. For example, because a SOAP service has a Web Service Definition Language (WSDL) file that defines its interface, the Connector Accelerator can create SOAP connectors. To use this accelerator, first create an abstract class (typically one that inherits from Data-) for the accelerator to use as the base for the generated rules, classes, and properties for the connector. Then run the accelerator and identify the class name and the file, URL, or database that defines the data structure of the external system. The accelerator uses the Interface Generator tool to import the metadata of the external system that you want connect to. It then parses and converts the information into data classes and properties (subclasses of the class that you specified), connector rules (instances of Rule-Connect-*), activities that call the connector rules. You can use the Connector Accelerator to create the following kinds of connectors: ■
Enterprise JavaBean™ (EJB)
■
Java class
■
SQL (relational database)
■
SOAP Web service
■
Microsoft .NET Web service
For more information, see Using the Connector Accelerator, available on the PDN.
2-10
Integrating with External Systems — Introduction
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:
Introduction — Integration Accelerators
■
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
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
Integrating with External Systems — Introduction
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.
Introduction — Integration Accelerators
2-13
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.
2-14
Integrating with External Systems — Introduction
As long as the name you choose for an authentication service object matches one of the default servlet definitions, you can implement up to five authentication service configurations without having to edit the web.xml file. Note that editing a web.xml file means undeploying and then redeploying Process Commander. For more information, see Authentication in PegaRULES Process Commander 5.2, which is available on the PDN.
Publish as Web Service Option The Publish as Web Service option on the flow forms creates service and connector rules that make a flow available as a BPEL process named PublishedFlows. To use this option, you must first create and save a flow. Then, select the Process tab and click the Publish button. The Publish feature creates two SOAP service rules and packages them with three SOAP connector rules to create a BPEL Web service. It also generates three WSDL documents and one BPEL document.
Introduction — Before You Begin
2-15
Before You Begin To create a service or connector, you must understand Process Commander terms, forms, functions, and the SmartBuild design and development process. You must have experience in defining Process Commander class rules, properties, models, activities, and other types of rules. You also need some knowledge of the technology or protocol for which you are building the service or connector. For example: ■
To create a SOAP service, you need to know how to write a SOAP client so that you can test the SOAP service.
■
To create a SQL connector, you need to know information about the database, such as the database name, database host server, and the JDBC connection pool name so that you can define the database with a Data-Admin-DB-Name data object. Additionally, you need to know how to write SQL queries so that you can test the connector.
■
To create Java-based services and connectors, you need to understand how classes are included in the Process Commanders. For information, see PRKB20931 “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.”
2-16
Integrating with External Systems — Introduction
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
■
Service Testing Features
■
Summary: Creating Service
3-2
Integrating with External Systems — Services Overview
Introduction A service receives input from an external system and can respond in some way. For example, a service can reply with data that the external system requested and it can process the incoming data to determine that it needs to create a work object and initiate a workflow. The following is a high-level description of how a service works: 1.
An external client or system assembles and delivers a message or request to a Process Commander service. The message identifies the service package that contains the service rule or method to invoke.
2.
The service package locates a service rule.
3.
The service rule, in turn, invokes the appropriate rules to map the incoming parameters to Process Commander properties.
4.
The service rule invokes an activity. The activity processes the input properties and completes the task of the service. As mentioned, perhaps the service extracts data from the Process Commander database or delivers a work item to Process Commander. The data mapping for the service rule then maps appropriate values into output properties.
5.
The service assembles a response message from the output properties and sends the response.
The architecture for this process is shown in Figure 3-1.
Services Overview — Introduction
3-3
External System or Client
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
Integrating with External Systems — Services Overview
Service Rule Types The Process Commander services are based on industry-standard technologies. Process Commander provides the following standard types of services: ■
EJB service rules expose functions in a Process Commander application as though they were methods of an Enterprise JavaBean.
■
JSR 94 service rules receive and respond to requests from external applications through JSR 94 invocations. A JSR 94 service is used when a part or all of a Process Commander application is embedded in another Java-based application.
■
Java service rules expose functions in a Process Commander application as though they were public methods of a Java class.
■
SOAP service rules provide Web services to SOAP (Simple Object Access Protocol) clients.
■
.NET service rules provide Web services to Microsoft .NET clients (external systems based on the Microsoft .NET Framework).
■
HTTP service rules process and respond to HTTP requests that contain XML or other string data (text) or HTML POST data. Use HTTP rules when you want to send XML or string data using a messaging protocol like SOAP.
■
JMS service rules respond to messages sent by Java Message Service clients to a queue or topic. JMS services read messages from the queue or topic.
■
MQ service rules accept WebSphere MQ (formerly called IBM MQSeries) messages from external systems and respond to them.
Note: When Process Commander is deployed as an enterprise application, you use a message-driven bean (MDB) as the listener for message-based service rules (JMS and MQ). This means that although you can use WebSphere MQ as a JMS service provider, you must use JMS MDB listeners with JMS service rules rather than MQ listeners with MQ service rules when Process Commander is deployed as an enterprise application. ■
Portlet service rules provide the mechanism for displaying Process Commander features and functions in JSR 168-compliant portlets that are
Services Overview — Introduction
3-5
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.
3-6
Integrating with External Systems — Services Overview
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.
Services Overview — Introduction
3-7
Java-Based Services and Distributed Transactions A distributed transaction is a set of operations that include more than one resource manager and that must be treated as one operation. For example, updates to more than one database in one transaction, or, a database operation and the sending or receiving of a JMS message in the same transaction. When Process Commander is deployed as an enterprise application, the processing performed by EJB, Java, and JMS services can participate in distributed transactions that are either bean-managed or container-managed. For more information, see Designing Applications that Ensure Data Integrity and Building EJB Services, both of which are posted on the Integration pages of the PDN.
3-8
Integrating with External Systems — Services Overview
Parts of a Service A service is made up of several rules and data objects; some types of services require more parts than others. For EJB, File, Java, JMS, JSR 94, MQ, .NET, and SOAP services, you can use the Service Accelerator to create the key parts. For COM, CORBA, e-mail, or portlet services, you create all the rules and data objects yourself. A service begins with a service package data object. A service package is similar to a container class. A service package represents the service as an application and the service rules represent individual functions or methods in that application. The class rule that the service exposes is typically a direct or indirect subclass of either the Data- or Work- base class. When creating the service, you determine the appropriate class rule and the significant properties for the service. A service has an activity that manipulates the values that are placed on a clipboard page by the service that may start a work object in a flow. But it is the service rule that assesses the incoming messages and writes input parameter values to the clipboard. The service rule also assembles and sends the appropriate response after the activity is finished with its task. Certain kinds of services typically have more than one service rule (EJB, BPEL, Java, SOAP, .NET), while other kinds typically have only one service rule (MQ, JMS, portlet). Additionally, depending on its type, a service has some of the following components: ■
For File services and sometimes for SOAP, dotNet, or Email services, a parse rule. For a SOAP, dotNet, or Email service, you may also need an XML stream rule for assembling the response.
■
For Email, File, JMS, or MQ services, a listener. A listener is a background process that monitors an inbox, a message queue, or a directory, routes messages from those locations to the appropriate service rule and transmits the reply messages.
■
For MQ and Email services, a server data object that holds connection information.
■
For JMS services, a JNDI server data object.
Services Overview — Parts of a Service
3-9
Service Package The central part of the service is the service package. As the name implies, the service package instance acts as a package or container for the service rules that make up the service. The first key in the three-part key to a service rule is the name of a service package. Therefore, all the services that use the same service package name as the first key belong to the same service package. The service package represents the service as an application. As such, the service package has global configuration settings for all the services that belong to it: ■
The access group that the service rules use when they run as unauthenticated users. The service rules must belong to one of the RuleSets listed in the access group.
■
Whether the services must run as authenticated users. If so, the incoming message from the external client application must include the name and password of a valid Process Commander operator.
■
Configuration information about the requestor pool when the service rules run as unauthenticated users and session state is stateless.
■
Whether the service is stateless or not.
− −
If the service is stateful, you specify whether to keep the requestor session open and when to close it in the service rules. (See “Requestors” on page 3-14 for more information.) If the service is stateless, the End Requestor option in the service rule does not apply.
Additionally, for several service types, you use the service package form to generate the deployment file that describes the functions in the service in a format that is appropriate for that protocol or technology.
Authentication Services can run as authenticated or unauthenticated users. To specify that a service must run as an authenticated user, select the Requires Authentication option on the Context tab of the service package. Typically, you
3-10
Integrating with External Systems — Services Overview
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.
Services Overview — Parts of a Service
3-11
There are two categories of requestors associated with a pool: ■
Idle requestors are currently in the pool, waiting for a service request.
■
Active requestors are currently out of the pool, managing service requests.
You specify how many requestors can be in the pool on the Pooling tab of the service package form. The setting for the number of idle requestors defines the size of the pool. The setting for the number of active requestors defines how many concurrent requestors you want to allocate to the services in the service package. When the pool has no idle requestors, Process Commander continues to create new requestors for service requests until it reaches the limit specified for active requestors. If a service request arrives after that limit is reached and no idle requestors are waiting in the pool, Process Commander waits to manage the request until an active requestor returns to the pool. When an active requestor completes processing, Process Commander checks the limit for idle requestors before returning that requestor to the pool. If the pool is under the limit, the requestor becomes idle and Process Commander returns it to the pool. If the pool is at the limit, Process Commander deletes the requestor instead. When you are testing or monitoring a service, you can examine the status of the requestor pool in the System Management application.
Deployment Components For SOAP, dotNet, BPEL, EJB, Java, Portlet, COM, and CORBA services, you use the service package form to generate deployment files. Process Commander translates the functions and processing provided by the service rules in that service package into the appropriate kind of deployment component for a service of that type. The service package can generate the items shown in Figure 3-2.
3-12
Integrating with External Systems — Services Overview
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.
Services Overview — Parts of a Service
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: ■
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 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
Integrating with External Systems — Services Overview
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.
Services Overview — Parts of a Service
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.
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.
3-16
Integrating with External Systems — Services Overview
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.
Services Overview — Parts of a Service
3-17
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.
3-18
Integrating with External Systems — Services Overview
More about JMS Listeners JMS listeners are implemented differently, based on how Process Commander is deployed. When Process Commander is deployed as a Web application, the listener runs as a Java thread that is created when Process Commander starts up. The listener waits for incoming messages on the JMS destination (queue or topic). At regular intervals (as specified on the listener form), the listener checks to see if Process Commander has issued a request for it to stop running. In this case, you create a JMS listener and a JNDI server data object for your JMS services. When Process Commander is deployed as an enterprise application, the listener is a message-driven bean (MDB) deployed inside your Process Commander application. The MDB routes messages to the Process Commander JMS service rule. In this case, you create a JMS MDB listener data object for your services. You use the form to generate a fragment of the EJB deployment descriptor file that describes the MDB. Then you insert the fragment into the message-driven beans subsection of the Process Commander EJB deployment descriptor file. For deployment instructions, see the Pega Developer Network article PRKB-23106 “How to Deploy a JMS Listener as a Message-Driven Bean.”
Services Overview — Service Testing Features
3-19
Service Testing Features Several features enable you to test your services while you develop them. During the design and development phase of your integration project, be sure to complete the following testing tasks for your service rules: ■
Unit test service rules with the Run button.
■
Watch service rules run in the Tracer
■
Collect statistics about the processing that services perform with Performance Analyzer (PAL)
This section provides brief descriptions of these features. For additional information about them, see Testing Services and Connectors, which is available on the PDN.
Unit Testing Service Rules Services start their processing in response to a request from an external application. What happens if the external application that makes the requests is being built and tested at the same time that you are creating your application in Process Commander? In this case, you can verify that the service will process data appropriately by manually providing it some representative data to process. When you click the Run button in a service rule, a dialog box appears in which you can provide test data. When you click the Execute button, Process Commander invokes the service rule. The service rule maps the test data and invokes the service activity. You can then determine whether the data mappings are configured correctly and if the service activity runs correctly without having to wait for the client application to be finished.
Tracing Service Rules The Tracer tool monitors an individual requestor session, tracking the execution of rules. You can set breakpoints, pause the processing while you examine the results of an action, and review and/or set property values.
3-20
Integrating with External Systems — Services Overview
You can use the Tracer to monitor any active requestor session. However, a service usually runs in a new requestor session with a requestor ID that is not created until the service begins processing. At that point, the processing a service performs occurs so quickly it can be hard to catch the event to trace it. Therefore, use the Trace Open Rule option to trace service rules. To use this option, open the service rule you want to trace and then select Run > Trace Open Rule. You can select the following Tracer options for services: ■
Services – the Tracer adds steps for when the service invocation begins and ends. Nested within those steps are entries that show when the inbound data mapping begins and ends, and when the outbound data mapping begins and ends.
■
Parse Rules – the Tracer adds steps for when parse rules (delimited, structured, or XML) begin and end their processing.
■
Stream Rules – the Tracer adds steps for when HTML or XML stream rules begin and end their processing.
Using PAL with Services The Performance Analyzer tool (PAL) enables you to gather statistics about the performance of your Process Commander system. This tool collects “snapshots” of your requestor on demand as it executes. You use it to observe the rules cache and to see how requests are resolved. You can examine summary, incremental, and detailed data, and you can save the data in spreadsheet format. PAL gathers the following statistics for service rules: ■
The elapsed time for the entire service processing event.
■
The elapsed time and the CPU time for the data mapping of the request message.
■
The elapsed time and the CPU time for the data mapping of the response message.
■
If the data is mapped to a parse rule or from a stream rule, the elapsed time and the CPU time for the parse or stream rule to process the data.
Services Overview — Service Testing Features
3-21
■
The number of parse rules that were called during the processing event.
■
The elapsed time and the CPU time it took to run the service activity.
■
For file services, the number of records contained in the file that was processed.
■
For file, e-mail, SOAP, MQ, and JMS services, the size of the data received in the request, in kilobytes.
If a service request takes longer than your design team has determined it should, use this information to determine if the problem is with a poorly designed activity, an overly large request or response message, and so on.
3-22
Integrating with External Systems — Services Overview
Summary: Creating Services The following procedures summarize the basic steps for creating services. For details about creating specific types of services, see the individual documents on the Integration Services section of the PDN.
EJB, File, Java, JMS, MQ, .NET, SOAP The basic procedure for creating a service with the Service Accelerator is as follows: 1.
Plan the service. Pick names for the service package, service class identifier, and service method. Decide on an access group and RuleSet (including version) for all the classes and rules. Determine the purpose of the service and identify the class rules and properties that are pertinent.
2.
If appropriate, run the Import XSD/DTD Accelerator or the Import Java Beans Accelerator to implement in Process Commander the data model of the external system that is to send requests to the service.
3.
If you used one of the accelerators to implement a data model that represents the external system, create properties to use to link that data model to the work object class.
4.
Run the Service Accelerator to generate the rules and data objects for the service. See Using the Service Accelerator, which is available on the PDN.
5.
Customize the generated rules and data objects as necessary, for example, by configuring the requestor pool in the service package instance or fine-tuning the data mapping settings in the service rule.
−
For a File service, write or identify the appropriate structured or delimited parse rule. Then specify the parse rule in the data map.
Services Overview — Summary: Creating Services
− −
3-23
For an SOAP or .NET service, assess the data that will be exchanged and determine whether you need to provide an XML parse rule or an XML stream rule for that data. For EJB and Java, open the service package and generate the deployment files.
6.
For an EJB, Java, NET, or SOAP service, copy the deployment file(s) to a client computer and then use the appropriate software development tools to develop the client application that communicates with this service. For more information about this step for EJB and SOAP services, see the Integration Services section of the PDN.
7.
Test the service.
COM, CORBA, Email, HTTP, Portlet The basic procedure for creating the rules and data objects for services of type COM, CORBA, Email, HTTP, or portlet is as follows: 1.
Plan the service. Pick names for the service package, service class identifier, and service method. Decide on an access group and ruleset (including version) for all the classes and rules.
2.
Create a service package.
3.
Create or identify the pertinent class rule and properties.
4.
For an Email service, assess the data that will be exchanged and determine whether you need to provide an XML parse rule or an XML stream rule for that data.
5.
For an HTTP service, assess the data that will be exchanged and determine whether you need to provide an XML, structured, or delimited parse rule, or an HTML or XML stream rule for the data.
3-24
Integrating with External Systems — Services Overview
6.
For a Portlet service or if the service must respond to requests with an HTML stream, write or identify the appropriate HTML stream rules.
7.
Create a service activity and specify that it applies to the class rule you identified in step 3.
8.
Create the service rule.
9.
For an Email service, create an e-mail listener and an e-mail server.
10. Return to the service package and identify the name of the service rule that you created in step 8. For a COM, CORBA, or portlet service, generate the deployment files. 11. Copy the deployment file(s) to a client computer and then use the appropriate software development tools to develop the client application that communicates with this service. For a portlet service, deploy the portlet.war file on a portal server. 12. Test the service.
BPEL To create a BPEL service, use the Publish Flow Accelerator. Create and save the flow that you want to publish as a BPEL Web service. Then select the Process tab and click Publish.
Chapter 4 Connectors Overview A connector is a set of rules and data that enables Process Commander, as a client, to send a message or a request for data to an external system. When you create a connector, you are defining how Process Commander invokes a service that is provided by an external system. After the processing or data retrieval is complete, the external system returns the results to Process Commander. This chapter contains the following sections: ■
Introduction
■
Parts of a Connector
■
Connectors and Flow Support
■
Summary: Creating Connector
4-2
Integrating with External Systems — Connectors Overview
Introduction A connector is typically used within a workflow, a flow rule. Perhaps at some point in a flow, the person who is assigned the work object needs information from an external system — a price, an account number, a referral code, a tax rate, for example — before the work object can move to the next step. In such a case, you create a connector and attach it to the workflow with an Integrator task. The following is a high-level description of how connectors work: 1.
A work object triggers an Integrator task in a flow.
2.
The Integrator task calls the connector activity and passes it the appropriate properties from the clipboard.
3.
The activity calls the connector.
4.
The connector assembles and sends a message or request to the external system.
5.
The external system replies to the connector with the data the connector requested.
6.
The connector receives the reply, processes it, and places the data as propertyvalue pairs on the clipboard. The connector then returns control to the Integrator task, and the flow resumes.
The architecture for this process is shown in Figure 4-1.
Connectors Overview — Introduction
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
Integrating with External Systems — Connectors Overview
Connector Rule Types As are services, connectors are based on industry-standard technologies. Process Commander provides the following standard types of connectors: ■
EJB connectors access an Enterprise JavaBean™ (EJB) and call its remote methods. You can also use them to communicate with WebSphere Business Integration adaptors.
■
SOAP connectors are SOAP (Simple Object Access Protocol) clients that call Web services.
■
SQL connectors send complex SQL statements to an external database.
■
Java connectors call the Java methods and constructors of Java classes or .jar files that are located in Process Commander’s classpath.
■
HTTP connectors send message data to external systems through HTTP GET or POST requests and process the response data.
■
JCA connectors send requests to external Enterprise Information Systems through resource adapters that implement the Common Client Interface of the J2EE Connector Architecture specification.
■
JMS connectors send request messages to an external system and process responses through an intermediate server that hosts Java Message Service middleware.
■
.Net connectors are Microsoft .NET clients that call Web services on external systems based on the Microsoft .NET Framework.
■
MQ connectors send request messages to an external system and process responses through an intermediate server that hosts IBM WebSphere MQ middleware.
■
BPEL connectors act as a container for the SOAP services and connectors that represent Process Commander as a partner of a Business Process Execution Language (BPEL) process when Process Commander starts the process.
To create connectors of type EJB, Java, .NET, SOAP, or SQL, use the Connector Accelerator.
Connectors Overview — Introduction
4-5
Java-Based Connectors vs. Other Ways to Use Existing Java Code There are several ways to take advantage of your existing Java code when developing a Process Commander application. You can use EJB connectors and Java connectors to invoke external Java applications; you can use Java activity steps in those exceptional cases when none of the Process Commander rule types implement the processing you need; and you can create utility function rules (Rule-UtilityFunction) to store reusable routines or procedural Java code. This section describes when you might use each option.
EJB and Java Connectors When your application must make requests to an external EJB application, use an EJB connector. When your application must make requests to an external Java-based application that is not an EJB, or must interact with an external Java class that must be maintained outside Process Commander, use a Java connector. By using a connector rule to invoke an external Java class, you can reuse the connector rule in multiple places while maintaining the Java code the connector interacts with in one place. Additionally, when connector rules run, they set Performance Analyzer timers for the external connections. If you have a performance issue or question, you can determine how much time the external Java class spends processing the connector's request. You can also track them in the Tracer: the Tracer tracks the beginning and end of a connector’s operation when it runs. For Process Commander to access the external application or Java class, the jar or class files must be in both the Process Commander compile time and runtime class path. For information, see PRKB-20931 “About the Process Commander Version 5 Class Paths,” available on the Pega Developer Network (PDN).
4-6
Integrating with External Systems — Connectors Overview
Java Steps While it is also possible to call external Java classes from Java steps in activities, it is best practice to use Java connectors instead. The SmartBuild design and development guardrails encourage you to use Java steps in activities sparingly. You should never use Java in an activity step when you can use rules to accomplish your processing goals. However, there are some very specific and limited reasons why you may need to use Java in an activity. In some cases, you must use a Java method from the Process Commander public API that does not have an activity method equivalent. For example, to create custom authentication activities, you use Java steps to invoke the setSecurityProfile and setUserAuthenticated Java methods from the PRAuthentication interface. (For information about writing custom authentication activities, see Authentication in PegaRULES Process Commander, available on the PDN)
Utility Function Rules If the specific piece of the existing Java code that you want to use is a procedural method or routine that does not use member variables, refer to other Java classes, or maintain state, you can create a utility function rule and store the code in the rule. That way you can maintain the code within the Process Commander database as a rule that is subject to versioning, which means the correct version of the function rule is selected at runtime based on the user’s RuleSet list. However, the SmartBuild design and development guardrails encourage you to use custom Java sparingly, even in function rules. Utility function rules typically perform simple computations or transformations. You can use them in activity preconditions and transitions, when rules, expressions, and so on. You can update them and recompile them without having to stop and restart Process Commander. For information about utility function rules, see the Application Developer Help system.
Connectors Overview — Introduction
4-7
SQL Connectors vs. Activity Methods There are two ways for your Process Commander application to interact with tables in external databases: use the Obj- activity methods in activities or use SQL connectors. ■
Use the Obj- activity methods for simple read/write interactions. To use these methods with an external table, the appropriate class and property rules and data objects must exist. Use the Create External Data Table Rules Wizard to generate these items.
■
For stored procedures and for SQL queries that include joins or are more complex than simple read/write interactions, use a SQL connector.
In either case, you must obtain the appropriate JDBC driver and a database account for Process Commander and then configure a data source for the external database in the application server hosting Process Commander. You must also create an instance of Data-Admin-DB-Name that uses the data source to identify the external database.
Connectors and Distributed Transactions A distributed transaction is a set of operations that include more than one resource manager and that must be treated as one operation. For example, updates to more than one database in one transaction, or, a database operation and the sending or receiving of a JMS message in the same transaction. When Process Commander is deployed as an enterprise application, it can participate in distributed transactions. Whether the transactions connectors participate in are bean-managed or container-managed depends on their requestor context. ■
Typically, connectors run in the requestor context of a user rather than as a background process. Users create a work object and when the work object reaches the Integrator task that invokes the connector, the connector runs in the user’s requestor context. When users the connector runs in a human user’s requestor context, transactions are bean-managed by Process Commander.
■
A service runs in the background, in a new requestor session. If the service processing for an EJB, Java, or JMS service invokes a connector, the connector
4-8
Integrating with External Systems — Connectors Overview
runs in the service’s requestor context. Whether the connector participates in a container-managed transaction depends on the transactional state of the service. For more information about distributed transactions and the boundaries (scope) of Process Commander’s bean-managed transactions, see the document Designing Applications that Ensure Data Integrity, which is posted on the PDN.
Connectors Overview — Parts of a Connector
4-9
Parts of a Connector A connector is made up of several rules and data objects; some types of connectors require more parts than others. If you are creating a JCA, JMS, or MQ connector, you create all the rules and data objects yourself. However, for any other connector type, you use the Connector Accelerator to create the rules and activities. First, you need a class rule that typically inherits from the Data- base class for the connector or the Create Connectors Rules Accelerator. The accelerator uses this class rule as the parent for any other classes and properties it needs to create. The accelerator also creates the main component of the connector, the connector rule, and an activity that calls the rule. The connector rule assembles the outgoing message. This rule also receives and processes any response that the external service sends back and performs any necessary data mapping. The Connector Accelerator creates the class, model, activity, property, and connector rules needed to implement the connector, using the abstract class that you specify as the parent class when you run the accelerator. Additionally, depending on its type, a connector might need some of the following components: ■
Depending on the system the connector interacts with, connectors of type JMS or MQ might require an XML stream rule to assemble the message. Conversely, if the reply contains an XML file that must be parsed, the connector must have an appropriate parse rule.
■
For a SQL connector, create an instance of Data-Admin-DB-Name that identifies the external database. Create this data object before running the Connector Accelerator.
■
For an EJB, JMS, or MQ connector, create a server data object.
■
For a JCA connector, create a JCA adapter data object that identifies the location of the resource adapter the connector will communicate with.
■
For a JMS connector, create a JMS producer model to identify message processing settings.
4-10
Integrating with External Systems — Connectors Overview
After creating the connector, you integrate it into your application with an Integrator task in a workflow.
Classes and Properties Whether or not you use the Connector Accelerator, you start by creating a parent (base) class rule with the following difference: ■
When you use the Connector Accelerator to generate the connector, create an abstract class.
■
When you create a JCA, JMS, or MQ connector, create or identify a concrete class.
The class rule that you create is likely to inherit from Data- because typically connectors request and retrieve data rather than work. However, depending on what the connector does, it is possible that the class rule can inherit from Work- or another appropriate class rule. The class rule for the connector must have a property for each parameter that will be used in the request or response. These properties are created as follows: ■
When you use the Create Connector Rules Accelerator, identify the source of the metadata (the location of a .wsdl file, for example). The accelerator examines that metadata and then creates, as subclasses of the parent class, the properties and any additional data classes that it needs to implement the connector.
■
When you create a JCA, JMS, or MQ connector, you create all the properties yourself (or identify them).
When you use the Connector Accelerator, it implements in Process Commander the data model of the external system to which the connector sends messages, and the connector interacts with this class structure. To move property values from that class structure to the work object class structure, the connector activity can set property values from the class structure for the messages into work object properties that you create for this purpose.
Connectors Overview — Parts of a Connector
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 bean’s Java methods to use. The connector rule handles the details for the request. The rule composes the outgoing message from clipboard properties, sends the request, obtains a response, and maps response data back into clipboard properties.
4-12
Integrating with External Systems — Connectors Overview
The connector rule holds the following kinds of information: ■
The RuleSet.
■
The number and type of output and input parameters.
■
Whether the system it communicates with accepts requests from authenticated users only, and, if so, the username and password the connector is to use.
■
Technology-specific information about connecting to a service of that type. For example, if the request is sent via HTTP (HTTP, SOAP, and dotNet connectors), the connector rule specifies session and time-out information.
With the exception of the SQL connector, a connector rule has two key parts: ■
Name of the class rule it applies to
■
Service name, which holds the name of the external service or method that it connects to
SQL connector rules have three key parts: ■
Name of the class rule it applies to, which also identifies the name of the database table data object that represents the external table the connector queries
■
The package name, which is typically set to JDBC
■
Name of the request type, a string that you enter to describe the purpose of the connector
Sample Rule Instances The PegaSample-IntSvcs RuleSet contains sample instances of each Rule-Connect-* type, each named CollectData. They are not working samples. They are examples that show the kind of information needed by a connector rule of that type.
Connectors Overview — Parts of a Connector
4-13
Parse and Stream Rules For some connector types, the connector rule needs information to assemble the request or to parse the response. Also known as import and export rules, parse rules interpret or parse a response from an external service, and stream rules assemble the XML or HTML stream that is sent in the connector request. Depending on what the connector needs to do, you may need to map outgoing data from a stream rule or incoming data to a parse rule.
Databases, Servers, and Other Data Objects Some connectors need additional data objects to provide reference information, such as port numbers, passwords, and hostnames. ■
Connectors of type SQL require a database name that identifies the external database that it connects to. They also need a database table object that identifies the table the connector queries.
■
Connectors of type EJB require a JNDI server data object to identify the EJB container where the EJB of interest is deployed.
■
Connectors of type MQ require an MQ server data object to specify the location of the server that manages the message queue it sends messages to.
■
Connectors of type JMS require the following additional data objects:
− −
A JNDI server object that identifies the application server that manages the message queue A JMS producer model that identifies message processing settings
4-14
Integrating with External Systems — Connectors Overview
Integrator Task for the Workflow The last step is to integrate the connector with your application. Typically, you add an Integrator task to your workflow. Integrator tasks are objects in the Process Commander Visio flow shape library. Figure 4-2 shows the standard Integrator task shape.
Figure 4-2. Standard Integrator Task When the processing of a flow rule reaches an Integrator flow shape, Process Commander runs the activity associated with the task — either the work activity for the connector or the extra caller activity that invokes the connector activity. The connector sends its request while the workflow waits. When the system receives a response, the flow resumes.
Connectors Overview — Connectors and Flow Support
4-15
Connectors and Flow Support Because connectors are typically called from flows, several connector features support flow design and development: ■
Run in parallel — asynchronous operation
■
Compensating actions
■
Connector simulation
■
ConnectionProblem flow
Running Connectors in Parallel By default, when a connector is invoked it retains control of the requestor session until it returns a response to the flow. However, when the RunInParallel parameter is selected for the Connect-* method called by the activity, the connector returns control of the session to the flow immediately after the request. This means that if the flow has another connector with a subsequent task to accomplish, the next connector can send its request immediately after the first makes its request — the second connector does not have to wait for the first connector to return a response. The RunInParallel parameter is typically used with SQL connectors because each SQL statement (SQL connector) is invoked by a separate connector activity. As an example, imagine that a work object reaches a point where the user needs both a referral code and a doctor name for the work item, and these pieces of data are in different tables in the same external database. As long as there are no dependencies (that is, the referral code does not depend on which doctor you select, for example), you can run these connectors in parallel, which speeds up the task.
Compensating Actions An action in a flow can have dependencies on later events. For example, perhaps a work object causes a bill to be sent to a customer, and the next step in the flow is a process that updates the accounts receivable data in the accounting system. What happens if the accounting system is offline? Do you need to cancel the bill and send the work item back to the previous step until the accounting system is back online? If
4-16
Integrating with External Systems — Connectors Overview
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.
Connectors Overview — Connectors and Flow Support
4-17
When the work object reaches the Integrator task for your connector, the activity that calls the connector checks for the simulator flag. It discovers that simulation mode is enabled; rather than calling the connector, it calls the associated simulation activity. The simulation activity responds by sending the simulated return values to the connector activity, the connector activity returns to the Integrator task, and you can continue testing the rest of the flow. For more information, see Using Connector Simulators, available on the PDN.
ConnectionProblem, the Standard Error Handler Flow Because connectors request information from external systems, there are external factors that can cause a connector to fail to obtain the data it needs – the external system could be offline, for example. Use the ConnectionProblem flow, a standard Process Commander flow, to track and resolve issues when a connector fails. To use this feature, you specify the ConnectionProblem flow in the Error Handler Flow field of the connector rule. When the Integrator task in a flow calls that connector, the following occurs if the connector fails: 1.
The connector returns an error message (exception).
2.
If the connector failed because it could not communicate with the external system, the current flow starts the ConnectionProblem flow. The work object or task is assigned to a workbasket named IncompleteConnections.
Note: If the connector failed because it is not configured correctly, the current flow starts the standard Process Commander flow named FlowProblems and reassigns the work object or task to an administrator user. 3.
The Service Unavailable SLA goes into effect. This SLA tries the Integrator task again five times.
−
If the connector succeeds, the ConnectionProblem flow ends, the ConnectionProblem flow assignment is cancelled, and the original flow resumes.
4-18
Integrating with External Systems — Connectors Overview
− −
If the connector fails for a new reason, the ConnectionProblem flow ends, the FlowProblems flow starts, and the assignment is reassigned to the FlowProblems flow. If the connector fails to connect to the external system after four attempts, the SLA stops trying. The assignment stays in the IncompleteConnections work basket until a user either restarts the flow or cancels the assignment.
When you create a new connector rule or use the Connector Accelerator to generate a connector rule, the ConnectionProblem flow is set in the Error Handler Flow field, which means that this feature is enabled by default. You can customize the standard ConnectionProblem flow by creating your own version of it or any of its parts in a separate ruleset. If you do not want to use this feature, delete the name of the ConnectionProblem flow from the Error Handler Flow field. When this field is blank, the feature is disabled. For more information, see Using Error Handler Flows, available on the PDN.
Connectors Overview — Summary: Creating Connectors
4-19
Summary: Creating Connectors The following procedure describes the basic procedure that you use to create connectors. For details about creating specific types of connectors, see the individual documents on the Integration Services section of the PDN. The basic procedure for creating a connector is as follows: 1.
Perform the appropriate system administration or setup tasks on the external system or service. For example, to create a SQL connector, a DBA must create an account for the connector on the external database. If you set up the service or system before you create the connector, you can use the Create Connector Accelerator to run validation tests against the actual service or system.
2.
Perform the appropriate system administration or setup tasks on the Process Commander system. For information, see Using the Connector Accelerator and Creating JMS and MQ Connectors, which are available on the PDN.
3.
If you plan to use the Connector Accelerator, create an abstract class, typically one that inherits from Data-. The Connector Accelerator writes properties and activities into this class. Depending on the connector type, the Connector Accelerator might also create subclasses of the data class. Additionally, create properties for the work object class that will link the data from the generated class structure to the work object.
4.
If the connector is of type HTTP, BPEL, JCA, JMS, or MQ, create the connector rules. Otherwise, Run the Connector Accelerator to generate the rules for the connector.
5.
Click the Test Connectivity button to test the connection to the external system.
6.
Edit the generated rules as necessary, for example, by adding security constraints or fine-tuning the data mapping settings.
4-20
Integrating with External Systems — Connectors Overview
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
■
Creating Data Maps
■
Sources and Targets for Mapped Data
■
Building Custom Map To and Map From Functions
5-2
Integrating with External Systems — Data Mapping
Introduction A data map controls how Process Commander selects, converts, and copies data between the formats that are used by an external system and the properties that are used by Process Commander. Data maps specify the correlation between external variables and Process Commander properties. For example, you can specify that when an external system passes in an integer named “x,” Process Commander will map the value of x to a property named “xtra” on the primary page of the clipboard. Each service rule and each connector rule contain two data mappings, one for the request and one for the response. In Process Commander terminology, these data maps are called Map To and Map From data maps.
Map To vs. Map From When you think about the flow of data for a service or a connector, remember that data mapping is always from the perspective of the Process Commander system: ■
A Map To data map describes data that is being sent to Process Commander. Data is mapped to Process Commander from the other system.
■
A Map From data map describes data that Process Commander is sending to an external system. Data is mapped from Process Commander to the other system. to
External System
from
Process Commander from
Figure 5-1. Data Flows to and from Process Commander
External System to
Data Mapping — Introduction
5-3
Request vs. Response To configure data maps, you create the request and/or response in a service or connector rule. To determine which tab (Request or Response) configures which kind of data map, consider this question: Is the primary role of the Process Commander application that of the client (requestor) or that of the server (responder)?
Services: the Responders For a service, the primary role of Process Commander is that of the responder: ■
Because the Request tab defines the request from the other system to the Process Commander service, the data map on the Request tab for a service is a Map To data map.
■
Because the Response tab defines the response from the service to the external request, the data map on the Response tab is a Map From data map. Map To = request
Process Commander Service
External System Map From = response
Figure 5-2. Data Mapping to and from a Service In some Process Commander forms, these tabs are not named Request and Response. For example, the response for a service of type EJB or COM is defined on the Parameters tab.
5-4
Integrating with External Systems — Data Mapping
Connectors: the Requestors For a connector, the primary role of Process Commander is that of the requester: ■
Because the Request tab defines the request or message that the connector sends from Process Commander to the other system, the data map on the Request tab for a service is a Map From data map.
■
Because the Response tab defines the response from the other system response to the connector request, the data map on the Response tab is a Map To data map. Map From = request
Process Commander Connector
External System Map To = response
Figure 5-3. Data Mapping From and To a Connector In some Process Commander forms, these tabs are not named Request and Response. For example, the request for a connector of type EJB is configured on the Create tab, and the response is configured on the Remote tab.
Mapping Options The goal of the data map is for properties and their values to be identified by the source system and to be recognizable to the target system. When the data is simple or is similar between systems, the data map is also simple — you can usually map data directly to and from properties on the clipboard. However, if a message must be assembled before it is sent out, or parsed before it can be processed, you map it using a rule.
Data Mapping — Introduction
5-5
The following is a list of the general categories of constructs that you can map data to or from in a data map: ■
A property on the clipboard
■
A constant, fixed value
■
Special default parameters, based on the kind of service or connector you are creating
■
HTML PostData
■
Parse rules that parse XML, structured files, or delimited files
■
Stream rules that create HTML or XML
■
Custom MapTo and MapFrom functions that you create.
Each of these options is described in more detail later in this chapter.
Properties Before you can create a data map, you must identify the key properties and their property modes (data types) so that you can map them correctly: ■
When you create a connector, you usually create the class rule that it needs. In this case, you know the definitions (modes) of the properties that will participate in the data maps because you created them.
■
When you create a service, however, your task is usually to expose a class rule that already exists. In this case, you must investigate the class rule to determine the property modes of the properties that will participate in the data map.
Data maps can handle properties of any of the following Process Commander property modes: Single Value, Value List, Value Group, Page, Page List, Java Property, Java Property List, Java Object, and Java Object List. All but the single value mode define aggregate or complex properties that store arrays and repeating groups.
5-6
Integrating with External Systems — Data Mapping
Properties of mode Page or Page List create embedded pages on the clipboard: ■
A property of mode Page can contain other properties of any mode.
■
A property of mode Page List can contain an indexed array of pages.
As you define data maps for aggregate properties, remember that in Process Commander, ordered collections (lists) are 1-based, not 0-based. When specifying the first item in a list, you identify it with a 1 rather than a 0; you identify the second item in a list with a 2 rather than a 1; and so on. For example, assume that you are mapping the first value of a Value List property named My Children, and the MyChildren property is located on the first page of a PageList property named Employee. In this case you use the following syntax: .Employee(1).MyChildren(1)
Top-level clipboard pages cannot be PageList. Use the period character (.) to specify an embedded PageList, such as the one in the example above. For additional information about properties and property modes, see Working with Java Objects in Process Commander and Designing Your Application with SmartBuild, available on the PDN. See also the Application Developer Help system.
Data Mapping — Creating Data Maps
5-7
Creating Data Maps The process of creating a data map is the same for Map To and Map From data maps. However, the options that you can configure are different. This section describes a row in a data map, especially the Map To, Map To Key, Map From, and Map From Key fields. The next section, “Sources and Targets for Mapped Data,” presents a more detailed description of each of the individual mapping options.
A Row in a Data Map Each row in a data map explains how to process a value. You provide the following information for the value in both a Map To and a Map From data mapping: ■
Data Type — the data type of the external value you are mapping.
■
Name — the name of the property used by the external system; that is, the name that Process Commander uses to identify the value in the request to or response from the external system.
■
Description — an optional description of the value you are mapping. This text is for information only; it is displayed in the Process Commander Portal, but it is not evaluated during processing.
Then, for a Map From data mapping, you also provide values for the following fields: ■
Map From — the source, or in some cases the type of source, of the value in Process Commander, for example, the clipboard, a rule type, or a custom function. The list of options in the selection box depends on the data type that is selected in the Data Type field.
■
Map From Key — the key to locating the property in the source. For example, if the source of the property is the clipboard, the key is the name of the property. If the source of the property is a rule, the key is the name of the rule.
5-8
Integrating with External Systems — Data Mapping
Conversely, for a Map To data mapping, you also provide values for the following fields: ■
Map To — the destination or the type of destination for the value in Process Commander, for example, the clipboard, a rule type, or a custom function. The list of options in the selection box depends on the data type selected in the Data Type field.
■
Map To Key — the key to locating the property in the destination. For example, if the destination of the property is the clipboard, the key is the name of the property. If the destination of the property is a rule, the key is the name of the rule.
Map From and Map From Key Fields A Map From data map describes the information in Process Commander to send to an external system and how to assemble it into the appropriate format or message that the external system needs. The value that you specify in the Map From Key field depends on the option that you selected in the Map From field. The Map From field presents the following options: ■
A constant, a fixed value that does not change
■
The clipboard
■
HTML stream
■
HTML frame
■
XML stream
■
Custom Map From functions (Rule-Utility-Function), if any are appropriate for the mapping
In addition, depending on the kind of service or connector you are creating, you can enter certain default parameters manually (the parameters do not appear in the Map From selection box).
Data Mapping — Creating Data Maps
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
Value in Map From Key
Constant
A string that specifies the literal value of the constant. See “Mapping from a Constant” on page 5-15.
Clipboard
The name of the property with a value to be sent. The name can include the name of the clipboard page or a keyword that specifies the clipboard page. See “Mapping to and from the Clipboard” on page 5-13.
Name of a default 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
The stream name of a rule that produces an HTML stream. See “Map From and the HTML Stream Option” on page 5-16.
HTML Frame
None. Use this option to specify the HTML that has already been generated by a Show-HTML method in a previous activity. See “Map From and the HTML Frame Option” on page 5-17.
XML Stream
The stream name of the appropriate XML rule. See “Mappping From XML Stream Rules” on page 5-18.
5-10
Integrating with External Systems — Data Mapping
Map From Option
Value in Map From Key
Name of a custom Map From function
The name of a clipboard property. The value of this property is passed to the custom function. See “Building Custom Map To and Map From Functions” on page 5-23.
Figure 5-4. Details for Map From and Map From Key Fields
Map To and Map To Key Fields A Map To data map describes how Process Commander processes an incoming message. The data map specifies how to extract values from the message and into which properties to put the values. The value that you specify in the Map To Key field depends on the option that you select in the Map To field. The Map To field includes the following options: ■
The clipboard
■
HTML Post Data
■
XML parse rule
■
Delimited parse rule
■
Structured parse rule
■
Custom Map To functions, if any are appropriate
In addition, depending on the kind of service or connector you are creating, you can enter certain default parameters manually (the parameters do not appear in the Map To selection box). Figure 5-5 describes how you provide the value for the Map To Key field for each option available in the Map To field.
Data Mapping — Creating Data Maps
5-11
Map To Option
Value for Map To Key
Clipboard
A string that specifies the name of the property to hold the incoming data. The string can also include the name of the clipboard page or a keyword that specifies the clipboard page. See “Mapping to and from the Clipboard” on page 5-13.
Name of a default 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.
HTML Post Data
None. The incoming URL provides (identifies) the property/value pairs. If the class that the service or connector interacts with has properties with the same names as those provided by the URL, Process Commander can put the data in the correct place. See on “Map To and the HTML Post Data Option” page 5-17.
XML Parse Rule
The name of the rule. See “Mapping To XML Parse Rules” on page 5-19.
Delimited Parse Rule
The name of the rule. See “Map To and the Delimited Parse Rule Option” on page 5-21.
5-12
Integrating with External Systems — Data Mapping
Map To Option
Value for Map To Key
Structured Parse Rule
The name of the 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.
See “Building Custom Map To and Map From Functions” on page 5-23. Figure 5-5. Details for Map To and Map To Key Fields
Data Mapping — Sources and Targets for Mapped Data
5-13
Sources and Targets for Mapped Data The data mapping options that appear in the Map From and Map To fields are both data sources and data targets. This section describes the data mapping options and presents information about how you identify and/or create them.
Mapping to and from the Clipboard When you select the Clipboard option in the Map To or Map From field, specify a property in the Map To Key or Map From Key field. If you enter the name of the property by itself (that is, .propertyName), it means that the property is located on the primary page of the service or connector activity. Figure 5-6 shows the data mapping for a string property named “pySearchResponse.” pySearchResponse is located on the primary page of the service, and its value is passed to the external system as a property-value pair for a property named “Result.”
Figure 5-6. Data Map for a Property on the Clipboard If you know that when a service or connector rule is invoked, a specific named page is on the clipboard, you can specify a property on that named page. Specify the page with a prefix to the property name. You can specify either the page name or the keyword param, which means that the property is on the parameter page of the service or connector activity.
Primary Page and Parameter Page The primary page and parameter page are as those of the following activities: ■
For services, they are the primary and parameter pages of the service activity that the service calls. This activity is the service activity.
5-14
Integrating with External Systems — Data Mapping
■
For connectors, they are the primary and parameter pages of the activity that calls the connector. This activity is the connector activity.
Syntax for Property References Figure 5-7 shows examples of the syntax used to refer to properties in the Map From Key and Map To Key fields for data mapping to or from the clipboard.
Syntax Example
Description
.myproperty
The value of the property named myproperty located on the primary page of the activity.
mypage.myproperty
The value of the property named myproperty located on a top-level user page named mypage.
.mylistproperty(5)
The value of the fifth element of the Value List property named mylistproperty located on the primary page.
Green.mygroupproperty(“LOW”)
For the Value Group property named mygroupproperty located on a top-level page named Green, the value of the element indexed by the literal value LOW.
param.radius
The value of the property named radius located on the parameter page of the activity.
Figure 5-7. Syntax Examples for Property References To provide an indirect property reference, use curly braces. For example, consider the following property reference: {Green.overthere}
Data Mapping — Sources and Targets for Mapped Data
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.
Mapping from a Constant A constant is a fixed, known value that remains the same no matter when the connector or service runs. For example, assume that a connector identifies itself to the external system through a user ID or a license key that does not change. You can map that value as a constant so the user who triggers the connector does not have to enter a value each time. To use a constant, enter the name of the constant in the Name field, select Constant from the Map From field, and enter the value of the constant surrounded by double quote characters in the Map From Key field. For example, Figure 5-8 shows a constant named Foo with the value Bar.
Figure 5-8. Mapping a Value as a Constant
5-16
Integrating with External Systems — Data Mapping
Mapping to and from Special Default Parameters Several service and connector types include a set of default parameters that are used for security, or session management. ■
Inbound SOAP, JMS, and MQ messages can contain parameter-value pairs for properties named “Username,” “Password,” and “RequestorID.”
■
Inbound .NET messages can contain parameter-value pairs for “Username” and “Password.”
Process Commander processes these parameters automatically, without requiring that the primary page class have properties that match these parameters. To map one of these special default parameters, set the Data Type value to String, then select the appropriate parameter from the selection list in the Map To or Map From field, and leave the Map To Key or Map From Key blank.
Mapping to and from HTML Three HTML options are available for data mapping, two for Map From data maps and one for Map To data maps: ■
Map From options — When the message to be sent to an external system is HTML, select HTML Stream or HTML Frame, as appropriate.
■
Map To option — When the incoming message is HTML, select HTML Post Data.
Map From and the HTML Stream Option Use the Map From option of HTML Stream when the HTML message to be sent to the external system must be created. You must first create an HTML rule before you can select the HTML Stream option. The rule can reference clipboard properties and use directives, which are assembly instructions for stream processing used to produce final HTML. The key to the rule name has two parts: the Applies To class and Stream Name.
Data Mapping — Sources and Targets for Mapped 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.
Figure 5-9. Sample Reference to HTML Rule For information about how to create HTML stream rules (Rule-Obj-HTML), see the Application Developer Help system.
Map From and the HTML Frame Option Use the HTML Frame option when the HTML data for the outbound message has already been created by an activity that uses the Show-HTML method. In this case, the HTML is already created and is waiting on the thread page (pxThread) on the clipboard for the service or connector activity. Select the HTML Frame option in the Map From field, and leave the Map From Key field blank. The service package form includes an option to suppress HTML. If Show-HTML is suppressed for a service package, do not select this option for a data mapping in the service rule.
Map To and the HTML Post Data Option An incoming message originating from a Web browser (forwarded by a client) is assembled in a specially formatted text stream (CGI format) and sent using the
5-18
Integrating with External Systems — Data Mapping
HTTP POST method from a form. When a service receives HTTP POST data, select the HTML Post Data option in the Map To field of the data map. The property values are presented in the URL that is streamed from the browser to Process Commander. The values are appended as field-value pairs to the URL and must include clipboard page names. For example, the following URL passes the field-value pairs “field1=foo” and “field2=bar”: http://servername?page1.field1=foo&page1.field2=bar
Process Commander automatically interprets the field-value pairs appended to a URL as property-value pairs and writes them to the clipboard. Therefore, you do not map them in the data map for the service or connector. Instead, when you select the HTTP Post Data option in the Map To field, you leave the Map To Key field blank. Be sure that the properties are defined — that there is a matching property (RuleObj-Property) in the data class associated with the connector or service for each value that is submitted in the URL.
Mapping XML When you are building SOAP, .NET, EJB, JMS, and MQ services or connectors, you may need to specify data mapping for messages that contain XML. When the message contains scalar arguments that match Process Commander properties or activity parameters and the data in the argument is to be treated as a single value, you can create simple argument-property mappings. However, if the message contains scalar arguments and the data in the argument is XML data, or if the message contains an XML object, you map the values and from the rules described in this section.
Mappping From XML Stream Rules XML stream rules describe how to assemble an XML document from property values. Use the XML Stream option if the message that your service or connector is sending is an assembled XML document.
Data Mapping — Sources and Targets for Mapped Data
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.
Mapping To XML Parse Rules XML parse rules, instances of Rule-Parse-XML, describe how to interpret XML embedded in a string argument into property-value pairs in Process Commander. Use the XML Parse Rule option when the incoming data includes XML that is held in a scalar argument. When processing an XML parse rule, Process Commander scans the incoming XML text, parses it into an internal tree structure, and then traverses the structure as instructed by the XML parse rule. Process Commander extracts specific element values and places them onto a clipboard page. An XML parse rule can perform searches, accept repeating groups by creating embedded pages, and navigate through the XML structure.
5-20
Integrating with External Systems — Data Mapping
Before you can select the XML Parse Rule option, you must have an XML parse rule to use. The easiest way to create XML parse rules is to use the Create Import/Export Rules Accelerator. After they are generated, open them and use the Validate tab to specify when Process Commander should validate the incoming XML stream against a published definition (XSD or DTD) before attempting to parse it. XML parse rules have three parts: class name, namespace, and element name. To use this Map To option, select XML Parse Rule in the Map To field, and then specify the namespace and element name of the appropriate XML parse rule in the Map To Key field using the syntax NamespaceName.ElementName. For services and connectors of type SOAP or dotNET, do not select the XML Parse Rule option if the Data Type of the value is XML Page. See “Mapping To and From Model Rules” on page 5-20. For information about how to create XML parse rules, see Data Mapping XML, available on the PDN. See also the Application Developer Help system.
Mapping To and From Model Rules The primary purpose for model rules, instances of Rule-Obj-Model, is to define initial property values for instances of a class rule. For services and connectors of type SOAP and .NET only, model rules can also be used as a schema description for XML documents when an incoming or outgoing SOAP message contains an XML object. Both the Import XSD/DTD Accelerator and the Create Connector Rules Accelerator generate model rules in addition to the other rules they generate. When a model rule is used as a schema description, it specifies the subset of properties that are significant for the XML document, specifies their default values, if appropriate, and determines their order. SOAP and .NET services and connectors can use a model rule to map an XML object’s property values to and from pages and properties on the clipboard. For services, mapping an argument to or from a model rule (and specified as an XML Page data type) means that you want schema definitions for complex
Data Mapping — Sources and Targets for Mapped Data
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.
Mapping Incoming Files For a service of type File, map the incoming files to a parse rule that provides processing logic for files of that type. Use either a structured parse rule or a delimited parse rule, as appropriate.
Map To and the Delimited Parse Rule Option Use this option when the incoming data is in delimited files, that is, files that have a comma, colon, or tab space that delimits each information type. You must create a delimited parse rule before you can use this option. The rule defines the delimiting character that separates the pertinent data in the incoming files (for example, comma, tab, or quote marks) and describes where to store the values — in a property value or in a special Value List property as one value. If necessary, the parse rule can use processing that is defined in other delimited or XML parse rules.
5-22
Integrating with External Systems — Data Mapping
To use this option, select Delimited Parse Rule in the Map To field, and then specify the appropriate rule by name in the Map To Key field. For information about creating delimited parse rules, see the Application Developer Help system.
Map To and the Structured Parse Rule Option Use this option when the incoming data is in flat files that have a fixed format with fields that have a fixed length. You must create a structured parse rule before you can use this option. The rule instructs Process Commander how to process the input file or input file record. To use this option, select Structured Parse Rule in the Map To field, and then specify the name of the appropriate rule by name in the Map To Key field. For information about creating structured parse rules, see the Application Developer Help system.
Data Mapping — Building Custom Map To and Map From Functions
5-23
Building Custom Map To and Map From Functions Even when the data types of a property at the source and a property at the target are compatible, the definitions of the data types can differ in length, number of characters allowed, range, special values allowed, and other ways. If the data mapping you need to express is not available from any of the default rules, you can use your own custom Java code to clean up or transform the data. For example, assume that you are mapping a double to a decimal. The incoming value carries three digits to the right of the decimal point, but the property you are mapping to can accept only two digits to the right of the decimal point. In this case, write a custom Map To function that rounds the value up before placing the property-value pair on the clipboard. To create a custom function, create a custom library and add the custom functions to it. Libraries are instances of Rule-Utility-Library and functions are instances of RuleUtility-Function. A library rule associates a library name with a RuleSet. Each function rule in a library must have a unique name. A custom function must meet the following requirements before it will appear in the selection box for a Map To or Map From field: ■
The custom library that the function belongs to must be named, literally, MapTo or MapFrom (as appropriate).
■
The method signature of the function must reflect a specific parameter list, as described in “Requirements for the Functions” on page 5-24.
■
The data type of the return parameter must match the data type of the property being mapped.
5-24
Integrating with External Systems — Data Mapping
In Figure 5-10, for example, the last three options displayed in the Map To selection box are custom Map To functions that return string values.
Figure 5-10. Custom Functions Listed in the Map From Field
Requirements for the Library Rule Before you can create a custom function, you must first create a custom library rule. A library rule associates a library name with a RuleSet name. The library rule must be named, literally, either MapFrom or MapTo, as appropriate: ■
For a custom function for a Map From data map, name the library “MapFrom.”
■
For a custom function for a Map To data map, name the library “MapTo.”
Create the library in a RuleSet that the service or connector can access. For additional information about creating a library rule, see the appropriate topics in the Application Developer Help system.
Requirements for the Functions When creating a custom function rule, designate whether it is a Map To or a Map From function by entering the appropriate name (MapTo or MapFrom) in the Library Name field. Additionally, the custom function must have a specific method signature, as described in the following sections.
Data Mapping — Building Custom Map To and Map From Functions
5-25
Parameters for Custom Map To Functions All Map To functions accept three method parameters of three specific data types, a fourth parameter that represents the data being mapped, and a Boolean return value to indicate that the function either succeeded or failed. For example, Figure 5-11 shows the Parameters tab for a function named MapTo.parseCsvDetail.
Figure 5-11. Custom Map To Function The first three parameters in the list in the Input Parameters section demonstrate the required method signature for a custom Map To function. The parameter names can be anything meaningful for your function rule, but the data type of the parameters must be those listed in Figure 5-12 and in the order listed.
5-26
Integrating with External Systems — Data Mapping
Parameter Data Type
Parameter Description
PublicAPI
Specifies the name of a Java object that provides access to the methods and objects in the Process Commander PublicAPI, including the thread context. For information about the Process Commander PublicAPI, see the Process Commander Javadocs.
ClipboardPage
Identifies the name of the clipboard page that holds the property that is the target for the data provided by the function. Typically it is the primary page of the service or connector activity.
String
Identifies a variable that holds the name of the property that is the target of the resulting data from this function. In data mapping, the value of this string (the name of the specific property) is passed from the Map To Key field.
Figure 5-12. Parameter List of Method Signature for Custom Map To Functions The fourth parameter for the function identifies a variable that holds the input value that is passed by the external system. Therefore, the third and fourth parameters represent the name-value pair for setting a clipboard property value: the third parameter represents the name, and the fourth parameter represents the value. In the data mapping form, Process Commander compares the data type of the value that is being mapped to the data type of the fourth parameter in the custom function to determine whether the custom function can be listed as an option in the Map To selection box. In the Output section, specify that the Return Type is “boolean” (with a lower-case “b”). You must program your custom function to return a value of true or false to inform Process Commander whether or not the value could be processed. If the function returns a value of “false,” the data mapping stops.
Data Mapping — Building Custom Map To and Map From Functions
5-27
Parameters for Custom Map From Functions All Map From functions accept three method parameters of three specific types, and return an output value that is sent to the external system. For example, Figure 5-13 shows the Parameters tab for a function named MapFrom.conditionalError.
Figure 5-13. Custom MapFrom Function
The list of parameters in the Input Parameters section demonstrates the required method signature for a custom MapFrom function. The names of the parameters can be any string that is meaningful for the function rule, but the Java data types of the parameters must be those listed in Figure 5-14 and in the order listed.
5-28
Integrating with External Systems — Data Mapping
Java Data Type
Purpose of the Parameter
PublicAPI
Specifies the name of a Java object that provides access to the methods and objects in the Process Commander PublicAPI, including the thread context. For information about the Process Commander PublicAPI, see the Process Commander Javadocs.
ClipboardPage
Identifies the name of the clipboard page that holds the property that is the source of the data provided to be processed by the function. Typically, it is the primary page of the service or connector activity.
String
Identifies the name of the property that holds the source of the data that will be processed by this custom function. When this function is used in a data mapping, the value of this string (the name of the specific property) is passed from the Map From Key field.
Figure 5-14. Parameter List of Method Signature for Custom Map From Functions The parameter that represents the return value is defined in the Output section. The third parameter in the list and the output parameter represent the name-value pair that is returned by the function: the third parameter represents the name, and the output parameter represents the value. In the data mapping form, Process Commander compares the data type of the value that is being mapped to the data type of the output parameter of the custom function to determine whether the custom function can be listed as an option in the Map From selection box.
Appendix A Contacting Pegasystems This appendix describes how to contact Pegasystems for the following: ■
Customer support
■
Education services
■
Documentation feedback
■
Office locations
For more information about our company and products, visit our Web site at www.pega.com.
A-2
Introduction — Contacting Pegasystems
Customer Support Pegasystems Global Services has a dedicated team of support engineers and product specialists ready to respond with support and consulting services. Pegasystems offers a choice of customer support programs to meet your business requirements. Global Services is committed to working in partnership with our customers to deliver 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: ■
Headquarters in Cambridge, Massachusetts
■
Chicago, Illinois
■
San Francisco, California
■
Reading, United Kingdom
■
Sydney, Australia
Pegasystems Certified Professional Program The Pegasystems Certified Professional Program is an important part of Education Services. The program provides certification examinations for System Architects on the aspects of PegaRULES Process Commander essential to implementing successful applications. For more information, go to www.pega.com.
Contacting Pegasystems — Documentation Feedback
A-3
Documentation Feedback Pegasystems strives to produce high-quality documentation. If you have comments or suggestions, please send us a fax or e-mail with the following information: ■
Document name, version number, and order number (located on the copyright page)
■
Page number
■
Brief description of the problem — for example, what instructions are inaccurate, or what information requires clarification
Send faxes to: 617-374-9620, attention Technical Communications. Send e-mail to:
[email protected].
Note: This e-mail address is only for documentation feedback. For a product or technical question, contact Pegasystems Global Services department.
A-4
Introduction — Contacting Pegasystems
Office Locations Pegasystems maintains offices in these locations: ■
Cambridge, Massachusetts (Headquarters)
■
Alpharetta, Georgia
■
Chicago, Illinois
■
Concord, New Hampshire
■
New York, New York
■
Irving, Texas
■
Toronto, Ontario, Canada
■
Melbourne, Australia
■
Sydney, Australia
■
Paris, France
■
Reading, United Kingdom
For more information, contact your Pegasystems Sales Representative or go to www.pega.com.
