1. Configuring Applications Using Application Composer
  2. Integrate with External REST Services

Integrate with External REST Services

You can make REST outbound calls from your application to a non-ADF REST endpoint. This topic illustrates different ways of making a call to an external REST endpoint deployed to an Oracle PaaS service, such as Oracle Java Cloud Service - SaaS Extension.

In this example, the assumption is that JCS-SaaS Extension and your application are in the same Oracle Identity Domain and are associated. This means that the user identities are in sync and trust is enabled allowing for SAML-based user identity propagation.

In this example, let's assume that you created an external, non-ADF trouble tickets application and deployed it to JCS-SaaS Extension. Now, you want to make calls to that resource. This topic illustrates the following:

  • Retrieving trouble tickets for a given account by passing an ID.

  • Exception handling.

  • Accessing elements in HTTP Response Headers.

Retrieving Trouble Tickets

First, let's retrieve trouble tickets for an account from a non-ADF REST endpoint on JCS-SaaS Extension.

Let's register the endpoint:

  1. In Application Composer, under Common Setup, click Web Services.

  2. Click the Create Web Service Reference icon.

  3. Select REST, then OK.

  4. Enter the variable name for this reference. For example, GetTicketForAccount.

  5. Enter the URL for the REST endpoint that you want to integrate with. In this case:

    https://jcs-cakp.java.us2.oraclecloudapps.com/invokeTicket/troubleTicketApi/account/##AccountId##

  6. For security, use the Security Assertion Markup Language (SAML) over Secure Socket Layer (SSL) authentication scheme. Select Propagate user identity using SAML over SSL.

  7. 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. (To enable the creation of new tickets, you can configure a POST method as part of this same endpoint registration.)

    Field

    Value

    Method Name

    GET

    Format

    JSON

    Request Payload

    Schema URL

    Response Payload

    Code Sample

    Code Sample

    		 
    {
  "accountHolder": "abc@xyz.com",
  "requester": "Test1",
  "assignee": "Auto Assigned User-1",
  "share": true,
  "subject": "New keyboard",
  "description": "New keyboard request",
  "status": "New",
  "type": "Task",
  "priority": "Urgent",
  "tags": "New"
}

After you register the endpoint, you can then reference the endpoint in your Groovy script to retrieve trouble tickets for a specific account.

The Groovy script would look like this:

def conn = adf.webServices.GetTicketForAccount
try{
  // Provide Account Id for which user wants to retrieve trouble ticket
  def tickets = conn.GET("6637911")

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

Exception Handling

In this next call, let's attempt to retrieve trouble tickets from the same non-ADF REST endpoint. However, in this example, the authentication scheme will be basic authentication, and the wrong credentials will be provided. This example illustrates how the REST endpoint behaves in the case of an unauthorized request.

Let's register the endpoint slightly differently this time. In this example, use basic authentication:

  1. In Application Composer, under Common Setup, click Web Services.

  2. Click the Create Web Service Reference icon.

  3. Select REST, then OK.

  4. Enter the variable name for this reference. For example, TroubleTicketBasicAuth.

  5. Enter the URL for the REST endpoint that you want to integrate with. In this case:

    https://jcs-cakp.java.us2.oraclecloudapps.com/invoke/troubleTicketApi/tickets

  6. For security, use basic authentication. Select Call with basic authentication.

  7. 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.

    For the purposes of this example, enter incorrect credentials.

  8. 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

    		 
    {
    "requester": "Mehul",
    "share": true,
    "subject": "Request for new monitor at my desk",
    "description": "Require bigger screen monitor",
    "status": "New",
    "type": "Task",
    "priority": "High",
    "tags": "Exchange"
}

After you register the endpoint, you can then reference the endpoint in your Groovy script to retrieve trouble tickets with the wrong credentials.

The Groovy script would look like this:

def conn = adf.webServices.TroubleTicketBasicAuth
try{
  def tickets = conn.GET()

  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Trouble Tickets:"+tickets)

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

The response shows a 401 error, since your connection was created using the wrong credentials. When invocations fail, it is important to have the ability to retrieve exception headers and payloads to inspect the cause of the error. This demonstrates the ability for groovy to retrieve error payloads as well.

Accessing Elements in HTTP Response Headers

Finally, let's retrieve trouble tickets from the same non-ADF REST endpoint. In this final example, the authentication scheme will be basic authentication, and the correct credentials will be provided. This example illustrates how to retrieve HTTP response headers.

Let's modify the endpoint used in the previous example.

  1. In Application Composer, under Common Setup, click Web Services.

  2. Edit the TroubleTicketBasicAuth connection.

  3. In the Credential Key field, specify the correct credentials for this call.

  4. Click Save.

After you modify the endpoint, you can then reference the endpoint in your Groovy script to retrieve trouble tickets with HTTP response headers, using correct credentials.

The Groovy script would look like this:

def conn = adf.webServices.TroubleTicketBasicAuth
try{
  def tickets = conn.GET()

  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Content-Type:"+conn.responseHTTPHeaders['Content-Type'])
  println("Trouble Tickets:"+tickets)

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

Related Topics