> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/adapters/get/build-an-adapter/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.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. 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. 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). > How to use Adapter Builder to create a custom adapter, including input format requirements, best practices, and troubleshooting guidance.