Adapters vs. integrations

Itential Platform offers two ways to connect to external systems: adapters and integrations. Both can make API calls to third-party systems, but they differ significantly in how they are built, deployed, and maintained. This guide explains those differences to help you choose the right approach.

Quick comparison

	Adapters	Integrations
Build method	Code-driven (Node.js)	Model-driven (OpenAPI/Swagger)
Deployment	Installed on the file system of each Platform server	Stored in MongoDB; no file system installation
Server restart	Required on initial deployment	Not required
Customization	Full — modify or extend API calls in code	Limited to the OpenAPI/Swagger specification
Memory	~130 MB per instance, even when idle	No resource usage when idle; scales on demand
CPU	Single process	Multi-process; scales on demand
Protocols	REST, SOAP, gRPC	REST, SOAP
Authentication	Basic, OAuth, static tokens, and others	Basic, OAuth, API Key (including AWS)
SSL	Supported, including self-signed certificates	Supported for publicly-signed certificates only
Version control	Update code and restart	Create and manage multiple versions via UI
Migration	Requires reinstall on each server	Portable; no reinstall required
Health checks	Yes — configurable as startup or intermediate	No
Logs	Yes — info, warn, debug, trace, error	Yes — info, warn, debug, trace, error

When to use each

Use an adapter when:

Your integration requires gRPC or a non-HTTP protocol
You need to add custom logic or transform API responses
You are working with a self-signed SSL certificate
You need health check monitoring against the external system
You are running on-premise with no resource constraints

Use an integration when:

An OpenAPI 3.0 or Swagger 2.0 specification is available for the target system
No customization beyond the spec is required
You are deploying on cloud infrastructure where memory and CPU are constrained
You want deployment without a server restart or file system access
You need to run multiple versions of the same integration concurrently

Building adapters and integrations

Adapters

Adapters are code-driven Node.js packages. Over 200 open-source adapters are available. To build a new adapter, use Adapter Builder, which generates a Node.js adapter from an OpenAPI 3.0 or Swagger 2.0 document. The generated code can be modified to suit your requirements.

Integrations

Integrations are model-driven. To build an integration, upload an OpenAPI 3.0 or Swagger 2.0 document via the Platform UI. Platform validates the document and creates an Integration Model stored in a MongoDB collection. No code is generated or placed on the file system.

Deploy adapters and integrations

Adapters

To deploy an adapter, copy the adapter code onto the Platform server file system, run npm install, then restart Platform. In a multi-server environment, repeat this process on each server — or copy the installed adapter directory and restart.

Open-source adapters are pre-installed in Itential cloud infrastructure.

See adapters overview for more information.

Integrations

Integration deployment is UI-based—no file system access or restart is required. In a multi-server environment, all Platform servers sync automatically when an integration is deployed.

See integrations overview for more information.

Customization

Adapters can be customized at the code level. You can modify existing API calls, add new calls, and transform responses. For example, if an API call returns a large nested object, you can customize the adapter to return only the value at status.result.data rather than the full response.

Integrations are limited to the operations defined in the uploaded OpenAPI or Swagger specification. Response payloads cannot be transformed — your workflow receives the full response from the external system.

Resource usage

Adapter instances each hold a process ID (PID) and consume approximately 130 MB of memory even when idle. Each adapter instance runs as a single process.

Integrations consume no system resources when idle and scale across multiple processes on demand. This makes integrations better suited for cloud environments where memory and CPU are constrained or metered.

Authentication

Adapters support a wide range of authentication mechanisms including Basic, OAuth, static tokens, and other methods that do not require manual intervention. Adapters can also authenticate against different endpoints for different calls.

Integrations support API Key (including AWS Signature), HTTP Basic, and OAuth 2.0.

OpenID Connect is not currently supported for integrations.

SSL and certificates

Adapters support SSL for all certificate types, including self-signed certificates.

Integrations support SSL for publicly-signed certificates only. To use a self-signed certificate with an integration, you must manually add the certificate to the Platform key store.

Version control

When a new adapter version is available, pull the updated code, reinstall the node modules, and restart the adapter.

Integrations support multiple concurrent versions. Each version can have multiple independent instances. Switching to a new integration version requires updating the workflows that reference it.

Health checks

Adapters support configurable health checks, which run as timed polls against the external system. Health checks can be configured as startup checks (run when the adapter starts) or intermediate checks (run at a configured interval). Health check calls do not count against rate limits or active call totals.

Integrations do not support health checks. The availability of an external system cannot be checked through an integration.

Logging

Both adapters and integrations support log levels: info, warn, debug, trace, and error. Use warn or info in non-production environments and error in production to limit log volume.

debug and trace are useful for troubleshooting but generate significant log output and should not be left enabled in production.