Use the Service tab of the Service REST rule to configure the mapping of the URL path parameters, data transforms, and other configuration options for your service.
- On the Service tab of your Service REST rule, configure the page
class or the resource depending on which Pega Platform version you are
Pega Platform version Actions Pega Platform versions later than 8.4 In the Resource properties section, in the Resource field, enter the class of the primary page for this service. Pega Platform versions prior to 8.4
- In the Primary page section, in the Page class field, enter the class of the primary page for this service.
- In the Data transform field, specify a data transform to run on the service page before processing the request. Use this option to set defaults on the page.
- In the Page name field, enter a name for the page so
that you can reference it from other rules. If you leave this field blank, a
page name is automatically generated.
Note: You can refer to the page as Primary from the Service REST rule and the activity or automation that it calls.
- In the Resource properties section, specify the URI path
- In the Name field, enter the name of the variable resource parameter in the resource path.
- In the Description field, enter a description for the variable resource parameter.
- In the Map to field, select the destination or the type of
destination for the value in Pega Platform.
- Clipboard – Map to the page name or a property on the clipboard specified by the Map to key field.
- Automation input – Use an automation to implement the method. If you select this option for any resource path parameters, you must use an automation as your implementation for each method that you implement in your rule.
- In the Map to key field, specify the key used to locate the
property or the rule in the destination that you specify in the Map
- If the Map to value is Clipboard, enter the property name to which to map the data at run time.
- If the Map to value is Automation input, this field is not editable. You specify the Map to key values on the Request tab of the method that you want to implement.
Note: The following fields are read-only:
- Service endpoint URL – Displays the complete URL for the REST endpoint.
- URI template – Displays the name of the URI template that was created or edited on the Create Service REST page.
- URI path parameters – URI path parameters are automatically populated from the URI template that was created or edited on the Create Service REST page. These parameters can be literal or variable values. Variable parameters are populated with values at run time.
- In the Processing options section, specify the following
- End Requestor When Done – When the Processing mode field on the service package is set to Stateful, you can select this option to have the system end the requestor after the activity ends and the response is sent. If the services are stateless, the value in this field is ignored. For more information, see Defining processing and authentication for service packages.
- Method is read-only – You can select this option to indicate that each use of this service does not count as a service invocation under the terms of your license agreement. For more information, see License compliance.
- Enable service SLA with fallback activity – You can select
this option to configure a fallback activity for a time-out. For example, when the
service activity is not finished after a configured amount of time and the maximum
number of violations has occurred, the fallback activity is called. No further requests
are attempted until the retry interval has passed. If the next attempt is successful,
normal processing is resumed.
If you select Enable service SLA with fallback activity, the following options are displayed:
- Maximum duration for service activity (milliseconds) – Enter the amount of time, in milliseconds, after which the service activity is considered to have failed. The default is 500 milliseconds.
- Maximum consecutive violations – Enter the number of SLA violations that must occur before the fallback activity is called. The default is 3.
- Retry interval (seconds) – Enter the amount of time, in seconds, to wait before attempting to process the service activity. The default is 10 seconds.
- Optional: If you select Enable service SLA with fallback activity, you can
choose the method for setting the values in the Maximum duration for service
activity (milliseconds), Maximum consecutive
violations, and Retry internal (seconds)
- Provide values – Select this option to manually enter
values in the Maximum duration for service activity
(milliseconds), Maximum consecutive violations, and
Retry internal (seconds) fields, or keep the default
Note: For services created prior to Pega Platform 8.3, this option is selected by default.
- Use application settings – Select this option 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.
Use the Down arrow key in each field to select an existing application setting from the
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 no values are specified, the application uses default values.
- Provide values – Select this option to manually enter values in the Maximum duration for service activity (milliseconds), Maximum consecutive violations, and Retry internal (seconds) fields, or keep the default values.
- To run the service with lightweight clipboard pages, in the Lightweight
clipboard mode section, select the clipboard page that you want to use.
- Select Use application settings.
- In the Setting name field, press the Down arrow key and select a clipboard page.
Note: Lightweight clipboard pages have better throughput than typical clipboard pages. By enabling lightweight clipboard mode, REST service execution is more performant because the system is running the service only with the following basic clipboard features:
- Hierarchical structure – Arbitrarily deep and complex tree structure formed by pages, lists, groups, and so on.
- JAVA objects – Pages can be wrapped around Java objects.
- Complex references – APIs on the page support arbitrarily complex property reference strings, including list subscript symbolics such as <APPEND>, <FIRST>, and so on.
- Messaging – Message metadata can be attached to properties and pages, for example, as a result of validation, Rule-Declare-Constraints, or various APIs and activity methods
- Dictionary – Information specified on the Property rule form is available during clipboard processing.
- Serialization/deserialization – Save page structure and contents for storage on disk or in a database, then later restore the page into memory.
Due to complexity, the following clipboard features are not supported with lightweight clipboard mode:
- Properties referencing a data page
- Linked properties
- Referenced properties
- Limited support for declaratives
- Limited support for declare expressions/backward and forward chained
- Change tracking for property value updates in the user interface
- In the Execution mode field, choose from the following
- Execute synchronously – Select this option if you want the service to run the request immediately.
- Execute synchronously (queue on error) – Select this option
when you want the service to queue the request for asynchronous execution only if
processing fails while executing the service activity.
Note: If no processing errors occur, the result is the same as a normal synchronous request. If a processing error occurs, the error details are stored in a Service Request Processor data instance (Data-Admin-RequestProcessor-Serviceclass), along with the request data that was originally mapped to the clipboard. The service returns the Queue Item ID to the external application, and the request is either reprocessed automatically by an Agent configured for queue processing, or manually by a system administrator.
- Execute asynchronously (queue for execution) – Select this
option when you want the service to queue the request for asynchronous execution, return
the Queue Item ID to the external application, and end the service call while the
Note: Choose this option only when a Service Request Processor data instance (Data-Admin-RequestProcessor-Serviceclass) exists with a key that matches the Service Package key part of the service rule. This means that when the queued service request executes, the execution is performed with the authorization profile of the service.
- In the Request processor field, select a request
processor.The list in this field displays only the request processors that are defined for the same service package as this service rule. If you have not defined a request processor, click the rule opener to create a new one.
For more information, see Service Request Processor data instances.
Note: If you select Execute asynchronously (queue for execution) in the Execution mode field, or you configured a
Queue Whencondition on the Response tab of the service rule, you must also select the name of the service request processor (the instance of (Data-Admin-RequestProcessor-Serviceclass)).
- To specify whether to monitor this rule, and whether to include the clipboard state
when monitoring, in the Service monitoring field, click
Note: Service package monitoring configuration settings are used only if the service/EnableGlobalMonitoring dynamic system setting is set to Deferred and the service package is set to As defined on service rule.
- To enable monitoring for this rule, in the Select service monitoring field, select Yes.
- If you enable monitoring and you want to include the state of the primary data page in the monitoring results, in the Capture clipboard state field, select Yes.
- Click Submit.
- Optional: The Service package (includes additional processing options) displays a link to the service package that contains this service REST rule. To easily navigate to the service package if you need to make changes to it, click the link.
- Click Save.