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
service activities
apply to
Samplebase-Phonebook
Properties for
service activity
class
SampleBase-Phonebook:
Name = Title, mode = Single Value
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
18 0BBuilding SOAP Services
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 Workbase
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
0BBuilding SOAP Services — 3BBuilding SOAP Service Packages 19
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.