workfront-actions

Workfront Runtime actions

Actions are the back end — small functions Adobe runs in its cloud on demand ("serverless"; Adobe I/O Runtime, built on OpenWhisk). The front end (SPA, see workfront-ui-extension) calls them via actionWebInvoke; they hold the credentials and call external APIs. The browser must never call Workfront/Adobe APIs directly — that is the action's job, so login tokens never reach the user's browser.

For generic action patterns and templates (webhook receiver, database CRUD, custom event provider, journaling consumer, large-payload redirect, action sequence, Asset Compute worker) and the App Builder SDKs (State/Files/Events/DB), use appbuilder-action-scaffolder. This skill is the Workfront-specific layer: the {data,error} contract, IMS passthrough, and Workfront's own Public API.

Anatomy

actions/<name>/index.js     # exports main(params)

• CommonJS only — export your function as exports.main. (App Builder supports only CommonJS, not ES Modules.)
• Register every action in app.config.yaml, or in an extension's ext.config.yaml (which compiles into app.config.yaml), following the OpenWhisk wskdeploy YAML spec.

async function main (params) {
  // ...
  return { statusCode: 200, body: { data, error: null } }
}
exports.main = main

Response shape

Always return { data, error } in the body; the UI checks error before using data.

return { statusCode: 400, body: { data: null, error: 'missing parameter(s) ...' } }

Auth & inputs

• require-adobe-auth is a per-action choice, off by default (the platform default) — decide deliberately, don't blanket-enable it. When true, Adobe validates the user's IMS token at the gateway before your code runs.
  • Turn it on when the action itself is the security boundary (privileged work, or nothing downstream authorizes the caller).
  • Leave it off when the downstream API enforces its own authorization — e.g. the action just forwards the user's imsToken to Workfront/Planning, which rejects bad tokens — or unless explicitly asked to enable it.
• The UI passes imsToken (→ Authorization: Bearer …) and the Workfront instance URL as params; never hardcode them.
• The IMS org id is in the shared context at auth.imsOrgID (capital ID — not imsOrgId/imsOrg; that casing trap costs hours). The front end reads sharedContext.get('auth').imsOrgID and passes it down; the action uses params.imsOrgId / the x-gw-ims-org-id header. Two traps: (1) reject the strings "undefined"/"null"/empty — an empty front-end value becomes the header string "undefined" (→ 401 "Org Id undefined is not in the list of user org Ids"); (2) with require-adobe-auth: true the gateway validates the org header before your code runs.
• Inputs flow .env → action inputs (in config) → params. Do NOT read process.env at runtime. Under aio app dev actions run in-process, so process.env may appear to work locally but will be empty once deployed. Wire keys/secrets as inputs and read them from params.