Integrate with Oracle SaaS REST Services

Registering the Base URL

To integrate with a REST endpoint, you must first register it as a variable in Application Composer so that you can later include that variable in your Groovy scripts. When you register the REST endpoint, you don't have to specify the entire endpoint. Instead, to save time, you can register only the base URL so that the REST endpoint is reusable. Later, in your Groovy script, you can specify the rest of the endpoint. For example, in your Groovy script, you can reference the base URL and then specify if you're making a call to retrieve information about contacts or accounts.

Let's look at an example. In this example, you will register a base URL. In the next section, you will use the base URL in a Groovy script.

First, register the base URL:

In Application Composer, under Common Setup, click Web Services.
Click the Create Web Service Reference icon.
Select REST, then OK.
Enter the variable name for this reference. For example, GetObjects.
Enter the base URL for the REST endpoint that you want to integrate with. For example:
```
https://<host:port>/crmCommonApi/resources/latest/##Object##
```
Use basic authentication. Select Call with basic authentication.
In the Credential Key field, specify a name for the secret key that can be used to access the web service. This key name along with the user name and password is stored in the credential store.

Next, select and configure methods against the resource. You can register the resource operation (GET, POST, and so on) and the associated payload format type (JSON/XML). Only registered operations appear in the Groovy expression builder. In this example, configure a GET method.

Field	Value
Method Name	GET
Format	JSON
Request Payload	Schema URL
Response Payload	Code Sample
Code Sample	`{ "items" : [ ], "count" : 0, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "<host:port>/crmCommonApi/resources/11.1.12/T1_c", "name" : "T1_c", "kind" : "collection" } ] }`

Finally, use the base URL in a Groovy script. Read the next section to learn how.

Appending to the Base URL

After you register the base URL, you can then reference the base URL in your Groovy scripts and manipulate the REST endpoint to specify which object you want to integrate with. For example, you can reference the same base URL to query either contacts or accounts. To do this, further append to the URL to specify which object you want to integrate with.

Continuing the example from the previous section, let's now reference the REST endpoint in a Groovy script.

def conn = adf.webServices.GETObjects
try{
  def Object = "contacts"
  def result = conn.GET(Object)
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Contacts:"+contacts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Output"+conn.httpErrorResponse)
}

To query accounts using the same base URL, use this Groovy script:

def conn = adf.webServices.GetObjects
try{
  def Object = "accounts"
  def accounts = conn.GET(Object)
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Accounts:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Output"+conn.httpErrorResponse)
}

Dynamically Passing Parameters in Your Groovy

When integrating with a REST endpoint, you can pass a parameter to refine your query. For example, when querying contacts, you might want to retrieve information for a particular party ID. You can do this without hard coding the party ID by dynamically passing the party ID in your Groovy script.

You can dynamically pass parameters based on where your Groovy is being called from. The page where the script is called from has context which you can use. For example, the page has context about the logged-in user, or about the contact record that the user is viewing. When you provide the URL, you can specify the party ID as a URL parameter.

Let's say that you defined a custom attribute to hold contact address information in a denormalized (concatenated) form. You require the denormalized form of the address to sync contact information into one of your legacy systems. You can achieve this use case by querying the Contacts API to fetch the address using Party Number as the parameter.

In this case, the REST endpoint would be:

https://<host:port>/crmCommonApi/resources/latest/contacts/##PartyNumber##/child/Address

And your Groovy script could look like this:

def ContactAddressAPI = adf.webServices.ContactAddressAPI
try
{
def contactAddress = ContactAddressAPI.GET("<PartyNumber>")
def address1 = contactAddress.items[0].Address1
def address2 = contactAddress.items[0].Address2
def city = contactAddress.items[0].City
def state = contactAddress.items[0].State
def country = contactAddress.items[0].Country
def postalCode = contactAddress.items[0].PostalCode

def denormalizedAddress = address1 + ", " + address2 + ", " + city + ", " + state + ", " + country + ", " + postalCode 
return denormalizedAddress //concatenated address

 }
  catch(Exception ex)
{
println(ContactAddressAPI.statusCode+""); //for diagnostic logging
println(ContactAddressAPI.httpErrorResponse+""); //for diagnostic logging
throw ex;
}

Using Finders

In your Groovy scripts, you can further refine the records that you retrieve by using finders to search a collection of data. Finders are predefined with your cloud service and are similar to a saved search. In your script, you state the finder name and include corresponding finder variables, if any, depending on the finder that you're using.

As mentioned earlier, you can attach the PartyNumber directly to the REST endpoint URL itself to retrieve a specific contact. For example:

https://<host:port>/crmCommonApi/resources/11.12.1.0/contacts/##PartyNumber##

Or, use a finder in your script. Each object in your cloud service is shipped with a set of finders. For example, the following are the available finders for the Contact REST endpoint:

ContactPartyNumberRF: Finds contacts by party number.
MyContacts: Finds a contact from My Contacts.
MyBusinessContacts: Finds a contact from My Business Contacts.
MyFavoriteContacts: Finds a contact from My Favorite Contacts.
PrimaryKey: Finds a contact with the specified primary key.

The format to use a finder is:

?finder=<finderName>;<variableName>=<variableValue>,<variableName2>=<variableValue2>

Let's look at an example of using a finder. In this example, you will use the PrimaryKey finder to find a contact with the specified primary key. The variables for this finder are:

PartyId (integer)

The Oracle record ID for the contact.
PersonProfileId (integer)

The unique identifier of the contact.

First, let's register the endpoint:

In Application Composer, under Common Setup, click Web Services.
Click the Create Web Service Reference icon.
Select REST, then OK.
Enter the variable name for this reference. For example, Contact_Basic.
Enter the URL for the REST endpoint that you want to integrate with. For example:
```
https://<host:port>/crmCommonApi/resources/latest/contacts
```
For security, use basic authentication. Select Call with basic authentication.
In the Credential Key field, specify a name for the secret key that can be used to access the web service. This key name along with the user name and password is stored in the credential store.

Next, select and configure methods against the resource. You can register the resource operation (GET, POST, and so on) and the associated payload format type (JSON/XML).Only registered operations appear in the Groovy expression builder. In this example, configure a GET method.

Field	Value
Method Name	GET
Format	JSON
Request Payload	Schema URL
Response Payload	Code Sample
Code Sample	`{ "items" : [ ], "count" : 0, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c", "name" : "T1_c", "kind" : "collection" } ] }`

After you register the endpoint, you can then reference the endpoint and use the PrimaryKey finder in your Groovy script. The following example illustrates the use of both a finder, the fields parameter, and the query parameter in a single call to the Contact REST endpoint. (See the next two sections for discussions about the fields parameter and the query parameter.)

def conn = adf.webServices.Contact_Basic
try{
  //Using finder and field parameters
  def queryParams = ['finder':'PrimaryKey;PartyId=100000017340195','fields':'PartyId,PartyNumber']
  conn.dynamicQueryParams = queryParams
  def contacts = conn.GET()
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Contact after applying finder and field query parameters:"+contacts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

For more information about finders and their corresponding finder variables that are available for each object, refer to the REST API documentation for your cloud service.

Passing Other Types of Parameters

Passing a parameter or using a finder are just two ways of modifying a REST endpoint. REST APIs also support queries that can filter a collection resource through the use of the q and fields parameters.

?q

This query parameter defines the where clause. The resource collection will be queried using the provided expressions.

The format to use the ?q parameter is:
```
?q=expression1;expression2 
```
For example, maybe you want to retrieve all contacts in NY who belong to a specific department.
```
?q=Deptno>=10 and <= 30;Loc!=NY
```
?fields

This parameter filters the resource attributes. Only the specified attributes are returned, which means that if no attributes are specified, no attributes are returned (useful to get only the links). Use this parameter to specify the fields that you want to retrieve with this call.

The format to use the ?fields parameter is:
```
?fields=Attribute1,Attribute2
```

For more information about additional parameters that you can attach to REST calls, refer to the REST API documentation for your cloud service.

Making Query Parameter Calls

In addition to passing parameters as described earlier, you can also make query parameter calls.

You can define a query parameter and pass it directly. Or, define a payload and then pass the payload.

For example, define the query parameter itself. Note the response method is GET.

def queryParam = [OpptyId:'6756253']
OpptyDC.dynamicQueryParams = queryParam
def response = adf.webservices.OpptyDC.GET()

Or, define a payload and add it to the REST endpoint. This is especially useful when trying to create or update a record. Note the response method in the following example is POST.

def requestPayload = [OpptyName:'GreenServerTech', Account:'Pinnacle', Owner:'Lisa.Jones']
def response = adf.webservices.OpptyDC.Post(requestPayload)

Let's look at an example of defining a query parameter for a specific account record. In this example, you will define a query parameter and also pass the q parameter.

First, let's register the endpoint:

In Application Composer, under Common Setup, click Web Services.
Click the Create Web Service Reference icon.
Select REST, then OK.
Enter the variable name for this reference. For example, GetAccountUsingSAML.
Enter the URL for the REST endpoint that you want to integrate with. For example:
```
https://<host:port>/crmCommonApi/resources/latest/accounts
```
For security, use the Security Assertion Markup Language (SAML) over Secure Socket Layer (SSL) authentication scheme. Select Propagate user identity using SAML over SSL.

Next, select and configure methods against the resource. You can register the resource operation (GET, POST, and so on) and the associated payload format type (JSON/XML).Only registered operations appear in the Groovy expression builder. In this example, configure a GET method.

Field	Value
Method Name	GET
Format	JSON
Request Payload	Schema URL
Response Payload	Code Sample
Code Sample	`{ "items" : [ ], "count" : 0, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c", "name" : "T1_c", "kind" : "collection" } ] }`

After you register the endpoint, you can then reference the endpoint and, in this example, pass both the query parameter and q parameter in your Groovy script.

def conn = adf.webServices.GetAccountUsingSAML
try{
  // Provide query parameter for the account object you want to receive 
  def queryParams = ['q':'PartyId=300100010638186']
  conn.dynamicQueryParams = queryParams
  def accounts = conn.GET()
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

Creating POST Requests

You can execute standard methods such as GET, POST, PATCH, and DELETE on REST resources, using their URL. In this section, let's review POST requests.

Use a POST request to create a new item in a resource. The request content type is:

application/vnd.oracle.adf.resourceitem+json

Let's look at two POST requests. First, let's register the endpoint:

In Application Composer, under Common Setup, click Web Services.
Click the Create Web Service Reference icon.
Select REST, then OK.
Enter the variable name for this reference. For example, Account_SAML.
Enter the URL for the REST endpoint that you want to integrate with. For example:
```
https://<host:port>/crmCommonApi/resources/latest/accounts
```
For security, use the SAML over SSL authentication scheme. Select Propagate user identity using SAML over SSL.

Next, select and configure methods against the resource. You can register the resource operation (GET, POST, and so on) and the associated payload format type (JSON/XML).Only registered operations appear in the Groovy expression builder. In this example, configure a POST method.

Field	Value
Method Name	POST
Format	JSON
Request Payload	Code Sample
Code Sample	{"OrganizationName":"M1"}
Response Payload	Code Sample
Code Sample	`{ "items" : [ ], "count" : 0, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c", "name" : "T1_c", "kind" : "collection" } ] }`

In the next two examples, you will create a POST request to create a new contact address using the REST endpoint that you registered earlier. Both examples show you how to set the HTTP headers in your Groovy script.

Set the HTTP request header content type in your POST request.

def conn = adf.webServices.Account_SAML
try{
  // Create new Account object by passing Organization name
  // Set Content-Type request header 
  def OrganizationName =[OrganizationName:'TestOrganization1']
  def httpHeaders=['Content-Type':'application/vnd.oracle.adf.resourceitem+json']
  conn.requestHTTPHeaders=httpHeaders
  def accounts = conn.POST(OrganizationName)
  
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

Set the HTTP response header content type in your POST request.

def conn = adf.webServices.Account_SAML
try{
  // Create new Account object by passing Organization name
  // Set Content-Type request header 
  def OrganizationName =[OrganizationName:'TestOrganization2']
  def httpHeaders=['Content-Type':'application/vnd.oracle.adf.resourceitem+json']
  conn.requestHTTPHeaders=httpHeaders
  def accounts = conn.POST(OrganizationName)
  
  println("Headers:"+conn.responseHTTPHeaders)
  // Retrieve Content-Type from response headers
  println("Content-Type:"+conn.responseHTTPHeaders['Content-Type'])
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}