Build an adapter

Use Adapter Builder to create custom adapters that integrate with network applications via Itential Platform. Adapter Builder is an interactive tool that guides you step-by-step to define your adapter, set properties, and create entities. After building the adapter, Adapter Builder provides installation instructions.

What Adapter Builder collects

Each step of Adapter Builder gathers information about the adapter and the system it connects to:

• Adapter ownership
• System integration details
• Authentication method
• Health check configuration
• API call usage
• Use cases
• Other properties

Use default values carefully

Adapter Builder simplifies the process by pre-filling much of the information above with defaults. Accepting all defaults is not recommended and will result in additional work later:

• Authentication — Accepting the default means you must configure the authentication method after deployment, including updating several files and adapter properties.
• Namespace — Accepting the default namespace instead of applying a custom one requires you to update the namespace across many files.
• Adapter name — Accepting an incorrect default name may require you to update it in multiple locations.

Best practices

Review and complete all fields

• Read the helper text on each field — many fields explain how to update the data after the adapter is built.
• For fields related to API calls (protocol, host, base path, version, etc.), Adapter Builder shows you a preview of the API call as it would be made. Verify this is correct before proceeding.

Optimize API call coverage

• Select all required API calls to achieve 100% coverage.
• Reduce adapter size by selecting only the API calls you know you will use.

Build use cases

Use cases are valuable when integrating with Itential Platform. Adapter use cases can provide workflows that you can:

• Use to test the adapter.
• Enhance to build automations.

After building

Follow the installation instructions Adapter Builder provides after the build completes. You should also:

• Lint the adapter — the goal is zero lint issues.
• Run the tests — the goal is 100% of tests passing.
• Allow time to get authentication and integration working correctly.
• Review the adapter authentication and troubleshooting documentation for more information.

Supported input formats

Adapter Builder accepts Swagger and OpenAPI documents as input. Postman Collections and WSDLs are not directly supported, but you can convert them first.

Swagger and OpenAPI

Adapter Builder accepts Swagger and OpenAPI documents. Issues in these documents can negatively affect the build:

• Certain errors prevent an adapter from building entirely; others cause issues in the generated adapter.
• Some parameters can cause lint failures.
• Unsupported data types (not supported by ajv or JavaScript) can cause test failures.
• Missing operationId values result in long, complex method names.
• Nested references — especially circular ones — can cause the Adapter Builder’s Swagger validator to loop indefinitely, leading to build times of five or more minutes and missing input/output data.

To improve your Swagger or OpenAPI document:

• Validate the document first using a tool such as Swagger Editor. Validation resolves many common issues.
• If the built adapter has lint or test failures, report it to the Itential Adapters Team so the issue can be addressed and future adapters are not affected.
• If many method names are long and complex, consider adding operationId values to the Swagger document to make method names more readable.
• If the build appears to hang, wait for it to complete — builds with heavily nested references can take 8–10 minutes. Cleaning up nested references will speed up future builds and produce better-defined input/output data.

Postman Collections

Adapter Builder no longer accepts Postman Collections directly. Convert your collection to OpenAPI/Swagger format first using a tool such as APIMatic.

WSDL

Adapter Builder no longer accepts WSDLs directly. Convert your WSDL to OpenAPI/Swagger format first using a tool such as APIMatic.

Troubleshoot

Common causes of issues in Adapter Builder:

• Keywords used as parameter names.
• Bugs introduced during API specification conversion.

For additional help, see Support.