appbuilder-workfront

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workfront UI extensions on App Builder

在App Builder上构建Workfront UI扩展

A customized Workfront UI, built as an App Builder app. It has two halves:

a front end — the screens the user sees. Built with React/Spectrum (Adobe's UI toolkit); in App Builder terms it's the SPA ("single-page app"). →
```
workfront-ui-extension
```
a back end — small functions that run in Adobe's cloud (Runtime actions; "serverless" = you write the function, Adobe runs it, no server to manage). They hold the credentials and call the Workfront / Planning / Adobe APIs. →
```
workfront-actions
```

The front end plugs into Workfront at fixed spots called extension points: a Main Menu button, an item in an object's left panel, or a widget embedded inside a custom form.

定制化Workfront UI是以App Builder应用的形式构建的，分为两部分：

前端：用户可见的界面。基于React/Spectrum（Adobe的UI工具包）构建；在App Builder术语中，这就是SPA（单页应用）。→
```
workfront-ui-extension
```
后端：运行在Adobe云端的小型函数（Runtime actions；“无服务器”即你编写函数，由Adobe负责运行，无需管理服务器）。这些函数存储凭证并调用Workfront / Planning / Adobe的API。→
```
workfront-actions
```

前端会接入Workfront中固定的位置，这些位置被称为扩展点：主菜单按钮、对象左侧面板中的选项，或嵌入自定义表单内的小组件。

End-to-end flow → which skill

端到端流程 → 对应技能模块

Step	What you do	Skill
0–1. Set up + create project	Node 20, install `@adobe/aio-cli` , `aio login` , pick IMS org, stage vs prod, create the project (Developer Console or `aio console project create` )	`appbuilder-project-init`
2. Scaffold	`aio app init` with template `@adobe/workfront-ui-ext-tpl` ; pick extension points	`appbuilder-project-init` + this skill's `references/commands.md`
3. Build front end	Extension points (Main Menu, `secondaryNav` , widgets), routing, shared context, `actionWebInvoke`	`workfront-ui-extension`
4. Build back end	Action anatomy, config, auth, inputs; call Workfront (Public API v21) / Planning / services	`workfront-actions`
5. Run + test in Workfront	`aio app dev` , then `extensionOverride` (local build) or Extension Manager / BYO (deployed app, no publish)	`workfront-local-testing`
6. Deploy	`aio app deploy`	`references/commands.md`
7. Publish (org-wide)	Submit for approval from the Production workspace; make sure Production has every API/service your actions need. Not required for BYO/override testing.	— (see below)

Publishing makes the app available to everyone in the IMS org without an
extensionOverride
. Deploy from the Production workspace (
aio app deploy
), then submit for approval in the Developer Console / App Builder distribution UI (guide:
https://developer.adobe.com/uix/docs/guides/publication/
). To use a deployed app in one org without approval, register its URL in Workfront's Extension Manager (Bring Your Own extension) instead — see
workfront-local-testing
. After deploy, the app's direct link is the Experience Cloud shell URL
…/workfront/custom-applications/<extensionId>/<menuRoute>
(not the bare CDN) — build and hand it over per
workfront-local-testing
.

Hit a wall? A symptom → cause → fix table of the real gotchas (Node/
aio
errors, the Main Menu
id
trap,
401 Org Id undefined
, BYO testing, and more) is in
references/troubleshooting.md
. The full
aio
command catalog is in
references/commands.md
.

步骤	操作内容	技能模块
0–1. 环境配置 + 创建项目	安装Node 20，安装 `@adobe/aio-cli` ，执行 `aio login` ，选择IMS组织，区分测试环境（stage）与生产环境（prod），创建项目（通过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. 构建后端	Action结构、配置、认证、输入；调用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工作区拥有你的actions所需的所有API/服务。BYO/override测试无需此步骤。	— （详见下文）

发布操作可让应用在IMS组织内全员可用，无需使用
extensionOverride
。从Production工作区部署（执行
aio app deploy
），然后在Developer Console / App Builder分发UI中提交审批（指南链接：
https://developer.adobe.com/uix/docs/guides/publication/
）。若要在单个组织内使用已部署的应用无需审批，可在Workfront的Extension Manager（自定义扩展导入）中注册其URL，具体请参考
workfront-local-testing
。部署完成后，应用的直接链接为Experience Cloud shell URL
…/workfront/custom-applications/<extensionId>/<menuRoute>
（而非裸CDN链接）——构建完成后可按照
workfront-local-testing
中的说明交付链接。

遇到问题？ 包含实际常见问题（Node/
aio
错误、主菜单
id
陷阱、
401 Org Id undefined
、BYO测试等）的“症状→原因→解决方案”表格位于
references/troubleshooting.md
。完整的
aio
命令目录请查看
references/commands.md
。

Plain-language glossary

通俗术语表

Term	In plain words
SPA / front end	The app screens the user sees inside Workfront.
Runtime action / "serverless"	A small function in Adobe's cloud that does the real work (fetching/saving data) and keeps credentials off the user's browser.
Extension point	A spot where your app appears in Workfront: the Main Menu, an object's left panel, or a custom-form widget.
Shared context	Info Workfront hands the app automatically — who's signed in, which object they're on, the instance URL.
`actionWebInvoke`	How the front end calls a back-end action.
IMS org	Your Adobe organization (identity / login).
Developer Console / workspace	Adobe's web admin where the project and its Production / Stage environments live.
Layout template	The Workfront admin setting that decides where an app actually shows up for users.

术语	通俗解释
SPA / 前端	用户在Workfront内看到的应用界面。
Runtime action / “无服务器”	运行在Adobe云端的小型函数，负责实际业务操作（获取/保存数据），并避免凭证暴露在用户浏览器中。
扩展点	你的应用在Workfront中的展示位置：主菜单、对象左侧面板或自定义表单小组件。
共享上下文	Workfront自动传递给应用的信息——当前登录用户、用户正在操作的对象、实例URL。
`actionWebInvoke`	前端调用后端action的方式。
IMS组织	你的Adobe组织（身份/登录账号所属组织）。
Developer Console / 工作区	Adobe的网页管理平台，项目及其Production/Stage环境均在此处管理。
布局模板	Workfront的管理员设置，用于决定应用对用户的实际展示位置。

Invariants for the whole family

全系列通用规则

Auth comes from
sharedContext
(
```
imsToken
```
, hostname) — Workfront hands the app the signed-in user and instance, so never build a custom login.
The browser never calls Workfront/Adobe APIs directly — always through a Runtime action via
```
actionWebInvoke
```
, so login tokens stay on the server. (The IMS org id is already in
```
sharedContext
```
at
```
auth.imsOrgID
```
— no WF call needed.)
Actions are CommonJS (
```
exports.main
```
; not ESM); secrets/inputs flow
```
.env
```
→ action
```
inputs
```
→
```
params
```
, and are never read from
```
process.env
```
at runtime.
Node 20. The default environment is prod (live); targeting stage (test) needs
```
AIO_CLI_ENV=stage
```
plus a re-login.
Workfront Public API is v21.0; custom
```
DE:
```
fields need
```
{field}_Mod=notblank
```
on search/count.

认证信息来自
sharedContext
（
```
imsToken
```
、主机名）——Workfront会将登录用户及实例信息传递给应用，因此切勿构建自定义登录功能。
浏览器切勿直接调用Workfront/Adobe API——务必通过
```
actionWebInvoke
```
调用Runtime action，确保登录令牌仅在服务器端使用。（IMS组织ID已包含在
```
sharedContext
```
的
```
auth.imsOrgID
```
中——无需调用Workfront接口获取。）
Actions采用CommonJS规范（
```
exports.main
```
；而非ESM）；密钥/输入信息从
```
.env
```
流向action的
```
inputs
```
再到
```
params
```
，绝对不要在运行时从
```
process.env
```
读取。
Node版本为20。默认环境为生产环境（prod）；若要针对测试环境（stage），需设置
```
AIO_CLI_ENV=stage
```
并重新登录。
Workfront Public API版本为v21.0；自定义
```
DE:
```
字段需要在搜索/统计时添加
```
{field}_Mod=notblank
```
参数。