In order to fetch data required by the application (from a backend service), callers can use the VB RestHelper utility directly or, use a Call Rest action or ServiceDataProvider.

Regardless of the mechanism used, for the request to happen the identifier of the endpoint along with the values of the endpoint "parameters" may need to be processed and transformed into a form that is expected by the target service / endpoint scheme. Likewise, the response received may need to be processed into to a form that is expected by the caller. In order to facilitate this every service configuration must register a transforms module that implements metadata, request and response transform functions.

Collectively, all three APIs are referred to as the Transforms API. The specific implementation of the Transforms API for a particular service is referred to by its name (for example, Business Objects Transforms). Refer to the JSDocs for serviceTransforms.js for details.

Standard Transforms File

A sample custom transforms implementation must return an object with three properties (metadata, request and response), each containing methods with specific signatures. Refer to the documentation for each type to understand how to implement them.

'use strict';

define([], () => {

  /**
   * Request class implements all the request tranforms functions needed to transform the input parameters to the 
   * Rest call. Each transforms function takes the parameters passed to it and transforms it to a form that the 
   * target service endpoint expects. Often this involves updating to the configuration.url
   */
  class Request {
    /**
     * filter builds filter expression query parameter using filterCriterion object set on the options.
     * @param {Object} configuration
     * @param {Object} options
     * @param {Object} transformsContext a transforms context object that can be used by authors of transform
     * functions to store contextual information for the duration of the request.
     * @returns {Object} configuration object, the url looks like ?filter=foo eq bar
     */
    static filter(configuration, options, transformsContext) {
      // process filter options and fix up configuration.url
      return configuration;
    }

    static body(configuration, options, transformsContext) {}

    static fetchByKeys(configuration, options, transformsContext) {}

    static query(configuration, options, transformsContext) {}

    static paginate(configuration, options, transformsContext) {}

    static select(configuration, options, transformsContext) {}

    static sort(configuration, options, transformsContext) {}

    static vbPrepare(configuration, options) {}
  }

  /**
   * Response class implements all the response tranforms functions needed to transform the response from the Rest 
   * call. Each transforms function takes the parameters passed to it and transforms the result to a form that the 
   * caller expects. Often this involves updating configuration.body, which 
   */
  class Response {
    static paginateResponse(configuration, transformsContext) {}

    static bodyResponse(configuration, transformsContext) {}
    
    someOtherMethod(config) {}
    somePrivateMethod() {}
  }
  
  class Metadata {
    static capabilities(configuration) {}
  }
  
  // Note: If the above classes implement other instance methods its best to return
  // just the methods a transforms user will need. For example, the response property
  // below returns just the exported methods 
  return {
    metadata: Metadata,
    request: Request,
    response: { paginate: Response.paginateResponse, body: Response.bodyResponse }
  };
});

Usage

Generally, all implementations for the various request, response and metadata transforms functions pertaining to a particular service, are included in a transforms file that is then associated to the service configuration.

In the example below, vb/BusinessObjectsTransforms is the pre-defined transforms implementation used with Business Objects based services.

In a catalog.json for a Business Objects based service, the transforms file is set in the backends (or services) section (see the example below). Refer to the Service Connection docs for exact details on how this is configured, and where it is defined.

This file contains the default implementations for the most common transforms functions, that are applied for the majority of service endpoints. However, specific endpoints can override the defaults, and/or add custom transforms implementations.

{
    "backends": {
        "crmBO": {
            "headers": {},
            "servers": [
                {
                    "variables": {
                        "faVersionVar": {
                            "default": "11.13.18.05"
                        }
                    },
                    "url": "vb-catalog://backends/fa/crmRestApi/resources/{faVersionVar}"
                }
            ],
            "transforms": {
                "path": "vb/BusinessObjectsTransforms"
            }
        }
    },
    "services": {
      "journeys": {
        "info": {
          "x-vb": {
            "transforms": {
              "path": "./finderOperationTransform.js"
            }
          }
        },
        "servers": [
          {
            "x-vb": {
              "headers": {
                "Accept": "application/vnd.oracle.openapi3+json"
              }
            },
            "url": "vb-catalog://backends/hcmBO/journeys/describe"
          }
        ]
      }
    }
}

Additionally, the default service transforms can also be overridden at the Service Data Provider, Call Rest action and the Rest Helper levels, using specific properties on each. Refer to the docs for the same for details.