Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Creating a Service SOAP rule

Updated on November 23, 2022

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.

Before you begin: Create a Service Package data instance. The name of the Service Package data instance is the first key part of a collection of Service SOAP rules. For more information, see Creating a service package.

The class and method name key parts of the Service SOAP rule are considered external 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.

  1. In the header of Dev Studio, click CreateIntegration-ServicesService SOAP.
  2. 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.
  3. 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.
  4. 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.
  5. In the Context section, in the Apply to field, select the class to which this rule applies.
  6. Click Create and open.
    Result: The Service SOAP rule form opens on the Service tab.
  7. On the Service tab, in the Primary page section, specify the page that the activity uses to call the SOAP service:
    1. In the Primary page class field, specify the Applies To class of the service activity.
    2. 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.
    3. 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.
  8. To identify the activity that this Service SOAP rule calls, in the Service activity section,complete the following fields:
    1. In the Activity name field, specify the name of the activity that provides the processing for this service rule.
      For example: The activity can start a work item in a flow, or perform a flow action on an existing work item. This activity is known as the service activity.
      Result: The system uses the value that you enter in the Primary page class field as the Applies To key part of the activity. The system creates a page with the name that is provided in the Page name field and passes the page to the activity as the primary page. If the Page name field is blank, the system passes the activity an unnamed page.
    2. 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.
      Note: If you set a parameter value and also map that value from inbound request data, the inbound request data value overrides the value that you set on this Service tab.
    3. 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.
  9. 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 RPC/encoded.

      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.

  10. In the Processing options section, choose one of the following processing configurations:
    • 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.

  11. 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-way option for sending the service call and only receiving the HTTP Response status code (that is, 2xx).
    Note: Choose one of the asynchronous options only if a Service Request Processor data instance (Data-Admin-RequestProcessor-Service class) exists with a key that matches the Service Package key part of this service rule:

    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).
  12. 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.
  13. For synchronous execution modes, to configure a fallback activity for a time-out, select Enable service SLA fallback activity.
    For example: If the service activity is not finished after a configured amount of time and the maximum number of violations has occurred, the system calls the fallback activity. The system does not attempt further requests until the retry interval has passed. If the next attempt is successful, the system resumes normal processing.
    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.
  14. 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.
      Note: For services that were created in earlier versions than Pega Platform 8.3, this option is selected by default.
    • 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.

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

  16. In the Fallback activity name field, select a fallback activity for the response when the SLA fails.
    For example: The fallback activity can display a default offer to an ATM customer instead of an offer based on the particular customer's data. If you do not select a fallback activity, the default response is sent back.
    • 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.
  17. Click Save.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us