How You Integrate With REST Services Using Rules

You can use rules to call GET operations on REST services registered in the Oracle Fusion Customer Relationship Management Application Composer.

Calling REST GET from Item Rules

You can use either of these functions to call the GET operation of a REST service, depending on your how you need to access data through the service, and how the REST service handles queries for data.

Function	Use Function To:
`InvokeRestGet( rest_service_name, map_of_query_parameters, return_value_expression, http_header_map)`	Pass in any combination of names and values to the GET's q query parameter. Use when the REST service is registered in Application Composer without any tokens in its URL.
`InvokeRestGetWithTokens( rest_service_name, token_value1, ... , token_value_n, return_value_expression)`	Pass in values for tokens representing attributes. Use when the REST service is registered in Applications Composer with tokens in its URL. Note that you can't pass in arbitrary query parameters if the URL contains tokens.

Function

Use Function To:

InvokeRestGet(
rest_service_name, 
map_of_query_parameters, 
return_value_expression, 
http_header_map)

Pass in any combination of names and values to the GET's q query parameter.

Use when the REST service is registered in Application Composer without any tokens in its URL.

InvokeRestGetWithTokens(
rest_service_name, 
token_value1, ... , token_value_n, 
return_value_expression)

Pass in values for tokens representing attributes.

Use when the REST service is registered in Applications Composer with tokens in its URL.

Note that you can't pass in arbitrary query parameters if the URL contains tokens.

For details about these functions, see the topic on item rule utility functions.

Keep these points in mind:

To call a REST service from a rule, you must first register the service Application Composer, as described in the following section.
To pass a map of name/value query parameter pairs to InvokeRestGet(), use the internal function ToMap().
To pass tokens to InvokeRestGetWithTokens() that require escaping of certain characters and words, or to pass the q parameter when calling InvokeRestGet() that requires specific escaping and formatting you can use the internal Replace() function to perform character escaping such as replacing " in an attribute value with \".

Register the REST Service

Before you call a REST service from a rule, you must register the service in Application Composer.

The details for registering a REST service are provided in the Configuring Applications Using Application Composer guide. Here's a summary of the steps:

You must be in a sandbox in order to register the web service in Apps Composer. Do the following to create and enter a sandbox.
1. Sign in with the application implementation consultant privileges.
2. Select Sandboxes from the Configuration section of the Navigation menu.
3. Click Create Sandbox. On the create Sandbox page, select Application Composer in the All Tools list. Click Create and Enter to enter the sandbox.
Inside the sandbox, select Application Composer from the Tools menu.
Click on the Web Services link, either in the Overview page or in the Common Setup list in the left pane.
Click the Create Web Service Reference button on the toolbar, select REST in the Select Connection Type dialog box, then click OK.
On the Create REST Web Service Connection page, enter your choice of name for the new REST service, keeping in mind that you will use this name to call the REST service from item rules.
On the Create REST Web Service Connection page, enter the URL for the REST service in the URL field. For example, you could use this URL to register the Product Management data security REST service:
```
https://vision.com/fscmRestApi/resources/latest/productManagementDataSecurities
```
You can specify tokens in the web service URL by using the form ##TOKEN_NAME##. Values for these tokens can then be passed in when calling the REST service. For example, you could use this URL to register the PIM data security REST service:
```
https://vision.com/fscmRestApi/resources/latest/productManagementDataSecurities?q=ObjectName=Item;Principal=Person;Name=##USER_NAME##;ItemClass=##ITEM_CLASS##;OrganizationCode=##ORG_CODE##
```
When this service is called from item rules, the rule must pass in values for all the tokens. In this example, URL contains the tokens USER_NAME, ITEM_CLASS, and ORG_CODE, which allows the rule to query data grants for a given user name, item class, and organization.
Note:
- If the REST URL doesn't contain tokens, then item rules will be able to call the GET operation and pass in any combination of names and values to the GET's q query parameter.
- If the REST URL does contain tokens, then item rules will only be able to pass in values for those tokens when calling the GET operation. It won't be possible to pass in arbitrary query parameters if the URL contains tokens.
On the Create REST Web Service Connection page, you can select an Authentication Scheme that should be used to call the REST service. For Product Management REST services, this scheme can generally be either Call with basic authentication or Propagate user identity using SAML.
- If you select Call with basic authentication, then you will set a user name and password that will always be used to call the REST service. For example, you could set the user name and password JSmith and xxyyzz99 are always used to call the REST service. In that case, even if you log in to the Product Information Management work area as an application implementation consultant and create an item, then the user name and password JSmith and xxyyzz99 will be used to call the REST service from item rules.
  
  When selecting Call with basic authentication you need to select the credentials that will be used to call the web service. You can select one of the existing entries in the Credential Key field. If the correct credential don't exist in the field you can click Create Credential Key to create a new key with the desired user name and password.
- If y u select Propagate user identity using SAML, then, when a user tries to create or edit an item in the Product Information Management work area, that same user's credentials will be used when trying to call the REST service from item rules. For example, if you're logged in as an application implementation consultant when creating an item, then the REST service invocation from item rules will fail if the application implementation consultant doesn't have privileges to call the REST service.

On the Create REST Web Service Connection page, in the Select and configure Methods against the Resource section, will set the operations that will be used on this REST service. You must check the GET check box here since that operation will be called from item rules. Only the following settings are supported when calling the GET operation from item rules.

Setting	Value
Method Name	GET
Format	JSON
Request Payload	Schema URL
Response Payload:	Code Sample To provide a code sample, enter a sample response copied from output of the REST service's GET operation.

Click Save and Close to save the REST service.
Once the REST service has been registered in Application Composer the sandbox must be published for the REST service to be accessible to item rules. To publish the sandbox, select Publish from the sandbox menu, then click the Publish button.