> This page is for Itential Adapters. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-test.itntl.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server. # Build an adapter > How to use Adapter Builder to create a custom adapter, including input format requirements, best practices, and troubleshooting guidance. Use [Adapter Builder](https://adapters.itential.io/) 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](https://editor.swagger.io/). 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](https://www.apimatic.io/). #### Open APIMatic Go to [APIMatic](https://www.apimatic.io/) and sign in or sign up for a free trial. #### Start the conversion On the dashboard, click **Transform API**. #### Upload your file Click **Choose File** to upload the Postman Collection, or provide the URL for the API document. #### Select the output format Select **OpenAPI/Swagger v2.0** or **v3.0** in JSON — these are the ideal formats for Adapter Builder. #### Convert Click **Convert** and download the output file. ### WSDL Adapter Builder no longer accepts WSDLs directly. Convert your WSDL to OpenAPI/Swagger format first using a tool such as [APIMatic](https://www.apimatic.io/). #### Open APIMatic Go to [APIMatic](https://www.apimatic.io/) and sign in or sign up for a free trial. #### Start the conversion On the dashboard, click **Transform API**. #### Upload your file Click **Choose File** to upload the WSDL, or provide the URL for the API document. #### Select the output format Select **OpenAPI/Swagger v2.0** or **v3.0** in JSON — these are the ideal formats for Adapter Builder. #### Convert Click **Convert** and download the output file. > **Note** > > If your WSDL references other WSDL files, combine them into a single complete WSDL before converting. Conversion tools cannot properly process references they cannot resolve. ## Troubleshoot Common causes of issues in Adapter Builder: * Keywords used as parameter names. * Bugs introduced during API specification conversion. > **Info** > > If you are aware of issues in your API specification before using Adapter Builder, fix them first. Correcting issues before building saves significant time. For additional help, see [Support](/adapters/support/get-support).