> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Work with the Adapter Utils library

> An overview of the Adapter Utils library — what it provides, how its capabilities work, how to use it in adapter.js, and how to update the dependency.

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:

```javascript
// identifyRequest(entity, action, requestObj, returnDataFlag, callback)
return this.requestHandlerInst.identifyRequest('entity', 'action', reqObj, true, (irReturnData, irReturnError) => {

  // Return any error from the libraries
  if (irReturnError) {
    /* HERE IS WHERE YOU CAN ALTER THE ERROR MESSAGE */
    return callback(null, irReturnError);
  }

  // Return an error if the response has no data
  if (!Object.hasOwnProperty.call(irReturnData, 'response')) {
    const errorObj = this.requestHandlerInst.formatErrorObject(
      this.id, meth, 'Invalid Response', ['action'], null, null, null
    );
    log.error(`${origin}: ${errorObj.IAPerror.displayString}`);
    return callback(null, errorObj);
  }

  /* HERE IS WHERE YOU CAN ALTER THE RETURN DATA */
  return callback(irReturnData, null);
});
```

For more detail on constructing the `reqObj` passed to `identifyRequest`, see [Work with adapter.js](./work-with-adapterjs).

## 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

```bash
rm -rf node_modules
rm package-lock.json
```

#### Reinstall dependencies

```bash
npm install
```