Introduction

Oracle Visual Builder (VB) has out of box support for calling REST services and can be configured to make calls directly from the client, or via the server proxy. There is no obvious support for making SOAP calls. While it is possible to make client side SOAP calls from javascript, without the VB Connection framework, the authentication would need to be handled by the client code and there is a high chance of a CORS error.

This post shows how the VB Service Connection framework can be used to make SOAP calls. By using a VB Service Connection, such calls inherit other connection capabilities such as the use of the proxy and authentication mechanisms.

Example Use Case

The example uses Visual Builder federated with Fusion Sales, and the endpoint being called is the submitRequest method of the Fusion Scheduler (ESS) service:

https://{hostname}/ess/esswebservice?wsdl

Note that this service supports security policy "wss11_saml_or_username_token_with_message_protection_service_policy" (see later for the significance of this).

The example will show how to submit the Optimize CRM Search Indexes job and display its Job Id.

Note - the objective of this post is to demonstrate how to setup and call the SOAP endpoint, it is not necessarily an endorsement of this use case. The use of the response within a VB page is beyond the scope of the article and it assumes a basic knowledge of Visual Builder, so the detailed steps required to reproduce the example are not covered.

Method

Overview

The steps to configure and make the call are:

1. Recommended - test the service in SOAP UI or similar to make sure the required endpoint, payload and parameters are known 
2. Define the SOAP endpoint as a VB Service Connection
3. Call the service from a Page Module function

Step1 . Test the service

The primary output of this step is a soap payload that can be used as a template in VB. The important things to note are the Content-Type and any SOAP headers that the service requires. In this example the service uses a Content-Type of text/xml;charset=UTF-8 and it requires a wsa header.

Step 2. Define the SOAP endpoint as a VB Service Connection

In VB, navigate to the Service Connections, create a new connection, and select Define by Endpoint

Enter the URL for the service, in this example it is:

https://{hostname}/ess/esswebservice

Configure the service as per the notes below:

• Method is POST
• Authentication is Oracle Cloud Account. The same SAML token as is used for FA REST calls will be used (ref security policy in the WSDL above)
• Always use the Proxy - this will ensure the call is made from the VB server, thus avoiding CORS errors
• Add a static Content-Type header to the Request to suit your service - in this example it is 'text/xml;charset=UTF-8'
  • Note, for most SOAP services the Content-Type will be 'application/soap+xml;charset=UTF-8'
• Set the request and response example body to {}

Note the Service Name and the Endpoint ID. In this example these are ess and postEsswebservice:

Step 3. Call the service from a Page Module function

The easiest way to demonstrate the connection and confirm it is working is to create a VB page with a button and an input text - the Button will call an action chain that calls the service and maps the response to the Input Text.

Details:

• Create a page with a Button and an Input Text
• Create a Page variable called JobId and bind the Input Text to this variable
• Create a new Event on the button, and select  "Quick Start: ojAction". This will create a listener on the button and an empty Action Chain.
• Add a reference the the Service Connection to the Application metadata

Action Chain

The Action Chain has 2 steps:

• Call Module Function - this function makes the SOAP call. The example does not use any parameters, but add them as necessary to suit your service
• Assign Variables - this maps the response from the module function to the JobId page variable

Module Function

The module function uses the VB Rest Helper Utility. This utility allows calling REST endpoints, which are defined in the service definitions. See the VB Documentation for further information.

//add reference to the VB Rest Helper API
define(['vb/helpers/rest'], function(Rest) {
  'use strict';

  var PageModule = function PageModule() {};

  PageModule.prototype.submitESSJob = function() {
  
return new Promise(function(resolve, reject) {  

//obtained from step #1. Note MESSAGEID, this will be replaced later
  const soapTemplate = `

   
   submitRequest
   MESSAGEID
   
      
            
            OptimizeContextSearchIndexJob
            /oracle/apps/ess/crmCommon
            JOB_DEFINITION
         
         CrmEss
         
         
      
   

    `;

const messageID = 'uuid:' + PageModule.prototype.createUUID();
//replace soap template placeholders with runtime values
const soapBody = soapTemplate.replace('MESSAGEID', messageID);

//obtained from service connnection definition
const endpoint = 'ess/postEsswebservice';

    //make the call and parse the response
    Rest.get(endpoint).body(soapBody).fetch().then(
      response => {
        const result = $.parseXML(response.body).getElementsByTagName("requestId")[0].textContent;
        resolve(result);
      });

});

  };

//this service needs a wsa message id, this function generates a uuid
PageModule.prototype.createUUID = function() {
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
      var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
      return v.toString(16);
   });
};

  return PageModule;
});

Assign the result of the Action Chain to the JobId variable:

Add the service reference to the Application metadata, app-flow.json:

  "services": {
    "ess": {
      "path": "./services/ess/openapi3.json"
    }
  }

Conclusion

The above demonstrates the basic setup required to make a SOAP call. An alternative solution is to wrap the code in a CCA and pass everything required, including the SOAP body (or a reference to it), as parameters. By doing this, one CCA could be used to call many SOAP end points.