To process service requests in your Pega Platform synchronously or asynchronously, create a Service SOAP rule. You use SOAP service rules when your Pega Platform applications needs to act as a web service.
The class and method name key parts of the Service SOAP rule are considered
and are unrelated to Pega Platform classes and methods, for flexibility.
For example, a service that is already exported and deployed on a client computer might be
changed to call a different Pega Platform activity. Because the external
representation and the WSDL file is not changed, you do not need to redeploy and modify the
application code on the client computer.
- In the header of Dev Studio, click .
- On the Service SOAP Record Configuration page, in the Label field, enter an identifier that describes the function of the Pega Platform activity that the service calls.
- In the Customer Package Name field, select the name of the
service package that is an instance of the Data-Admin-ServicePackage
class.This package groups related Service SOAP rules. Choose a name that is already defined through a Service Package data instance.
- In the Customer Class Name field, enter a class name to
logically group related methods.This name does not need to match the Pega Platform class to which the activity belongs, but must be a valid Java identifier.
- In the Context section, in the Apply to field, select the class to which this rule applies.
- Click Create and open.
- On the Service tab, in the Primary page
section, specify the page that the activity uses to call the SOAP service:
- In the Primary page class field, specify the Applies To class of the service activity.
- Optional: To identify a data transform that the system applies after creating the page, in the Data transform field, select a data transform in the class that you chose in the Primary page class field.
- In the Page name field, enter a page name for the class that
is specified in the Primary page class field, or accept the
default value MyServicePage.This field identifies the top-level clipboard page that Pega Platform uses as the primary page by the activity that the SOAP service calls. The activity property values might be written to or read from this page.The default page name has no special characteristics.
- To identify the activity that this Service SOAP rule calls, in the Service
activity section,complete the following fields:
- In the Activity name field, specify the name of the activity that provides the processing for this service rule.
- In the Parameters section, provide constant values for the
parameters of the service activity, in case not all values are mapped from the inbound
service request data.If a parameter value is the same for every service request, you can set that parameter's value in this section rather than requiring a client application to supply the value in each request. If a service activity starts a flow for a work item and the organization is always the same, you can specify the name of the organization on this tab.
- Optional: If you edit the parameters in the activity that you specified in the Activity name field, to display the changes in this section, click Refresh parameters.
- In the Style and use section, specify the parameters of the SOAP
messaging format for this service:
- To use the preferred style when all request and response data is contained in XML
literal parameters, select Document/literal.
Use when all data is mapped using XML mapping rules.
- To use the style for backwards compatibility, select
This style is not WS-I compliant. This style is deprecated, but provided for backward compatibility.
- To use the preferred style when either the request or response data contains
simple parameter values, select RPC/literal.
Use when mapping data to or from the clipboard.
- To use the preferred style when all request and response data is contained in XML literal parameters, select Document/literal.
- In the Processing options section, choose one of the following
- To apply the W3C Message Transmission Optimization Mechanism (MTOM) formatting to
binary data in SOAP messages, select Enable MTOM?.
This option is selected by default as the recommended format.
- To have the system end this requestor session when the activity completes, select
End requestor when done.
This check box affects only stateful processing. This check box is ignored when the Processing Mode on the service package data instance is set to Stateless.
- To indicate that each use of this service is not to count as a service invocation
under the terms of your license agreement, Method is read-only.
For more information, see Creating a license.
- To apply the W3C Message Transmission Optimization Mechanism (MTOM) formatting to binary data in SOAP messages, select Enable MTOM?.
- In the Execution mode field, choose how you want to run the
request:Each mode has an option for using both a request and a response, and a
one-wayoption for sending the service call and only receiving the HTTP Response status code (that is, 2xx).
When a queued service request runs, the run is performed with the authorization profile of the service.
- To immediately process the request and return the SOAP response, select Execute synchronously.
- To immediately process the request and return only the HTTP Response code, select Execute synchronously (one-way operation).
- To queue the request, return the response with the Queue Item ID to the caller, and then end the service call while processing starts, select Execute asynchronously (queue for execution).
- To queue the request, return only the HTTP Response status code, and then end the service call while processing starts, select One-way operation (queue for execution).
- If you select one of the asynchronous options in the Execution
mode field or you configure a Queue When condition on
the Faults tab, in the Request processor
field, select the name of the service request processor that is an instance of
Data-Admin-RequestProcessor-Service rule.The list in this field displays only the request processors that are defined for the same service package as this service rule.
- For synchronous execution modes, to configure a fallback activity for a time-out,
select Enable service SLA fallback activity.If you use a service SLA, you ensure that a logical response is made in a timely manner. Configure the fallback activity on the Methods tab. If a fallback activity is not configured, the default response is sent back.
- If you select Enable service SLA with fallback activity, choose
the method for setting the values in the Maximum duration for service activity
(milliseconds), Maximum consecutive violations, and
Retry internal (seconds) fields:
- To manually enter values or keep the default values in the Maximum duration for service activity (milliseconds), Maximum consecutive violations, and Retry internal (seconds) fields, select Provide values.
- To use the application settings to define the values in the Maximum
duration for service activity (milliseconds), Maximum
consecutive violations, and Retry internal
(seconds) fields, select Use application settings,
and then press the Down arrow key in each field to select an existing application
setting from the list.
At run time, the application uses the values in the application setting that correspond with the current environment. For example, if you specify 30 seconds for the retry interval for the Development value, the application uses a 30-second retry interval in your development environment at run time. If you do not specifry any values, the application uses the default values.
- If you select Enable service SLA with fallback activity,
configure the following options:
- In the Maximum duration for service activity (milliseconds)
field, enter the amount of time, in milliseconds, after which the service activity is
considered to have failed.
The default is 500 milliseconds.
- In the Maximum consecutive violations field, enter the
number of SLA violations that must occur before the fallback activity is called.
The default is 3.
- In the Retry interval (seconds) field,enter the amount of
time, in seconds, to wait before attempting to process the service activity.
The default is 10 seconds.
- In the Maximum duration for service activity (milliseconds) field, enter the amount of time, in milliseconds, after which the service activity is considered to have failed.
- In the Fallback activity name field, select a fallback activity
for the response when the SLA fails.
- If a parameter value is the same for every service request, to set that parameter's value rather than requiring a client application to supply that value in each request, in the Parameters section, provide the static values.
- If you edit the parameters in the activity that you specified in the Fallback activity name field, to display the changes in this section, click Refresh parameters.
- Click Save.