building soap connectors pegarules process commander ... · sample soap connectors the sample soap...

Building SOAP Connectors

PegaRULES Process Commander Versions 5.1 and 5.2

© Copyright 2006 Pegasystems Inc., Cambridge, MA

All rights reserved.

This document and the software describe products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. This information should not be disclosed to third parties unless otherwise provided for by a contract or business agreement with Pegasystems. This document and the software are protected by federal copyright law, international laws, and/or applicable treaties.

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

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: Building SOAP Connectors Software Version: 5.1 and 5.2 Posting Date: December 2006

Contents

Introduction...............................................................................................................2 About the SOAP Connector Sample ..................................................................3 Summary of Steps for Building SOAP Connectors.............................................8

About SOAP Connectors .........................................................................................9

Rule and Data Objects for a SOAP Connector...................................................9 The Process .....................................................................................................12 Data Mapping ...................................................................................................13 Authentication...................................................................................................14 Session State ...................................................................................................15 Response Timeout ...........................................................................................15

Building SOAP Connectors ...................................................................................16

Plan the SOAP Connector ................................................................................16 Create Class and Property Rules .....................................................................19 Create the Connector and its Supporting Rules ...............................................19 (Optional) Edit the Connnector Rules...............................................................19 Link the Classes that Represent the External Data to the Work Object ...........20 (Optional) Generate or Write XML Parse or Stream Rules...............................20 Edit the Connector Activity and the Data Mappings .........................................21 Test the Activity and the Connector Rule .........................................................25 Add the Connector to the Workflow..................................................................26

Running the Sample...............................................................................................27

Web Service Application Setup ........................................................................27 Process Commander Setup .............................................................................28 Run the Sample................................................................................................30 Compensating Actions Demonstration .............................................................31 Connector Simulator Demonstration.................................................................34

Error Handling ........................................................................................................37

Using an Error Handler Flow ............................................................................37 Handling Exceptions in Connector Activities ....................................................38

Troubleshooting .....................................................................................................39

SOAP Message Monitoring ..............................................................................40 Common Error Messages.................................................................................41

Building SOAP Connectors

A PegaRULES Process Commander® (Process Commander) 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 specify how Process Commander invokes a service that is provided by an external system.

The SOAP integration interface in Process Commander supports interactions between your Process Commander applications and other systems through Web services. Process Commander supports SOAP communications through both services and connectors. These tools enable your Process Commander applications to communicate with external Web services and to act as a Web service.

Building SOAP Connectors describes how to create SOAP connectors that enable your Process Commander application to act as a client of an external Web service.

This document contains the following sections:

■ Introduction

■ About SOAP Connector

■ Building SOAP Connectors

■ Running the Sample

■ Error Handling

■ Troubleshooting

2 Building SOAP Connectors

Introduction Building SOAP Connectors is part of a package of materials that includes a sample external Web service and sample Process Commander flows that use a SOAP connector to retrieve data from the sample Web service. The document and sample are intended for Process Commander system architects who understand XML and are familiar with the SOAP and WSDL protocols. Additionally, to install the sample Web service, you must be able to deploy a WAR file in an application server or servlet container.

The SOAP connector example is provided in two zip files, located on the Integration Services pages of the Pega Developer Network:

■ A PegaSample-IntSvcs RuleSet, which contains the Integration Services examples, including the rules for the SOAP connector sample

■ CreditReportWebService.zip. This zip file contains the following items:

− The CreditService.war file.

− The CreditServices.wsdl file

− Java class and source files for the CreditService Web application and for the TestClient application that you use to verify the Web application was installed correctly.

− Batch files and shell scripts that run the TestClient application. Additionally, build scripts for both the TestClient and the CreditService applications, that you can use to experiment with.

It is recommended that you read the Process Commander book Integrating with External Systems v 4.2 before you continue reading this document. The book was shipped with your software and it is available on the Integration Services pages of the Pegasystems Support Network. Use these sample materials and implement the SOAP connector example on your Process Commander system as a training exercise before implementing your SOAP connectors.

All the materials listed above are available at the following location:

http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp


Building SOAP Connectors — 0BIntroduction 3

About the SOAP Connector Sample The SOAP connector sample illustrates how to configure a Process Commander flow to connect to an external SOAP Web service. The work objects managed by the sample flows are applications for lines of credit. The credit application flows use a SOAP connector to obtain a credit report for one of four sample customers from the sample external Web service.

The SOAP connector sample has three parts:

■ CreditService, the sample Web application that provides two SOAP Web services: CreateCreditReport and RollbackCreditReport.

■ CreateCreditReport and RollbackCreditReport, the Process Commander SOAP connectors. They invoke the service functions in the sample Web services.

■ Connector Samples Credit Application, the sample Process Commander application that provides the following two flows:

− ApplyForCredit uses the CreateCreditReport connector to obtain a credit report for one of four sample customers.

− ApplyForCreditCompensate is a modified version of ApplyForCredit that also uses the RollbackCreditReport connector to illustrate how to use compensating actions.

Sample Web Services Application – CreditServices The sample Web services application, CreditServices, was built with Apache Axis, an open source SOAP server and client that provides a Java platform for creating and deploying Web services applications. It provides two Web services: CreateCreditReport and RollbackCreditReport.

CreateCreditReport The CreateCreditReport service provides a credit report for four sample customers. This service requires the following input parameters in a request:

■ Name

■ Social Security Number

■ Subscriber ID

CreateCreditReport returns a credit report that includes employment history, credit history, a credit rating, and a report ID. It subtracts a point from the credit rating each time a credit report is requested for that customer.


RollbackCreditReport The RollbackCreditReport Web service corrects the customers’ calculated credit ratings by decrementing their request counters by one. This service requires the following input parameters in a request:

■ Reason

■ Report ID

■ Subscriber ID

RollBackCreditReport uses the Report ID to identify the customer whose credit rating should be modified and then decrements the request counter for that person, which causes the lost point to be added back to the score. The sample flow that illustrates compensating actions uses this Web service when an individual work object (application for credit) is canceled.

Sample SOAP Connectors The sample SOAP connectors were created with the Create Connector Rules Accelerator. The Accelerator processed the CreditServicesPort.wsdl file and generated the following items:

■ Class, property, and model rules that implement the data model in the credit report. After you upload the PegaSample-IntSvcs RuleSet, examine the classes and properties under the ConnectorSamples-Data-SOAP- base class.

■ Two connector rules: CreateCreditReport and RollbackCreditReport. The connector rules apply to the ConnectorSamples-Data-SOAP-CreditServices- class. The CreateCreditReport connector was configured to use a compensating action after the rule was generated.

■ Two connector activities: CreateCreditReport and RollbackCreditReport. The connector activities apply to the work object class ConnectorSamples-SampleWork-ApplyForCredit. The Property-Set steps and the entries on the Pages and Classes tab of these activities were edited after the activities were generated.

To demonstrate the Connector Simulator feature, the following items were created manually after the accelerator generated the connectors:

■ The simulator activities SimulateCreateCreditReport and SimulateRollbackCreditReport. They apply to the connector class rule ConnectorSamples-Data-SOAP-CreditServices- rather than the work object class rule.

■ An instance of Data-Admin-IS-Simulation named SimulatorsForConnectorSamples.


Connector Samples Credit Application The Connector Samples Credit Application creates and processes credit applications for four sample customers. It provides two flows: ApplyForCredit and ApplyForCreditCompensate.

In both flows, a credit report is requested for the customer whose credit application is being processed. A map value rule compares the value of the credit rating in the report to the dollar amount of credit requested and determines whether the application can be approved without underwriting input. If the map value rule returns the value “approved,” the work object is routed back to the originator (sample user). If the map value rule returns the value “underwriting,” the work object is routed to the underwriter user.

In the ApplyForCreditCompensate flow, the CreateCreditReport connector sets a compensating action: to call the activity that invokes the RollbackCreditReport connector. If either the sample user or the underwriter user cancels the application for credit work object, the Cancel action triggers the compensating action to run the RollbackCreditReport connector, and the customer’s credit rating is restored to what it was before the work object obtained the credit report.

The following list describes the highlights of the class structure in the Connector Samples Credit Application:

■ The work object class for both flows is ConnectorSamples-SampleWork-ApplyForCredit. This class has several properties, including an embedded page property of class ConnectorSamples-Data-SOAP-CreditReportType, which is one of the classes generated by the Connector Accelerator. This property links the credit report received from the CreateCreditReport web service to the ApplyForCredit work objects.

■ Flow, harness, section, router activity, connector activity, and decision map rules apply to the work object class.

■ The compensating action activities apply to the ConnectorSamples-SampleWork class, which is the class group (work pool) class.

After you upload the PegaSample-IntSvcs ruleset, examine the classes, properties, and other rules under the ConnectorSamples-SampleWork- class.


Figure 1 shows the Visio diagram of the ApplyForCredit flow.

Figure 1. ApplyForCredit Flow Diagram


Figure 2 shows the Visio diagram of ApplyForCreditCompensate.

Figure 2. ApplyForCreditCompensate Flow Diagram


Summary of Steps for Building SOAP Connectors The following list summarizes the general steps for building a SOAP connector in Process Commander:

Identify or create the work object class of the flow from which the connector will run.

1. Create an abstract class to serve as the container or base for the rules generated by the Create Connector Rules Accelerator.

2. Identify the URL of the WSDL file that represents the Web service.

3. Run the Create Connector Rules Accelerator.

4. Using an embedded page property, link the data structure of the generated connector rule to the work object.

5. Edit the generated connector activities, and, possibly, the connector rules.

6. Place an Integrator flow shape at the appropriate place in the flow and specify the generated connector activity.

Building SOAP Connectors — 1BAbout SOAP Connectors 9

About SOAP Connectors To create a SOAP connector, you run the Create Connector Rules Accelerator (Connector Accelerator) and identify the URL of the WSDL that describes the processing and methods of the SOAP service you want to connect to. Integrating With External Systems describes the Connector Accelerator and provides a procedure for using the Connector Accelerator to create SOAP connectors.

This section describes the SOAP connector itself, including its rules and classes, processing, data mapping, session state, authentication, and performance.

■ For information about handling exceptions, see “Error Handling” on page 37.

■ For information about compensating actions, see “Compensating Actions Demonstration” on page 31. See also the document Using Compensating Actions located on the Integration Services section of the Pega Developer’s Network.

■ For information about the connector simulator feature, see “Connector Simulator Demonstration” on page 34. See also the document Using the Connector Simulator located on the Integration Services section of the Pega Developer’s Network.

Rule and Data Objects for a SOAP Connector A SOAP connector requires the standard list of components as described in Integrating with External Systems, with no additional servers, database definitions, or other data objects.

Figure 3 provides a list of the rules and data objects that implement SOAP connectors.

Component Purpose

Base class rule (instance of Rule-Obj-Class that inherits from Data-)

Used by the Connector Accelerator as the parent class for the connector rule and any classes and properties necessary to implement the data model represented by the WSDL file that the connector connects to.

Class rules and properties (Rule-Obj-Class and Rule-Obj-Property)

Implement in Process Commander the data model of the external Web service. The Connector Accelerator generates the class and property rules that represent the data in the SOAP requests and responses.


Component Purpose

Connect rules (Rule-Connect-SOAP)

Maps request data to send to the external SOAP service, holds configuration and connection information for communicating with the external SOAP service, specifies how to handle errors, and maps response data back to the clipboard.

The Connector Accelerator generates the SOAP connector rules. They apply to one of the generated data class rules.

Connector activities (Rule-Obj-Activity)

Puts the request data where the connector rule is programmed to find it, invokes the connector rule, sets response data from the clipboard into work object properties, calls other activities that perform additional processing, and does what is necessary to complete the processing of the data received from the external SOAP service.

The Connector Accelerator generates the connector activities. They apply to a pre-existing work object class rule.

Typically, you edit the Property-Set steps and the pages and classes specified in the activity rules after they are generated.

Class rule and properties for the work object (Rule-Obj-Class) (Rule-Obj-Property)

The class rule and properties that represent the work object for which the connector contacts the external SOAP Web service. The class rule must exist before you run the Connector Accelerator because the connector activities apply to this class rule.

Model rules for data mapping (Rule-Obj-Model)

(Optional) Used when the SOAP operation style of the external SOAP service is document and the WSDL processed by the Connector Accelerator contains a schema description of the data that is processed.

The connector rule uses the model rule to determine how to map an object’s properties to or from a clipboard page.

The Connector Accelerator generates the model rules.


Component Purpose

XML stream rules for data mapping (Rule-Obj-XML)

(Optional) Used when the SOAP operation style of the external SOAP service is RPC and the request message includes a string argument with XML embedded in it.

In this case, the connector activity can use an XML stream rule to format clipboard data appropriately and put the value in a string property that the connector rule uses to create the request message.

Use the Import XSD/DTD Accelerator to generate XML stream and parse rules.

XML parse rules for data mapping

(Rule-Parse-XML)

(Optional) Used when the SOAP operation style of the external SOAP service is RPC and the response message includes a string argument with XML embedded in it.

In this case, the connector rule maps the incoming value to a string property. The connector activity then uses an XML parse rule to extract the data from the string property and write the data to the clipboard.

Use the Import XSD/DTD Accelerator to generate XML stream and parse rules.

Properties for authentication (Rule-Obj-Property)

(Optional) Used when the target Web service requires HTTP Basic Authentication. You specify string properties that apply to the connector rule class whose values represent a user name and password.

The Connector Accelerator does not generate these properties. You must create the properties after the rules are generated and then edit the connector rules.

Properties for error handling (Rule-Obj-Property)

(Optional) Used to hold status information generated by Process Commander when the call to the external Web service is complete. You can use the standard properties pyStatusValue and pyStatusMessage.

For information about using these properties, see “Error Handling” on page 37.

Figure 3. Summary of Components Required for SOAP Connector


The Process Typically, a connector is triggered from within a flow rule. At some point in the flow, the operator assigned the work object triggers the Integrator task (flow shape) that represents the connector. The connector collects data values that are required as input to the external Web service, wraps them in an XML document envelope (SOAP envelope) that contains the name of the requested service, and posts the envelope to the end point URL of the external service.

Figure 4 illustrates the architecture of the SOAP connector.

Process Commander

Clipboard

Page

Page

Connector Activity

Rule-Connect-SOAP.Invoke

Integrator680Integrator Task

Rule-Connect-SOAP

request

External SOAP Web Service

response

Figure 4. Architecture of a SOAP Service

The following describes how a SOAP connector works:

1. A work item in a flow reaches an Integrator task.

2. The Integrator task invokes a connector activity (activity type is Connect).

3. The connector activity sets parameter and property values to parameter and clipboard pages, as necessary, and then uses the Connect-SOAP activity method to identify a SOAP connector rule and call the standard Invoke activity. (Note that your activity does not call the Invoke activity directly – the Connect-SOAP method calls it in the background.)

4. The Invoke activity calls the SOAP connector rule.


5. The SOAP connector marshals the output values from Process Commander properties according to its Map From data mapping settings. The connector then returns control to the Invoke activity.

6. The Invoke activity evaluates the clipboard page, generates a SOAP request, and sends it to the end point URL of the external SOAP service identified in the connector rule.

7. The external SOAP service processes the SOAP request and returns a SOAP response.

8. The Invoke activity receives the SOAP response, writes it to the clipboard, then calls the SOAP connector rule.

Note: If the external Web service fails for any reason, the Invoke activity returns an exception. Otherwise, it returns a status message.

9. The SOAP connector parses the SOAP response, writes parameter values to the Process Commander properties on the clipboard according to its data mapping settings, and then returns control to the Invoke activity.

10. The Invoke activity returns control to the connector activity.

11. The connector activity evaluates the clipboard values and acts upon them. Typically, the activity sets data from the SOAP response into the work object.

12. The flow resumes, perhaps with an assignment in which the data gathered from the web service is evaluated by either a user or a decision rule.

Data Mapping Data mapping defines the relationships between field-value pairs in external systems and property-value pairs on Process Commander clipboard pages. Before you continue reading this section, read Chapter 5 (Data Mapping) in Integrating with External Systems.

A SOAP connector rule form has two tabs for mapping data:

■ Request — Use this tab to specify how the connector rule maps arguments for the SOAP request messages from properties on the clipboard (Map From).

■ Response — Use this tab to specify how the connector rule maps the reply message from the external SOAP service to the clipboard (Map To).

To determine how to configure data mapping for a SOAP connector rule, assess the data that is to be transmitted in the SOAP messages. Does the message contain parameters


with simple string or numeric values? Does the message contain a string parameter with XML code embedded in its value? Does the message contain an XML object? Does the message contain any SOAP headers?

Your assessment reveals which of the following data mapping options to use for each argument in the message.

■ Simple argument-property mapping – used when the message contains scalar arguments that match Process Commander properties (or activity parameters), and the data in an argument is to be treated as a single value.

■ XML parse and stream rules – used when:

− The message body contains scalar arguments, the data in the argument is XML, and the SOAP operation style is RPC encoded. In this case, the data typically provides values for a complex Process Commander property.

− The message contains one or more SOAP headers. The values of SOAP headers are W3C element objects (instances of org.w3c.dom.Element).

■ Model rules – used when the message contains an XML object, which is also a complex type. Typically, but not always, it means the SOAP operation style is document literal. This type of data mapping is automatically configured by the Connector Accelerator when appropriate and cannot be configured manually.

For information about using XML parse and stream rules, and model rules that are used to define schema, see the document Data Mapping XML posted on the Integration Services pages of the Pega Developer Network. For information about the data types for simple argument-property mapping, see the Application Developer Help system.

Authentication If the Web service that a SOAP connector communicates with requires that authentication credentials be sent via HTTP Basic Authentication, configure the authentication settings after the accelerator generates the connector rule.

To enable authentication:

1. For the connector’s Applies To class, create properties that represent user name and password. For example, if you were able to enable authentication for the sample, you would create properties for user name and property for the ConnectorSamples-Data-SOAP-CreditServices- class rule.

2. In the connector rule’s Service tab, under Authentication, select the Use Authentication check box.

3. In the Username Property field, select the property that represents user name.


4. In the Password Property field, select the property that represents password. Note that this property should not be of type Password. Figure 5 shows an example.

Figure 5. Authentication Settings in Rule-Connect-SOAP

5. In the connector activity, include an activity step that sets values for these properties before it calls the connector rule. Figure 6 shows an example.

Figure 6. Setting User Credentials in the Connector Activity

Session State

Most public Web services do not offer callers the ability to maintain stateful session data. However, if the Web service provider uses HTTP token passing to maintain stateful session data between service requests, you can configure the connect rule to run in a stateful session and maintain state between connector interactions.

Select the Maintain Session option and then provide a value in the Connection ID field. The value in this field is an arbitrary sting used to identify an HTTP connection. Assign a string that relates to the purpose of the connector or the set of connectors. Then use the same Connection ID value in all related connector rules so they all use the same HTTP connection and can share session state information.

Response Timeout The Response Timeout field is located on the Service tab of the connector rule. Use it to specify a timeout interval in milliseconds for Process Commander to use when waiting for a response from the external Web service. If the external service does not return a response in that amount of time, the Invoke activity returns the exception Resource Unavailable Exception.


Building SOAP Connectors This section describes how to create SOAP connectors using the SOAP connector example to illustrate each step. This document does not describe every field on every form. For help or information about a field that is not defined in this document, see the Application Developer Help system.

To create a SOAP connector, complete the following tasks:

■ Plan the SOAP Connector

■ Create Class and Property Rules

■ Create the Connector and its Supporting Rules

■ (Optional) Edit the Connnector Rules

■ Link the Classes that Represent the External Data to the Work Object

■ (Optional) Generate or Write XML Parse or Stream Rules

■ Edit the Connector Activity

■ Test the Activity and the Connector Rule

■ Add the Connector to the Workflow

These tasks are described in the following sections.

Plan the SOAP Connector During the planning stage, you plan the flow and determine the data that you need from the external system. In the sample, the flow retrieves a credit report so a decision can be made about whether to grant or deny a request for credit. For your flow, how do you need to use the data? At what point in the flow do you need the information provided by the external system?

What are the input parameters required by the Web service? Identify the work object properties that will provide the values for those input parameters. For example, the CreateCreditReport service needs a Social Security number, a subscriber ID, and a reason code. It was determined that only the value of the Social Security number parameter should be provided by the work object and that the other parameters could be hard-coded in the connector activity.

How does the Web service handle complex data types? Must the request contain XML embedded in the value of a string argument? Does the response contain XML embedded in the value of a string argument? If so, your connector rules or activities need to use XML parse and/or stream rules. Additionally, if any SOAP headers are required, your

Building SOAP Connectors — 2BBuilding SOAP Connectors 17

connector rules or activity need to use XML parse and/or stream rules. These data types are typically defined in the WSDL of the service, which means you can use the Import XSD/DTD Accelerator to generate XML parse and stream rules for you after you run the Connector Accelerator. Start the Import XSD/DTD Accelerator, select the XSD option, but then specify the URL of the WSDL.

Determine which class rules to identify to the Connector Accelerator for the generated items. Identify the following:

■ An abstract class rule, typically one that inherits from Data-, for the accelerator to use as the container or base for the generated items with the sole exception of the connector activities.

Note: The accelerators limit class names to 56 characters so the name of the base class rule must be short, especially if the names of the data types described in the WSDL you will connect to are long. If the generated class names are longer than 64 characters, the Connector Accelerator truncates them to fit under the limit and then it can be difficult to determine which elements they represent.

■ A concrete class rule for the connector activities. If you plan to call the connector from a flow, this class rule should inherit from the Work- class rule so the connector activities can be called directly from an integrator task.

Typically, you select the class of the work object whose flow you will call the connector from.

What happens if the Web service is offline and the connector rule cannot communicate with it? You can create (or identify) an error handler flow or plan how to configure the connector activity to handle exceptions. For more information, see “Using an Error Handler Flow” on page 37. Choose names for the individual components in the SOAP connector, and use Figure 7 to keep track of the names. For reference purposes, the middle column of Figure 7 lists the component names in the SOAP connector example. Write the names of the components you create in the remaining column. Choose meaningful, explanatory names.

Component SOAP Connector Example Your Connector Project

URL of WSDL to connect to

http://localhost:8080/CreditService/ services/CreditServicesPort?WSDL

RuleSet PegaSample-IntSvcs

RuleSet version


Component SOAP Connector Example Your Connector Project

Abstract class rule to be the parent class

ConnectSamples-Data-SOAP-

Generated connector rules

CreateCreditReport

RollbackCreditReport

Work object class rule for the connector activities

ConnectSamples-SampleWork-ApplyForCredit

Generated connector activities

CreateCreditReport

CollbackCreditReport

Work object properties to use in the SOAP request

SocialSecurityNumber (single value String property)

Property that links to the work object the classes that represent the external data

CreditReport (Page property of class ConnectSamples-Data-SOAP-CreditReportType)

Model rules ConnectSamples-Data-SOAP-CreateCreditReport.pyDefault

ConnectSamples-Data-SOAP-CreateCreditReportResponse.pyDefault

Error handler flow Work-.ConnectorProblems

XML parse rules None

XML stream rules None

Figure 7. Component Names for a SOAP Connector


Create Class and Property Rules During the planning stage, you determined the class rules to identify to the Connector Accelerator. If the class rules do not yet exist, create them.

The input for the requests to the Web service comes from property values. If you can, examine the WSDL of the Web service to determine what the input parameters are. Then examine the work object class to see if there are properties that can represent the input parameters. Create any new properties that are necessary.

Note that if you cannot identify the input parameters before you run the Connector Accelerator, you can also create the necessary properties after the accelerator generates the connector rules. Then you edit the data mapping settings in the connector rules to use those properties.

Create the Connector and its Supporting Rules Use the Connector Accelerator to create the connector. Follow the instructions for creating SOAP connectors as described in Using the Connector Accelerator, which is available on the PDN. Note the following:

■ The Connector Accelerator can create data mappings to and from scalar properties of top-level or embedded page properties. It cannot create data mappings for list properties. For list properties, accept the default data mapping settings. Then edit them later in the generated activity.

■ To map values for complex parameters, click the plus sign to expand it. Then select values for each item you want to map.

■ The results form displays a list of all the generated items and the ID of the Interface Generator record that holds this list. The ID value is written into the Usage field of each generated item.

The Connector Accelerator generates connectors, connector activities, and the class and property rules necessary to represent the data structure described in the WSDL you identified.

(Optional) Edit the Connnector Rules Although the Connector Accelerator automates much of the process of creating connectors, it is likely that you will need to edit at least some of the default settings. You must edit the generated connector rules if you want to configure any of the following:

■ Authentication — for information, see “Authentication” on page 14.

■ Stateful session — for information, see “Session State” on page 15.


■ Response timeout — for information, see “Response Timeout” on page 15.

■ Error handler flow — by default, the value of the Error Handler Flow field is set to a standard flow named ConnectorProblems. If you create your own error handler flow, edit the value in this field. See “Using an Error Handler Flow” on page 37.

■ Compensating actions — for information, see “Compensating Actions Demonstration” on page 31.

Link the Classes that Represent the External Data to the Work Object After the Connector Accelerator creates the connector and the data structure of the external Web service, link that data structure to the work object with a property of mode page or page list.

For example, the ConnectorSamples-SampleWork-ApplyForCredit class (work object) has a property named CreditReport. CreditReport is a page property of class ConnectorSamples-Data-SOAP-CreditReportType. The property was created after the connector was generated.

Addtionally, two properties were created in the work object class to hold the values of confirmation messages returned by the external Web services. They are string properties named ServiceStatusMessage and RollbackServiceStatusMessage.

(Optional) Generate or Write XML Parse or Stream Rules As mentioned in “Data Mapping” on page 13, XML parse rules describe how to interpret incoming XML data held in string arguments, and XML stream rules describe how to assemble outgoing XML documents for responses.

■ If the SOAP message style of the service you are connecting to is RPC-encoded, and any of the scalar arguments in the SOAP messages contain embedded XML, you need to create XML parse and/or stream rules.

■ No matter what the SOAP message style, if the message contains SOAP headers, you need XML parse and/or stream rules to generate or process the value of the SOAP header.

It is best practice to use the Import XSD/DTD Accelerator to generate your XML parse and stream rules rather than to create them manually. In the case where you need rules to provide or process values for SOAP headers, examine the WSDL of the web service to determine whether the data types of the SOAP headers are defined in the WSDL. If they are not, obtain an XML Schema Descriptor (XSD) file or Document Type Definition (DTD) file that describes the schema in the SOAP messages. After you run the


accelerator, you can use the XML parse or stream rules in either the connector rule or the connector activity to map the data in the messages.

When you run the Import XSD/DTD Accelerator, note the following:

■ In the Enter Rule Information form, specify the same base class as you did for when you ran the Connector Accelerator.

■ Select the XSD option, even if you are importing a WSDL file.

■ In the Select Rule Types for, select only the XML Parse Rules and XML Stream Rules options.

For more information about XML parse and stream rules, see the following sources:

■ Data Mapping XML, posted on the Integration Services pages of the Pega Developer Network

■ Chapter 5, “Data Mapping,” in Integrating with External Systems

■ Application Developer Help system

Edit the Connector Activity and the Data Mappings A connector activity has its Type set to Connect. The generated connector activities have the following kinds of steps:

■ A step that creates a clipboard page named DataPage for the class rule that the connector rule applies to. This page becomes the primary page for the connector.

■ A step that sets work object properties or activity parameter values into the DataPage properties; these represent the input required by the Web service. The DataPage properties are specified as the Map From properties or activity parameters in the connector rule.

■ A step that calls the connector rule on the DataPage page. This step uses the Connect-SOAP activity method, which takes one required and two optional parameters:

− (Required) Service name is the second key to the connector rule, and uses the name of the Web service the connector connects to. The first key is the class identified by the DataPage page.

− (Optional) RunInParallel is a Boolean property. By default, an invoked connector retains control of the requestor session until it returns a response to the flow. When RunInParallel is selected, the connector returns control of the session to the flow immediately after the request. If there is another connector in the flow with a subsequent task to accomplish, that next connector can send its request before the first connector returns a response.


− (Optional) EndPointURL is the URL of the Web service to connect to. When provided, it overrides the URL specified in the connector rule.

■ A step that uses the Property-Set activity method to set data from the Map To properties specified in the connector rule into activity parameters or work object properties.

■ A step that uses the Show-Page method to display the clipboard page in your browser window. By default, this step is disabled. To use it, remove the comments.

■ A step that uses the Page-Remove method to delete the page from the clipboard.

If you did not create or identify work object properties to provide values for input and output parameters, or, if data needs to be mapped to or from XML parse or stream rules, you now create additional properties and edit the data mapping settings in the connector rules and the Property-Set steps in the connector activities.

For example, compare the activities named CreateCreditReportASGENERATED and CreateCreditReport activity. As implied by its name, CreateCreditReportASGENERATED is the original connector activity generated by the Connector Accelerator for the sample. The default data mapping settings – which map input parameters from and output parameters to activity parameters – were accepted because the appropriate work object properties did not exist yet. After the work object properties were created, the CreateCreditReport activity was modified to manage the data mapping properly.

CreateCreditReportASGENERATED CreateCreditReportASGENERATED defines one page on the Pages and Classes tab:

■ Name: DataPage.

■ Class: ConnectorSamples-Data-SOAP-CreditServices- (the connector’s Applies To class).

The Property-Set step that sets the values for the request sets values for the activity parameters described in Figure 8:


PropertiesName PropertiesValue

.CreateCreditReport_CreateCreditReport. SubscriberID

param. CreateCreditReport_CreateCreditReport_SubscriberID

.CreateCreditReport_CreateCreditReport. ApplicantSSN

param. CreateCreditReport_CreateCreditReport_ApplicantSSN

.CreateCreditReport_CreateCreditReport. Reason

param. CreateCreditReport_CreateCreditReport_Reason

Figure 8. Parameters Set for the Request by the CreateCreditReportASGENERATED Activity

The Property-Set step that sets the values from the SOAP response sets the activity parameter value specified in Figure 9:

PropertiesName PropertiesValue

param. CreateCreditReport_CreateCreditReportResponse _StatusMessage

DataPage. CreateCreditReport_CreateCreditReportResponse. StatusMessage

Figure 9. Parameters Set from the Response by the CreateCreditReportASGENERATED Activity

Additionally, the Parameters tab holds definitions for all the activity parameters used in the Property-Set steps as shown in Figure 10.

Figure 10. Activity Parameters in CreateCreditReportASGENERATED


CreateCreditReport In the modified activity, CreateCreditReport, properties from the Applies To class of the connector rule are used instead of the activity parameters. The following additional page definitions were created on the Pages and Classes tab:

■ DataPage.CreateCreditReport_CreateCreditReport, for the request data

■ DataPage.CreateCreditReport_CreateCreditReportResponse, for the response data

The parameter definitions were removed from the Parameters tab because they are not used.

The Property-Set step that sets values for the request uses the DataPage.CreateCreditReport_CreateCreditReport page as the Step Page, as shown in Figure 11.

Figure 11. Properties Set for Request in the CreateCreditReport Activity

The Property-Set step that sets values from the response uses the DataPage.CreateCreditReport_CreateCreditReportResponse page as the Step Page, as shown in Figure 12.

Figure 12. Property Set from Response in the CreateCreditReport Activity


Test the Activity and the Connector Rule To verify that the connector rule can reach the SOAP service, open the connector rule and click the Test Connectivity button. You should see a message like this one:

Figure 13. Results from Test Connectivity Button

Next, examine and test the connector activity. If it does not set data into the properties for the SOAP request, the connector will fail. If the activity does not process the data from the response correctly, the work object might stall because a routing decision cannot be made without that data.

To run the activity manually (that is, by clicking the Run button in the activity form), you must provide values for the connector’s input properties. Use the Property-Set activity method to set values for the SOAP request, and then run the activity. Alternately, you can crate a primary page for the activity in the Run window.

For example, to test the CreateCreditReport activity manually, you would provide a static value for the ApplicantSSN property as shown in Figure 14.

Figure 14. Testing the Connector Activity

Run the activity and examine the clipboard page. You can also remove the comment from the Show-Page activity step and examine that data. Verify that you see the pages and values that you expected. Then configure the Property-Set step to obtain the values programmatically from the pyWorkPage. To continue with the preceding example, you would change the value of ApplicantSSN back to Primary.SocialSecurityNumber.


If the Web service is offline and you cannot test against it, consider using a connector simulator. This feature enables you to mimic the behavior of the connector by providing static test data to the flow, enabling you to continue to test and program the flow.

To see a working implementation of the connector simulator feature, install the sample and see “Connector Simulator Demonstration” on page 34. For more information about connector simulators, see the document Using Connector Simulators posted on the Integration Services pages of the Pega Developer Network.

Add the Connector to the Workflow To use the connector rule in your flow, insert an Integrator task at the appropriate position in the flow. Then, specify the name of the connector activity. Finish creating the flow and then create a work object to test it. For information about troubleshooting, see “Troubleshooting” on page 39.

To run the sample SOAP connector, see “Running the Sample” on page 27

Building SOAP Connectors — 3BRunning the Sample 27

Running the Sample This section describes how to set up and run the SOAP connector sample. Complete the configuration and setup tasks described in this section for both Process Commander and the Java application that provides the SOAP Web services.

Web Service Application Setup To set up the sample Web services application, you install or locate an installation of an application server or servlet container, download the sample Web services application, and deploy the creditservice.war file.

Download the Sample Web Application

1. Create a directory named CreditServiceSample.

2. Download the CreditReportWebService.zip file from the Integration Services section of the Pega Developers Network:


3. Unzip the file into the CreditServiceSample directory.

Deploy the creditservice.war File The following instructions explain how to deploy the creditservice.war file in a Tomcat servlet container. If you want to use WebSphere or WebLogic, follow the instructions provided by that vendor to deploy the creditservice.war file located in the CreditServiceSample directory.

1. If you do not have a Tomcat installation, go to the Apache Web site and download a copy of the Apache Tomcat servlet containter software:

http://jakarta.apache.org/tomcat/

To install it, follow the installation instructions provided by Apache.

2. Copy the CreditServiceSample\creditservice.war file to the webapps directory in Tomcat.

3. Stop and start Tomcat. When Tomcat starts, it finds the creditservice.war file and deploys it.


http://jakarta.apache.org/tomcat/


4. Verify that the webapps\creditservice directory exists. Then delete the CreditService.war file from the webapps directory.

Run the TestClient Application to Test the Installation After deploying the creditservice.war file, run the TestClient application to verify that the Credit Service application is running.

1. The TestClient application is a small Java application. Verify that you have the Java Software Developer Kit (SDK) version 1.4.2 or higher installed on the system you plan to run the TestClient application from.

2. In the CreditServiceSample directory, find and open the RunTestClient batch file or shell script (as appropriate) in a text editor.

3. Edit the set AXIS_LIB statement to point at the creditservice\WEB-INF\lib directory in the Tomcat servlet. (The creditservice.war contains the Axis application, which it needs in order to deploy correctly.)

4. Save the file.

5. Run the RunTestClient batch file or shell script to verify that the Web service is running. When it is successful, a message like the following appears:

D:\CreditServiceSample>java TestClient -url

http://localhost:8080/creditservice/services/CreditServicesPort

create 1001 001-01-0001 testing

Successfully created credit report

Credit Score: 448

Process Commander Setup To set up Process Commander to run the sample, you import the PegaSample-IntSvcs ruleset and change the end point URL in the connector rules to point at the location of the Web services you installed on your Tomcat servlet container.

Import the PegaSample-IntSvcs RuleSet Complete the following steps:

1. Download the PegaSample-IntSvcs RuleSet that matches your version of Process Commander from the Integration Services section of the Pegasystems Support Network:


http://localhost:8080/creditservice/services/CreditServicesPort



2. From the menu, choose File > Import Archive.

3. In the Select Import Mode field, choose Local Zip File.

4. Click the Browse button next to the File Name field to choose the file.

5. Click Upload File. The wizard uploads the file to the Process Commander ServiceDirectory directory and displays the message File Uploaded Successfully.

6. In the Select Import Mode field, choose Zip File on Server.

7. From the list of files, choose the one you just uploaded. The wizard examines the file and displays several options.

8. Click Import. Process Commander processes the zip file. When it is finished, it displays a status message.

9. Log out of Process Commander and log back in as the sample user:

− User ID: [email protected]

− Password: rules.

Edit the End Point URL in the Connector Rules Complete the steps in this procedure to configure the connector rules to connect to the Credit Service web application.

1. From the Rule by Type explorer, select Integration-Connectors > Connect SOAP.

2. Open the rule named CreateCreditReport.

3. Scroll to the HTTP Connection section. Edit the value in the Service End Point URL field so it uses the correct server name and port number on your installation.

4. Save the rule.

5. Click the Test Connectivity button. If you see anything other than a success message, the URL is incorrect. Make the necessary modifications and try again.

6. Return to the list of SOAP connectors and open the RollbackCreditReport connector rule.

7. Repeat steps 3 through 5.

Do not try to run the sample until both connectors can communicate with the Web services, unless you decide that using the connector simulator will suffice.


Run the Sample To run the sample, create a work object:

1. From the menu, select Run > Process > Application for Credit..

2. In the New form, under Customer Information, select a customer name and matching Social Security number. Figure 15 lists the customer information:

Customer name Social Security Number

Rebecca Smith 001-01-0001

William Jones 002-02-0002

Robert Black 003-03-0003

Katrina White 004-02-0004

Figure 15. Sample Customers and Their Social Security Numbers

3. Select a credit limit in the Credit Amount field and then click Create.

The flow calls the CreateCreditReport Web service, which responds with a credit report. The map value rule DetermineApproval evaluates the credit rating of the customer you selected and the amount of credit you selected. Based on the rule’s decision, the work object moves to either the Confirm assignment or to the Underwriting assignment.

Both the Confirm and Underwriting assignment forms display the information from the credit report. For example, Figure 16 shows Rebecca Smith’s credit report displayed in the Confirm assignment form.

Figure 16. A Credit Report Displayed in the Confirm Assignment Form


Compensating Actions Demonstration A compensating action associates an activity (and, optionally, some data) with a work object. The action is triggered, which means the activity runs, when the Work-.compensate activity is invoked by the flow.

The flow ApplyForCreditCompensate illustrates how to use compensating actions.

1. Open the CreateCreditReport connector rule, select the Response tab, and examine the values specified in the Compensating Action section, as shown in Figure 17.

Figure 17. Compensating Action Configuration in CreateCreditReport Connector

When the CreateCreditReport connector receives a response, it stores in the pyCompensatingContainer page property on pyWorkPage a reference to the activity RollbackCreditReport. It also stores the report ID of the credit report in the activity parameter named ActionDataReportID.

2. Open and examine the activity ConnectSamples-SampleWork-ApplyForCredit.RollbackCreditReport. This activity sets the value of the ActionDataReportID parameter into the ReportID field and then calls the RollbackCreditReport connector rule.


Figure 18. The RollbackCreditReport Activity

After the connector returns a response, RollbackCreditReport maps the status message from the Web service to a property on the pyWorkPage.

3. On the Process Work tab, select Application for Credit Compensate from the New selection list.

4. Select a customer name, the matching Social Security number, and a credit amount, and then click submit.

5. When the appropriate Pending form appears, open the clipboard, expand pyWorkPage, and look for the pyCompensatingContainer page property, as show in Figure 19.

Figure 19. pyCompensatingContainer Page

Figure 20 shows the details of the compensating action on the pyChildNodes(1) page.


Figure 20. Compensating Action Details

6. Cancel the assignment.

When you select cancel, the following processing occurs:

■ The CACompensate Utility shape invokes the Work-.CACompensate activity.

■ The CACompensate activity runs the compensate utility function.

■ The compensate utility function invokes the compensating actions set on the pyCompensatingContainer page.

■ Because the compensating action on the page is to run the ConnectSamples-SampleWork-ApplyForCredit.RollbackCreditReport activity, the activity is called.

■ The RollbackCreditReport activity calls the RollbackCreditReport connector, which communicates with the RollbackCreditReport Web service.

■ The RollbackCreditReport Web service corrects the customer’s credit rating and returns a confirmation message.

Figure 21 shows the history of a work object that was canceled.


Figure 21. History of a Canceled Work Object from the ApplyForCreditCompensate Flow

For more information about the compensating actions feature, see the document Working with Compensating Actions located on the Integration Services section of the Pega Developers Network.

Connector Simulator Demonstration The sample also includes simulation activities and a Connector Simulator data instance. The simulator activities are SimulateCreateCreditReport and SimulateRollbackCreditReport. They apply to the connector rule class.

Complete the following steps:

1. Open and examine the activity ConnectSamples-Data-SOAP-CreditServices.SimulateCreateCreditReport. This activity has one step that sets values for a credit report.

2. On the Integration page, under Resources, select Connect Simulators.

3. Open SimulatorsForConnectorSamples.

4. Verify that the Enabled check box next to the SimulateCreditReport and SimulateRollback activities are selected as shown in Figure 22. If they are not, select them and then click Save.


Figure 22. Example Connector Simulator

5. Click Enable Simulation.

6. Examine the clipboard. Verify that the pyISSimulation page appears as shown in Figure 23.

Figure 23. pyISSimulation Page

7. Select one of the child pyConnector pages and verify that the value of the pyEnabled property on that page is set to True as shown in Figure 24.

Figure 24. pyConnectors(1), a Child Page of pyISSimulation

8. Create a work object.

9. Examine the data that you see displayed in the Confirm or Underwriting assignment (Figure 25 shows an example). The SimulateCreateCreditReport activity set a value


for credit rating so the DetermineApproval map value rule was able to make a decision and route the work object to the appropriate assignment.

Figure 25. Simulated Data for a Credit Report

Building SOAP Connectors — 4BError Handling 37

Error Handling Because connectors request information from external systems, external factors can cause a connector to fail to get the data it needs – the external system could be offline, for example.

The standard Invoke activity returns status and exception information to the clipboard when the call to the external Web service completes. The activity returns both a status code such as “Success” or “Fail” and a description of the problem such as “SOAP service failed” with the message from the external service. A Fail status causes an exception.

Configure your connectors to handle exceptions and errors in one of the following ways:

■ Use an error handler flow to route work objects that cannot continue because a connector was unsuccessful to a designated workbasket.

■ Configure the connector activity to manage exceptions returned by the standard Invoke activity.

Note: You can use one, but not both of these methods. The error handler flow feature is not triggered if the connector activity has a transition step that catches exceptions.

Using an Error Handler Flow The error handler flow feature enables you to route to a system administrator a work object that cannot continue in its current flow because a connector was unsuccessful. The system administrator can then determine the source of the problem, correct the problem, and restart the original flow for the work object.

This feature is enabled by default. When you create a new connector, the standard flow named ConnectionProblem is specified in the Error Handler Flow field. You can use the ConnectionProblem flow as it is, save it into your application RuleSet and modify it, or create your own error handler flow and specify it in the connector rule. Whenever the Invoke activity returns a status code of Fail, the work object is routed to the flow you specified in that field.

When you do not use an error handler flow, you must configure your connector activity to manage exceptions. If the connector activity does not handle the exception, the work object is then routed to a standard flow named FlowProblems.


Handling Exceptions in Connector Activities To manage exceptions with the connector activities, you specify the names of properties to hold status messages returned by the Invoke activity and configure the connector activity to trap exceptions and evaluate the values of those properties.

When the Status Value Property and Status Message Property fields have values, the Invoke activity writes status values and status messages to those properties. When you generate connector rules with the Connector Accelerator, the fields are set to the standard properties pyStatusValue and pyStatusMessage by default. When you create connector rules without using the Connector Accelerator, you must select properties in those fields if you want to use the messages that are returned.

Figure 26 shows an example of a status value returned by the Invoke activity and written to the pyStatusValue property on the connector’s primary page.

Figure 26. pyStatusValue Property on the Connector Page

To manage exceptions in the connector activity, specify the pyStatusValue and pyStatusMessage properties in the error handling property fields and then configure the connector activity to handle exceptions. In the step that follows the Connect-SOAP step, that is, the post-processing step, enable the transition step and enter a label in the Later Step Label field. Create an exception handling step and label it with the value you entered in the Later Step Label field in the transition step. Use the values in the pyStatusValue and pyStatusMessage properties to provide information about the cause of the exception.

Building SOAP Connectors — 5BTroubleshooting 39

Troubleshooting If the SOAP connector cannot successfully interact with the external SOAP service, the problem typically falls into one of the following categories:

■ The end point URL is incorrect. Start by verifying that the connector can communicate with the Web service. Open the connector rule and examine the value in the End Point URL field. Click the Test Connectivity button.

■ The activity you wrote does not map the data for the request or from the response properly. See “Edit the Connector Activity” on page 21.

■ You are using clipboard pages improperly. Examine the following fields and tabs to verify that the page names (and their class rules) are configured correctly:

− Page Name and Class Name fields on the XML Page tab of the connector rule

− Page Name and Class Name fields on the Pages and Classes tab of the connector activity

− Page names in activity steps that use the Page-New and Property-Set methods

■ The Web service is not coded or configured properly. Perhaps the problem is with the SOAP Web service. Ask yourself the following questions:

− Are there problems with authenticating the client/service session? See “Authentication” on page 14.

− Are transient issues preventing the client from running? Confirm that the network connection between client and server is up.

− Does the Web service send the data you expect in the messages? Is the SOAP connector sending the data the Web service expects in the messages?

The following is a list of tools and practices that you can use for troubleshooting SOAP connector rules:

■ Run a local test on the connector activity. See “Test the Activity and the Connector Rule” on page 25.

■ Use the Tracer tool. For information about this tool, see the document Testing Services and Connectors, available on the PDN.

■ Run a SOAP listener or SOAP monitoring application to study the connector’s request and the Web service’s response. For example, use the tcpmon utility (TCP/IP monitor) from Apache Axis or another SOAP viewer. See “SOAP Message Monitoring” on page 40.

■ Configure logging level settings so Process Commander generates status and error messages about the SOAP connector rule. For information, read the section about the log files in PegaRULES Process Commander Administration and Security. Then configure loggers for the following:


− The activity Rule-Connect-SOAP.Invoke

− The com.pega.pegarules.services.ServiceHelper Java class, especially if you are having difficulty with data mapping for complex data types.

Start by setting the logging level to “info.” If you do not see enough information, increase the level to “debug.”

SOAP Message Monitoring While you debug a Web service and SOAP connector rule, you may need to examine the contents of the SOAP messages. For example, to verify that an XML parse or stream rule is configured correctly or that the SOAP Web service is constructing its requests correctly, you need the SOAP message to make your determination.

Several SOAP viewing tools are available. When these tools run on your PC, your PC serves as an intermediary SOAP node — a listener — between the SOAP sender and SOAP receiver, capturing the SOAP requests and responses.

Apache Axis tcpmon Utility Apache Axis provides a free SOAP monitoring utility named tcpmon. Use it to set up an interception point (on your PC) between Process Commander SOAP connectors and the SOAP Web service. Then you can examine the messages and monitor the interaction. Complete the following steps:

1. Download the Apache Axis application from the following Web site.

http://ws.apache.org/axis/

2. Follow the instructions in the Axis documentation to start tcpmon.

3. In the tcpmon window, on the Admin tab, click in the Listen Port # field and enter any port number on your machine that is not currently in use, for example, 9174.

4. Select Listener.

5. Click in the Target Hostname field and enter the host name or IP address of the system that is running the Web service.

6. Click in the Target Port # field and specify the port number on which the Web service is listening. Typically, the port number is 8080.

7. Click Add.

The tcpmon utility is now listening.

http://ws.apache.org/axis/

Building SOAP Connectors — 5BTroubleshooting 41

8. Click the tab that represents the listener you just configured.

9. In Process Commander, open the activity that invokes the SOAP connector. Expand the step that calls the Connect-SOAP activity method. Click in the End Point URL parameter and enter a Service URL that points at your PC and the port number that you specified as the listener port in step 3 of this procedure.

For example, assume that the following is the End Point URL as specified in the connector rule:

http://serverx:8080/axis/services/CreditServicePort

If the port number that you specified as the Listen Port # in step 3 is 9174, you would override the End Point URL in the connector activity by entering the following End Point URL in the activity:

http://localhost:9174/ axis/services/CreditServicePort

10. Run the SOAP connector.

The tcpmon utility on your PC intercepts the SOAP request and displays it in the tcpmon window. The utility then forwards the request to the Web service that you identified with the Target Hostname and Target Port # fields in steps 5 and 6 of this procedure. The response from the SOAP service at that location is also intercepted by the tcpmon utility and then passed on. Both the SOAP request and the response appear in the tcpmon window.

Common Error Messages This section lists some of the errors that you might see when building a SOAP connector.

Data Mapping Problems Message: “Complex request (or response) parameters can only be used via WSDL schema definitions.” Problem: you are trying to manually configure a data mapping using the XML Page data type. The XML Page data type can be used only in SOAP connector rules that the Connector Accelerator generated.

Most of the other error messages that describe data mapping problems usually appear because pages and classes are defined incorrectly, either in the connector activity or on the XML Page tab of the connector rule.


XML Parse Rule Problems Message: “Caught exception parsing XML stream” Problem: The XML parse rule the request is mapped to is either the wrong rule or it has an error in one or more of its parse actions.

Message: “Failed to open…: <key to XML parse rule>” Problem: The root element provided in the incoming XML stream does not match the third key of any XML parse rules.

XML Stream Rule Problems Message: “Couldn’t map <parameter> from XML stream rule: Missing stream source page: <pagename>.” Problem: the data mapping in the connector rule uses specifies the XML stream rule to use with the pageName.streamName syntax, but the page it refers to does not exist at runtime.

Problems with the Web Service Message: “SOAP service failed: <message from the external service>” Problem: the Web service is not functioning.

Message: “Service URL <URL of the Web service> is invalid.” Problem: the End Point URL specified on the Service tab is not well formed.

building soap connectors pegarules process commander ... · sample soap connectors the sample soap...

Documents