Uipath Connector Builder

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).

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.

Critical Rules

1. 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).
2. 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.
3. 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.
4. 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 by-id /{id} 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. The by-id path token and the primary key are separate — the token is substituted before the request leaves us (the vendor never sees its name), while the primary key names a field read back from the vendor's response. A trailing {token} in --vendor-path is NOT adopted as the key; pass --primary-key <vendor response key>.
5. 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.
6. 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.
7. Output is the {Result, Code, Data} envelope. Add --output json to parse it. Failures exit non-zero. Never suppress stderr.
8. 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.
9. 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.
10. 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().
11. Windows + Git Bash: disable MSYS path conversion FIRST. In Git Bash any argument starting with / is rewritten to a Windows path before the CLI ever sees it — --vendor-path /latest lands in element.json as C:/Program Files/Git/latest, validate PASSES it, the connector publishes, and it only fails at request time against the vendor with no local trace. Export MSYS_NO_PATHCONV=1 and MSYS2_ARG_CONV_EXCL='*' once per shell (or prefix every builder command). Affects every path option — --vendor-path, --resource-path, --method-vendor-path, --reference-path, --validation-vendor-path, --path, --polling-url. Quoting does NOT help (the rewrite happens after the shell strips quotes). If a connector already carries a mangled path, repair it with state patch.
12. 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.
13. The icon must stay visible on a dark surface. app/element/image.svg is the connector's icon in Studio Web. builder validate does NOT check this (it only warns when the file is missing), but the periodic build fails an icon whose ink has under 1.5:1 contrast on Studio Web's dark surface (#1F1F1F) — a black logo, or shapes with no fill. When you add or replace the icon, check it against the rules in references/icon.md. Fix black ink with a @media (prefers-color-scheme: dark) rule or fill="currentColor". Never recolour a brand logo.

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.