Integration Service SDK

TypeScript SDK for UiPath Integration Service APIs (Connections and Elements).

Overview

The SDK provides:

1. Generated API clients for Connections and Elements endpoints (auto-generated from OpenAPI specs)
2. Factory functions for creating authenticated API clients
3. DAP utilities for building connector essential configuration, metadata extraction, and node validation

Installation

bun install @uipath/integrationservice-sdk

API Clients

createApiClient (Recommended)

Generic factory that creates any API client using the current login session from @uipath/auth:

The SDK has two API domains:

• Connections (connections_ endpoint) — ConnectionsApi, ConnectorsApi, SessionsApi, ConnectionOperationsApi
• Elements (elements_/v3/element endpoint) — ElementsApi

import { createApiClient, ElementsApi, ConnectorsApi } from "@uipath/integrationservice-sdk";

// Elements client (most common — used by flow-tool, case-tool, agent-tool)
const elements = await createApiClient(ElementsApi);

// Connectors client (part of the Connections domain — lists/describes connectors)
const connectors = await createApiClient(ConnectorsApi);

// With tenant override
const client = await createApiClient(ElementsApi, { tenant: "my-tenant" });

For Connections/Sessions APIs, the integrationservice-tool uses the manual config pattern:

import {
    ConnectionsApi,
    SessionsApi,
    createConnectionsConfig,
    folderOverride,
} from "@uipath/integrationservice-sdk";

const config = await createConnectionsConfig({ tenant: "my-tenant" });
const connectionsApi = new ConnectionsApi(config);
const sessionsApi = new SessionsApi(config);

// With folder override
const connections = await connectionsApi.getConnections({}, folderOverride("folder-key"));

Options (CreateApiClientOptions):

| Option | Type | Description | |--------|------|-------------| | tenant | string? | Tenant name override. Falls back to session tenant. | | loginValidity | number? | Minimum token validity in minutes. |

createConnectionsConfig / createElementsConfig

Lower-level factories for when you need the raw configuration object:

import { createConnectionsConfig, createElementsConfig } from "@uipath/integrationservice-sdk";

const connConfig = await createConnectionsConfig();
const elemConfig = await createElementsConfig();

executeOperation

Direct HTTP operation against a connection instance:

import { executeOperation } from "@uipath/integrationservice-sdk";

// GET (list records)
const tickets = await executeOperation(options, connectionId, "tickets", "GET");

// POST (create record)
const result = await executeOperation(options, connectionId, "tickets", "POST", {
    subject: "New Ticket",
    priority: "high",
});

// GET with query parameters
const filtered = await executeOperation(options, connectionId, "tickets", "GET", undefined, {
    limit: "10",
});

folderOverride

Creates an InitOverrideFunction for folder-scoped API calls:

import { ConnectionsApi, createConnectionsConfig, folderOverride } from "@uipath/integrationservice-sdk";

const config = await createConnectionsConfig();
const api = new ConnectionsApi(config);
const connections = await api.getConnections({}, folderOverride("folder-key"));

Generated API Classes

Two API domains, auto-generated from OpenAPI specs in generated/:

• Connections domain ({baseUrl}/{orgId}/{tenant}/connections_) — ConnectorsApi, ConnectionsApi, SessionsApi, ConnectionOperationsApi
• Elements domain ({baseUrl}/{orgId}/{tenant}/elements_/v3/element) — ElementsApi

ElementsApi

Objects & Metadata (Static — no connection needed)

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | getObjects | { elementKey } | List objects for a connector | is-tool, case-tool | | getActivities | { elementKey } | List activities (curated operations) | is-tool, case-tool | | getObjectMetadata | { elementKey, objectName, includeParentArray? } | Get object field metadata | case-tool | | getObjectMetadataRaw | { elementKey, objectName, includeParentArray? } | Get raw metadata response (for JSON parsing) | flow-tool | | getObjectSwagger | { elementKey, objectName } | Get object swagger/OpenAPI definition | case-tool | | getEventObjects | { elementKey, operationName } | List trigger event objects | is-tool | | getEventObjectMetadata | { elementKey, operationName, objectName, allFields? } | Get trigger event metadata | is-tool |

Objects & Metadata (Instance — connection-specific, includes custom fields)

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | getInstanceObjects | { connectionOrInstanceId, elementKey } | List objects for a connection instance | is-tool, agent-tool | | getInstanceObjectMetadata | { connectionOrInstanceId, elementKey, objectName, includeParentArray? } | Get instance object metadata | agent-tool | | getInstanceObjectMetadataRaw | { connectionOrInstanceId, elementKey, objectName, includeParentArray? } | Get raw instance metadata response | flow-tool | | getInstanceEventObjects | { connectionOrInstanceId, elementKey, operationName } | List trigger event objects for instance | is-tool | | getInstanceEventObjectMetadata | { connectionOrInstanceId, elementKey, operationName, objectName, allFields? } | Get instance trigger event metadata | is-tool, flow-tool |

Other Elements Methods

| Method | Description | |--------|-------------| | getElementMetadata | Get element-level metadata (connector details) | | getAvailableConnectors | List available connectors via elements endpoint | | getElementSwagger | Get full connector swagger definition | | getEventOperations | List event operations (static) | | getInstanceEventOperations | List event operations (instance) | | getInstanceWebhookSpec | Get webhook specification for instance | | getInstanceDocs | Get instance documentation | | getInstanceObjectDocs | Get instance object documentation |

ConnectorsApi

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | apiV1ConnectorsGet | { hasHttpRequest? } | List all connectors | is-tool | | apiV1ConnectorsKeyOrIdGet | { keyOrId } | Get connector by key or ID | is-tool, agent-tool | | apiV1ConnectorsKeyOrIdConnectionGet | { keyOrId } | Get default connection for a connector | is-tool, agent-tool | | apiV1ConnectorsKeyOrIdConnectionsGet | { keyOrId, allFolders?, pageSize?, ... } | List connections for a connector | is-tool, case-tool | | apiV1ConnectorsKeyOrIdConnectionsPost | { keyOrId, createConnectionRequest } | Create connection for a connector | — | | apiV1ConnectorsKeyOrIdMetadataGet | { keyOrId } | Get connector metadata | — | | apiV1ConnectorsKeyOrIdTriggersGet | { keyOrId, allFolders? } | Get triggers for a connector | — |

ConnectionsApi

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | apiV1ConnectionsGet | { allFolders?, pageSize?, filter?, ... } | List all connections | is-tool | | apiV1ConnectionsPost | { createConnectionRequest } | Create new connection (OAuth flow) | is-tool | | apiV1ConnectionsConnectionIdGet | { connectionId, includeConfigs? } | Get connection by ID | agent-tool | | apiV1ConnectionsConnectionIdAuthPost | { connectionId } | Re-authenticate connection | is-tool | | apiV1ConnectionsConnectionIdPingGet | { connectionId, forceRefresh? } | Check if connection is active | is-tool | | apiV1ConnectionsConnectionIdDelete | { connectionId } | Delete connection | — | | apiV1ConnectionsConnectionIdRenamePatch | { connectionId, renameRequest } | Rename connection | — | | apiV1ConnectionsConnectionIdSetDefaultPatch | { connectionId } | Set as default connection | — | | apiV1ConnectionsConnectionIdTokenGet | { connectionId, tokenType? } | Get connection access token | — | | apiV1ConnectionsConnectionIdTriggersGet | { connectionId } | Get triggers for connection | — |

SessionsApi

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | apiV1SessionsSessionIdGet | { sessionId } | Poll OAuth session status during auth flow | is-tool |

ConnectionOperationsApi

| Method | Parameters | Description | Used By | |--------|-----------|-------------|---------| | apiV1ConnectionsConnectionIdOperationsGet | { connectionId } | List operations for a connection | — | | apiV1ConnectionsConnectionIdOperationsOperationObjectsGet | { connectionId, operation } | Get objects for an operation | — | | apiV1ConnectionsConnectionIdOperationsOperationNameObjectsObjectNameEventFieldsGet | { connectionId, operationName, objectName } | Get event fields | — |

DAP (Design-time Automation Platform) Utilities

Custom logic for building connector node configurations. Shared across flow-tool, case-tool, coded-apps, and other surfaces.

Essential Configuration Builders

Build the essentialConfiguration blob that DAP uses to restore connector nodes:

import {
    buildActivityEssentialConfiguration,
    buildTriggerEssentialConfiguration,
    type ConnectorMethodInfo,
} from "@uipath/integrationservice-sdk";

// Activity node
const config = buildActivityEssentialConfiguration(instanceParameters, methodInfo);
// Returns: "=jsonString:{\"essentialConfiguration\":{...}}"

// Trigger node
const config = buildTriggerEssentialConfiguration(instanceParameters);

buildActivityEssentialConfiguration(instanceParameters, methodInfo)

| Parameter | Type | Description | |-----------|------|-------------| | instanceParameters | Record<string, unknown> | Identity object — connectorKey, objectName, activityType | | methodInfo | ConnectorMethodInfo | From IS metadata — operation, method, path |

buildTriggerEssentialConfiguration(instanceParameters)

| Parameter | Type | Description | |-----------|------|-------------| | instanceParameters | Record<string, unknown> | Identity object — connectorKey, objectName, activityType |

Input Metadata & Multipart Extraction

import { extractMultipartParameters, buildInputMetadata } from "@uipath/integrationservice-sdk";

// Extract multipart parameters from IS method parameters
const multipartParams = extractMultipartParameters(methodInfo.parameters);

// Build inputMetadata for the node detail
const inputMeta = buildInputMetadata(multipartParams, methodInfo.operation, methodInfo.pagination?.maxPageSize);

extractMultipartParameters(params) — Filters IS metadata parameters where type === "multipart".

buildInputMetadata(multipartParams, operation, maxPageSize?) — Builds inputMetadata with:

• type: "multipart" + multipart.bodyFieldName when multipart params exist
• operation: "list" + pagination.maxPageSize for list operations
• Uses maxPageSize from IS metadata when provided, falls back to 1000

DAP Types

import type {
    ConnectorMethodInfo,   // { operation, method, path, parameters[], pagination? }
    ISMetadata,            // { fields, metadata.method map }
    ISField,               // { name, type, displayName, method map, reference? }
    ISFieldMethod,         // { request, response, required }
    ISMetadataParam,       // { name, type, dataType, required, curated }
    FieldReference,        // { objectName, lookupValue, lookupNames?, path? }
    MultipartParam,        // { name, dataType }
    InputMetadata,         // { type?, multipart?, operation?, pagination? }
    TriggerObjectMetadata, // { fields, eventMode, elementKey }
    TriggerField,          // { name, type, displayName, events? }
    TriggerFieldEvent,     // { name, curated, required }
} from "@uipath/integrationservice-sdk";

Connector Node Validation

A composable, surface-agnostic validation framework for connector nodes. Each rule is a standalone pure function that can be used individually or composed into a rule set.

Quick Start

import { validateIntSvcNode, type ConnectorValidationContext } from "@uipath/integrationservice-sdk";

const context: ConnectorValidationContext = {
    nodeKind: "activity",
    connectionId: detail.connectionId,
    folderKey: detail.connectionFolderKey,
    objectName: "send-mail-v2",
    httpMethod: detail.method,
    endpoint: detail.endpoint,
    bodyParameters: detail.bodyParameters,
    queryParameters: detail.queryParameters,
    pathParameters: detail.pathParameters,
    configuration: detail.configuration,
    // Optional — enables deeper validation:
    methodInfo,   // from IS metadata
    metadata,     // from IS metadata
};

const issues = validateIntSvcNode(context);
detail.errorState = { issues };

Available Rules

Structural Rules (no IS metadata needed)

| Rule | Applies To | What It Checks | DAP Code | |------|-----------|----------------|----------| | validateConnectionId | Both | connectionId is non-empty | DAP-RT-1002 | | validateFolderKey | Both | folderKey is non-empty | — | | validateObjectName | Both | objectName is non-empty | DAP-RT-1053 | | validateHttpMethod | Activity | Valid HTTP verb (GET/POST/PUT/PATCH/DELETE) | DAP-RT-1100 | | validateEndpoint | Activity | Endpoint starts with / | — | | validateEventMode | Trigger | eventMode is non-empty | — | | validateEventType | Trigger | eventType (operation) is non-empty | DAP-RT-1053 | | validateConfiguration | Both | Configuration is valid JSON with essentialConfiguration | DAP-RT-1000 | | validatePathTemplateParams | Activity | Path template {vars} have matching pathParameters | DAP-RT-1003 |

Metadata-Aware Rules (require IS metadata in context)

| Rule | Applies To | What It Checks | DAP Code | |------|-----------|----------------|----------| | validateMethodInMetadata | Activity | httpMethod exists in IS metadata method map | DAP-DT-2201 | | validateRequiredParameters | Activity | Required method params (path/query/body) have values | DAP-RT-1003 | | validateRequiredFields | Activity | Required IS fields have values in bodyParameters | DAP-RT-1003 | | validateRequiredEventParameters | Trigger | Required event params have values in eventParameters | DAP-RT-1003 |

Custom Rules

import { validateIntSvcNode, DEFAULT_RULES, type ValidationRule } from "@uipath/integrationservice-sdk";

// Add a custom rule
const myRule: ValidationRule = (context) => {
    if (context.nodeKind === "activity" && !context.bodyParameters?.subject) {
        return [{ type: "Warning", title: "Subject is recommended for email activities." }];
    }
    return [];
};

const issues = validateIntSvcNode(context, [...DEFAULT_RULES, myRule]);

Using Individual Rules

import { validateConnectionId, validateRequiredParameters } from "@uipath/integrationservice-sdk";

// Run only specific checks
const connectionIssues = validateConnectionId(context);
const paramIssues = validateRequiredParameters(context);

Validation Context

type ConnectorValidationContext = {
    // Node identity
    connectorKey?: string;
    objectName?: string;
    nodeKind?: "activity" | "trigger";

    // Connection
    connectionId?: string;
    folderKey?: string;

    // Activity-specific
    httpMethod?: string;
    endpoint?: string;

    // Trigger-specific
    eventMode?: string;
    eventType?: string;

    // Parameter values
    bodyParameters?: Record<string, unknown>;
    queryParameters?: Record<string, unknown>;
    pathParameters?: Record<string, unknown>;
    eventParameters?: Record<string, unknown>;

    // Configuration blob
    configuration?: string;

    // IS metadata (optional)
    methodInfo?: ConnectorMethodInfo;
    metadata?: ISMetadata;
    triggerMetadata?: TriggerObjectMetadata;
};

Who Uses This SDK

| Package | API Classes | Factory / Helpers | DAP Utilities | |---------|------------|-------------------|---------------| | integrationservice-tool | ConnectorsApi, ConnectionsApi, SessionsApi, ElementsApi | createApiClient, createConnectionsConfig, executeOperation, folderOverride | — | | flow-tool | ElementsApi | createApiClient | buildActivityEssentialConfiguration, buildTriggerEssentialConfiguration, buildInputMetadata, extractMultipartParameters | | case-tool | ElementsApi, ConnectorsApi | createApiClient | — | | agent-tool | ConnectorsApi, ConnectionsApi, ElementsApi | createApiClient, createElementsConfig | — |

integrationservice-tool Method Usage

| Command | API | Methods | |---------|-----|---------| | uip is connectors list | ConnectorsApi | apiV1ConnectorsGet | | uip is connectors describe | ConnectorsApi | apiV1ConnectorsKeyOrIdGet | | uip is connections list | ConnectorsApi, ConnectionsApi | apiV1ConnectorsKeyOrIdConnectionsGet, apiV1ConnectionsGet | | uip is connections create | ConnectionsApi, SessionsApi | apiV1ConnectionsPost, apiV1SessionsSessionIdGet | | uip is connections auth | ConnectionsApi, SessionsApi | apiV1ConnectionsConnectionIdAuthPost, apiV1SessionsSessionIdGet | | uip is connections ping | ConnectionsApi | apiV1ConnectionsConnectionIdPingGet | | uip is activities list | ElementsApi | getActivities | | uip is triggers list | ElementsApi | getEventObjects, getInstanceEventObjects | | uip is triggers describe | ElementsApi | getEventObjectMetadata, getInstanceEventObjectMetadata | | uip is resources list | ElementsApi | getObjects, getInstanceObjects | | uip is resources describe | ElementsApi | getObjectMetadataRaw, getInstanceObjectMetadataRaw | | uip is resources run | — | executeOperation (direct HTTP) |

Development

# Build
bun run build

# Test
bun run test

# Generate SDK from OpenAPI specs
bun run generate

# Lint
bun run lint

License

Copyright (c) UiPath. All rights reserved.