appbuilder-workfront

App Builder 上の Workfront UI 拡張機能

App Builder アプリとして構築されたカスタマイズ済み Workfront UI です。次の 2 つの部分で構成されています。

• フロントエンド — ユーザーに表示される画面です。React/Spectrum（Adobe の UI ツールキット）で構築されます。App Builder では SPA（「シングルページアプリ」）と呼ばれます。→ workfront-ui-extension
• バックエンド — Adobe のクラウドで実行される小さな関数です（Runtime アクション。「サーバーレス」とは、関数を作成し、Adobe が実行するため、管理するサーバーが不要という意味です）。認証情報を保持し、Workfront／Planning／Adobe API を呼び出します。→ workfront-actions

フロントエンドは、拡張ポイントと呼ばれる固定の場所（メインメニューボタン、オブジェクトの左パネルにある項目、またはカスタムフォーム内に埋め込まれたウィジェット）に追加します。

エンドツーエンドのフロー → 対応するスキル

手順	実施内容	スキル
0–1. セットアップとプロジェクト作成	Node 20、@adobe/aio-cli のインストール、aio login、IMS 組織の選択、ステージング環境と本番環境の選択、プロジェクトの作成（Developer Console または aio console project create）	appbuilder-project-init
2. スキャフォールディング	テンプレート @adobe/workfront-ui-ext-tpl を使用した aio app init の実行、拡張ポイントの選択	appbuilder-project-init + このスキルの references/commands.md
3. フロントエンドの構築	拡張ポイント（メインメニュー、secondaryNav、ウィジェット）、ルーティング、共有コンテキスト、actionWebInvoke	workfront-ui-extension
4. バックエンドの構築	アクションの構成、設定、認証、入力；Workfront（Public API v21）／Planning／サービスの呼び出し	workfront-actions
5. Workfront での実行とテスト	aio app dev を実行し、extensionOverride（ローカルビルド）または Extension Manager／BYO（デプロイ済みアプリ、公開不要）を使用	workfront-local-testing
6. デプロイ	aio app deploy	references/commands.md
7. 公開（組織全体）	Production ワークスペースから承認を申請します。Production に、アクションが必要とするすべての API／サービスがあることを確認してください。BYO／override によるテストでは不要です。	—（以下を参照）

公開すると、extensionOverride を使わずに、IMS 組織内の全員がアプリを利用できるようになります。Production ワークスペースからデプロイし（aio app deploy）、Developer Console／App Builder の配布 UI で承認を申請します（ガイド：https://developer.adobe.com/uix/docs/guides/publication/）。承認を得ずに 1 つの組織でデプロイ済みアプリを使用するには、代わりに Workfront の Extension Manager（Bring Your Own extension） にその URL を登録してください。詳しくは workfront-local-testing を参照してください。デプロイ後、アプリの直接リンクは Experience Cloud シェルの URL …/workfront/custom-applications/<extensionId>/<menuRoute> です（CDN の URL だけではありません）。workfront-local-testing に従って作成し、引き渡してください。

行き詰まった場合は、よくある実際の問題（Node／aio のエラー、メインメニューの id の落とし穴、401 Org Id undefined、BYO テストなど）の症状 → 原因 → 解決方法をまとめた表を、references/troubleshooting.md で確認してください。aio コマンドの全一覧は references/commands.md にあります。

やさしい用語集

用語	わかりやすい説明
SPA／フロントエンド	Workfront 内でユーザーに表示されるアプリの画面です。
Runtime アクション／「サーバーレス」	データの取得や保存などの実処理を行い、ユーザーのブラウザーに認証情報が渡らないようにする、Adobe のクラウド上の小さな関数です。
拡張ポイント	アプリが Workfront に表示される場所です。メインメニュー、オブジェクトの左パネル、カスタムフォームのウィジェットがあります。
共有コンテキスト	Workfront がアプリに自動的に渡す情報です。サインイン中のユーザー、対象のオブジェクト、インスタンスの URL などが含まれます。
actionWebInvoke	フロントエンドからバックエンドのアクションを呼び出す方法です。
IMS 組織	Adobe の組織です（ID／ログイン）。
Developer Console／ワークスペース	プロジェクトと Production／Stage 環境を管理する Adobe のウェブ管理画面です。
レイアウトテンプレート	アプリをユーザーに表示する場所を決める Workfront 管理者向けの設定です。

ファミリー全体の不変条件

• 認証情報は sharedContext（imsToken、ホスト名）から取得します。Workfront がサインイン済みのユーザーとインスタンスをアプリに渡すため、独自のログインを作成しないでください。
• ブラウザーから Workfront／Adobe API を直接呼び出すことはありません。必ず actionWebInvoke を介して Runtime アクション経由で呼び出し、ログイントークンをサーバー上に保持します。（IMS 組織 ID はすでに sharedContext の auth.imsOrgID に含まれているため、WF 呼び出しは不要です。）
• アクションは CommonJS（exports.main。ESM ではありません）です。シークレット／入力値は .env → アクションの inputs → params の順に渡し、実行時に process.env から取得することはありません。
• Node は 20 です。デフォルト環境は prod（本番環境）です。stage（テスト環境）を対象にするには、AIO_CLI_ENV=stage を設定して再ログインする必要があります。
• Workfront Public API は v21.0 です。カスタム DE: フィールドを検索／カウントする際は、{field}_Mod=notblank が必要です。