Body Transform

(Required) <Enter a short description here.>

The body request transform allows the author to modify the body payload for the fetch request. Some getAll endpoints in any type of service, be it Business Object / BOSS / ElasticSearch, may use a POST operation with a body (example, where the search criteria is set on the 'body' of the request payload) in order to retrieve search results. The body of the payload is generally provided by the caller of the request, which can be modified using this request transform function.

The body transform function is called after all other transforms are run. This is to allow additional contextual information to be added by the previous transforms (to the transformsContext parameter) that need to be included in the body.

Signature

The body transform function can be declared like this:

Request.prototype.body = function(configuration, options, transformsContext) {
  // Clients can manipulate the options of the fetch that contains the body of the payload to send.
}

This function has the following parameters:

configuration an object with the following properties:
- Refer to the signature in Request Transformation Functions for details on the various properties.
options the body for the POST request.
transformsContext is an object that is set by the author (ServiceDataProvider, RestHelper, Call Rest action) to then be passed as is to all transforms for the current fetch cycle.

The function returns the updated configuration object.

Usage

The examples below illustrate the arguments passed to the body transform, as well as the effect its code has on the fetch performed by the RestHelper.

The example below uses a service fixitfast that has a POST endpoint to retrieve the list of incidents currently open in the system.

The service has an operation postToGetIncidents similar to what is shown below. Please refer to the VB Docs on creating a Service Connection on how to add/configure POST endpoints and also set up a custom transforms for the same.

{
  "/incidents": {
    "post": {
      "operationId": "postToGetIncidents",
      "responses": {
        "default": {
          "description": "Default response"
        }
      },
      "x-vb": {
        "transforms": {
          "path": "./fixitfast-post-transforms.js",
          "disabled": {
            "request": [
              "sort",
              "filter",
              "query"
            ]
          }
        },
        "headers": {
          "Content-type": "application/json",
          "Accept": "application/json"
        }
      }
    }
  }
}

Transform Script

As indicated above, the transform script fixitfast-post-transforms.js is specified in the fixitfast service catalog, along with the endpoint definition. This artifact contains the body transform method.

If the service fixitfast had a transform script, the method for body could be declared there as long as the transforms code applies to this POST endpoint.

Example 1-16 ServiceDataProvider variable

Assume that the following variable of type vb/ServiceDataProvider is defined in a page that refers to the above POST endpoint.

{
  "variables": {
    "userFilter": {
      "type": "object",
      "defaultValue": {
        "technician": "hcr",
        "role": "tech"
      }
    },
    "searchCriteria": {
      "type": "object",
      "defaultValue": {
        "searchLevel": "allReports"
      }
    },
    "incidentsList": {
      "type": "vb/ServiceDataProvider",
      "defaultValue": {
        "endpoint": "fixitfast-service/postToGetIncidents",
        "keyAttributes": "id",
        "itemsPath": "result",
        "body": {
          "userFilter": "{{ $page.variables.userFilter }}",
          "searchCriteria": "{{ $page.variables.searchCriteria }}"
        }
      }
    }
  }
}

The above SDP variable incidentsList is bound to listview component that initiates a fetch to retrieve all incidents. This creates a RestHelper instance and subsequently the request transforms to be run. The body request transforms function is called, and the body is updated as needed, on the configuration object, before the POST request is made.

The body transform is implemented in fixitfast-post-transforms.js as follows:

define([], function () {
  class Request {
    static body(configuration, options, transformsContext) {
      const c = configuration;

      /*
       * options = {
       *   userFilter: {
       *     technician: 'hcr',
       *     role: 'tech'
       *   },
       *   searchCriteria: {
       *     searchLevel: 'allReports' 
       *   }
       * }
       */

      // Update the body values if needed
      const body = c.initConfig.body || {};

      return c;
    };
  }
  
  class Metadata {};
  class Response {};

  // Note: as an example, the Request object is expanded to include just the body property   
  return {
    metadata: Metadata,
    request: { body: Request.body },
    response: Response
  };
});