Skip to content

Commit c4bfefb

Browse files
maninder-uipathclaude
maninder-uipath
and
claude
committed
feat(integration-service): add Connectors service [JAR-IS-2]
Adds the Integration Service Connectors service (getAll, getById, getDefaultConnection, getConnections) exposed via the @uipath/uipath-typescript/is-connectors subpath. Connectors delegates connection lookups to the Connections service. Includes unit tests, endpoint constants, OAuth scope docs, and mkdocs nav. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 4077cfa commit c4bfefb

12 files changed

Lines changed: 763 additions & 0 deletions

File tree

‎docs/oauth-scopes.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
This page lists the specific OAuth scopes required in external app for each SDK method.
44

5+
## Integration Service — Connectors
6+
7+
| Method | OAuth Scope |
8+
|--------|-------------|
9+
| `getAll()` | `ConnectionService` or `ConnectionServiceUser` |
10+
| `getById()` | `ConnectionService` or `ConnectionServiceUser` |
11+
| `getDefaultConnection()` | `ConnectionService` or `ConnectionServiceUser` |
12+
| `getConnections()` | `ConnectionService` or `ConnectionServiceUser` |
13+
514
## Integration Service — Connections
615

716
| Method | OAuth Scope |

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,7 @@ nav:
200200
- Choice Sets: api/interfaces/ChoiceSetServiceModel.md
201201
- Governance: api/interfaces/GovernanceServiceModel.md
202202
- Integration Service:
203+
- Connectors: api/interfaces/ConnectorsServiceModel.md
203204
- Connections: api/interfaces/ConnectionsServiceModel.md
204205
- Maestro:
205206
- Processes: api/interfaces/MaestroProcessesServiceModel.md

‎package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,16 @@
216216
"default": "./dist/governance/index.cjs"
217217
}
218218
},
219+
"./is-connectors": {
220+
"import": {
221+
"types": "./dist/is-connectors/index.d.ts",
222+
"default": "./dist/is-connectors/index.mjs"
223+
},
224+
"require": {
225+
"types": "./dist/is-connectors/index.d.ts",
226+
"default": "./dist/is-connectors/index.cjs"
227+
}
228+
},
219229
"./is-connections": {
220230
"import": {
221231
"types": "./dist/is-connections/index.d.ts",

‎rollup.config.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,11 @@ const serviceEntries = [
229229
input: 'src/services/governance/index.ts',
230230
output: 'governance/index'
231231
},
232+
{
233+
name: 'is-connectors',
234+
input: 'src/services/integration-service/connectors/index.ts',
235+
output: 'is-connectors/index'
236+
},
232237
{
233238
name: 'is-connections',
234239
input: 'src/services/integration-service/connections/index.ts',

‎src/models/integration-service/connectors.models.ts‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
/**
2+
* Integration Service — Connector models
3+
*
4+
* Connectors are read-only catalog entries — no bound entity methods are
5+
* attached (no `update`, `cancel`, etc. operate on a connector).
6+
*/
7+
8+
import {
9+
RawConnectorGetResponse,
10+
ConnectorGetAllOptions,
11+
ConnectorGetDefaultConnectionOptions,
12+
ConnectorGetConnectionsOptions,
13+
} from './connectors.types';
14+
import { ConnectionGetResponse } from './connections.models';
15+
16+
/**
17+
* A connector catalog entry from the Integration Service.
18+
*/
19+
export type ConnectorGetResponse = RawConnectorGetResponse;
20+
21+
/**
22+
* Service for inspecting UiPath Integration Service connectors.
23+
*
24+
* Connectors are the catalog of integrations available on a tenant (Slack,
25+
* Microsoft 365, Salesforce, custom connectors, ...). Use this service to
26+
* discover connectors, fetch their metadata, and list / locate the connection
27+
* instances built on top of them.
28+
*
29+
* ### Usage
30+
*
31+
* Prerequisites: Initialize the SDK first - see [Getting Started](/uipath-typescript/getting-started/#import-initialize)
32+
*
33+
* ```typescript
34+
* import { Connectors } from '@uipath/uipath-typescript/is-connectors';
35+
*
36+
* const connectors = new Connectors(sdk);
37+
* const allConnectors = await connectors.getAll();
38+
* ```
39+
*/
40+
export interface ConnectorsServiceModel {
41+
/**
42+
* List all connectors available on this tenant.
43+
*
44+
* Returns a plain array — the Integration Service does not paginate this endpoint.
45+
*
46+
* @param options - Optional filter (e.g. limit to connectors exposing HTTP Request activities)
47+
* @returns Promise resolving to an array of {@link ConnectorGetResponse}
48+
* @example
49+
* ```typescript
50+
* import { Connectors } from '@uipath/uipath-typescript/is-connectors';
51+
*
52+
* const connectors = new Connectors(sdk);
53+
*
54+
* const all = await connectors.getAll();
55+
* for (const connector of all) {
56+
* console.log(`${connector.key} — ${connector.name} (${connector.lifeCycleStage})`);
57+
* }
58+
* ```
59+
*
60+
* @example
61+
* ```typescript
62+
* // Only connectors that expose an HTTP Request activity
63+
* const httpEnabled = await connectors.getAll({ hasHttpRequest: true });
64+
* ```
65+
*/
66+
getAll(options?: ConnectorGetAllOptions): Promise<ConnectorGetResponse[]>;
67+
68+
/**
69+
* Get a single connector by key or numeric ID.
70+
*
71+
* @param keyOrId - Connector key (e.g. `uipath-slack`) or numeric ID as a string
72+
* @returns Promise resolving to a {@link ConnectorGetResponse}
73+
* @example
74+
* ```typescript
75+
* import { Connectors } from '@uipath/uipath-typescript/is-connectors';
76+
*
77+
* const connectors = new Connectors(sdk);
78+
*
79+
* const slack = await connectors.getById('uipath-slack');
80+
* console.log(slack.name, slack.authentication?.type);
81+
* ```
82+
*/
83+
getById(keyOrId: string): Promise<ConnectorGetResponse>;
84+
85+
/**
86+
* Get the default connection for a connector in the current folder.
87+
*
88+
* Each connector may have a single connection marked as default per folder;
89+
* use this to resolve "which connection should I use for Slack?" without
90+
* paging through the full list.
91+
*
92+
* @param keyOrId - Connector key or numeric ID as a string
93+
* @param options - Folder scoping options
94+
* @returns Promise resolving to a {@link ConnectionGetResponse}
95+
* @example
96+
* ```typescript
97+
* import { Connectors } from '@uipath/uipath-typescript/is-connectors';
98+
*
99+
* const connectors = new Connectors(sdk);
100+
*
101+
* const defaultSlack = await connectors.getDefaultConnection('uipath-slack', {
102+
* folderKey: '<folderKey>',
103+
* });
104+
*
105+
* // Use bound methods directly on the entity
106+
* const status = await defaultSlack.ping();
107+
* console.log(status.status);
108+
* ```
109+
*/
110+
getDefaultConnection(
111+
keyOrId: string,
112+
options?: ConnectorGetDefaultConnectionOptions,
113+
): Promise<ConnectionGetResponse>;
114+
115+
/**
116+
* List all connections for a connector.
117+
*
118+
* Returns a plain array — the Integration Service uses page-indexed
119+
* pagination (no continuation cursor). Increment `pageIndex` to walk pages.
120+
*
121+
* @param keyOrId - Connector key or numeric ID as a string
122+
* @param options - Folder scoping, paging, and sorting options
123+
* @returns Promise resolving to an array of {@link ConnectionGetResponse}
124+
* @example
125+
* ```typescript
126+
* import { Connectors } from '@uipath/uipath-typescript/is-connectors';
127+
*
128+
* const connectors = new Connectors(sdk);
129+
*
130+
* // First page of Slack connections in a folder
131+
* const slackConnections = await connectors.getConnections('uipath-slack', {
132+
* folderKey: '<folderKey>',
133+
* pageSize: 25,
134+
* });
135+
*
136+
* for (const conn of slackConnections) {
137+
* const status = await conn.ping();
138+
* console.log(`${conn.name}: ${status.status}`);
139+
* }
140+
* ```
141+
*
142+
* @example
143+
* ```typescript
144+
* // Walk subsequent pages
145+
* const page2 = await connectors.getConnections('uipath-slack', {
146+
* folderKey: '<folderKey>',
147+
* pageSize: 25,
148+
* pageIndex: 2,
149+
* });
150+
* ```
151+
*/
152+
getConnections(
153+
keyOrId: string,
154+
options?: ConnectorGetConnectionsOptions,
155+
): Promise<ConnectionGetResponse[]>;
156+
}

‎src/models/integration-service/connectors.types.ts‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/**
2+
* Integration Service — Connector types
3+
*
4+
* Types for the Connectors API (`connections_/api/v1/Connectors`).
5+
*/
6+
7+
/**
8+
* Authentication scheme descriptor on a connector (`oauth2`, `basic`, `apiKey`, ...).
9+
* Shape is connector-dependent; exposed as a record so the SDK doesn't impose
10+
* a closed schema on third-party connectors.
11+
*/
12+
export interface ConnectorAuthentication {
13+
/** Auth type identifier (e.g. `oauth2`, `basic`, `apiKey`). */
14+
type?: string;
15+
/** Free-form fields specific to the auth scheme. */
16+
[key: string]: unknown;
17+
}
18+
19+
/**
20+
* Template metadata describing how the connector should be configured at runtime.
21+
* Shape is connector-dependent; preserved as-is from the API.
22+
*/
23+
export interface ConnectorTemplateProperties {
24+
[key: string]: unknown;
25+
}
26+
27+
/**
28+
* Raw connector response from the Integration Service API.
29+
*/
30+
export interface RawConnectorGetResponse {
31+
/** Numeric connector ID. */
32+
id: number;
33+
/** Stable connector key (used as `elementKey` for Elements API calls). */
34+
key: string;
35+
/** Display name (e.g. "Slack", "Microsoft OneDrive"). */
36+
name: string;
37+
/** Free-form description. */
38+
description?: string;
39+
/** URL to the connector's logo image. */
40+
image?: string;
41+
/** Whether the connector is private (custom or org-scoped). */
42+
isPrivate: boolean;
43+
/** Whether the connector publishes events / triggers. */
44+
hasEvents?: boolean;
45+
/** Event types the connector emits. */
46+
eventTypes?: string[];
47+
/** Lifecycle stage (e.g. `GA`, `BETA`, `CUSTOM`). */
48+
lifeCycleStage?: string;
49+
/** Tag string (comma-separated). */
50+
tags?: string;
51+
/** Connector classification (e.g. `application`, `database`). */
52+
type?: string;
53+
/** Tier (e.g. `1`, `2`). */
54+
tier?: string;
55+
/** Boolean feature flags exposed by the connector. */
56+
flags?: Record<string, boolean>;
57+
/** Template properties describing how to configure the connector. */
58+
templateProperties?: ConnectorTemplateProperties;
59+
/** Authentication scheme(s) supported by the connector. */
60+
authentication?: ConnectorAuthentication;
61+
/** Categories the connector belongs to (e.g. `CRM`, `Communication`). */
62+
categories?: string[];
63+
/** Number of connection instances for this connector. */
64+
connectionCount?: number;
65+
/** ID of the parent custom connector (when this connector is a fork). */
66+
customConnectorId?: number;
67+
/** Whether the connector is enabled on this tenant. */
68+
enabled?: boolean;
69+
/** Whether the caller owns the connector. */
70+
isOwner?: boolean;
71+
/** Vendor / publisher name. */
72+
vendorName?: string;
73+
}
74+
75+
/**
76+
* Options for {@link ConnectorsServiceModel.getAll}.
77+
*/
78+
export interface ConnectorGetAllOptions {
79+
/** Limit results to connectors that expose an HTTP Request activity. */
80+
hasHttpRequest?: boolean;
81+
}
82+
83+
// getById takes no body/query options — keyOrId is positional.
84+
85+
/**
86+
* Options for {@link ConnectorsServiceModel.getDefaultConnection}.
87+
*/
88+
export interface ConnectorGetDefaultConnectionOptions {
89+
/** Folder key (GUID) to scope the lookup. */
90+
folderKey?: string;
91+
/** Search across folders the caller has access to. */
92+
allFolders?: boolean;
93+
}
94+
95+
/**
96+
* Options for {@link ConnectorsServiceModel.getConnections}.
97+
*
98+
* The API returns a plain array — pagination is page-indexed via `pageIndex`/`pageSize`.
99+
* There is no continuation cursor; callers paginate by incrementing `pageIndex`.
100+
*/
101+
export interface ConnectorGetConnectionsOptions {
102+
/** Folder key (GUID) to scope the query to a specific folder. */
103+
folderKey?: string;
104+
/** Include connections from all folders the caller has access to. */
105+
allFolders?: boolean;
106+
/** Include only default connections. */
107+
folderDefaults?: boolean;
108+
/** 1-indexed page number. */
109+
pageIndex?: number;
110+
/** Page size (number of items per page). */
111+
pageSize?: number;
112+
/** Sort newest-first. */
113+
mostRecentFirst?: boolean;
114+
/** Force a connector refresh, skipping cache. */
115+
fetchLatest?: boolean;
116+
}

‎src/models/integration-service/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,7 @@
44
* Internal-types files are intentionally not re-exported.
55
*/
66

7+
export * from './connectors.types';
8+
export * from './connectors.models';
79
export * from './connections.types';
810
export * from './connections.models';

0 commit comments

Comments
 (0)