Work with the Adapter Utils library

The Adapter Utils library provides the runtime capabilities that most adapter logic depends on. By building on this shared foundation, all adapters that use it gain the same set of capabilities instantly, and improvements to the library become available to every adapter when they update their dependency.

Capabilities

Capability	Description
Authentication	Systems authenticate in different ways. Adapter Utils is regularly extended with new authentication methods to support complex authentication patterns.
Throttling	Throttling enables successful integration with systems that cannot handle heavy request loads or that have licensing constraints limiting concurrent usage.
Translation	Adapter Utils translates JSON objects betweenItential Platform and the external system. It also handles JSON-to-XML and XML-to-JSON conversion, so communication with XML-based systems requires no additional work in the adapter.
Consistent error handling	Adapter Utils generates consistently formatted error messages for any error an adapter receives.
Metrics	Metrics are gathered for each call and saved over time. Tracked values include round-trip time, capability time (time spent inside the adapter libraries), overall time (if `adapter.js` calls the library method), and response handling (count of each HTTP status code received).
Filtering	When the external system does not support its own filtering, Adapter Utils can filter the response to return only the dataItential Platform needs.
Encoding and encryption	When data must be encoded or encrypted before being sent, Adapter Utils handles this automatically before the request goes out. Incoming data is decoded or decrypted before being returned.
Intelligent handling	Adapter Utils manages proxies, redirects, and automatic retries on errors and timeouts. For token-based systems, if a token has expired, the adapter automatically retrieves a new token and retries the request. Adapter Utils also supports stub mode, which returns mock data from within the adapter rather than making live calls — useful for testing and for buildingItential Platform workflows when the external system is not available.

Use adapter utils in adapter.js

The two primary calls into Adapter Utils are identifyRequest (to make a request to the external system) and formatErrorObject (to produce a consistently formatted error). A third call for returning adapter metrics is also available.

The example below shows a complete call to identifyRequest, including error handling:

1 // identifyRequest(entity, action, requestObj, returnDataFlag, callback)
2 return this.requestHandlerInst.identifyRequest('entity', 'action', reqObj, true, (irReturnData, irReturnError) => {
3 
4   // Return any error from the libraries
5   if (irReturnError) {
6     /* HERE IS WHERE YOU CAN ALTER THE ERROR MESSAGE */
7     return callback(null, irReturnError);
8   }
9 
10   // Return an error if the response has no data
11   if (!Object.hasOwnProperty.call(irReturnData, 'response')) {
12     const errorObj = this.requestHandlerInst.formatErrorObject(
13       this.id, meth, 'Invalid Response', ['action'], null, null, null
14     );
15     log.error(`${origin}: ${errorObj.IAPerror.displayString}`);
16     return callback(null, errorObj);
17   }
18 
19   /* HERE IS WHERE YOU CAN ALTER THE RETURN DATA */
20   return callback(irReturnData, null);
21 });

For more detail on constructing the reqObj passed to identifyRequest, see Work with adapter.js.

Update the adapter utils dependency

If changes have been made to Adapter Utils — either by updating to a new release or by running the adapter migrator — update the dependency in your adapter by following these steps:

Update the version in package.json

Change the adapter-utils version in the dependencies section of package.json to the desired version.

Remove the existing node_modules and lock file

$ rm -rf node_modules
$ rm package-lock.json

Reinstall dependencies

$ npm install