uipath-connector-builder

Connector Builder

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 は対象外です。用語については、作成時の呼称は アクティビティ です（element.json のリソースと標準リソースファイルに対応します）。

このスキルを使用する場面

• ベンダーの API ドキュメントをもとに、新しいコネクタを作成するとき（init → 認証 → アクティビティ → 検証 → import → publish）。
• 既存のコネクタを編集するとき：アクティビティ、フィールド、パラメーター、メソッド、フックの追加。
• 認証（OAuth2、PKCE、クライアントクレデンシャル、API キー、ベーシック、JWT、AWS v4 など）を設定または切り替えるとき。
• JavaScript のリクエスト／レスポンスフックを作成または修正するとき。
• 既存のアクティビティにポーリングまたは Webhook トリガーを設定するとき。
• element.json／標準リソースファイルで、コネクタ、アクティビティ、フック、トリガーの問題をデバッグするとき。
• リリース前に検証するとき、またはデザインコネクタをテナントに対してプル／プッシュするとき。

重要なルール

1. 編集前に調査してください。 既存のコネクターでは、まず builder inspect を実行し、認証、設定、アクティビティ、フック、トリガーを把握してください。状態を確認せずに編集してはいけません。設定キー、アクティビティのパス、IDを推測してはいけません。最初に状態を確認してください（inspect、activity list、state query）。
2. 完了前に検証してください。 各ワークフローの最後と、修正のたびに builder validate を実行してください。完全な定期チェック一式が実行され、失敗するとゼロ以外の終了コードが返ります。失敗したら、報告されたフィールドを確認し、その項目を修正して再検証してください。同じエラーで3回失敗したら中断し、validate の出力を提示してください。推測を続けてはいけません。「エラー0件」で終わらず、警告も確認してください。 警告は、フィールドのないアクティビティや壊れた SR リンクなど、未完成のコネクターがそのままリリースされる原因となる実際の不足を示しています。許容できる理由を明確に説明できない限り、必ず修正してください。
3. すべての認証は auth set で管理します。 1回の呼び出しで設定エントリー、authentication.type ／ typeOauth ／ authenticationTypes、トークン更新リソースを書き込みます。スコープもここで定義してください（--scope、--scope-options、--required-scopes、--preselected-scopes）。スコープ専用の別コマンドはありません。init --auth oauth2|customApiKey は作成時によく使うケース向けのインライン形式です。それ以外はすべて auth set を使ってください。state patch で認証を手作業で作成してはいけません。
4. activity create は1回の呼び出しで両方を書き込みます。 標準リソースファイルと、メソッドごとの element.json エントリーの両方です。既存のアクティビティに対して再実行すると、追記／マージされます。SR ファイルが不要なシステムリソースに限り、--skip-sr を渡すか auth system create を使用してください。GETBYID／PATCH／PUT／DELETE をモデル化するのは、実際の by-id エンドポイントの場合だけです。検索に対して使ってはいけません。by-id の /{id} パスパラメーターは自動的に追加されます。GETBYID には必ず追加され、PATCH／PUT／DELETE にはアクティビティが CRUD（GET／GETBYID も含む）の場合のみ追加されます。書き込み専用／アクション型のアクティビティではベースパスが維持されます。by-id のパストークンと主キーは別物です。 リクエストがこちらから送信される前にトークンが置換されるため（ベンダーにトークン名は渡りません）、主キーはベンダーのレスポンスから読み取るフィールド名です。--vendor-path の末尾にある {token} はキーとして採用されません。--primary-key <vendor response key> を渡してください。
5. state patch はポインター先のノード全体を置換します（マージはしません）。 1つのフィールドを変更するには、まず state query でエントリーを取得し、編集してから、オブジェクト全体を state patch に渡してください。element-metadata.json にはアドレス指定可能なサブパスがありません。ファイル全体を読み取り、更新して書き戻してください。ポインター内のアクティビティパスは URL エンコードされます。/contacts → %2Fcontacts。作成には state patch ではなく、専用の作成コマンドを使用してください。
6. コネクターの指定方法。 Builder のコマンドは、作業ディレクトリから親ディレクトリを順にたどり、次に直下のサブディレクトリをスキャンし、最後に init が実行元のディレクトリに書き込む .uip-connector.json マーカーを参照します。そのため、同じディレクトリから後続のコマンドを実行すると、他のコネクターディレクトリが隣接していても、最後に init したコネクターが自動的に対象になります。上書きする場合や別の場所から作業する場合は --connector-dir <PATH> を渡してください。import も同じ方法で --connector-dir を読み取ります（app/element/element.json を含むコネクターのルート）。ただし download では、取得したコネクターを書き込む出力ディレクトリを指定します。例外：init はサブディレクトリをスキャンしません。 そうしないと、隣接するコネクターを解決して誤って編集／名前変更してしまうためです。新規作成するには、空のディレクトリで init を実行してください（コネクターのサブディレクトリを含むだけのディレクトリ、たとえば /tmp では新しいコネクターが作成され、子ディレクトリ内のコネクターを編集することはありません）。編集するには、コネクター内から実行するか、--connector-dir を渡してください。
7. 出力は {Result, Code, Data} エンベロープ形式です。 解析するには --output json を追加してください。失敗時にはゼロ以外の終了コードが返ります。stderr を抑制してはいけません。
8. import ／ download ／ publish と、新規作成時の init には uip login が必要です。 テナントから取得／テナントへの送信の前に認証してください。新しいコネクターのキー design-{org}-{slug} の org は、ログイン中のセッションから取得されます。そのため、ログインしていない状態で init を実行するとエラーになります。org は自動取得させてください。推測した --organization を渡してはいけません（誤った org はキーに埋め込まれ、import ／ publish 時になって不一致として発覚します）。--organization <slug> は、org が既知のオフライン／CI ビルドでのみ使用してください。
9. シークレットを表示、ログ出力、ハードコードしてはいけません。 シークレット設定キー（クライアントシークレット、API キー、パスワード、トークン）は、auth set により暗号化して書き込まれます（encrypt: true）。多くは PASSWORD フィールドですが、OAuth トークンやサービスアカウント JSON など、一部は暗号化された TEXTFIELD ／ TEXTAREA です。エンドユーザーは接続時に実際の認証情報を入力します。コネクターが保持するのは認証タイプ、エンドポイント URL、スコープのみです。すべてのコマンド例ではプレースホルダーを使用してください。
10. フックより組み込み機能を優先してください。 JavaScript を記述する前に、判断表（references/hooks.md の「まず判断する：フックか組み込み機能か？」）を確認してください。フックを使うのは、宣言的な機能では表現できない変換、オーケストレーション、派生処理に限ります。アクティビティ、メソッド、フェーズの組み合わせごとにフックファイルを1つ用意します。フックは Denali で実行され（モダン JavaScript と、追加の呼び出し用の require('axios') を使用）、すべての実行経路の最後で done() を呼び出す必要があります。
11. Windows ＋ Git Bash：最初に MSYS のパス変換を無効にしてください。 Git Bash では、/ で始まる引数は CLI に渡される前に Windows パスへ書き換えられます。--vendor-path /latest は element.json 内で C:/Program Files/Git/latest となり、validate は成功し、コネクターは公開されてから、ベンダーへのリクエスト時に失敗しますが、ローカルには痕跡が残りません。シェルごとに1回 MSYS_NO_PATHCONV=1 と MSYS2_ARG_CONV_EXCL='*' をエクスポートするか、すべての builder コマンドの前に指定してください。次のすべてのパスオプションに影響します。--vendor-path、--resource-path、--method-vendor-path、--reference-path、--validation-vendor-path、--path、--polling-url。引用符で囲んでも解決しません（シェルが引用符を取り除いた後に書き換えが行われるためです）。コネクターにすでに誤変換されたパスが含まれている場合は、state patch で修正してください。
12. すべてのアクティビティでフィールドスキーマを定義してください。activity create はフィールドを推測しません。 フィールドのないアクティビティは、Studio Web では入力が生の JSON ボディ1つ、出力も生の JSON 1つとして表示され、型付きの入出力はありません。これは検証や公開ができてしまう未完成のコネクターであり、見落としやすい不足です（スキーマを省いたまま「有効化して公開できた」という失敗が繰り返し発生しています）。activity create の後、必ずベンダーのドキュメントに記載されたスキーマに基づいて、リクエスト／レスポンスのフィールドを定義してください。スキーマ全体を一度に指定する場合は activity create に --fields-file <json> を渡し、フィールドを1つずつ追加する場合は activity field create を使います。フィールドのないアクティビティがあると、validate は警告を出します。必ず修正してください。フィールドのないアクティビティを含むコネクターを「完了」と報告してはいけません。生のボディをそのまま通す意図が本当にある場合は、その旨を明記してください。
13. アイコンは暗い背景でも見える状態にしてください。 app/element/image.svg は Studio Web でコネクターのアイコンとして使われます。builder validate はこれをチェックしません（ファイルがない場合に警告するのみです）が、アイコンのインクと Studio Web の暗い背景色（#1F1F1F）とのコントラスト比が 1.5:1 未満の場合、定期ビルドは失敗します。黒いロゴや、fill のない図形が該当します。アイコンを追加または置換する場合は、references/icon.md のルールを確認してください。黒いインクは @media (prefers-color-scheme: dark) ルールまたは fill="currentColor" で修正してください。ブランドロゴの色を変更してはいけません。

接続設計（ホスト、リージョン、検出される値）

スキャフォールディングの前に、接続ごとの各値をリクエストにどう渡すかを決めてください。ここを誤ると、最も頻繁に手戻りが発生します。

• ホストを決める設定は1つにします。URLを3つに分けないでください。 ベース、トークン、認証の各ホストで接続ごとの要素（インスタンス名、リージョン、データセンター、ワークスペースなど）を共有する場合は、設定を1つだけ用意し、それをすべてのURLにテンプレートとして埋め込みます。init --base-url 'https://{instance}.../api' + auth set --token-url 'https://{instance}.../token' --authorization-url 'https://{instance}.../authorize'。CLIは、3つのURLすべてに反映される、入力可能な単一の{instance}フィールドを自動で初期設定します（references/configuration.md §テンプレート化されたホスト）。base.url／oauth.token.url／oauth.authorization.urlを接続フィールドとして個別に公開しないでください。
• 自由入力値にはTEXTFIELD、固定の選択肢にはCOMBOを使います。 自由形式のインスタンス名／ワークスペース名／アカウント名は、自動で初期設定されるテンプレート化されたTEXTFIELDです。これは正当で一般的な形式であり、問題ではありません。本当に固定されたデータセンター／環境のリストがある場合に限り、初期設定された項目をstate patchでtype:COMBOに変更し、optionsを指定してください。valueにはホストの一部をそのまま設定できます。
• ユーザーに尋ねる前に、値を導出または検出してください。 接続ごとの値（APIホスト、組織／アカウントIDなど）がトークン応答で返される場合や、認証済みの呼び出しで検出できる場合は、手動入力フィールドを追加する代わりにその値を取得してください。ただし、本当に必要で、かつ取得可能な場合に限ります。単一のテンプレート設定がよりシンプルな既定の方法なので、通常のフィールドで十分な場合に検出を過剰に設計しないでください。トークン応答からホストを取得する場合は、ホストがhttpsで許可リストに登録されていることを検証し、トークンを決してログに記録せず、done({configuration})で永続化するpostRequestフックを使います。手順はreferences/hooks.md §「パターン：ベースURL …」を参照してください。検出可能なIDの場合は、接続時に検索を呼び出すonProvisionシステムリソースを使います（references/system-resources.md）。
• ユーザー向けの設定には説明が必要です。 configScreenType:"pre"または"pre-optional"のフィールドにはすべて、値の例や入手先を示すhintTextを指定してください。接続フォームで表示されるすべてのフィールドにもヒントを設定してください（現時点ではvalidateで確認されません）。対象にはインスタンス／ワークスペースID、テナントホスト、トークン種別ごとの認証情報が含まれます。
• 複数データセンターでのOAuth： アカウント／トークンのホスト自体がリージョンによって異なる場合は、ベースURLだけでなく、リージョン設定を--token-url／--authorization-urlにもテンプレートとして埋め込んでください。

ワークフロー

各ワークフローは、コピーしてそのまま実行できるコマンドを順序に沿って並べたものです。プレースホルダー（<ORG>、https://api.example.com）を使い、実際のシークレットは決して使わないでください。

新しいコネクター（ライフサイクル全体）

# 0. Log in FIRST. The key `design-{org}-{slug}` takes its org from your logged-in
#    session, so `init` (create) ERRORS if you're not logged in. Let it derive the
#    org — do NOT guess --organization (a wrong org bakes into the key and only
#    surfaces, mismatched, at import). --organization <slug> is for offline/CI only.
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.)

# 1. Scaffold the shell. --name is required when creating; key + folder are derived
#    (the org comes from your login — see step 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',
#   'Collaboration', 'Productivity', 'E-commerce') — NOT lowercase slugs like `crm,sales`.
#   Validated at init AND `validate`: wrong case is canonicalized, an unknown value fails fast
#   and the error lists the approved enum. init seeds element-metadata.json:latestVersion = "1.0.0".

# 2. Add an activity (writes element.json entries + 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 12). `activity create`
#    does NOT infer fields; without this the activity ships as a raw JSON body and
#    `validate` warns. Pass `--fields-file <json>` on `activity create` for the whole
#    schema at once, or add fields one at a time with `field create`
#    (visibility flags apply to every --method listed; re-runs merge):
uip is connectors builder activity field create --resource accounts --name email \
  --type string --method GET --method POST --response

# 4. Replace the placeholder app/element/image.svg with the vendor's logo, and check
#    it stays visible on a dark surface (Rule 13). validate does not check this.

# 5. Validate — must be 0 errors AND no unresolved warnings (fieldless activity,
#    broken SR link) before import.
uip is connectors builder validate

# 6. Import (create-or-update on the tenant) then publish.
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)

新しいコネクターを公開する場合、--versionは不要です（initで1.0.0が初期設定されます）。既存のコネクターを再公開する場合は、より大きいバージョンが必要です。element-metadata.json:latestVersionを引き上げるか、--version 1.0.1を渡してください。同じバージョンはサーバーに拒否されます。

既存のコネクターにアクティビティを追加する

uip is connectors builder inspect --output json     # map what exists first
# research the vendor API, then:
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

ポーリングトリガーを追加する

trigger createはPOLLLINGトリガーを作成します。対象のアクティビティはすでに存在し、SRファイルも必要です（そうでない場合、trigger createは必ず失敗します）。

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

--event-kindの値にかかわらず、--updated-date-fieldは必須です。このコマンドは常にポーリングループを作成します。--event-kind polling|webhook|all（既定値はpolling）は設定バンドルを選択するだけです。webhook／allではWebhook設定キーが追加されますが、配信処理は実装されません。Webhook配信、ポーリングとWebhookのセマンティクス、各フラグの既定値については、すべてreferences/events.mdを参照してください。

キュレーション済みアクティビティをカスタマイズする

activity create は、デフォルトで各メソッドを個別の Studio アクティビティとして自動的にキュレーションします（--no-curate で無効化できます）。method curate は、生成された name/displayName を上書きするとき、または --no-curate を指定したメソッドをキュレーションするときにのみ使用してください。 汎用 CRUD アクティビティは、キュレーション済みアクティビティとは別に常に表示されます。List/Get/Create/Update/Delete Records を使うと、ユーザーは該当メソッドをサポートする任意のオブジェクトを選べます。キュレーション済み／リスト対応オブジェクトを追加するときに、これらを削除したり、ノイズとして報告したりしないでください。汎用オブジェクトピッカーと並行して、キュレーション済みのサービスアクションを作成してください。

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

デバッグ

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:
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

接続時に決定されるベース URL や ID には、トークン呼び出しで値が返される場合はトークン応答の postRequest フックを使い、認証後に値を検出する必要がある場合は onProvision システムリソースを使ってください。値を検証してから、done({configuration}) で保存してください。state patch は使用しないでください。これはビルド時に、ある接続の値をすべての接続に反映してしまいます。詳しい手順については、references/hooks.md §「Pattern: base URL …」を参照してください。調査用チェックリストについては、references/debugging.md を参照してください。

コマンド一覧

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 は PublishId を返します。--wait は SUCCESS/FAILURE になるまでポーリングします（タイムアウトは --timeout-seconds で指定、デフォルトは 600 です）。後から確認するには publish-status <id>（位置引数）を使います。ステータスの列挙値：IN_PROGRESS | SUCCESS | FAILURE。

リファレンスの参照先

詳細は references/ にあります。それぞれ単独で参照できます。SKILL.md では、上記のワークフロー、コマンド一覧、ルールを管理します。リファレンスでこれらを繰り返す必要はありません。最新のフラグ情報は uip is connectors builder <noun> <verb> --help で確認できます。

タスク → 参照先	リファレンス
コネクターとは何か、ファイル構成、CRUD／キュレーション済み／HTTP アクティビティのモデル	references/overview.md
コネクターのアイコン（image.svg）：定期ビルドでの暗い背景上の視認性の判定方法と修正方法	references/icon.md
element.json の内部構造：トップレベルフィールド、resources[]、parameters[]、値の補間、フックの順序	references/element-json.md
標準リソースファイル：リンク、metadata.method、キュレーション、フィールド（表示、デザイン、検索可能性）	references/standard-resources.md
configuration[] エントリー：ウィジェットの種類、画面の種類、認証ごとのキーセット、ページネーションとイベントキー	references/configuration.md
認証の設定：19 種類すべての認証タイプ（JWT Bearer クレーム、FPS、none を含む）と OAuth/JWT スコープの対象範囲	references/auth.md
認証システムリソース：auth-validation、onProvision/onDelete、OAuth トークンのオーバーライド	references/system-resources.md
フックを記述するか、組み込み機能を使うかの判断（判断表と推奨／回避パターン）、実行順序、コンテキスト変数、done()、命名	references/hooks.md
ポーリングと Webhook トリガー：設定キー、event.poller.configuration のスキーマ	references/events.md
認証／アクティビティ／フック／トリガー／ページネーションの問題のデバッグ（ワークフローとチェックリスト）	references/debugging.md

アンチパターン

1. 最初に builder inspect を実行せずに編集する（ルール 1）— 存在しないキーやパスを作り出してしまいます。
2. auth set ではなく state patch を使って独自に認証を設定する（ルール 3）— 認証ブロックの整合性が失われます。
3. 部分的な値で設定エントリを編集する（ルール 5）— state patch はノードを置き換えるため、省略したフィールドが削除されます。エントリ全体を取得し、完全なオブジェクトをパッチとして書き戻してください。
4. 別のアクティビティを作るつもりで、既存の名前を指定して activity create を再実行する — 同じ名前のアクティビティにマージする冪等なアップサートです（メソッドを追加し、--overwrite-fields を指定しない限り既存のフィールド定義を維持します）。エラーにはならないため、名前を間違えても警告されず、同じ名前のアクティビティにマージされます。
5. 検索／一覧エンドポイントに GETBYID を使う（ルール 4）— by-id 動詞は /{id} パラメーターを自動追加するため、単一レコードの読み取りにのみ使用してください。
6. 例に実際のシークレットを記載する、またはコネクターがシークレットを保存すると想定する（ルール 9）— シークレットは暗号化フィールド（通常は PASSWORD）であり、接続時に指定します。
7. バージョンを上げずに再公開する — サーバーは同じバージョンを拒否します。latestVersion を上げるか、--version を指定してください。
8. --categories に独自の値を指定する — 承認済みの列挙値から選ぶ必要があります。validate で一覧を確認できます。
9. 組み込み機能で処理できるジョブのフックを作成する（ルール 10、hooks.md §「回避可能なフックの見分け方」）、または末尾の done() を省略してフックが戻らないようにする。
10. 削除済みのコマンドを使おうとする — connector scaffold/inspect/validate というラッパーはありません（init／inspect／validate を直接使用してください）。また、global／metadata／config／resource*／event polling add／auth scope／remote*／describe／reference もありません。
11. フィールド名、特に主キーを、URL パストークンや独自の命名規則に基づいて付ける。実際にベンダーから返されるキーを使ってください。レスポンスフィールドは、名前を基に生のベンダー JSON から解決されるため、名前が間違っているとアクティビティの出力が空になり、どのレイヤーでもエラーは発生しません（standard-resources.md §fields）。
12. フィールドのないアクティビティを含むコネクターを「完成」として報告する（ルール 12）— activity create が書き込むのはエンドポイント／メソッド／認証であり、フィールドスキーマは書き込みません。field create や --fields-file がないアクティビティは Studio で生の JSON ボディのみを表示し、validate の WARNING を引き起こします。完了前にフィールドを作成し、エラーが 0 件で警告がある状態を合格と見なさないでください。
13. 黒一色、または塗りつぶされていないアイコンを出荷する（ルール 13）— validate は通過しますが、Studio Web のダークサーフェスでは表示されなくなり、定期ビルドで失敗します。prefers-color-scheme: dark ルールを追加するか、currentColor を使用してください。