Skip to main content


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

Creating a Connect REST rule

Updated on April 6, 2022

Create a Connect REST rule and identify the external system with which this connector rule communicates.

Note: When you open a REST connector that was created before Pega Platform 8.3, you can upgrade the connector so that it supports all URL components. To upgrade a REST connector, click Upgrade to new endpoint configuration on the Service tab.
  1. In the header of Dev Studio, click CreateIntegration-ConnectorsConnect REST.
  2. On the Create form, enter values in the fields to define the context of the flow.
    1. In the Label field, enter text that describes the purpose of the circumstance definition.
    2. Optional: To change the default identifier for the circumstance definition, click Edit, and then provide a unique value in the Identifier field.
    3. Select the Context.
    4. In the Apply to field, press the Down Arrow key and select the class that defines the scope of the circumstance definition.
    5. In the Add to ruleset field, select the name and version of a ruleset that stores the circumstance definition.
  3. Click Create and open.
  4. On the Service tab, in the URL Configuration section, choose from the following options.
    • Select Provide URL to display the Endpoint URL field and enter the URL of the external system that you want to connect to.
      Note: Braces {} in the URL denote a dynamic resource parameter that must be mapped to a clipboard property or a constant in the Resource path parameters section. For example, in the URL http://restServiceHostName/CustomerDB/resources/entities.customer/{id}, the parameter ID is the dynamic resource parameter.
    • Select Use application setting to reference an application setting that defines the base URL for the external system that you want to connect to.

      When you select Use application setting, the Base URL field is displayed. Press the Down arrow key to select an existing application setting from the list or select Create New Setting.

  5. In the Resource path parameters section and Query string parameters section, complete the following fields:
    Note: If you selected Use application setting in step 1, the Resource path and Query string fields are populated with the parameters that you set in the Resource path parameters and Query String parameters sections.

    The Resource path field does not support Global Resource Settings.

    1. In the Name field, enter the name of the resource parameter.
    2. In the Map from field, specify the source type for the value:
      • Select Clipboard to map from the page name or property on the clipboard that is specified by the Map from key field.
      • Select Constant to specify that the data is a fixed value that does not change.
      • Select Parameter (query string parameters only) to map from a parameter on the connector parameter page.
    3. In the Map from key field, specify the name (key) of the property or the parameter that holds the value that should be mapped to the URL parameter.
      • If you chose map from Clipboard, enter the property name from which the data is mapped at run time.
      • If you chose map from Constant, enter the value of the constant surrounded by double quotation marks.
      • If you chose map from Parameter (query string parameters only), enter the name of the parameter from which the data is mapped at run time.
    4. In the Empty behavior field, specify which action to perform if a query string parameter is empty:
      • Select Throw error/required to indicate that the parameter value is required and cannot be empty. An error occurs if the value is empty at run time.
      • Select Name only so that only the parameter name is appended to the URL.
      • Select Name= blank value so that the parameter name and an = character is appended to the URL.
      • Select Skip so that the parameter is not appended to the URL.
    5. In the Encoding field, specify whether to do URL encoding on the URL parameter:
      • Select URL to encode the parameter value before the parameter is appended to the URL.
      • Select Already encoded so that the parameter value is not encoded before the name-value pair is appended to the URL.
  6. In the Integration system section, press the Down arrow key to select the integration system to use as the system of record.
    You can select any user-defined system or robotics. The Pega integration system is not available in this list.
  7. In the Authentication section, choose from the following options:
    • Select the Use authentication profile option and press the Down arrow key in the Authentication profile field to select the authentication profile that contains the authentication details that the remote service requires.
    • Select Use application setting to use an application setting to specify the name of the authentication profile that you want to use for each production level.

      When you select Use application setting, press the Down arrow key in the Authentication profile field to select an existing application setting from the list, or select Create New Setting.

  8. Use the Secure protocol configuration section to configure a secure protocol to connect to the external system. In the Lowest allowable SSL/TLS version field, select the version of SSL or TLS protocol that you want to use to securely connect to the external system with which this connector rule communicates.
  9. Use the Security settings section to configure the Truststore and Keystore settings to secure your connection with the external system.
    1. In the Truststore field, press the Down arrow key to select or create a Truststore record that contains the server certificate to use in the TLS/SSL handshake.
    2. In the Keystore field, press the Down arrow key to select or create a Keystore record that stores the Pega Platform client's private/public key pair that is used by the server to authenticate the client. For more information about Keystores, see About Keystore data instances.
  10. Optional: In the Connection section, complete the following fields:
    1. In the Response timeout field, enter the number of milliseconds after which this rule times out with a failure message if it does not receive a response. Enter zero or leave blank to wait indefinitely.
      This field is disabled and ignored at run time when the Intended for field is set to queuing.

      This field supports the Global Resource Settings syntax (=PageName.PropertyName). The default property name for this field is pyResponseTimeout. For more information, see Using the Global Resource Settings feature.

    2. Select Maintain session to use HTTP token-passing as the mechanism for maintaining a stateful session with the Web service provider. If selected, enter the connection ID value in the Connection ID field.
      This field is disabled and ignored at run time when the Intended for field is set to queuing.
    3. If the external system uses HTTP token passing to maintain stateful session data between requests, use the Connection ID field to specify that a group of logically related connectors shares a single session. Enter an arbitrary text value in this field, and enter the same text value in the other REST connector rules that are to share the session data.
    4. To enable the connector to follow a 3xx response on a GET request, select Follow redirects.
      Result: The connector resolves the location header by using a GET call, and maps the redirected response message to the clipboard.
    5. To enable the connector to follow the 3xx response for POST, PUT, DELETE methods, select Enable lax redirection.
    6. If you selected Enable lax redirection in step 10e, click Add host to make sure that the connector follows lax redirects.
      Result: The connector resolves the location header by using a POST, PUT, or DELETE call, and maps the redirected response message to the clipboard.
  11. Optional: To specify a proxy for your REST connector, in the Proxy section, select Use proxy, and then configure the remaining proxy parameters:
    1. In the Host field, enter the address of the proxy host.
    2. In the Port field, enter the port number.
    3. In the Authentication field, select the type of authentication to apply to the proxy:
      • To avoid using any authentication, select Not applied.
      • To use an authentication profile for the proxy, select Use authentication profile, and then enter or select the authentication profile in the Authentication profile field.
      • To use an application setting for the proxy, select Use application setting, and then enter or select the application setting that holds the authentication details to use in the Authentication profile field.
  12. Optional: In the Error handling section, complete the following fields:
    1. In the Status value property field, select a property to hold the status code of the Connect REST method. The literal value Good identifies success. You can use the standard property @baseclass.pyStatusValue.
    2. In the Status message property field, select a property to hold status descriptions or return values from the external system that are by the Connect REST method. You can use the standard property @baseclass.pyStatusMessage.
      This field is disabled and ignored at run time when the Intended for field is set to queuing.
    3. In the Error handler flow field, identify a flow rule to route work items that cannot continue in its current flow because this connector rule was unable to connect to the external system. The default flow rule Work-.ConnectionProblem provides one approach for handling such problems. See Handling connector exceptions.
  13. Optional: Use the Processing options section to allow connector requests from this Connect REST method to be processed asynchronously in parallel with the calling activity, or in the background by an agent. The mode of execution of each connector request is determined by the Execution mode parameter of the Connect REST method, as enabled by the values in the following fields.
    1. In the Intended for field, choose from the following options:
      • immediate execution — the REST connector run synchronously; the calling activity waits for results.
      • queuing (response will not be available) — the REST connector executes asynchronously, with calls placed in a queue. The calling activity continues without waiting for results.

        Queuing, when selected, occurs only if also specified in the Connect REST method.

    2. If you selected queuing for the Intended for field, use the Request processor field to identify a Connect Request Processor data instance that defines the classes and other characteristics of the queued connector requests. The Connect Request Processor data instance must also have a ruleset key part that matches the ruleset of this Connect REST rule.
  14. Click Save.
What to do next: After you complete and save the rule, you can do the following:
  • Click Test connectivity to test whether Pega Platform can connect to the external system. Pega Platform verifies the connectivity to the service URL/endpoint. It does not confirm the ability to authenticate with the service.

    The system presents test results in a separate window, which identifies the parameters used in the test, the steps attempted, and the outcome of each step.

  • Click Simulations to create a simulator for this connect rule. See Connect Simulators.
  • Map the request and response data for your Connect REST rule.
  • Define the input parameters of your REST connector on the Parameters tab. For more information, see Defining the input parameters of a rule.

Related articles

Connect REST rulesJSON mapping for special characters

Tags

Pega Platform 8.6 Data Integration

Have a question? Get answers now.

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

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

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