uipath-connector-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Connector Builder

连接器构建器

Author UiPath Integration Service connectors on disk with

uip is connectors builder

, then

import

publish

them through the parent

uip is connectors

. A connector is a

periodic-*

repo (

periodic-uipath-{vendor}-{product}

for official;

periodic-design-{org}-{slug}

for custom —

init

derives the

design-{org}-{slug}

element key from

--name

--organization

) whose core is

app/element/element.json

plus

standard-resources/*.json

and JavaScript

hooks/

. Connectors wrap REST APIs that return JSON only — no SOAP, GraphQL, or XML. Terminology: the authoring noun is activity (it maps to an element.json resource + a standard-resource file).

通过

uip is connectors builder

在磁盘上创作UiPath Integration Service连接器，随后通过父级

uip is connectors

进行

import

（导入）和

publish

（发布）操作。连接器是一个

periodic-*

类型的仓库（官方连接器为

periodic-uipath-{vendor}-{product}

；自定义连接器为

periodic-design-{org}-{slug}

——

init

命令会通过

--name

和

--organization

参数生成

design-{org}-{slug}

元素标识），其核心是

app/element/element.json

文件，外加

standard-resources/*.json

和JavaScript代码目录

hooks/

。连接器仅封装返回JSON格式的REST API——不支持SOAP、GraphQL或XML。术语说明：创作过程中的核心名词是activity（活动）（对应element.json中的资源以及一个standard-resource文件）。

When to Use This Skill

何时使用此技能

Creating a new connector from a vendor's API docs (init → auth → activities → validate → import → publish).
Editing an existing connector: adding activities, fields, parameters, methods, or hooks.
Configuring or switching authentication (OAuth2, PKCE, client credentials, API key, basic, JWT, AWS v4, etc.).
Writing or fixing JavaScript request/response hooks.
Wiring a polling or webhook trigger on an existing activity.
Debugging a connector, activity, hook, or trigger problem in
```
element.json
```
/ a standard-resource file.
Validating before release, or pulling/pushing a design connector to a tenant.

根据供应商的API文档创建新连接器（初始化 → 认证配置 → 活动创建 → 验证 → 导入 → 发布）。
编辑现有连接器：添加活动、字段、参数、方法或钩子。
配置或切换认证方式（OAuth2、PKCE、客户端凭证、API密钥、基础认证、JWT、AWS v4等）。
编写或修复JavaScript请求/响应钩子。
为现有活动配置轮询或webhook触发器。
调试
```
element.json
```
或standard-resource文件中的连接器、活动、钩子或触发器问题。
发布前验证，或将设计连接器拉取/推送至租户。

Critical Rules

关键规则

Inspect before editing. On any existing connector, run
```
builder inspect
```
first to map auth, config, activities, hooks, and triggers. Never edit blind. Never invent config keys, activity paths, or IDs — read state first (
```
inspect
```
,
```
activity list
```
,
```
state query
```
).
Validate before you finish. Run
```
builder validate
```
at the end of every workflow and after each fix — it runs the full periodic check set and exits non-zero on failure. On failure, read the reported field, fix that one entry, re-validate. After 3 failed attempts on the same error, stop and surface the
```
validate
```
output — don't keep guessing. Don't stop at "0 errors": read the WARNINGS too — they flag real gaps that still ship a half-built connector (a fieldless activity, a broken SR link). Treat them as must-fix unless you can articulate why a given one is acceptable.
auth set
owns all authentication. It writes the config entries,
```
authentication.type
```
/
```
typeOauth
```
/
```
authenticationTypes
```
, and the token-refresh resource in one call. Define scopes here too (
```
--scope
```
,
```
--scope-options
```
,
```
--required-scopes
```
,
```
--preselected-scopes
```
) — there is no separate scope command.
```
init --auth oauth2|customApiKey
```
is inline sugar for the create-time common case; everything else goes through
```
auth set
```
. Never hand-roll auth via
```
state patch
```
.
activity create
writes both sides in one call — the standard-resource file AND one
```
element.json
```
entry per method. Re-running on an existing activity appends/merges. Pass
```
--skip-sr
```
(or use
```
auth system create
```
) only for system resources that need no SR file. Model
```
GETBYID
```
/
```
PATCH
```
/
```
PUT
```
/
```
DELETE
```
only for TRUE by-id endpoints — never for search. The
```
/{primaryKey}
```
path param is added automatically: ALWAYS for
```
GETBYID
```
, and for
```
PATCH
```
/
```
PUT
```
/
```
DELETE
```
only when the activity is CRUD (it also has a
```
GET
```
/
```
GETBYID
```
); a write-only/action activity keeps its base path.
state patch
REPLACES the whole node at a pointer (no merge). To change one field:
```
state query
```
the entry, edit it, then
```
state patch
```
the COMPLETE object back.
```
element-metadata.json
```
has no addressable sub-paths — round-trip the whole file. Activity paths in pointers are URL-encoded:
```
/contacts
```
→
```
%2Fcontacts
```
. Use the dedicated authoring verbs for creation, not
```
state patch
```
.
Connector targeting. Builder verbs walk up from the cwd, then scan immediate subdirectories, then fall back to the
```
.uip-connector.json
```
marker
```
init
```
writes in the directory it ran from — so follow-up commands from that same directory hit the last-init connector automatically, even next to other connector dirs. Pass
```
--connector-dir <PATH>
```
to override or when working from elsewhere.
```
import
```
reads
```
--connector-dir
```
the same way (the connector root holding
```
app/element/element.json
```
); on
```
download
```
it instead names the OUTPUT directory to write the pulled connector into. Exception —
init
does NOT scan subdirectories (it would otherwise resolve a SIBLING connector and silently EDIT/rename it): to CREATE, run
```
init
```
from a fresh/empty directory (a dir that merely contains connector subdirs — e.g.
```
/tmp
```
— creates a new connector, it will not dive into a child to edit it); to EDIT, run from inside the connector or pass
```
--connector-dir
```
.
Output is the
{Result, Code, Data}
envelope. Add
```
--output json
```
to parse it. Failures exit non-zero. Never suppress stderr.
import
/
download
/
publish
— and
init
when CREATING — need
uip login
. Authenticate before any tenant pull/push. A NEW connector's key
```
design-{org}-{slug}
```
takes its org from your logged-in session, so
```
init
```
create ERRORS when you're not logged in. Let it derive the org; do NOT pass a guessed
```
--organization
```
(a wrong org bakes into the key and only surfaces, mismatched, at import/publish) —
```
--organization <slug>
```
is only for offline/CI builds with a known org.
Never echo, log, or hard-code a secret. Secret config keys (client secret, API key, password, token) are written by
```
auth set
```
ENCRYPTED (
```
encrypt: true
```
) — most as
```
PASSWORD
```
fields, though some (OAuth tokens, a service-account JSON) are encrypted
```
TEXTFIELD
```
/
```
TEXTAREA
```
. End users supply real credentials at connection time; the connector holds only the auth TYPE + endpoint URLs + scopes. Use placeholders in every example command.
Prefer a built-in over a hook. Before writing JS, consult the decision table (references/hooks.md §"Decide first: hook or built-in?") — a hook is only for transforms, orchestration, or derivation no declarative feature expresses. One hook file per activity+method+phase; hooks run in Denali (modern JS +
```
require('axios')
```
for secondary calls) and must end every path with
```
done()
```
.
Author the field schema for EVERY activity —
activity create
does NOT infer fields. An activity with no fields renders in Studio Web as a single raw JSON body in and raw JSON out, with zero typed inputs/outputs — a half-built connector that still validates and publishes, so the omission is easy to miss (it's a recurring failure: "got it valid and published" while skipping the schema). After
```
activity create
```
, ALWAYS define the request/response fields from the vendor's documented schema — either pass
```
--fields-file <json>
```
on
```
activity create
```
for the whole schema at once, or add them one at a time with
```
activity field create
```
.
```
validate
```
emits a WARNING for any fieldless activity — treat it as must-fix. Never report a connector "done" with fieldless activities; if a raw-body passthrough is genuinely intended, say so explicitly.

编辑前先检查。对于任何现有连接器，先运行
```
builder inspect
```
来梳理认证、配置、活动、钩子和触发器信息。切勿盲目编辑。切勿自行创建配置键、活动路径或ID——先读取状态信息（
```
inspect
```
、
```
activity list
```
、
```
state query
```
）。
完成前先验证。在每个工作流结束后以及每次修复后运行
```
builder validate
```
——它会执行完整的周期性检查，若失败则返回非零退出码。失败时，查看报告的字段，修复对应条目后重新验证。若同一错误连续3次修复失败，请停止操作并提交
```
validate
```
的输出结果——不要继续猜测。不要仅满足于“0错误”：还要查看警告信息——它们会标记出可能导致连接器半成品发布的实际问题（如无字段的活动、损坏的SR链接）。除非能明确说明某条警告无需修复，否则必须处理。
所有认证配置由
auth set
负责。它会一次性写入配置条目、
```
authentication.type
```
/
```
typeOauth
```
/
```
authenticationTypes
```
以及令牌刷新资源。也可在此定义权限范围（
```
--scope
```
、
```
--scope-options
```
、
```
--required-scopes
```
、
```
--preselected-scopes
```
）——没有单独的权限范围命令。
```
init --auth oauth2|customApiKey
```
是创建时常见场景的简化写法；其他所有认证配置均需通过
```
auth set
```
完成。切勿通过
```
state patch
```
手动配置认证。
activity create
会一次性创建两端内容——standard-resource文件和每个方法对应的
```
element.json
```
条目。对现有活动重新运行该命令会进行追加/合并。仅当系统资源无需SR文件时，才使用
```
--skip-sr
```
参数（或使用
```
auth system create
```
）。仅针对真正的按ID查询端点建模
```
GETBYID
```
/
```
PATCH
```
/
```
PUT
```
/
```
DELETE
```
——切勿用于搜索。
```
/{primaryKey}
```
路径参数会自动添加：
```
GETBYID
```
始终添加；
```
PATCH
```
/
```
PUT
```
/
```
DELETE
```
仅当活动为CRUD类型（同时包含
```
GET
```
/
```
GETBYID
```
）时添加；仅写入/动作类活动保留其基础路径。
state patch
会替换指针指向的整个节点（不进行合并）。要修改单个字段：先通过
```
state query
```
查询条目，编辑后再通过
```
state patch
```
将完整对象写回。
```
element-metadata.json
```
没有可寻址的子路径——需往返整个文件。指针中的活动路径会进行URL编码：
```
/contacts
```
→
```
%2Fcontacts
```
。请使用专用的创作命令进行创建操作，而非
```
state patch
```
。
连接器定位。构建器命令会从当前工作目录向上查找，然后扫描直接子目录，最后回退到
```
init
```
命令在其运行目录中写入的
```
.uip-connector.json
```
标记文件——因此即使在其他连接器目录旁，从同一目录执行后续命令会自动定位到最后初始化的连接器。可通过
```
--connector-dir <PATH>
```
参数覆盖此行为，或在其他目录工作时使用该参数。
```
import
```
命令以相同方式读取
```
--connector-dir
```
（指向包含
```
app/element/element.json
```
的连接器根目录）；而
```
download
```
命令则使用该参数指定拉取的连接器要写入的输出目录。例外情况——
init
不会扫描子目录（否则会解析到兄弟连接器并静默编辑/重命名）：要创建连接器，请在全新/空目录中运行
```
init
```
（仅包含连接器子目录的目录——如
```
/tmp
```
——会创建新连接器，不会深入子目录进行编辑）；要编辑连接器，请在连接器目录内运行
```
init
```
或传递
```
--connector-dir
```
参数。
输出格式为
{Result, Code, Data}
信封结构。添加
```
--output json
```
参数可解析输出结果。失败时返回非零退出码。切勿抑制标准错误输出。
import
/
download
/
publish
——以及创建时的
init
——需要
uip login
。在执行任何租户拉取/推送操作前先认证。新连接器的标识
```
design-{org}-{slug}
```
会从登录会话中获取组织信息，因此未登录时
```
init
```
（创建）会报错。请让系统自动推导组织信息；切勿传递猜测的
```
--organization
```
参数（错误的组织信息会嵌入标识中，仅在导入/发布时才会暴露不匹配问题）——
```
--organization <slug>
```
仅适用于离线/CI构建且已知组织信息的场景。
切勿回显、记录或硬编码密钥。密钥配置项（客户端密钥、API密钥、密码、令牌）由
```
auth set
```
加密写入（
```
encrypt: true
```
）——大多数为
```
PASSWORD
```
字段，部分（OAuth令牌、服务账户JSON）为加密的
```
TEXTFIELD
```
/
```
TEXTAREA
```
。最终用户会在连接时提供真实凭证；连接器仅保存认证类型、端点URL和权限范围。在所有示例命令中使用占位符。
优先使用内置功能而非钩子。编写JS代码前，请参考决策表（references/hooks.md §"先决定：使用钩子还是内置功能？"）——仅当无声明式功能可实现转换、编排或派生时才使用钩子。每个活动+方法+阶段对应一个钩子文件；钩子在Denali中运行（现代JS +
```
require('axios')
```
用于二次调用），且每条路径必须以
```
done()
```
结尾。
为每个活动编写字段 schema——
activity create
不会自动推断字段。无字段的活动在Studio Web中会显示为单一的原始JSON输入和输出体，没有任何类型化的输入/输出——这是一个半成品连接器，但仍可通过验证并发布，因此容易遗漏该问题（这是常见错误：“已通过验证并发布”但跳过了schema定义）。执行
```
activity create
```
后，务必根据供应商文档定义的schema添加请求/响应字段——可在
```
activity create
```
时通过
```
--fields-file <json>
```
参数一次性传入完整schema，或通过
```
activity field create
```
逐个添加字段。
```
validate
```
会对无字段的活动发出警告——必须处理该警告。切勿将存在无字段活动的连接器标记为“完成”；如果确实需要原始体透传，请明确说明。

Connection design (host, region, discovered values)

连接设计（主机、区域、发现值）

Decide how each per-connection value reaches the request BEFORE scaffolding — getting this wrong is the most common rework:

One config drives the host — not three URLs. When the base, token, and authorize hosts share a per-connection part (an instance name, region, datacenter, or workspace), surface ONE config and template it into every URL:
```
init --base-url 'https://{instance}.../api'
```
+
```
auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'
```
. The CLI auto-seeds a single fillable
```
{instance}
```
field that resolves all three (references/configuration.md §Templated hosts). Do NOT expose
```
base.url
```
/
```
oauth.token.url
```
/
```
oauth.authorization.url
```
as separate connection fields.
Open value → TEXTFIELD; fixed set → COMBO. A free-form instance/workspace/account name is the auto-seeded templated TEXTFIELD — that is a legitimate, common shape, not a smell. Only a genuinely fixed datacenter/environment list becomes a COMBO (
```
state patch
```
the seeded entry to
```
type:COMBO
```
with
```
options
```
, whose
```
value
```
can be the host fragment itself).
Derive or discover before you ask. If a per-connection value (the API host, an org/account id) is returned in the token response or is discoverable via an authenticated call, capture it instead of adding a manual field — but ONLY when it is genuinely needed AND obtainable; a single templated config is the simpler default, so don't over-engineer discovery where a plain field suffices. Token-response host → a
```
postRequest
```
hook that validates (https + allowlisted host, never log the token) and persists via
```
done({configuration})
```
— recipe: references/hooks.md §"Pattern: base URL …". Discoverable id → an
```
onProvision
```
system resource that calls the lookup at connection time (references/system-resources.md).
User-facing configs need guidance. Every
```
configScreenType:"pre"
```
or
```
"pre-optional"
```
field should have
```
hintText
```
with an example or where to find the value. give every visible connection-form field a hint (
```
validate
```
does not currently check this) for instance/workspace IDs, tenant hosts, and token-type-specific credentials.
Multi-datacenter OAuth: the accounts/token host itself varies by region — template the region config into
```
--token-url
```
/
```
--authorization-url
```
too, not just the base URL.

在搭建前先确定每个连接值如何到达请求——这是最常见的返工原因：

一个配置驱动主机——而非三个URL。当基础URL、令牌URL和授权URL共享连接特定部分（实例名称、区域、数据中心或工作区）时，只需暴露一个配置项并将其模板化到所有URL中：
```
init --base-url 'https://{instance}.../api'
```
+
```
auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'
```
。CLI会自动生成一个可填写的
```
{instance}
```
字段，用于解析所有三个URL（references/configuration.md §模板化主机）。请勿将
```
base.url
```
/
```
oauth.token.url
```
/
```
oauth.authorization.url
```
作为单独的连接字段暴露。
开放值→TEXTFIELD；固定集合→COMBO。自由格式的实例/工作区/账户名称是自动生成的模板化TEXTFIELD——这是合理且常见的形式，并非问题。只有真正固定的数据中心/环境列表才需设置为COMBO（通过
```
state patch
```
将生成的条目修改为
```
type:COMBO
```
并添加
```
options
```
，其
```
value
```
可以是主机片段本身）。
先推导或发现，再询问用户。如果连接特定值（API主机、组织/账户ID）在令牌响应中返回或可通过认证调用发现，请捕获该值而非添加手动字段——但仅当该值确实需要且可获取时才这样做；单一模板化配置是更简单的默认方案，因此不要在普通字段足够的情况下过度设计发现机制。令牌响应中的主机→使用
```
postRequest
```
钩子验证（必须是HTTPS且在允许列表中，切勿记录令牌）并通过
```
done({configuration})
```
持久化——参考方案：references/hooks.md §"模式：基础URL …"。可发现的ID→使用
```
onProvision
```
系统资源在连接时调用查询（references/system-resources.md）。
面向用户的配置需要引导信息。每个
```
configScreenType:"pre"
```
或
```
"pre-optional"
```
字段都应包含
```
hintText
```
，提供示例或说明在哪里找到对应值。为每个可见的连接表单字段添加提示（
```
validate
```
目前不检查此项），例如实例/工作区ID、租户主机和特定令牌类型的凭证。
多数据中心OAuth：账户/令牌主机本身因区域而异——请将区域配置模板化到
--token-url
/
--authorization-url
中，而不仅仅是基础URL。

Workflows

工作流

Each workflow is an ordered sequence of copy-paste-ready commands. Use placeholders (

<ORG>

https://api.example.com

) — never real secrets.

每个工作流都是一系列可直接复制粘贴的命令。使用占位符（

<ORG>

、

https://api.example.com

）——切勿使用真实密钥。

New connector (full lifecycle)

新连接器（完整生命周期）

bash

undefined

bash

undefined

0. Log in FIRST. The key

design-{org}-{slug}

takes its org from your logged-in

0. 先登录。标识

design-{org}-{slug}

会从登录会话中获取组织信息，

session, so

init

(create) ERRORS if you're not logged in. Let it derive the

因此未登录时

init

（创建）会报错。请让系统自动推导组织信息——

org — do NOT guess --organization (a wrong org bakes into the key and only

不要猜测--organization参数（错误的组织信息会嵌入标识中，仅在导入时才会暴露不匹配问题）。

surfaces, mismatched, at import). --organization <slug> is for offline/CI only.

--organization <slug>仅适用于离线/CI构建场景。

uip login status # check Data.Status == "Logged in" — NOT the envelope # Result/exit, which is "Success" even when the session # is dead (refresh-failed / expired). (

init

create # itself re-checks the live login status and blocks.)

uip login status # 检查Data.Status == "Logged in" — 不要查看信封的 # Result/退出码，因为即使会话已失效（刷新失败/过期）， # 它仍会返回"Success"。（

init

创建时会重新检查实时登录状态并阻止操作。）

1. Scaffold the shell. --name is required when creating; key + folder are derived

1. 搭建连接器框架。创建时必须指定--name；标识和文件夹会自动生成

(the org comes from your login — see step 0).

（组织信息来自登录状态——见步骤0）。

uip is connectors builder init --name 'Acme Widgets'
--description 'Acme Widgets connector' --categories 'CRM,Sales and marketing'
--base-url https://api.acme.com --auth oauth2
--authorization-url https://acme.com/oauth/authorize
--token-url https://acme.com/oauth/token --scope 'read write'

--categories must be approved DISPLAY-NAME values (e.g. 'CRM', 'Sales and marketing',

--categories必须使用已批准的显示名称（如'CRM'、'Sales and marketing'、

'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like

crm,sales

'Collaboration'、'Productivity'、'E-commerce'）——不能使用小写别名如

crm,sales

。

Validated at init AND

validate

: wrong case is canonicalized, an unknown value fails fast

会在init和

validate

时验证：错误的大小写会被规范化，未知值会立即失败，

and the error lists the approved enum. init seeds element-metadata.json:latestVersion = "1.0.0".

错误信息会列出已批准的枚举值。init会在element-metadata.json中设置latestVersion = "1.0.0"。

2. Add an activity (writes element.json entries + standard-resources/accounts.json).

2. 添加活动（写入element.json条目 + standard-resources/accounts.json）。

uip is connectors builder activity create --name accounts --vendor-path /v1/accounts
--methods GET,GETBYID,POST,PATCH,DELETE --primary-key id --has-ceql

3. Author the field schema — REQUIRED, not optional (Rule 11).

activity create

3. 编写字段 schema —— 必填项，而非可选项（规则11）。

activity create

does NOT infer fields; without this the activity ships as a raw JSON body and

不会自动推断字段；不执行此步骤的话，活动会以原始JSON体形式发布，

validate

warns. Pass

--fields-file <json>

activity create

for the whole

且

validate

会发出警告。可在

activity create

时通过

--fields-file <json>

参数

schema at once, or add fields one at a time with

field create

一次性传入完整schema，或通过

field create

逐个添加字段

(visibility flags apply to every --method listed; re-runs merge):

（可见性标志适用于所有列出的--method；重新运行会合并配置）：

uip is connectors builder activity field create --resource accounts --name email
--type string --method GET --method POST --response

4. Validate — must be 0 errors AND no unresolved warnings (fieldless activity,

4. 验证——导入前必须确保0错误且无未解决的警告（如无字段活动、

broken SR link) before import.

损坏的SR链接）。

uip is connectors builder validate

5. Import (create-or-update on the tenant) then publish.

5. 导入（在租户上创建或更新）然后发布。

uip login uip is connectors import uip is connectors publish --wait # blocks until SUCCESS; live in Studio Web then # (fire-and-forget without --wait: allow ~5-10 min)

Publishing a NEW connector needs no `--version` (init seeded `1.0.0`). **Re-publishing** an existing connector requires a HIGHER version — bump `element-metadata.json:latestVersion` (or pass `--version 1.0.1`); the server rejects an equal version.

uip login uip is connectors import uip is connectors publish --wait # 阻塞直至成功；随后会在Studio Web中上线 # （不使用--wait的异步方式：需等待约5-10分钟）

发布新连接器无需指定`--version`（init已设置为`1.0.0`）。**重新发布**现有连接器需要更高版本——需更新`element-metadata.json:latestVersion`（或传递`--version 1.0.1`）；服务器会拒绝版本号相同的发布请求。

Add an activity to an existing connector

为现有连接器添加活动

bash

uip is connectors builder inspect --output json     # map what exists first

bash

uip is connectors builder inspect --output json     # 先梳理现有内容

research the vendor API, then:

研究供应商API，然后执行：

uip is connectors builder activity create --name contacts --vendor-path /v1/contacts
--methods GET,GETBYID,POST --primary-key id --fields-file ./contacts-fields.json uip is connectors builder activity field create --resource contacts --name status
--type string --method GET --response --searchable uip is connectors builder activity hook create --resource-name contacts --method GET
--hook-type postRequest --custom-code-file ./contacts-postRequest.js # optional response shaping (you write the JS) uip is connectors builder validate

undefined

uip is connectors builder activity create --name contacts --vendor-path /v1/contacts
--methods GET,GETBYID,POST --primary-key id --fields-file ./contacts-fields.json uip is connectors builder activity field create --resource contacts --name status
--type string --method GET --response --searchable uip is connectors builder activity hook create --resource-name contacts --method GET
--hook-type postRequest --custom-code-file ./contacts-postRequest.js # 可选的响应格式化（需自行编写JS） uip is connectors builder validate

undefined

Add a polling trigger

添加轮询触发器

trigger create

authors a POLLING trigger. The target activity must already exist and have an SR file (

trigger create

hard-fails otherwise).

bash

uip is connectors builder activity list --output json    # confirm the activity exists
uip is connectors builder trigger create --resource-name accounts --event-kind polling \
  --updated-date-field LastModifiedDate --id-field Id     # seeds the event config + hasEvents flag
uip is connectors builder validate

--updated-date-field

is REQUIRED for every

--event-kind

— the command always authors a polling loop.

--event-kind polling|webhook|all

(default

polling

) only picks the config bundle;

webhook

all

add webhook config keys but don't implement delivery. Webhook delivery, the polling-vs-webhook semantics, and per-flag defaults all live in references/events.md.

trigger create

用于创建轮询触发器。目标活动必须已存在且拥有SR文件（否则

trigger create

会直接失败）。

bash

uip is connectors builder activity list --output json    # 确认活动存在
uip is connectors builder trigger create --resource-name accounts --event-kind polling \
  --updated-date-field LastModifiedDate --id-field Id     # 生成事件配置和hasEvents标志
uip is connectors builder validate

--updated-date-field

是每个

--event-kind

的必填项——该命令始终会生成轮询循环配置。

--event-kind polling|webhook|all

（默认

polling

）仅选择配置包；

webhook

all

会添加webhook配置键，但不会实现交付功能。Webhook交付、轮询与webhook的语义以及各标志的默认值均在references/events.md中定义。

Customize a curated activity

自定义精选活动

activity create

auto-curates every method into a standalone Studio activity by default (opt out with

--no-curate

). Use

method curate

only to override the generated name/displayName, or to curate a

--no-curate

method. Generic CRUD activities are always present separately from curated activities: List/Get/Create/Update/Delete Records let the user choose any object that supports that method. Do not remove them or report them as pollution when you add a curated/list-capable object; author the curated service action alongside the generic object picker.

bash

uip is connectors builder activity method curate --resource cases --method GET \
  --display-name 'Get Support Request'
uip is connectors builder activity field create --resource cases --name subject --type string \
  --method GET --response --response-curated --design-position primary
uip is connectors builder validate

默认情况下，

activity create

会自动将每个方法整理为独立的Studio活动（可通过

--no-curate

参数取消）。仅当需要覆盖生成的名称/displayName，或要整理

--no-curate

方法时，才使用

method curate

。通用CRUD活动始终与精选活动分开存在：List/Get/Create/Update/Delete Records允许用户选择任何支持对应方法的对象。添加精选/支持列表的对象时，请勿删除这些通用活动或认为它们冗余；请在通用对象选择器旁创作精选服务操作。

bash

uip is connectors builder activity method curate --resource cases --method GET \
  --display-name 'Get Support Request'
uip is connectors builder activity field create --resource cases --name subject --type string \
  --method GET --response --response-curated --design-position primary
uip is connectors builder validate

Debug

调试

bash

uip is connectors builder inspect --output json

bash

uip is connectors builder inspect --output json

state patch REPLACES the node — query the WHOLE entry, change ONLY the field at fault, patch it ALL back:

state patch会替换节点——查询完整条目，仅修改有问题的字段，然后将完整对象写回：

uip is connectors builder state query element.json/configuration/oauth.token.url --output json uip is connectors builder state patch element.json/configuration/oauth.token.url
--value '<full entry from the query above, with defaultValue corrected>' uip is connectors builder validate

For a base URL or id derived at connection time: use a token-response `postRequest` hook when the value is returned by the token call, or an `onProvision` system resource when it must be discovered after auth. Validate the value, then persist it with `done({configuration})` — NOT `state patch`, which baking-time-edits one connection's value into every connection. Full recipe: [references/hooks.md](references/hooks.md) §"Pattern: base URL …"; investigation checklists: [references/debugging.md](references/debugging.md).

uip is connectors builder state query element.json/configuration/oauth.token.url --output json uip is connectors builder state patch element.json/configuration/oauth.token.url
--value '<上述查询得到的完整条目，修正defaultValue>' uip is connectors builder validate

对于连接时推导的基础URL或ID：如果值由令牌调用返回，使用令牌响应的`postRequest`钩子；如果必须在认证后发现，使用`onProvision`系统资源。验证值后，通过`done({configuration})`持久化——不要使用`state patch`，因为它会将单个连接的值固化到所有连接中。完整方案：[references/hooks.md](references/hooks.md) §"模式：基础URL …"; 排查清单：[references/debugging.md](references/debugging.md)。

Command Map

命令映射

text

uip is connectors                      # tenant/catalog + design-connector lifecycle (needs `uip login`)
  list | get <key> | swagger <key> | export <key> | audit-logs | event-operations
  download <key> | import | publish | publish-status <id> | probe
  builder                              # author a connector ON DISK
    init                               # create-or-EDIT the connector shell in ONE verb
                                       #   (folds the old scaffold / metadata / global / base+pagination preset)
        preset apply --kind base|pagination
        header delete <vendorName>
    auth     set | get | system (create|list)
    activity create | list | get | delete
             field  (create|list|get|delete)
             method (get|set|curate)
             param  (create|list|get|delete)
             hook   (create|list|get|delete)
    trigger  create                    # --event-kind polling|webhook|all (folds the event preset + polling)
    inspect                            # read-only whole-connector rollup
    validate                           # full check set; exits non-zero on failure
    state    query <pointer> | patch <pointer>

publish

returns a

PublishId

;

--wait

polls to SUCCESS/FAILURE (timeout via

--timeout-seconds

, default 600); check later with

publish-status <id>

(positional). Status enum:

IN_PROGRESS | SUCCESS | FAILURE

text

uip is connectors                      # 租户/目录 + 设计连接器生命周期（需要`uip login`）
  list | get <key> | swagger <key> | export <key> | audit-logs | event-operations
  download <key> | import | publish | publish-status <id> | probe
  builder                              # 在磁盘上创作连接器
    init                               # 用一个命令创建或编辑连接器框架
                                       #   （整合了旧版的scaffold / metadata / global / base+pagination预设）
        preset apply --kind base|pagination
        header delete <vendorName>
    auth     set | get | system (create|list)
    activity create | list | get | delete
             field  (create|list|get|delete)
             method (get|set|curate)
             param  (create|list|get|delete)
             hook   (create|list|get|delete)
    trigger  create                    # --event-kind polling|webhook|all（整合了event预设 + polling）
    inspect                            # 只读的全连接器汇总信息
    validate                           # 完整检查集；失败时返回非零退出码
    state    query <pointer> | patch <pointer>

publish

会返回

PublishId

；

--wait

会轮询直至成功/失败（可通过

--timeout-seconds

设置超时，默认600秒）；后续可通过

publish-status <id>

（位置参数）检查状态。状态枚举：

IN_PROGRESS | SUCCESS | FAILURE

。

Reference Navigation

参考导航

Depth lives in

references/

— each self-contained. SKILL.md owns the workflows, command map, and rules above; references must not repeat them. The always-current flag source is

uip is connectors builder <noun> <verb> --help

Task → read this	Reference
What a connector is, file layout, the CRUD/curated/HTTP activity model	references/overview.md
element.json internals: top-level fields, resources[], parameters[], value interpolation, hook order	references/element-json.md
Standard-resource files: linking, metadata.method, curated, fields (visibility/design/searchable)	references/standard-resources.md
configuration[] entries: widget types, screen types, per-auth key sets, pagination + event keys	references/configuration.md
Authentication setup: all 19 auth types (incl. JWT Bearer claims, FPS, none) and the OAuth/JWT scope surface	references/auth.md
Auth-system resources: auth-validation, onProvision/onDelete, OAuth token overrides	references/system-resources.md
When to write a hook vs use a built-in (decision table + good/avoidable patterns), execution order, context vars, done(), naming	references/hooks.md
Polling and webhook triggers: config keys, event.poller.configuration schema	references/events.md
Debugging auth / activity / hook / trigger / pagination issues (workflow + checklists)	references/debugging.md

详细内容位于

references/

目录下——每个文件都是独立的。SKILL.md负责上述工作流、命令映射和规则；参考文件不得重复这些内容。最新的命令参数说明请查看

uip is connectors builder <noun> <verb> --help

。

任务 → 阅读此文档	参考链接
连接器定义、文件布局、CRUD/精选/HTTP活动模型	references/overview.md
element.json内部结构：顶级字段、resources[]、parameters[]、值插值、钩子执行顺序	references/element-json.md
Standard-resource文件：链接、metadata.method、精选、字段（可见性/设计/可搜索）	references/standard-resources.md
configuration[]条目：组件类型、屏幕类型、各认证类型的键集合、分页 + 事件键	references/configuration.md
认证设置：所有19种认证类型（包括JWT Bearer声明、FPS、无认证）以及OAuth/JWT权限范围配置	references/auth.md
认证系统资源：认证验证、onProvision/onDelete、OAuth令牌覆盖	references/system-resources.md
何时编写钩子vs使用内置功能（决策表 + 推荐/避免的模式）、执行顺序、上下文变量、done()、命名规则	references/hooks.md
轮询和webhook触发器：配置键、event.poller.configuration schema	references/events.md
调试认证/活动/钩子/触发器/分页问题（工作流 + 检查清单）	references/debugging.md

Anti-patterns

反模式

Editing without
```
builder inspect
```
first (Rule 1) — you'll invent keys/paths that don't exist.
Hand-rolling auth via
```
state patch
```
instead of
```
auth set
```
(Rule 3) — leaves the auth block inconsistent.
Editing a config entry with a partial value (Rule 5) —
```
state patch
```
REPLACES the node, dropping omitted fields. Query the whole entry and patch the complete object back.
Re-running
```
activity create
```
with a name that already exists when you meant a SEPARATE activity — it's an idempotent upsert that MERGES into the same-named activity (appends methods, preserves existing field definitions unless
```
--overwrite-fields
```
); it does not error, so a wrong name silently merges instead of warning.
Modeling
```
GETBYID
```
for a search/list endpoint (Rule 4) — by-id verbs auto-add the
```
/{primaryKey}
```
param; reserve them for true single-record reads.
Putting a real secret in an example or expecting the connector to store one (Rule 9) — secrets are encrypted fields (usually PASSWORD) supplied at connection time.
Re-publishing without bumping the version — the server rejects an equal version; bump
```
latestVersion
```
or pass
```
--version
```
.
Invented
```
--categories
```
values — they must come from the approved enum;
```
validate
```
reports the list.
Writing a hook for a job a built-in does (Rule 10; hooks.md §"Recognizing an avoidable hook"), or omitting the trailing
```
done()
```
so the hook never returns.

Reaching for a removed command — there is no

connector scaffold/inspect/validate

wrapper (use

init

inspect

validate

directly), no

global

metadata

config

resource*

event polling add

auth scope

remote*

describe

reference

Reporting a connector "done" with fieldless activities (Rule 11) —
```
activity create
```
writes endpoints/methods/auth but NOT the field schema; an activity with no
```
field create
```
/
```
--fields-file
```
shows only a raw JSON body in Studio and trips a
```
validate
```
WARNING. Author fields before finishing, and never treat a 0-error/has-warnings validate as a pass.

未先运行
```
builder inspect
```
就进行编辑（规则1）——会创建不存在的键/路径。
通过
```
state patch
```
手动配置认证而非使用
```
auth set
```
（规则3）——会导致认证块不一致。
使用部分值编辑配置条目（规则5）——
```
state patch
```
会替换节点，丢失未指定的字段。请查询完整条目并将完整对象写回。
当需要创建独立活动时，对已存在的名称重新运行
```
activity create
```
——这是幂等的更新操作，会合并到同名活动中（追加方法，保留现有字段定义除非使用
```
--overwrite-fields
```
）；不会报错，因此错误的名称会静默合并而非发出警告。
为搜索/列表端点建模
```
GETBYID
```
（规则4）——按ID查询的动词会自动添加
```
/{primaryKey}
```
参数；请仅将其用于真正的单记录读取。
在示例中使用真实密钥或期望连接器存储密钥（规则9）——密钥是加密字段（通常为PASSWORD），由用户在连接时提供。
未升级版本就重新发布——服务器会拒绝版本号相同的请求；请更新
```
latestVersion
```
或传递
```
--version
```
参数。
使用自定义的
```
--categories
```
值——必须使用已批准的枚举值；
```
validate
```
会列出可用值。
为内置功能可完成的任务编写钩子（规则10；hooks.md §"识别可避免的钩子"），或遗漏结尾的
```
done()
```
导致钩子无法返回。

使用已移除的命令——没有

connector scaffold/inspect/validate

包装器（请直接使用

init

inspect

validate

），也没有

global

metadata

config

resource*

event polling add

auth scope

remote*

describe

reference

命令。

将存在无字段活动的连接器标记为“完成”（规则11）——
```
activity create
```
会写入端点/方法/认证信息，但不会写入字段schema；未执行
```
field create
```
/
```
--fields-file
```
的活动在Studio中仅显示原始JSON体，且会触发
```
validate
```
警告。请在完成前编写字段，切勿将0错误但存在警告的验证结果视为通过。

uipath-connector-builder

Original

Translation

Connector Builder

连接器构建器

When to Use This Skill

何时使用此技能

Critical Rules

关键规则

Connection design (host, region, discovered values)

连接设计（主机、区域、发现值）

Workflows

工作流

New connector (full lifecycle)

新连接器（完整生命周期）

0. Log in FIRST. The key design-{org}-{slug} takes its org from your logged-in

0. 先登录。标识design-{org}-{slug}会从登录会话中获取组织信息，

session, so init (create) ERRORS if you're not logged in. Let it derive the

因此未登录时init（创建）会报错。请让系统自动推导组织信息——

org — do NOT guess --organization (a wrong org bakes into the key and only

不要猜测--organization参数（错误的组织信息会嵌入标识中，仅在导入时才会暴露不匹配问题）。

surfaces, mismatched, at import). --organization <slug> is for offline/CI only.

--organization <slug>仅适用于离线/CI构建场景。

1. Scaffold the shell. --name is required when creating; key + folder are derived

1. 搭建连接器框架。创建时必须指定--name；标识和文件夹会自动生成

(the org comes from your login — see step 0).

（组织信息来自登录状态——见步骤0）。

--categories must be approved DISPLAY-NAME values (e.g. 'CRM', 'Sales and marketing',

--categories必须使用已批准的显示名称（如'CRM'、'Sales and marketing'、

'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like crm,sales.

'Collaboration'、'Productivity'、'E-commerce'）——不能使用小写别名如crm,sales。

Validated at init AND validate: wrong case is canonicalized, an unknown value fails fast

会在init和validate时验证：错误的大小写会被规范化，未知值会立即失败，

and the error lists the approved enum. init seeds element-metadata.json:latestVersion = "1.0.0".

错误信息会列出已批准的枚举值。init会在element-metadata.json中设置latestVersion = "1.0.0"。

2. Add an activity (writes element.json entries + standard-resources/accounts.json).

2. 添加活动（写入element.json条目 + standard-resources/accounts.json）。

3. Author the field schema — REQUIRED, not optional (Rule 11). activity create

3. 编写字段 schema —— 必填项，而非可选项（规则11）。activity create

does NOT infer fields; without this the activity ships as a raw JSON body and

不会自动推断字段；不执行此步骤的话，活动会以原始JSON体形式发布，

validate warns. Pass --fields-file <json> on activity create for the whole

且validate会发出警告。可在activity create时通过--fields-file <json>参数

schema at once, or add fields one at a time with field create

一次性传入完整schema，或通过field create逐个添加字段

(visibility flags apply to every --method listed; re-runs merge):

（可见性标志适用于所有列出的--method；重新运行会合并配置）：

4. Validate — must be 0 errors AND no unresolved warnings (fieldless activity,

4. 验证——导入前必须确保0错误且无未解决的警告（如无字段活动、

broken SR link) before import.

损坏的SR链接）。

5. Import (create-or-update on the tenant) then publish.

5. 导入（在租户上创建或更新）然后发布。

Add an activity to an existing connector

为现有连接器添加活动

research the vendor API, then:

研究供应商API，然后执行：

Add a polling trigger

添加轮询触发器

Customize a curated activity

自定义精选活动

Debug

调试

state patch REPLACES the node — query the WHOLE entry, change ONLY the field at fault, patch it ALL back:

state patch会替换节点——查询完整条目，仅修改有问题的字段，然后将完整对象写回：

Command Map

命令映射

Reference Navigation

参考导航

Anti-patterns

反模式

0. Log in FIRST. The key
`design-{org}-{slug}`
takes its org from your logged-in

0. 先登录。标识
`design-{org}-{slug}`
会从登录会话中获取组织信息，

session, so
`init`
(create) ERRORS if you're not logged in. Let it derive the

因此未登录时
`init`
（创建）会报错。请让系统自动推导组织信息——

'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like
`crm,sales`
.

'Collaboration'、'Productivity'、'E-commerce'）——不能使用小写别名如
`crm,sales`
。

Validated at init AND
`validate`
: wrong case is canonicalized, an unknown value fails fast

会在init和
`validate`
时验证：错误的大小写会被规范化，未知值会立即失败，

3. Author the field schema — REQUIRED, not optional (Rule 11).
`activity create`

3. 编写字段 schema —— 必填项，而非可选项（规则11）。
`activity create`

`validate`
warns. Pass
`--fields-file <json>`
on
`activity create`
for the whole

且
`validate`
会发出警告。可在
`activity create`
时通过
`--fields-file <json>`
参数

schema at once, or add fields one at a time with
`field create`

一次性传入完整schema，或通过
`field create`
逐个添加字段