Configuring a REST connector
Create a Connect REST rule and identify the external system with which this connector rule communicates.
- In the header of Dev Studio, click .
- On the Create form, enter values in the fields to define the
context of the flow.
- In the Label field, enter text that describes the purpose of the circumstance definition.
- Optional: To change the default identifier for the circumstance definition, click Edit, and then provide a unique value in the Identifier field.
- Select the Context.
- In the Apply to field, press the Down Arrow key and select the class that defines the scope of the circumstance definition.
- In the Add to ruleset field, select the name and version of a ruleset that stores the circumstance definition.
- Click Create and open.
- 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.
- 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.
- In the Resource path parameters section and Query
string parameters section, complete the following fields:
- In the Name field, enter the name of the resource parameter.
- In the Map from field, specify the type of source of 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Use the Security settings section to configure the Truststore
and Keystore settings to secure your connection with the external system.
- 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.
- 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.
- Optional: In the Connection section, complete the following fields:
- 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 ispyResponseTimeout
. For more information, see Using the Global Resource Settings feature. - 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.
- 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.
- 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.
- Optional: In the Error handling section, complete the following
fields:
- 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. - 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.
- 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.
- In the Status value property field, select a property to
hold the status code of the Connect REST method. The literal value
- 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.
- 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.
- 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.
- In the Intended for field, choose from the following
options:
- Click Save.
Previous topic Connect REST rules Next topic Mapping the request and response data for Connect REST rules