21.4 Connector Builder: Custom Integration Service Connectors

21.4 Connector Builder: Custom Integration Service Connectors

Core Concept: When an application has a REST API but no prebuilt connector, Connector Builder lets you create a custom connector for Integration Service. Once published, it works like any other connector: connections, activities in Studio and Studio Web, and the connection-based HTTP Request.

---

When to Build a Connector

Connector Builder targets REST APIs that use JSON.

---

Creating a Connector

You can start a connector in several ways:

• From scratch, defining the base URL, authentication, and resources yourself.
• From an API definition, importing a Swagger/OpenAPI file (JSON or YAML) or a Postman collection, which creates resources and methods automatically.

Authentication

Choose how the connector authenticates, for example with an API key, basic credentials, or OAuth 2.0 flows such as authorization code or client credentials. Users then create connections with that method, and Integration Service stores and refreshes the tokens.

Resources and methods

Each resource (for example /customers) gets methods such as GET list, GET by ID, POST, PATCH, and DELETE. For each method you define:

• path and query parameters, with which fields are required,
• the request body fields and the response fields,
• pagination settings for list operations.

These definitions become the fields that appear in the connector's activities.

Scripting

Global Scripts in JavaScript let you adjust requests and responses, for example to add a computed header or to reshape a response before it reaches the activity.

Testing

Test each method against the real API from the builder, using a test connection, before publishing.

---

Publishing and Using the Connector

1. Publish the connector to the tenant. It then appears in the connector catalog for that tenant.
2. Users create connections to it in their folders or Personal Workspaces.
3. In Studio (2023.10 and later) and Studio Web, the connector's activities appear like those of prebuilt connectors, and its HTTP Request activity reuses the connection.
4. In Orchestrator, per-environment connections are chosen through Package Requirements, as for any connector.

---

Design Guidelines

• Name resources and fields for business users, for example "Customer" and "Credit limit" rather than raw API names.
• Mark required fields so the activities validate input before calling the API.
• Keep secrets out of the connector definition. Credentials belong in connections.
• Version deliberately. Changing a published method's fields can break automations; add new methods or fields rather than renaming existing ones.
• Document limits such as rate limits and page sizes in the resource descriptions.

---

Worked Example: An Internal Asset-Tracking API

A company's asset-tracking system exposes a REST API with an OpenAPI file and OAuth 2.0 client credentials.

1. The developer imports the OpenAPI file into Connector Builder, which creates /assets and /assignments resources.
2. They choose client credentials authentication and set the token URL.
3. They rename fields for readability, mark assetTag as required, and configure pagination for the list method.
4. A Global Script adds a X-Source: UiPath header that the API team requested.
5. They test each method, publish to the tenant, and create a service-account connection in the shared IT folder.
6. Automations now use activities such as "Get asset" and "Create assignment" instead of hand-built HTTP requests.

---

Key Terms

• Resource: an API object such as /customers, grouping related methods.
• Method: one operation on a resource, such as GET by ID or POST, which becomes an activity.
• Global Script: JavaScript that runs around requests and responses for the whole connector.
• Connection: a user's authenticated instance of the connector, stored in an Orchestrator folder or Personal Workspace.

---

Connector Builder Versus Other Options

A custom connector pays off when several automations use the same API. For a single call in one project, a plain HTTP request is usually enough.

---

Common Traps

• Building a connector for an API that is not REST/JSON.
• Putting credentials into the connector definition instead of connections.
• Forgetting to publish to the tenant before looking for the connector in Studio.
• Renaming published fields and breaking existing automations.