FetchByKeys Transform

A fetchByKeys transforms function allows the page author to take a key or Set of keys passed in via the options and tweak the URL, to fetch the data for the requested keys.

When the consumer of the SDP calls the fetchByKeys() method, if the transforms author has provided a 'fetchByKeys' transforms implementation, it is called over the other transforms. If no fetchByKeys transforms function is provided then the default transforms are called.

The built-in business object REST API transforms already provides a fetchByKeys transforms function implementation that appends the keys to the URL. This should suffice for most common cases and should result in at most one fetch request to the server. For third-party REST endpoints, the author can provide a custom fetchByKeys transforms implementation.

Signature

The fetchByKeys transform function can be declared like this:

const fetchByKeys = function (configuration, options, transformsContext) {

  var c = configuration;
  // use the keys provided to update the c.url

  return c;
}

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 keys to fetch
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.

Examples

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

Example 1-8 FixItFast service

The examples below use a service fixitfast that has a GET endpoint to retrieve the list of customers.

ServiceDataProvider variable

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

{
  "variables": {
    "customersSDP": {
      "type": "vb/ServiceDataProvider",
      "defaultValue": {
        "endpoint": "fixitfast-service/getCustomers",
        "keyAttributes": "id",
        "itemsPath": "result",
        "responseType": {
          "result": "customerResponse[]"
        }
      }
    },
    "customersSDP2": {
      "type": "vb/ServiceDataProvider2",
      "constructorParams": [
        {
          "endpoint": "fixitfast-service/getCustomers",
          "keyAttributes": "id",
          "itemsPath": "result",
          "responseType": {
            "result": "customerResponse[]"
          }
        }
      ]
    }
  }
}

The above SDP variable customersSDP, an extended type variable, is bound to an endpoint that returns all customers. Another variable, customersSDP2 is an instance factory type - vb/ServiceDataProvider2 that is bound to the same endpoint.

Note:

In the former case, the fetchByKeys capability may need to be set explicitly to values other than the defaults for optimal behavior. This is because the extended type vb/ServiceDataProvider does not automatically fetch the capabilities from the service metadata transforms, whereas this is not the case for the extended type. Example,

{
  "customersSDP": {
    "type": "vb/ServiceDataProvider",
    "defaultValue": {
      // ...
      "capabilities": {
        "fetchByKeys": {
          "implementation": "lookup",
          "multiKeyLookup": "single"
        }
      }
    }
  }
}

Refer to the Service Data Provider docs for details.

In both cases, when a component bound to the SDP variable initiates a fetchByKeys calls it passes the Set of keys whose data needs to be fetched. In both cases, a RestHelper instance is created and the fetchByKeys request transforms alone is run prior to the fetch. The fetchByKeys request transforms function uses the Set of keys passed in to build a query param on the configuration url.

The fetchByKeys transform is implemented in the default service transforms as follows:

define([], function () {
  class Request {

    static fetchByKeys(configuration, options, transformsContext) {
      const c = configuration;
      const fetchConfig = c.fetchConfiguration;
      const fetchByKeysCap = !!(c && c.capability === 'fetchByKeys'); // check if current fetch call is a fetchByKeys

      if (fetchByKeysCap) {
        const fetchKeys = options;
        if (fetchKeys && fetchKeys instanceof Set && fetchKeys.size > 0) {
          const keyAttribute = fetchConfig.context.keyAttributes || fetchConfig.context.idAttribute;
          const keysArr = Array.from(keys);

          // use the key values provided along with the keyAttribute to update the c.url
        }
      }

      return c;
    }
  }

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