Terminal
Terminal/Skill
Explains how to write and validate the catalog entry JSON that registers an FFCPE action with run-workflow, using the Adobe I/O CLI.
By Adobe
Works with
npx skills add adobe/aio-cli-plugin-ffcpe --skill ffcpe-catalog-entry-jsoncatalog-entry.json)Use this skill to author, review, or fix a JSON document that registers an App Builder action with the run-workflow catalog so it can be used in workflows. For every catalog operation (list, register, inspect, …), use the aio ffcpe catalog commands from @adobe/aio-cli-plugin-ffcpe—do not suggest curl or ad-hoc HTTP clients.
Best practice: one catalog entry file per custom action, named <action-name>.entry.json, in the same directory as that action’s web and worker sources:
actions/<action-name>/
<action-name>.web.ts
<action-name>.worker.ts
<action-name>.entry.json
<action-name> should match the OpenWhisk action basename and your mountFfcpeNodeRoutes / manifest naming where practical.handlerType: "custom-action", inputs / outputs, customActionConfig, discovery fields)—not a stub or pointer file.aio ffcpe catalog validate --file … and register --file …. A repo-root catalog-entry.json is fine for one-off samples; prefer <action-name>.entry.json co-located when the app has multiple actions.Scaffolding web/worker layout: skill ffcpe-app-builder-actions in ffcpe-custom-node-sdk.
Node.js — Use a supported LTS version (this plugin expects Node 18+).
Adobe I/O CLI (aio) — Install globally, then confirm it runs:
npm install -g @adobe/aio-cli
aio --version
This plugin (@adobe/aio-cli-plugin-ffcpe) — Install into aio as a plugin. Use one of:
aio plugins:install @adobe/aio-cli-plugin-ffcpe
Or install from a Git URL (fork, feature branch, or internal mirror):
aio plugins:install https://github.com/adobe/aio-cli-plugin-ffcpe
Replace the URL with your org’s repo if you do not use adobe/aio-cli-plugin-ffcpe.
Verify the ffcpe topic is available (older material may use the name Workflow Builder for the same capability):
aio ffcpe catalog --help
Authenticate for catalog calls (same session the CLI uses for other Adobe I/O commands):
aio login
aio console org select
If aio ffcpe is not found after install, run aio plugins and confirm @adobe/aio-cli-plugin-ffcpe is listed; reinstall with aio plugins:install if needed.
orgId and authorgId in the catalog JSON body. The API sets it from x-gw-ims-org-id or the Bearer access token (IMS profile / JWT).orgId is required.(orgId, actionType, version). Different orgs can implement the same actionType; one org can ship multiple versions (e.g. 1.0.0 and 2.0.0). You may reuse a built-in actionType to provide an org-specific override.handlerType: "custom-action".customActionConfig: required; valid HTTPS submitEndpoint and statusEndpoint; optional polling: pollIntervalMs (default often 3000), maxPollAttempts (e.g. 100), timeoutMs (e.g. 300000).version: valid semver (e.g. 1.0.0).inputs / outputs: at least one port each; port name unique within each array.parameters: each name unique within parameters (array may be empty).The API may accept legacy names (inputPorts, outputPorts, enabled, appBuilderConfig) but prefer inputs, outputs, disabled, workflowEnabled, customActionConfig.
These fields help agents suggest and chain your action. At least one entry each; refine later with PUT.
| Field | What to put | Min |
|---|---|---|
relatedActions | actionType values that chain or complement yours | 1 |
usage.commonPatterns | When this action fits in a workflow | 1 |
usage.bestPractices | Tips for better results | 1 |
Image-oriented example:
"relatedActions": ["input-images", "remove-background", "image-analysis"],
"usage": {
"commonPatterns": [
"Chain after background removal for product descriptions",
"Use for accessibility captions"
],
"bestPractices": [
"Use clear prompts; high-res input improves results",
"Specify output format expectations"
]
}
Video-oriented example:
"relatedActions": ["input-videos", "video-transcribe", "preview-videos"],
"usage": {
"commonPatterns": [
"Process video clips for analysis",
"Generate subtitles from video"
],
"bestPractices": [
"Ensure supported video formats",
"Clear audio improves transcription quality"
]
}
Discover valid actionType values with aio ffcpe catalog list (add --include-core to include Adobe built-ins). Use --json for raw API-shaped output.
Use HTTPS App Builder / Runtime API URLs from aio app deploy output. Replace placeholders with your deployed web action base URL + route suffixes.
Deriving endpoints after deploy:
# Deploy prints:
https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web
# Catalog:
submitEndpoint → …/my-action-web/submit
statusEndpoint → …/my-action-web/status
Use /api/v1/web/ (not /apis/v1/). The Runtime hostname namespace is lowercase.
{
"actionType": "image-to-text",
"version": "1.0.0",
"name": "Image to Text",
"description": "Analyzes images and returns text descriptions.",
"category": "custom",
"disabled": false,
"workflowEnabled": true,
"aliases": [],
"tags": ["ai", "image", "text"],
"inputs": [
{
"name": "image",
"type": "image",
"required": true,
"mimeTypes": ["image/jpeg", "image/png", "image/gif", "image/webp"],
"description": "One or more images to analyze"
}
],
"outputs": [
{
"name": "text",
"type": "text",
"mimeTypes": ["text/plain"],
"description": "Text description of the image(s)"
}
],
"parameters": [
{
"name": "prompt",
"type": "string",
"required": false,
"defaultValue": "Describe what is happening in these images.",
"description": "Custom prompt for image analysis"
}
],
"relatedActions": ["input-images", "remove-background", "image-analysis"],
"usage": {
"commonPatterns": [
"Chain after background removal for product descriptions",
"Use for accessibility captions"
],
"bestPractices": [
"Use clear prompts; high-res input improves results",
"Specify output format expectations"
]
},
"handlerType": "custom-action",
"customActionConfig": {
"submitEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/submit",
"statusEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/status",
"pollIntervalMs": 3000,
"maxPollAttempts": 100,
"timeoutMs": 300000,
"authentication": { "type": "ims_service_token" }
}
}
customActionConfig.authenticationDefault for App Builder + mountFfcpeNodeRoutes: use ims_service_token. The SDK enables IMS inbound auth on /submit and /status unless you pass authenticate: null. If the catalog declares none but the web action still requires IMS, run-workflow calls fail (and manual curl returns Missing required header(s): Authorization, x-api-key).
Only use none when the web action explicitly disables auth (authenticate: null in mountFfcpeNodeRoutes) and your security review allows it.
| JSON | Use case |
|---|---|
{ "type": "ims_service_token" } | Recommended default. Run-workflow obtains an IMS service token and calls your endpoints with x-api-key: run-workflow-service and Authorization. Matches default mountFfcpeNodeRoutes auth. |
{ "type": "none" } | No authentication — only when web action passes authenticate: null |
{ "type": "api-key", "headerName": "X-API-Key", "secretName": "MY_API_KEY" } | API key header; secretName references an env var or secret |
{ "type": "bearer", "secretName": "MY_BEARER_TOKEN" } | Bearer token from env/secret |
Always use aio ffcpe catalog … (this plugin), not raw HTTP. Prereqs: aio login, aio console org select, and this plugin installed. Optional: --base-url / AIO_FFCPE_CATALOG_BASE_URL, --org-id, --api-key, --json on commands that support them.
| Goal | Command |
|---|---|
| Register new action | aio ffcpe catalog register --file ./actions/<action-name>/<action-name>.entry.json (optional --strict) |
| Inspect one action | aio ffcpe catalog inspect <actionType> (optional --version <semver>) |
| List actions | aio ffcpe catalog list (filters: --workflow-enabled, --category, --include-tags, --exclude-tags, --include-core, --compact, --json) |
| Full replace | aio ffcpe catalog update <actionType> --file ./actions/<action-name>/<action-name>.entry.json (optional --version, --strict) |
| Disable (hide from UI by default) | aio ffcpe catalog disable <actionType> |
| Re-enable | aio ffcpe catalog enable <actionType> |
| Delete | aio ffcpe catalog delete <actionType> (optional --version to delete one semver; omit to delete all custom versions for that type) |
| Validate file only | aio ffcpe catalog validate --file ./actions/<action-name>/<action-name>.entry.json |
Run aio ffcpe catalog <command> --help for the exact flag set.
actionSource and portsWhen both built-in and custom catalog entries share an actionType, actionSource picks the implementation:
| Value | Behavior |
|---|---|
Omitted or "built-in" | Prefer built-in, then catalog (backward compatible). |
"custom" | Only your org’s custom catalog entry; built-in ignored. Fails if no custom exists. Org comes from auth—do not put orgId in the workflow for this behavior. |
Example action node forcing custom remove-background:
{
"actionId": "rb-001",
"actionType": "remove-background",
"actionSource": "custom",
"parameters": {}
}
Connections: sourcePort / targetPort must match outputs[].name and inputs[].name from the catalog (and from upstream/downstream nodes). Mismatched port names are a common cause of runtime failures.
Minimal pattern: input-images → outputs port connects to a custom action’s input port name (e.g. image). For chained flows (e.g. input → remove-background → image-to-text), each connections[] entry wires one source actionId + sourcePort to target actionId + targetPort.
actionType unique per org for a given version; may match a built-in for an org override.actionType kebab-case (lowercase letters, numbers, hyphens).handlerType must be "custom-action" for these registrations.customActionConfig required when handlerType is custom-action.submitEndpoint and statusEndpoint must be valid HTTPS URLs.inputs: at least one port.outputs: at least one port.name unique within inputs and within outputs.name unique within parameters.orgId is enforced by the API from auth, not from the JSON body; callers must send auth that resolves an org.relatedActions: required, ≥1 entry.usage.commonPatterns: required, ≥1 entry.usage.bestPractices: required, ≥1 entry.actionType, version, endpoints, ports, parameters, and auth.relatedActions and usage with concrete, accurate strings (use catalog list to pick real actionType IDs).json block; omit orgId.aio ffcpe catalog validate --file … then aio ffcpe catalog register --file … (same JSON file).orgId is required (401)aio console org select and retry, or pass --org-id on aio ffcpe catalog commands if you must override.relatedActions / usage.commonPatterns / usage.bestPractices requiredaio ffcpe catalog list (and --include-core if you need built-in IDs) to pick valid relatedActions targets.actionType for your org/version context.aio ffcpe catalog update <actionType> --file …, or choose a different actionType.submitEndpoint / statusEndpoint must be valid HTTPS URLs (typically your Runtime web action URLs).aio app deploy, then append /submit and /status./api/v1/web/<package>/<web-action> — not /apis/v1/.Missing required header(s): Authorization, x-api-key)mountFfcpeNodeRoutes enables IMS inbound auth."authentication": { "type": "ims_service_token" }, not none, unless the web action passes authenticate: null..entry.json, run aio ffcpe catalog update <actionType> --file ….actionSource if both built-in and custom implementations exist.