Pega Soap

Building SOAP Services
PegaRULES Process Commander Versions 5.1 and 5.2

© Copyright 2007
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 Services
Software Version: 5.1 and 5.2
Posting Date: January 2006
Contents
Introduction...............................................................................................................2
Summary of Steps for Building SOAP Services .................................................3
About the SOAP Service Example .....................................................................4
The SOAP Service ....................................................................................................6

Rule and Data Objects for a SOAP Integration ..................................................6
Process...............................................................................................................8
Data Mapping ...................................................................................................10
Session State ...................................................................................................11
Authentication...................................................................................................13
WSDL Files and SOAP Operation Style...........................................................14
Character Encoding..........................................................................................15
Building SOAP Service Packages.........................................................................16

Plan the SOAP Service ....................................................................................16
Create or Identify the Class Rule, Properties, and Data Mapping Rules..........18
Create the Service Activities.............................................................................19
Create the Service Package and Service Rules...............................................21
Generate the WSDL File ..................................................................................27
Build the SOAP Client ......................................................................................29
Run the Client and Test the Service.................................................................31
Running the Sample...............................................................................................32

Process Commander Setup .............................................................................32
Client Application Setup ...................................................................................33
Run the PhoneBookUser Client Application .....................................................35
Troubleshooting .....................................................................................................36
SOAP Message Monitoring ..............................................................................37
Building SOAP Services
The SOAP integration interface in PegaRULES Process Commander® (Process

Commander) supports interactions between your Process Commander application and
other systems through Web Services. Process Commander supports SOAP
communications through both services and connectors. These tools enable your Process
Commander applications to act as a Web Service and to communicate with external Web
Services.
Building SOAP Services describes how to create a package of SOAP services in Process
Commander. It also provides information about creating SOAP clients that communicate
with Process Commander SOAP services.
This document contains the following sections:
■ Introduction
■ The SOAP Service
■ Building SOAP Service Packages
■ Running the Sample
■ Building SOAP Service Packages
■ Troubleshooting
2 0BBuilding SOAP Services
Introduction
Building SOAP Services is part of a package of materials that includes a sample SOAP
client application and sample SOAP service rules. The document and sample are intended
for Process Commander system architects who are XML and/or Java programmers and
who understand the SOAP and WSDL protocols.
The SOAP service 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 the SOAP service example and for the PhoneBook sample
application.
■ pegaphonebookuserclientapp.zip. This zip file contains the following items:

− The PhoneBook.xsd file that was used to build the PegaRULES sample
application named PhoneBook.
− The Java class and source files for the SOAP client application,
PhoneBookUser.
− Batch files and UNIX shell scripts that run the PhoneBookUser client
application. Additionally, build scripts for the client application that you can use
to experiment with.
− The PhonebookDocument.wsdl and PhonebookRPC.wsdl files that were
generated by the PegaRULES SOAP service package and then used to create the
client stub files for the PhoneBookUser client application
It is recommended that you read the Process Commander book Integrating with External
Systems v 5.1 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 service sample
on your PegaRULES Process Commander system as a training exercise before
implementing your own SOAP services.
All the materials listed above are available at the following location:
http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp
0BBuilding SOAP Services — 1BIntroduction 3
Summary of Steps for Building SOAP Services

The following procedure lists the general steps to build a SOAP service in PegaRULES
Process Commander:
1. If the PegaRULES application that you are making available through SOAP
services has not yet been built, use the Create Import/Export Rules Accelerator to
build it. The accelerator generates rules that expedite the development process,
especially if you use XML parse and stream rules for your SOAP services.
Note: It is outside the scope of this document to describe how to design and
develop a PegaRULES Process Commander application. For information about
using the rule generation accelerators, see Integrating with External Systems, Data
Mapping XML, and the Application Developer Help system. For information about
creating applications in general, see Designing Your Application with SmartBuild.
2. Create the rules and data objects that make up the service, as described in “Building
SOAP Service Packages,” starting on page 16.
3. Use the service package (instance of Data-Admin-ServicePackage) to generate a

WSDL file that lists the functions implemented by the service rules, as described in
“Generate the WSDL File” on page 27. The end point URL in the WSDL is set to
use PRSOAPServlet rather than PRServlet.
4. Use the WSDL file to develop the SOAP client. While it is outside the scope of this
document to describe how one develops SOAP clients, this document does describe
the information a SOAP client uses to identify and communicate with a Process
Commander SOAP service. See “Build the SOAP Client” on page 29.
About the SOAP Service Example

The SOAP service example makes a sample Process Commander application available to
an external SOAP client application. The Process Commander application is a simple
phonebook application. The sample SOAP services receive phonebook and contact
entries and requests for entries from the sample SOAP client application.
The SOAP sample has three parts:
■ The PegaRULES PhoneBook application
■ The SOAP PhoneBookUser client application, which creates new phonebooks and
sends them to the PhoneBook application, adds contact information to phonebooks
stored in the PhoneBook application, and sends requests for contact information to
the PhoneBook application
■ The PegaRULES SOAP services, which make the PhoneBook application available
to the PhoneBookUser application. The six services in the sample service package
receive requests from and send responses to the PhoneBookUser application.
The Process Commander PhoneBook Application

The PhoneBook application includes two class rules, three model rules, and five
properties. The class and property rules implement the data model described in an .xsd
file named PhoneBook.xsd. This file was created so it could be used by the Create
Import/Export Rules accelerator to build the PhoneBook application.
The accelerator imported the PhoneBook.xsd file into a base class rule named
SampleBase-. It created two class rules that represent the two elements defined in the
PhoneBook.xsd file:
■ The SampleBase-PhoneBook class rule represents the Phonebook element.
■ The SampleBase-Contact class rule represents the Contact element.
The Contact element is a complex type that is an attribute of the Phonebook element. To
represent that data relationship in Process Commander, the class rule that represents the
Contact element (SampleBase-Contact) is embedded in the class rule that represents the
Phonebook element (SampleBase-Phonebook) as the Page List property named Contact.
The accelerator created two XML parse rules (Rule-Parse-XML), two XML stream rules
(Rule-Obj-XML), and two model rules (Rule-Obj-Model), one each for the PhoneBook
and the Contact class rules. The model rule named PhoneBookData was then created
manually for the ImportPhoneBook service.
0BBuilding SOAP Services — 1BIntroduction 5
The Sample SOAP Service

The sample SOAP service provides the following functions as SOAP services:
■ Create a phonebook
■ Open a phonebook
■ Add a contact to a phonebook
■ Look up a phone number
■ Update a phone number
■ Import a phonebook
The service sample includes a service package rule, six service rules, six service activity
rules, a model rule, and two XML stream rules. There are also three activity rules that
you can use to manually test and debug the sample services. The XML stream rules were
generated by the Create Import/Export Rules Accelerator. The accelerator also generated
two XML parse rules that the service example does not use.
After the services were configured, the sample service package (an instance of Data-
Admin-ServicePackage) was used to generate the WSDL files PhonebookDocument.wsdl
and PhonebookRPC.wsdl.
The PhoneBookUser Client Application

The SOAP client application, PhoneBookUser, was created with Apache Axis version
1.1, an open source toolkit for building Web Services and Web Service clients. The two
WSDL files were processed by the WSDL2Java utility from the Axis toolkit. The
WSDL2Java utility generated eleven client stub files based on the WSDL files.
The PhoneBookUser application includes the following files:
■ The eleven client stub files (Java source and class files) generated by the Apache
Axis toolkit
■ The PhoneBookUser class file
■ Windows batch files and UNIX shell scripts that build and run PhoneBookUser
The PhoneBookUser class uses the client stub class files to create SOAP messages that
contain phonebook and contact records. The RunPhoneBookUser batch file and shell
script supply the phonebook and contact records for the SOAP messages. The
PhoneBookUser Java class accepts the input from RunPhoneBookUser, creates SOAP
messages with the phonebook and contact information, and then sends the messages to
the PhoneBook application via the appropriate SOAP service rule.
The SOAP Service

This section describes the SOAP service, including its rules and data objects, deployment
file (WSDL), processing, data mapping, session state, and authentication.
Rule and Data Objects for a SOAP Integration

A “Process Commander SOAP service” means a SOAP service package that provides a
group of multiple service methods for an external application to use rather than a single
method or function. Each method in the service package corresponds to an individual
SOAP service rule that identifies an activity to run and maps the incoming and outgoing
data.
A SOAP service requires the standard list of components as described in Integrating with
External Systems, with no additional listeners, servers, or other data objects. SOAP
services do not require a listener because SOAP requests are processed through a servlet
named PRSOAPServlet that listens for SOAP requests.
Figure 1 provides a list of the rules and data objects that implement SOAP services.
Component Purpose
Service package Serves as a container that bundles the other components
(Data-Admin- for the service. After you create the SOAP service rules,
ServicePackage) use the service package to generate a WSDL file that
describes the functions provided by the service rules.
Service rule Receives messages from a SOAP client, maps incoming

(Rule-Service-SOAP) and outgoing values, calls an activity, and assembles a
response if one is necessary. A SOAP service rule
represents one function or feature such as create,
update, or delete. A SOAP service typically has more
than one service rule.
Service activity Manipulates values on the clipboard, calls other activities

(Rule-Obj-Activity) that perform additional processing, and does what is
necessary to complete the processing for the service.
Each SOAP service rule has a service activity.

Depending on how you code the activities, it is possible
to use the same service activity with more than one
service rule in the same service package.
0BBuilding SOAP Services — 2BThe SOAP Service 7
Component Purpose
Class rule and properties for Hold the data for the part of the Process Commander
the service activities application that you are making available to the SOAP
(Rule-Obj-Class) client. The service activities apply to this class rule and
(Rule-Obj-Property) the properties in this rule are those for which the
incoming SOAP messages have values.
XML stream rules for data (Optional) Used to create the response message when
mapping the message contains scalar arguments, the data in an
(Rule-Obj-XML) argument is XML, and the SOAP operation style is RPC.
The service rule uses an XML stream rule to format
clipboard data as XML in the response to the external
SOAP application.
XML parse rules for data (Optional) Used to process the incoming request
mapping message when the message contains scalar arguments,
the data in an argument is XML, and the SOAP operation
(Rule-Parse-XML)
style is RPC The service rule uses an XML parse rule to
extract data from a string argument in an incoming SOAP
message and map it to the clipboard when the string
holds XML data.
Model rules for data mapping (Optional) Used when an incoming or outgoing message
(Rule-Obj-Model) contains an XML object and the SOAP operation style is
document. The service package uses the model rule to
generate descriptions of the XML objects for the WSDL
file. The service rule uses the model rule to determine
how to map an object’s properties to or from a clipboard
page.
Figure 1. Summary of Components Required for SOAP Integration

Process
To call a Process Commander SOAP service, an external application collects data values
that are required as input to the service, wraps them in an XML document envelope
(SOAP envelope) that contains the name of the requested service, and posts the envelope
to the URL of the Process Commander WebSOAP servlet, PRSOAPServlet.
Figure 2 illustrates the architecture of the SOAP service.
External SOAP Client
request
PRSOAPServlet Process
Commander
Data-Admin-
ServicePackage response
Page
Rule-Service-SOAP
Clipboard
Page
Service Activity
Figure 2. Architecture of a SOAP Service

The following describes how a SOAP service works:
1. A Web services SOAP client gathers parameters and posts a SOAP request to the
URL of the Process Commander WebSOAP servlet, PRSOAPServlet. The SOAP
request identifies the service package, class, and method (service rule) to be
invoked.
2. PRSOAPServlet examines the SOAP request and locates the appropriate service
package (Data-Admin-ServicePackage).
3. The service package calls the SOAP service rule (Rule-Service-SOAP) that
corresponds to the specified package, class, and method names.
4. The SOAP service rule invokes the appropriate rules to map the input SOAP
parameters to Process Commander properties.
5. The SOAP service rule invokes a service activity.
6. The service activity processes the input properties and writes values into one or
more output properties.
7. The service activity returns control to the SOAP service.
8. The SOAP service rule invokes the appropriate rules to map the output properties
into a SOAP response.
9. The SOAP service rule returns control to PRSOAPServlet.
10. PRSOAPServlet transmits the SOAP response to the SOAP client.
11. The SOAP client evaluates the response and takes appropriate actions.
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 PegaRULES Process Commander
Integrating with External Systems.
A SOAP service rule form has two tabs for mapping data:
■ Request — use this tab to specify how to map the arguments from incoming SOAP
messages to properties on the clipboard (Map To).
■ Response — use this tab to specify how the service rule constructs the response to be
sent from Process Commander in reply to the request (Map From).
To determine how to configure the data mapping for a SOAP service rule, consider how
you want to work with the data in the SOAP client application. For example, will the
client application work with simple string or numeric values? Will the client application
work with XML data or complex object values? Your assessment reveals which of the
following data mapping options you must use for each argument included in the SOAP
message:
■ Simple argument-property mapping – used when the data in the SOAP message
arguments can be mapped directly to and from clipboard properties or activity
parameter values.
■ XML parse and stream rules – used to parse or assemble string argument values that
contain XML data and the SOAP operation style is RPC.
■ Model rules – used to describe the schema of the message when the message
contains an XML object and the SOAP operation style is document.
■ Special parameters – used to map authentication values for a stateful service when a
SOAP client does not support HTTP Basic Authentication, or to map the requestor
ID for a stateful service when the SOAP client does not support cookies.
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.
Special Parameters
The SOAP service allows values for user name and password to be sent directly to
PRSOAPServlet through HTTP Basic Authentication. During a stateful session, the
Requestor ID is automatically sent to the SOAP client as a token in a cookie. In certain
cases, however, you cannot take advantage of these built in features. For those cases, the
SOAP service rule supports three default parameters that appear as options in the Map To
field on the Request tab:
■ Username
■ Password
■ Requestor ID
For example, if the SOAP client does not support HTTP Basic Authentication but the
service must run as an authenticated user, create data mapping entries for the Username
and Password parameters on the Request tab of the service rule. If the SOAP client does
not support cookies and the session is stateful, create a data mapping entry for the
Requestor ID parameter on the Response tab of the service rule. In both cases, you select
the parameter from the list in the Map To or Map From field and leave the Map To Key
or Map From Key field blank.
Process Commander and the PRSOAPServlet manage these default parameters

automatically. You do not need to create properties named Username, Password, and
Requestor ID.
For more information about authentication, see “Running as an Authenticated User” on

page 13.
Session State
The session state of a SOAP session (stateless vs. stateful) is specified in two places:
■ In the Process Commander service package
■ In the SOAP client application code that sets up the message context for the SOAP
message
The session semantics of the SOAP client and the service package must match. If they do
not, you may get unexpected results when you test your service because session state for
the service is determined by the service package, not the SOAP client:
■ If the SOAP client requests a stateless session but the service package is set to
stateful, the session is stateful and requestor pooling is disabled.
■ If the SOAP client requests a stateful session but the service package is set to
stateless, the session is stateless and clipboard properties are cleared after the service
completes its processing.
Stateful Sessions
When the session is stateful, the state of the clipboard remains intact between requests.
You can specify the individual behavior of the requestor used by each service rule in the
package, and the SOAP client can invoke multiple methods (service rules) during the
same session, as the same requestor if necessary. Each subsequent service rule has access
to clipboard values that were set by a previous method (service rule).
Stateful sessions do not use requestor pooling.
The Process Commander application that you are making available through SOAP
services may require functions to occur in a specific sequence because subsequent
functions rely on data set earlier in a session. To implement session continuity, configure
the service package and service rules as follows:
1. Set the Processing Mode field in the service package to Stateful.
2. In the service rules other than the one that ends the sequence, clear the End
Requestor check box, which keeps the requestor session open after the response is
sent.
3. In the last service rule invoked in the sequence of methods, select the End
Requestor check box, which closes the requestor session after the response is sent.
Note: If you do not select the End Requestor check box to close the requestor
session, the session remains open until another method closes it or the session times
out.
Stateless Session
If the session is stateless, the service uses requestor pooling. The clipboard is cleared for
the requestor when the service completes its response. Subsequent requests to the same
service do not have access to any previous values.
However, the requestor pool does not include authenticated requestors (users). Therefore,
when the session is stateless and the service runs as an authenticated user, requestor
pooling is not available.
For more information about requestor pooling, see PegaRULES Process Commander
Integrating with External Systems.
Authentication
A SOAP service can run as either an authenticated or an unauthenticated user.
Running as an Unauthenticated User

If you configure your SOAP service to run in a stateless, unauthenticated session, the
SOAP client does not provide an operator ID. The rule session is assigned a requestor ID
from the requestor pool created for the service. The access group specified in the service
package is used for rule resolution.
Running as an Authenticated User

A Process Commander system can be configured to authenticate users in several ways, as
described in the document Authentication in PegaRULES Process Commander, which is
available on the PDN. Therefore, your first step is to determine how the SOAP service
requestors are to be authenticated. For example, if your Process Commander system is
configured to authenticate users through container-managed authentication, should the
SOAP service requestors (users) be authenticated in the same way?
To configure a SOAP service to run as an authenticated user, complete the following

steps:
1. Determine how SOAP service requestors are to be authenticated. If they are to be

authenticated by container-managed authentication, follow the instructions in
Authentication in PegaRULES Process Commander to configure the WebSOAP
servlet definition in the Process Commander web.xml file.
Note: Do not change the URL pattern for the WebSOAP servlet from its default
value of PRSOAPServlet. PRSOAPServlet is used as the end point URL specified
in the WSDL files generated for your SOAP services. If you change it in the
web.xml file, the end point URLs in the WSDL files will not match the URL of the
WebSOAP servlet on your system.
2. In the service package (Data-Admin-ServicePackage) on the Context tab, select the

Requires Authentication option.
3. Code the SOAP client to provide the user name and password of a valid Process
Commander operator ID in the SOAP messages it sends. User name and password
values can be provided in any of the following ways:
− In the HTTP header, using HTTP Basic Authentication. The PRSOAPServlet
automatically recognizes authentication information sent in an HTTP header as
such.
− As parameter values in the SOAP envelope header. If you choose this method,
use the WSDL file from the service package to determine the correct format for
the header and its contents.
− As parameter values in the SOAP envelope body.
4. Verify that that access group of the Operator ID lists the RuleSet and version that
the rules in the SOAP service use.
5. (Optional) If the SOAP client does not support HTTP Basic Authentication, select
the Request tab and then enter a data mapping row for the special parameters
Username and Password. Figure 3 shows an example.
Figure 3. Data Mapping for User Name and Password
6. (Optional) If the SOAP client does not support cookies, select the Request and
Response tabs and then enter a data mapping row for the special parameter
Requestor ID. Figure 4 shows an example.
Figure 4. Data Mapping for Requestor ID
WSDL Files and SOAP Operation Style

After building a SOAP service package in Process Commander, use the service package
to generate WSDL files that describe the services in the package. Then you can copy the
generated WSDL file to the system on which you are developing the SOAP client and use
it to create your SOAP client application.
The SOAP service sample has two WSDL files, generated by the same service package
(SampleSOAP). A generated WSDL describes all the service rules (service methods) that
have the same values for their first two key parts: service package name and service class
name. The SOAP example has two WSDL files because there are two service class
names in the package: PhonebookDocument and PhonebookRPC.
The Process Commander SOAP service supports both SOAP operation styles: document-
literal and RPC-encoded. The data type definitions of the arguments specified in the
service rule determine whether the SOAP operation style of the service rule is set to
document or RPC in the generated WSDL file.
If the SOAP service rule includes an argument with a data type set to XML Page and
mapped to a model rule, the SOAP operation style is set to document-literal in the
generated WSDL. Otherwise, the operation style is RPC-encoded.
Character Encoding
By default, Process Commander uses UTF-8 as the character set encoding for SOAP
response messages. To change character set encoding for SOAP responses, modify the
value of the CharacterEncoding parameter specified for the WebSOAP servlet definition
in the Process Commander web.xml file.
Alternately, you can configure Process Commander so that the encoding of the response
matches that of the SOAP request, no matter what it is set to. To implement this
configuration, do the following:
1. Remove the CharacterEncoding parameter from the servlet definition of WebSOAP

servlet in the web.xml file.
2. Configure the external application that sends the SOAP requests so that it uses the
Content-Type HTTP request header in the SOAP request to specify the character set
encoding of the message.
Then, if a SOAP request provides an encoding value, the WebSOAP servlet uses that
character set for the response. But if the SOAP request does not specify an encoding
value, the WebSOAP servlet uses UTF-8.
Building SOAP Service Packages

This section describes how to create SOAP services, using the SOAP service example to
illustrate each step. As is typical with Web Services, the SOAP example is a package of
several service rules that each perform a specific, separate function. 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 service package, complete the following tasks:
■ Plan the SOAP Service
■ Create or Identify the Class Rule, Properties
■ Create the Service Activities
■ Create the Service Package and Service Rules
■ Generate the WSDL File
■ Build the SOAP Client
■ Run the Client and Test the Service
These tasks are described in the following sections.
Plan the SOAP Service

During the planning stage, determine which parts of the PegaRULES Process
Commander application should be made available to the external SOAP client. Then
determine the individual functions that the external system needs. Each function
corresponds to a SOAP service rule, identified by its key parts as one method in the same
service package.
For each method, determine what the service activity is to accomplish. Identify the input
and output of each activity. Identify the class rules, properties, and other rules (parse,
stream, model) that are necessary for storing and processing the input and output data.
As mentioned in “Data Mapping” on page 10, 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 creating is RPC encoded and any of the scalar arguments in the SOAP
messages contain embedded XML, you need XML parse and/or stream rules.
Then, choose names for the individual components in the SOAP service and use Figure 5
to keep track of the names. For reference purposes, the middle column of Figure 5 lists
0BBuilding SOAP Services — 3BBuilding SOAP Service Packages 17
the component names in the SOAP service example. Write the names of the components
you create in the remaining column. Choose meaningful, explanatory names.
Component SOAP Service Example Your Service Project

RuleSet PegaSample-IntSvcs
RuleSet version (various)
Access group sampleuser@samples.com
Class rule that Samplebase-Phonebook

service activities
apply to
Properties for SampleBase-Phonebook:
service activity
Name = Title, mode = Single Value
class
Name=Contact, mode= Page List,
page class = SampleBase-Contact
SampleBase-Contact:
Name = LastName, mode = Single

Value
Name = FirstName, mode = Single
Value
Name = PhoneNumber, mode =
Single Value
Service activities AddContact

Create
FindContact
Open
Save
UpdateContact
Service package SampleSOAP
Service class PhoneBookDocument

PhoneBookRPC
Service methods AddContact

Create
LookupPhoneNumber
ImportPhoneBook
Open
UpdatePhoneNumber
Component SOAP Service Example Your Service Project

XML parse rules SampleBase-
Contact.urn:PhoneBook.Contact
SampleBase-
PhoneBook.urn:PhoneBook.PhoneBook
XML stream rules SampleBase-

PhoneBook.PhoneBook.MapFrom
SampleBase-Contact.Contact.MapFrom
Model rules SampleBase-

PhoneBook.PhonebookData
Figure 5. Component Names for a SOAP Service Package
Create or Identify the Class Rule, Properties, and Data Mapping Rules
During the planning stage, you identified the class rule and properties for the service
activities. You determined whether any of your service methods use the document SOAP
operation style, which determines whether you need to create a model rule. You
determined whether the input and/or output would contain XML and whether you would
need XML parse and/or stream rules. If the class rules, properties, model rules, or XML
parse and stream rules do not exist yet, create them.
The class rule that a service activity applies to usually inherits from the Data- or Work-
base class rules. If you need to save objects of this type into the database, define the class
rule as a concrete class and specify which property is the key.
When you need XML parse and stream rules for the service, the easiest way to create the
classes, properties, and other rules that represent the data structure of the data processed
by the service is to use the Import XSD/DTD Accelerator. Create or obtain an XML
schema description (XSD) file that describes the XML data handled by the service. Then
run the Accelerator. It creates class rules for each complex element or type defined in the
schema document and creates properties for each element or attribute in the complex
element or type. It also creates XML parse and/or stream rules and model rules.
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

Create the Service Activities

The service activity, which is specified in the service rule, processes the input from the
SOAP client. Create or identify the service activity before you or the Services
Accelerator creates the service rule.
■ If the service starts or resumes a flow for a work object, the Services Accelerator
assigns the createWorkProcess or the resumeWorkProcess activity to the service, as
appropriate. For information about these activities, see Using the Service
Accelerator, which is posted on the PDN. Then continue with “Create the Service
Package and Service Rules” on page 21.
■ If the service uses a custom activity, for each activity, identify the class rule it
applies to (that is, its primary page), the properties that it manipulates, the parameters
it expects, and the step pages that it needs, if any.
To create custom service activities planned for your package of SOAP service rules,
complete the following steps:
1. From the Rules by Type explorer, select Technical > Activity.
2. Click New.
3. In the New form, complete the fields as shown in Figure 6.
Field Selection
Applies To Enter the name of the Process Commander class rule
that you determined was the correct one for this
service activity during the planning stage (see
Figure 5).
For example, the class rule that the five service

activities in the SOAP service example apply to is
SampleBase-Phonebook.
Name Enter the name that you chose for this service activity
in the planning stage (see Figure 5).
For example, the name of the service activity for the

AddContact service rule is also named AddContact.
Figure 6. Fields in the New Window for a Service Activity
4. In the Activity form, on the Pages and Classes tab, configure any pages that the
activity needs. Figure 7 shows the Pages and Classes tab for the AddContact
service activity.
Figure 7. Pages and Classes Tab for AddContact Service Activity
The SampleBase-Phonebook class contains a Page List property named Contact for
holding instances of the class SampleBase-Contact. The AddContact activity uses
one page named Phonebook to hold the persistent phonebook data and another page
named Contact to hold data to be added to the list of contacts in the phonebook.
Because the AddContact activity sets properties in both class rules, pages are
specified for both class rules on the Pages and Classes tab for the AddContact
activity.
5. On the Steps tab, create the steps that implement the purpose of the service rule
that uses this activity. For example, the AddContact service activity opens the
phonebook object, determines whether this is a new contact, creates the Contact
page, sets the contact properties to the values that were provided in the SOAP
message, appends the contact to the phonebook object, and then saves the
phonebook data.
6. On the Security tab, accept the default settings.
7. On the History tab, enter a description in the Full Description and the Usage fields.
8. Click Save.
9. Repeat steps 1 through 8 of this procedure for each service activity planned for the
package of SOAP service rules.
Create the Service Package and Service Rules

For information about using the Services Accelerator to create the service package and
service rules, see Using the Service Accelerator, which is posted on the PDN. In the
Application Developer Help system, see the topics for each form the accelerator displays
as you work through the sequence.
To create a service package and service rules without using the Services Accelerator,
complete the following procedures.
Create a Service Package

Complete the following steps to create a service package:
1. From the Process Commander home page, click Integration.
2. On the Integration page, under Resources, select Service Packages.
3. Click New.
4. In the New form, in the Service Package name field, enter the name that you chose
for the service package in your planning stage (see Figure 5). For example, the
service package in the SOAP service example is called “SampleSOAP.”
5. In the Service Package window, on the Context tab, complete the fields as shown in
Figure 8.
Field Value
Processing Mode Select Stateless or Stateful, as appropriate for the
service. For example, if the service runs as an
authenticated user or the functions that you plan to
implement require session continuity, select Stateful.
For more information see “Session State” on page 11.
Service Access Group Enter the name of the access group that you chose
during the planning stage (see Figure 5). The access
group is used for rule resolution when the WSDL file
is generated and for finding the correct SOAP service
rules at runtime.
When the service package does not require

authentication, this access group is used to identify
the correct version of the service activity and data
mapping rules, if any.
Field Value
Requires authentication? Select if you want the requestor that interacts with the
services to be an authenticated user. In this case, the
Processing Mode field must be set to Stateful and the
SOAP client must provide the user name and
password of a valid Process Commander operator.
For information, see “Running as an Unauthenticated

User” on page 13.
Figure 8. Fields on the Context Tab of the Service Package Window
6. If you selected Stateless in the Processing Mode field on the Context tab, select the
Pooling tab and then configure the requestor pool as appropriate for your
configuration. Because requestor pooling is not available for stateful sessions, the
Pooling tab is ignored if Processing Mode is set to Stateful.
7. On the History tab, enter a description in both the Full Description and the Usage
fields.
8. Click Save.
Note: Ignore the Methods and Deployment tabs for now. You cannot generate the
WSDL file for your SOAP services until after you have created the service rules for
the service package.
Create the SOAP Service Rules

To create service rules without using the Services Accelerator, verify that the service
package, service activities, and data mapping rules exist. Then, complete the following
steps for each service rule in your package of SOAP services:
1. From the Rules by Type explorer, select Integration-Services > Service SOAP.
2. Click New.
3. In the New form, complete the fields as shown in Figure 9.
Field Value
Customer Package Name Enter the name of the service package you created
for this service. This name must match the
packageName component of the Service URI
specified by the SOAP client.
Field Value
For example, the service package for the SOAP
service example is SampleSOAP.
Customer Class Name Enter the name that you chose for the service class in
the planning stage (see Figure 5). This value is used
for grouping related SOAP service methods in the
generated WSDL file; this value is not the name of a
Rule-Obj-Class rule.
For example, the service class name for the

ImportPhoneBook service rule is
PhoneBookDocument. The service class name for the
other five service rules in the sample is
PhoneBookRPC.
Customer Method Name Enter the name that you chose for the service method
represented by this service rule during the planning
stage (see Figure 5).
For example, the service method name for the first

service rule in the SOAP example is AddContact. The
other method names in the SOAP service example
are Create, LookupPhoneNumber, Open, and
UpdatePhoneNumber.
Figure 9. Fields in the New Form for a Service Rule
4. In the Service Rule form, on the Service tab, complete the fields as shown in
Figure 10.
Field Value
Page Class Select the Process Commander class rule that
corresponds to the page that will serve as the primary
page of the service activity that you specify in the
Activity Name field. For example, the Page Class for
the service activities in the SOAP service sample is
SampleBase-Phonebook.
Page Model (Optional) Select a page model, if appropriate. If

specified, the model is applied to the primary page
when it is first created by the service rule. The SOAP
example does not use a page model.
Field Value
Page Name (Optional) Enter the name of the page that serves as
the primary page for the service activity specified in
the Activity Name field.
When the service package is stateless, or when the

service package is stateful but the page does not yet
exist on the clipboard, the service rule creates the
page before it maps any data or invokes the service
activity.
If a Page Name is not specified, the service rule

creates an unnamed page that is removed from the
clipboard after the response is sent.
Activity Name Enter the name of the service activity that you created
for this service rule. For example, the name of the
service activity for the AddContact SOAP service rule
is AddContact.
End Requestor When If the Processing Mode field in the service package is
Done? set to Stateless, the service package defines the
requestor configuration so you can leave this field
blank.
If the Processing Mode is set to Stateful, either select

or clear this option, as appropriate for this service
rule. For help with determining whether or not to
select this option, see “Stateful Sessions” on page 12.
Figure 10. Fields on the Service Tab for a SOAP Service Rule
Figure 11 shows the Service tab for the AddContact service rule.
Figure 11. Service Tab for the SOAP Service Example Service Rule
5. On the Request tab, under Request Parameters, add a row for each argument value
that is present in the SOAP messages sent to this service rule. For help with this
step, see “Data Mapping” on page 10. Figure 12 shows the request parameters for
the AddContact service rule.
Figure 12. Request Parameters for AddContact Service Rule
This example configures the service to use RPC as the SOAP operation style.
Because the AddContact service activity is configured to use a parameter page, all
the values are mapped to parameters on the parameter page. (The AddContact
service activity then sets the parameter values into properties.) For example, the Map
To Key for the PhoneBook argument specifies Param.PhoneBook.
Figure 13 shows the request parameters for the ImportPhoneBook service rule.
Figure 13. Request Parameters for ImportPhoneBook Service Rule
This data mapping defines the PhoneBookData argument as a complex type. For
information about using the XML Page data type, see the document Data Mapping
XML, which is posted on the Integration Services page of the Pega Developer’s
Network.
6. On the Response tab, under Response Parameters, add a row for each argument
value that the SOAP service rule sends in the response to the SOAP client.
Figure 14 shows the response parameters for the AddContact service rule example.
Figure 14. Response Parameters for the Example SOAP Service Rule
This sample data mapping specifies that the XML stream rule named SampleBase-
PhoneBook.PhoneBook generates an XML document named PhoneBookData. The
AddContact service rule sends the PhoneBookData XML file to the PhoneBookUser
application as the response.
7. On the Faults tab, specify the SOAP Fault message to return to the external SOAP
client if the SOAP service rule encounters a fatal processing error. Figure 15
shows the Faults tab for the AddContact service rule.
Figure 15. Faults Tab for the AddContact Service Rule
The fault mapping uses the When rule named StepStatusFail, which checks to see if
the value of the return parameter is 0. If this condition is true, the AddContact rule
sends the string specified in the Map From Key field: Phonebook not found.
8. Use the XML Page tab only if you select XML Page as the data type for an
argument on the Request or Response tab. Specify the class rule, model rule, and
page name that provides the schema description for the XML Page argument. For
more information, see Data Mapping XML, posted on the Integration Services
pages of the Pega Developer’s Network.
Figure 16 shows the XML Page tab for the ImportPhoneBook service rule.
Figure 16. XML Page Tab for ImportPhoneBook Service Rule
9. On the History tab, enter a description in the Full Description and the Usage fields.
10. Click Save.
11. Complete steps 1 through 10 of this procedure for each SOAP service rule to be
included in the SOAP service package.
Generate the WSDL File

After you create all the service rules for the service package (either manually or with the
Service Accelerator), return to the service package and generate the WSDL file that
represents your SOAP service. Complete the following steps:
1. Open the service package that you created for the SOAP service. For example, the
sample SOAP service package is SampleSOAP.
2. On the Methods tab, click Service Type and select Rule-Service-SOAP from the
selection list.
3. Click the Show Methods button and verify that the methods (service rules) are
listed. The list contains service rules that belong to RuleSets included in the
service access group specified on the Context tab.
4. Select the Deployment tab.
5. In the Deployment Type field, select WSDL from the selection list.
6. In the Service Class field, select the service class name. For example, there are two
service class names for the SOAP service example: PhoneBookRPC and
PhoneBookDocument.
7. Click Generate Deployment Files.
Process Commander creates the WSDL file and displays the location of the file. The
WSDL file describes all the services that have the name of this service package as
their first key and the name of the service class that you selected in step 4 as their
second key.
8. Make a note of the location of the file and then copy it to your client development
system so you can use it with your SOAP client generator (if that generator takes a
WSDL as input, as does Axis 1.1 and others).
Note: If any of the input or output arguments in any of the SOAP service rules are
modified after you generate the WSDL file, regenerate the file so that it reflects the
changes. Modifying the service activities does not require regenerating the WSDL
file.
9. Repeat steps 4 through 8 for each service class name in your service package. For
example, this process was completed twice for the SOAP service example — once
for the PhoneBookDocument service class and once for the PhoneBookRPC service
class.
SOAP Operation Style

The data types of the arguments specified in the service rule determine whether the
SOAP operation style of the service rule is set to RPC or document in the WSDL file. If a
SOAP service rule includes an argument with a data type set to XML Page, the SOAP
operation style is set to document-literal. Otherwise, the operation style is RPC-encoded.
When you use the RPC operation style for a service rule, the generated WSDL file shows
the following:
■ The soap:operation style attribute is set to “rpc.”
■ The soap:body use attribute is set to “encoded.”
■ No XML schema types (objects) are defined. The data types and the service rule are
kept separated (weak data typing).
With the RPC operation style, XML processing is separate from the service processing.
Therefore, if the data model changes, you do not have to regenerate the WSDL file unless
you also change something in the service rule.
When you use the document operation style, the generated WSDL file shows the
following:
■ The soap:operation style attribute is set to “document.”
■ The soap:body use attribute is set to “literal.”
■ XML schema types (objects) are defined (strong data typing). They are generated
based on the model rules specified on the XML Page tab of the service rule.
With the document operation style, the data model is exposed to the SOAP client through
the XML types defined in the WSDL. Therefore, if the PegaRULES data model changes,
you must regenerate the WSDL file. However, performance should be better than with
RPC style because the inbound XML is parsed once only.
Troubleshooting
If the WSDL file is missing operations or contains incorrect operation names, argument
names, or argument data types, assess the components in the service package as follows:
■ Verify that the service rules specified on the Methods tab of the service package
belong to the correct RuleSet and version.
■ Verify that access group set in the service package contains the RuleSet that the
service rules belong to and that the RuleSet version is correct.
■ Verify that none of the service rules are checked out into your private RuleSet.
Build the SOAP Client

Now that you have the generated WSDL file, you can create the SOAP client. The SOAP
client must call your SOAP service, passing in the appropriate parameter(s) and
processing the returned value. To see an example, unzip the pegasample-04-02-
soapserviceapp.zip file and examine the Java files in the \src directory.
For information about writing Java code that creates service and call objects, see the
SOAP 1.1 specification at the following URL:
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
For information about the Web Services Description Language (WSDL) documents that
describe Web Services, see the WSDL 1.1 specification at the following URL:
http://www.w3.org/TR/wsdl
Apache Axis is an open source toolkit for building Web Services and Web Service
clients. The example SOAP client application, PhoneBookUser, was created with
Axis 1.1. For information about downloading and installing Axis, see the instructions on
the Axis web site:
http://ws.apache.org/axis/
SOAP Target Node

The URL for PegaRULES Process Commander as a SOAP target node is the URL
pattern of the WebSOAP servlet, a special servlet that listens for SOAP requests. By
default, this servlet uses the same TCP/IP port as the WebStandard servlet that provides
browser access to Process Commander. The URL for the WebSOAP servlet is:
http://ServerName:portnumber/contextroot/PRSOAPServlet
For example:
http://MyServer:8080/prweb/PRSOAPServlet
Determine whether your Process Commander system administrator has defined a

different port, path, or URL for the WebSOAP servlet.
The PhoneBookUser SOAP client specifies the URL of the WebSOAP servlet with a
variable named TARGET_URL.
private static final String TARGET_URL =

"http://localhost/prweb/PRSOAPServlet";
Because the PhoneBookUser application is coded to accept the WebSOAP servlet URL
as a program argument, you can use the RunPhoneBookUser batch file or shell script to
set the value of the TARGET_URL variable to point to your PegaRULES Process
Commander system without editing and recompiling the PhoneBookUser.java file.
Service Namespace URI

The service namespace URI of a PegaRULES Process Commander SOAP service is the
service package and service class name used for the package of SOAP service rules. An
individual service rule name has a three-part key:
■ Package name
■ Service class name
■ Service method name
Java programmers will recognize the terms package, class, and method as organizational
terms, from the large scale (package) down to a smaller scale (class and then method). As
in Java, a Process Commander service package represents a collection of classes involved
in a common purpose. In the context of service rules, Process Commander uses the terms
service class and service method to represent more granular divisions within a service
package.
All the services in the sample package have the same package name. Five of the six
service also have the same class name, PhonebookRPC, which is why they are all
represented in the generated PhonebookRPC.wsdl file. The class name of the
ImportPhoneBook service is PhonebookDocument, which is why it has a separate WSDL
file.
To specify the service namespace URI of a SOAP service, the SOAP client must use the
following syntax to identify the package and class name of the rules it intends to use:
"urn:PegaRULES:SOAP:packageName.className"
For example, the URI of the example SOAP service is the following:
"urn:PegaRULES:SOAP:SampleSOAP:PhoneBook"
For a full example, examine the source code for the PhonebookServiceLocator Java class
located in the following subdirectory of the SOAP client example:
src\com\pega\pegarules\sample\phonebook.
Request Message Parameters

The SOAP service maps the request parameters in the order in which they appear in the
message. It maps the value of the first parameter in the request message according to the
first data mapping configured on the Request tab; it maps the value of the second
according to the second data mapping on the tab, and so on. Be sure to configure the
client’s request messages so the input parameters are in the order in which they appear in
the WSDL file (and on the Request tab of the service rule).
Summary of Steps
Typically, to create SOAP client you complete the following tasks:
1. Copy the WSDL files that you generated to the system on which you are
developing your SOAP client.
2. Use the import facility in your SOAP client toolkit to generate client stub files
from the WSDL files. For example, Apache Axis uses the WSDL2Java utility to
create client stub files. This utility was used to generate eleven client stub files
from the two WSDL files for the sample client application, PhoneBookUser. The
files are located in classes\com\pega\pegarules\sample\phonebook, and their source
files are located in scr\com\pega\pegarules\sample\phonebook.
3. Write a client application that uses the client stub files.
4. Compile and run the client application.
Note: If the SOAP client passes complex objects in the SOAP messages or sends
authentication information in SOAP envelope headers, it is highly recommended that
you use the WSDL file to create the client stubs so you can ensure that the format of
the header or object is correct.
Run the Client and Test the Service

To test a SOAP service, you run the SOAP client and then determine whether the service
works correctly. To run the example SOAP client, PhoneBookUser, see “Running the
Sample” on page 32. For information about troubleshooting, continue with
“Troubleshooting” on page 36.
Running the Sample

This section describes how to set up and run the SOAP service sample. Complete the
configuration and setup tasks described in this section for both Process Commander and
the SOAP client application before running the sample.
Process Commander Setup

To set up Process Commander to run the sample, you must 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 page on the Pega Developers Network:
2. From the Process Commander 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: sampleuser@samples.com
− Password: rules.
Note: If you need help with any of the steps in this procedure, see PegaRULES
Process Commander Administration and Security.
0BBuilding SOAP Services — 4BRunning the Sample 33
Client Application Setup

To set up the example SOAP client application, you must verify that your system can run
Java classes, download and unzip the pegaphonebookuserclientapp.zip file, and then edit
the RunPhonebookUser batch file or shell script so that you can run the PhoneBookUser
application on your system
Verify that Java is Installed on the Client System

Because the PhoneBookUser client application is a Java program, you must have the Java
Runtime Environment (JRE) installed to run it and Java installed if you want to build it.
Verify that you have the Java Developer Kit (JDK) version 1.4.2 or higher installed on
the system you plan to run the PhoneBookUser from.
If you have an older version of Java and you do not want to upgrade, you must perform
an additional configuration step: obtain an XML parser and make it available to the
PhoneBookUser client application. (Java 1.4 and higher includes the Crimson XML
parser by default.) For example, download Xerces2 from the Apache website and put the
xercesImpl.jar and xml-apis.jar files in the classpath of the PhoneBookUser application.
Create the Client Application Directory for the Example

Complete the following steps:
1. Create a directory for the PhoneBookUser client application on the system you plan
to run it from.
2. Download the SOAP service client application zip file

(pegaphonebookuserclientapp.zip) from the Integration Services page on the Pega
Developers Network:
3. Unzip the file into the client application directory. Be sure to extract the files using
a method that maintains the directory structure of the files. For example, if you are
using WinZip, use the Extract button to unzip the file.
Install Apache Axis

The PhoneBookUser client application for the SOAP service example was developed
with Apache Axis 1.1. To run it, certain Axis .jar files must be in its classpath.
1. Go to http://ws.apache.org/axis/java/releases.html
2. Download Apache Axis 1.1. (Be sure to get Axis 1.1. The sample does not work
with Axis 1.2 unless you modify the batch file.)
3. Install Apache Axis and verify that you have the following .jar files:
− axis.jar
− commons-discovery.jar
− commons-logging.jar
− jaxrpc.jar
− saaj.jar
Edit the RunPhoneBookUser Batch File or Shell Script

The client application ZIP file contains batch file and UNIX shell script examples that
compile and run the PhoneBookUser class file. Before you can run the PhoneBookUser
application, you must edit the RunPhoneBookUser batch file or shell script to identify the
location of the Axis .jar files on your system and to specify the URL of your Process
Commander system.
1. In the client directory that you created, select and open the appropriate
RunPhoneBookUser file in a text editor.
2. Edit the “set AXIS_LIB” statement to reflect the location of either the axis-1_1\lib
directory or the location of the Axis .jar files.
3. Edit the “set TARGET_URL” statement to reflect the URL of the PRSOAPServlet
on your Process Commander system.
4. Save the RunPhoneBookUser file.
Note: Leave the file in the client directory at the top level. If you move the batch file
or shell script from the client directory, you must also edit the “set
SAMPLECLASSES” statement.
0BBuilding SOAP Services — 4BRunning the Sample 35
Run the PhoneBookUser Client Application

To run the PhoneBookUser client application example, complete the following steps:
1. Verify that you have completed all the setup tasks in the “Process Commander
Setup” and “Client Application Setup” sections of this document.
2. Run the RunPhoneBookUser batch file or shell script, as appropriate.
3. Watch the console as it runs. The output should be similar to the following:
C:\SOAPExample>RunPhoneBookUser
C:\SOAPServiceSample>echo off
Created Phonebook
Phone Number: 980-3728
Updated Contact Info:
<Contact>
<LastName>Anderson</LastName>
<FirstName>Steven</FirstName>
<PhoneNumber>888-4567</PhoneNumber>
</Contact>
Created Phonebook
Phone Book Content:
<PhoneBook Title="TestPhoneBook2">
<Contact>
<LastName>Doe</LastName>
<FirstName>Jane</FirstName>
</Contact>
</PhoneBook>
Phone Book Content:

<PhoneBook Title="TestPhoneBook2">
<Contact>
<LastName>Doe</LastName>
<FirstName>Jane</FirstName>
</Contact>
</PhoneBook>
C:\SOAPServiceSample>
You can edit the file to change which SOAP service method to invoke, and to provide
values for the parameters that the service methods take – add a contact, change a phone
number, open a phonebook, and so on.
Troubleshooting
If the SOAP client cannot successfully interact with your SOAP service, the problem
typically falls into one of the following categories:
■ The access privileges specified by the service rule do not give it access to the
rules it needs to function properly.
■ You did not create all the required components. Review “Building SOAP Service
Packages” (starting on page 16) and verify that you created all the necessary rules.
■ The activity you wrote does not work properly.
■ 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 field on the Service tab of the service rule
− Page Name and Class Name fields on the XML Page tab of the service rule.
− Pages and Classes tab of the service activity
− Page names in activity steps that use the Page-New method
■ The client is not coded or configured properly. Perhaps the problem is with the
SOAP client. Ask yourself the following questions:
− Did you generate the client (or stubs) from the correct WSDL file? Examine the
WSDL file and make sure that the input and output parameters match your
expectations.
− Do the input parameters in the request message appear in the order in which they
are listed in the WSDL? The parameters in the request message must be in the
same order as they are listed in the WSDL.
− Are there problems with authenticating the client/service session? See “Running
as an Authenticated User” on page 13.
− Are transient issues preventing the client from running? Confirm that the
network connection between client and server is up.
The following is a list of tools and methods that you can use for troubleshooting your
SOAP service rules:
■ Use the Run button in the service rule to unit test the rule before you test the client
application’s ability to communicate with the rule. For information, see Testing
Services and Connectors, available on the PDN.
■ Trace the service rule while you unit test it and watch it as it runs. For information,
see Testing Services and Connectors, available on the PDN.
■ Run a SOAP listener or SOAP monitoring application to study the client’s SOAP
request and the SOAP service rule’s SOAP response. For example, use the tcpmon
0BBuilding SOAP Services — 5BTroubleshooting 37
utility (TCP/IP monitor) from Apache Axis or another SOAP viewer. See “SOAP
Message Monitoring” on page 37.
■ Configure logging level settings so Process Commander generates status and error
messages about the SOAP service rule. For information, see the section on log files
in PegaRULES Process Commander Administration and Security. Then configure
loggers for the following:
− com.pega.pegarules.services.soap
− com.pega.pegarules.services.soap.SOAPService
− com.pega.pegarules.services.soap.SOAPRequestHandler
− com.pega.pegarules.services.soap.SOAPUtils
− com.pega.pegarules.services.ServiceAPI
− com.pega.pegarules.services.ServiceHelper
Start with a logger for com.pega.pegarules.services.soap and increase the logging

level if necessary. If you need more information, enable logging for the other Java
classes in this list as needed.
SOAP Message Monitoring

While you debug a SOAP client application and SOAP service 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 client is constructing its SOAP
requests correctly, you need the SOAP message to make the determination.
Several SOAP viewing tools are available. When you use these tools, your workstation
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. To use tcpmon to
monitor the interaction between a SOAP client and Process Commander SOAP services,
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 name of the system that is running
Process Commander.
6. Click in the Target Port # field and specify the port number on which the
WebSOAP servlet is listening.
7. Click Add.
The tcpmon utility is now listening.
8. Click the tab that represents the listener you just configured.
9. In the SOAP client, edit the Service URL (which points at the Process Commander
system) so that it points at your workstation, including the port number that you
specified as the listener port in step 6 of this procedure.
For example, assume that the following is the Service URL specified for the Process
Commander system:
http://PRPCSystemServer:8080/prweb/PRSOAPServlet
You would edit it as follows:
http://localhost:port_number/prweb/PRSOAPServlet
Where port_number is the port number that you specified as the Listen Port # in step 3.
10. Run the SOAP client.
The tcpmon utility on your workstation intercepts the SOAP request and displays it in the
tcpmon window. The utility then forwards the request to the WebSOAP servlet that you
identified with the Target Hostname and Target Port # fields in steps 5 and 6 of this
procedure. The response from the WebSOAP servlet at that location is also intercepted by
the tcpmon utility and then passed on. Both the SOAP request and the SOAP response
appear in the tcpmon window.

Pega Soap

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pega Soap

Uploaded by

Copyright:

Available Formats

Building SOAP Services

PegaRULES Process Commander Versions 5.1 and 5.2

This document is the property of:

PegaRULES Process Commander

The SOAP Service ....................................................................................................6

Building SOAP Service Packages.........................................................................16

Running the Sample...............................................................................................32

The SOAP integration interface in PegaRULES Process Commander® (Process

This document contains the following sections:

■ The SOAP Service

■ Building SOAP Service Packages

■ Running the Sample

■ Building SOAP Service Packages

■ A PegaSample-IntSvcs RuleSet, which contains the Integration Services examples,

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

Summary of Steps for Building SOAP Services

3. Use the service package (instance of Data-Admin-ServicePackage) to generate a

About the SOAP Service Example

The SOAP sample has three parts:

■ The PegaRULES PhoneBook application

The Process Commander PhoneBook Application

■ The SampleBase-PhoneBook class rule represents the Phonebook element.

■ The SampleBase-Contact class rule represents the Contact element.

The Sample SOAP Service

■ Add a contact to a phonebook

■ Look up a phone number

■ Update a phone number

The PhoneBookUser Client Application

The PhoneBookUser application includes the following files:

■ The PhoneBookUser class file

The SOAP Service

Rule and Data Objects for a SOAP Integration

Service rule Receives messages from a SOAP client, maps incoming

Service activity Manipulates values on the clipboard, calls other activities

Each SOAP service rule has a service activity.

Figure 1. Summary of Components Required for SOAP Integration

Figure 2 illustrates the architecture of the SOAP service.

External SOAP Client

Figure 2. Architecture of a SOAP Service

The following describes how a SOAP service works:

5. The SOAP service rule invokes a service activity.

7. The service activity returns control to the SOAP service.

9. The SOAP service rule returns control to PRSOAPServlet.

10. PRSOAPServlet transmits the SOAP response to the SOAP client.

Process Commander and the PRSOAPServlet manage these default parameters

For more information about authentication, see “Running as an Authenticated User” on

■ In the Process Commander service package

Stateful sessions do not use requestor pooling.

1. Set the Processing Mode field in the service package to Stateful.

Running as an Unauthenticated User

Running as an Authenticated User

To configure a SOAP service to run as an authenticated user, complete the following

1. Determine how SOAP service requestors are to be authenticated. If they are to be

2. In the service package (Data-Admin-ServicePackage) on the Context tab, select the

Figure 3. Data Mapping for User Name and Password

Figure 4. Data Mapping for Requestor ID

WSDL Files and SOAP Operation Style

1. Remove the CharacterEncoding parameter from the servlet definition of WebSOAP

Building SOAP Service Packages

To create a SOAP service package, complete the following tasks:

■ Plan the SOAP Service

■ Create or Identify the Class Rule, Properties

■ Create the Service Activities