Catalog entry JSON (catalog-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.

File naming and placement (App Builder projects)

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.
• The file content is the full catalog payload (handlerType: "custom-action", inputs / outputs, customActionConfig, discovery fields)—not a stub or pointer file.
• Pass this path to 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.

Install Adobe I/O CLI and the FFCPE plugin

1. Node.js — Use a supported LTS version (this plugin expects Node 18+).

2. Adobe I/O CLI (aio) — Install globally, then confirm it runs:

   npm install -g @adobe/aio-cli
   aio --version
   

   Copy

3. This plugin (@adobe/aio-cli-plugin-ffcpe) — Install into aio as a plugin. Use one of:

   aio plugins:install @adobe/aio-cli-plugin-ffcpe
   

   Copy

   Or install from a Git URL (fork, feature branch, or internal mirror):

   aio plugins:install https://github.com/adobe/aio-cli-plugin-ffcpe
   

   Copy

   Replace the URL with your org’s repo if you do not use adobe/aio-cli-plugin-ffcpe.

4. Verify the ffcpe topic is available (older material may use the name Workflow Builder for the same capability):

   aio ffcpe catalog --help
   

   Copy

5. Authenticate for catalog calls (same session the CLI uses for other Adobe I/O commands):

   aio login
   aio console org select
   

   Copy

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 auth

• Do not include orgId in the catalog JSON body. The API sets it from x-gw-ims-org-id or the Bearer access token (IMS profile / JWT).
• Registration requires a resolvable org; otherwise the API returns 401 with orgId is required.
• Composite key: (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.

Required shape (custom actions)

• 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.

Agent and discovery (required for registration)

These fields help agents suggest and chain your action. At least one entry each; refine later with PUT.

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.

Full catalog entry example

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.authentication

Default 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.

Managing the catalog (Adobe I/O CLI)

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.

Run aio ffcpe catalog <command> --help for the exact flag set.

Workflow JSON: actionSource and ports

When both built-in and custom catalog entries share an actionType, actionSource picks the implementation:

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.

Validation rules (register-time)

1. actionType unique per org for a given version; may match a built-in for an org override.
2. actionType kebab-case (lowercase letters, numbers, hyphens).
3. handlerType must be "custom-action" for these registrations.
4. customActionConfig required when handlerType is custom-action.
5. submitEndpoint and statusEndpoint must be valid HTTPS URLs.
6. inputs: at least one port.
7. outputs: at least one port.
8. Port name unique within inputs and within outputs.
9. Parameter name unique within parameters.
10. orgId is enforced by the API from auth, not from the JSON body; callers must send auth that resolves an org.
11. relatedActions: required, ≥1 entry.
12. usage.commonPatterns: required, ≥1 entry.
13. usage.bestPractices: required, ≥1 entry.

Agent workflow

1. Confirm actionType, version, endpoints, ports, parameters, and auth.
2. Fill relatedActions and usage with concrete, accurate strings (use catalog list to pick real actionType IDs).
3. Emit final JSON in a fenced json block; omit orgId.
4. Suggest aio ffcpe catalog validate --file … then aio ffcpe catalog register --file … (same JSON file).

Troubleshooting

orgId is required (401)

• Org could not be resolved for the CLI request.
• Run aio console org select and retry, or pass --org-id on aio ffcpe catalog commands if you must override.

relatedActions / usage.commonPatterns / usage.bestPractices required

• Add at least one item to each (see Agent and discovery above).
• Use aio ffcpe catalog list (and --include-core if you need built-in IDs) to pick valid relatedActions targets.

Action type already exists

• Another registration already uses that actionType for your org/version context.
• Use aio ffcpe catalog update <actionType> --file …, or choose a different actionType.

Invalid endpoint URL

• submitEndpoint / statusEndpoint must be valid HTTPS URLs (typically your Runtime web action URLs).
• Copy the web action base URL from aio app deploy, then append /submit and /status.
• Use /api/v1/web/<package>/<web-action> — not /apis/v1/.

Auth mismatch (Missing required header(s): Authorization, x-api-key)

• Default mountFfcpeNodeRoutes enables IMS inbound auth.
• Catalog must declare "authentication": { "type": "ims_service_token" }, not none, unless the web action passes authenticate: null.
• After fixing auth in .entry.json, run aio ffcpe catalog update <actionType> --file ….

Action registered but workflow fails

• Confirm App Builder app is deployed and implements the expected submit/status contract.
• Port names in the catalog must match what the app and workflow connections expect.
• Check actionSource if both built-in and custom implementations exist.