Creating a response for Service REST methods by using an automation implementation

For the GET, PUT, POST, PATCH, and DELETE methods, specify how the service rule constructs the response that Pega Platform sends in reply to the request. You can set up more than one response, based on conditions. You can also specify additional HTTP response codes to send with the response.

1. In your Service REST rule, click the Methods tab, and then click the method for which you want to construct a response.
2. Click the Response tab.
3. In the Condition field, select one of the following conditions:
   • Default – Send this response when there are no errors to report. If you plan to set up more than one condition, configure the Default condition as the last one in the list. To send an HTTP response code other than 200, specify a different code for the Default condition in the HTTP status code field.
   • When – The system evaluates the when condition specified by the When field. If the condition is true, the system returns the response message data. If the condition is false, the system evaluates the next when condition rule in the list. If all of the listed when condition rules are false, the system returns the default response data. Use this feature to extend the normal set of fatal error conditions that result in exceptions returned to the client, such as inappropriate inputs to the service activity, or other tests that you define.
   • Queue when – The system evaluates the when condition rule specified by the When field. If the condition evaluates to true, the system queues the service request and returns the queue item ID of the service request. If you configure a Queue When condition, you must specify a request processor in the Request Processor field on the Service tab. For more information, see Defining resource and processing details for a Service REST rule.
   • Mapping error – If an error occurs while mapping incoming data from a request message to the clipboard, the service returns the specified response message data. If the list of response conditions does not include an entry for mapping errors, Pega Platform returns the HTTP status code 500.
   • Security error – If an error occurs while authenticating the client credentials, Pega Platform returns the specified response message data. If the list of response conditions does not include an entry for security errors, Pega Platform returns the HTTP status code 401.
   • Service error – If a service error occurs, the system sends the specified response message data. If the list of response conditions does not include an entry for service errors, Pega Platform returns a standard error message.
   • Automation error – If you are using an automation as your implementation, you can list errors, specify a classification with which to group related errors, and configure a response that is specific to a group classification of errors. For example, when you map to an Automation input, Pega Platform uses the type of input to parse the request. If the system encounters a failure while parsing the input because it was not the expected type, an Invalid Inputs error is returned. If you specified a response condition for Mapping error and a condition for an Invalid inputs error, then the condition for the Invalid inputs error is used.
4. If you set the conditional value to When or Queue when, in the When field, specify the name (the second key part) of a when condition rule to evaluate for this condition.
   The system uses the first key part (the Applies To class) of the service activity as the first key part of the when condition rule.
5. If you set the conditional value to Automation error, in the Error classification field, define the classification of the error that Pega Platform sends in its response.
6. In the Response type field, select the type of response that you want to return to the external application.
   The default response is application/json. If you specify to build the response body from multiple outputs in step 9, this field becomes read-only.
7. Optional: In the HTTP status code field, enter an HTTP status code to return to the external application with the response.
   Note: If you selected Automation error, this field is read-only because each error classification is mapped to a specific HTTP code. To view this mapping, open the pxErrorClassificationToHttpStatusCode decision table.
8. If the response is to include a header other than the default headers, complete the following fields in the Headers section:
   1. In the Name field, enter the external name of the header field.
   2. In the Description field, enter a short description of the header field.
   3. In the Map from field, specify the source or the type of source of the value in Pega Platform:
      • Clipboard – Map from the page name or property on the clipboard specified by the Map from key field, or map from a parameter by specifying param.<some param name>.
      • Constant – The data is a fixed value.
      • Automation output – Map from the automation output that you specify in the Map from key field.
        Note: If you select a page type output, you must select a scalar property within that page using the Field within page option. You cannot map a header from a page or page list directly.
   4. In the Map from key field, specify the key to locating the property or rule in the source specified in the Map from field:
      • If the Map from value is Clipboard, enter the property name to which the data is mapped at run time.
      • If the Map from value is Constant, enter the value of the constant, surrounded by double quotation marks.
      • If you selected Automation output in step 8.c, select an automation output from the list of available outputs.
9. In the Message data section, in the How response body is built from outputs field, specify whether the response builds from one output or multiple outputs.
   • If you build a response from one output, go to step 9.a.
   • If you build a response from multiple outputs, go to step 10.
   1. In the Description field, enter a short description of the incoming string.
   2. In the Map from field, specify the source or the type of source of the value in Pega Platform:
      • Automation output – The source is an automation. If you select this option, review the following details:
        • If you specify a page type output, you can provide a JSON data transform to define how to turn the provided JSON into the page.
        • If you map to a page type output and do not provide a JSON data transform, the system uses a default JSON data transform. The JSON data transform is set to auto-map all and uses Pega API format as the date formatting option.
        • If you map to a page list type output, the system uses automapping logic to convert the JSON array into the page list. Pega API format is the date formatting option.
        • If you map to a scalar output, valid JSON of the same type is expected, for example, strings within quotations or Boolean. Dates are expected to be in Pega API format.
      • Clipboard – The source is a property or a page on the clipboard.
      • Constant – The source is a fixed value that does not change.
      • JSON – The source is a stream of JSON data formatted by a Page or Page List property.
      • XML stream – The source is a stream of XML data formatted by an XML Stream rule.
      • HTML stream – The source is a stream of HTML data formatted by an HTML rule.
      • HTML frame – The source is a stream of HTML data generated by the service activity.
   3. Optional: If you select JSON in step 9.b, the Use fast processing check box appears. Select this check box to improve processing speed.
   4. In the Map from key field, specify the key to locating the property or rule in the source specified in the Map from field.
   5. If you specified a page type input in step 9.d, in the JSON data transform field, select the JSON data transform that you want to use to turn the provided JSON into a page.
10. To build a response from multiple outputs, complete the following steps:
    Note: If you build from multiple outputs, the response is a JSON object.
    1. In the Name field, enter the name of the output to map to the response body.
       The values that you enter in the Name field for each output become the fields of the root JSON object.
    2. In the Description field, enter a short description for the incoming string.
    3. In the Map from field, select Automation output.
    4. In the Map from key field, select the key to locating the property or the rule in the source specified in the Map from field.
       The Map from and Map from key fields are used to specify what to do with the value in those root fields.
    5. If you specified a page type input in step 10.d, in the JSON data transform field, select the JSON data transform that you want to use to turn the provided JSON into a page.
11. Click Save.