ffcpe-catalog-entry-json

# 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: ```text 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](https://github.com/adobe/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: ```sh-session npm install -g @adobe/aio-cli aio --version ``` 3. **This plugin (`@adobe/aio-cli-plugin-ffcpe`)** — Install into `aio` as a plugin. Use **one** of: ```sh-session aio plugins:install @adobe/aio-cli-plugin-ffcpe ``` Or install from a **Git URL** (fork, feature branch, or internal mirror): ```sh-session 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`. 4. **Verify** the **`ffcpe`** topic is available (older material may use the name **Workflow Builder** for the same capability): ```sh-session aio ffcpe catalog --help ``` 5. **Authenticate for catalog calls** (same session the CLI uses for other Adobe I/O commands): ```sh-session 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 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. | 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:** ```json "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:** ```json "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:** ```text # 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. ```json { "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. | 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 | ## 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. | 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>` |