automation-pilot-command-generation

# SAP Automation Pilot Command Development This skill provides guidance for creating SAP Automation Pilot commands by composing existing reference commands from the content library. ## Command Release Policy Deployed commands start in DRAFT state. Do not release automatically — only release when: 1. The command has been tested and works correctly 2. The user explicitly requests release Draft state allows safe iteration without affecting production. ## Overview SAP Automation Pilot commands are JSON definitions that automate operations on SAP BTP. Commands can be: - **Atomic**: Execute a single operation (e.g., `HttpRequest`, `SendEmail`) - **Composite**: Orchestrate multiple steps using executors ### Reference Materials - **`examples/`** — Pattern examples (HTTP, ForEach, polling workflows) - **`references/patterns.md`** — Common implementation patterns - **`references/expressions.md`** — Expression language reference ### Discovering Available Executors Use the **catalog-explorer** skill to discover available executors via API: ```bash # List available catalogs curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/catalogs?own=false" # Find commands in a catalog curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/commands?catalog=applm-sapcp" # Get full command definition (inputs, outputs, executors) curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/commands/applm-sapcp:RestartCfApp:1" ``` This ensures you always use valid executor names and correct parameters, even for newly added catalogs. ## Dry Run `dryRun` is always present on every executor. Set it to `null` unless you have a specific reason to provide mock output. ```json "dryRun": null ``` The `dryRun: {output: {...}}` form (with mock values) is only needed if a downstream executor references this executor's output AND you want dry-run mode to propagate realistic values through the chain. In practice, `null` is the standard. ## IMPORTANT: Catalog Naming & ForEach Version See **`references/catalogs.md`** for the complete catalog reference. Key rules: - **Generated commands**: Use `<<<TENANT_ID>>>` suffix (e.g., `mycommands-<<<TENANT_ID>>>:MyCommand:1`) - **Built-in SAP commands**: Use `sapcp` suffix (e.g., `http-sapcp:HttpRequest:1`) - **ForEach**: Always use `ForEach:2`, never `ForEach:1` (deprecated) ## Command Structure ### Naming Conventions | Element | Convention | Example | |---------|------------|---------| | Command name | PascalCase | `RestartCfApp`, `GetHanaInstance` | | Input name | PascalCase | `BtpCredentials`, `JiraConfig` | | Input/output keys | camelCase | `resourceName`, `subAccount` | | Aliases | camelCase | `getResource`, `createInstance` | | Catalog ID | kebab-case | `mycommands-xxx` | Names must not contain spaces (causes API issues). PascalCase matches SAP's built-in commands. ### Basic Command Definition ```json { "id": "mycommands-<<<TENANT_ID>>>:CommandName:1", "catalog": "mycommands-<<<TENANT_ID>>>", "name": "CommandName", "description": "What the command does", "version": 1, "inputKeys": { }, "outputKeys": { }, "configuration": null, "tags": { } } ``` ### Input Keys Define command parameters: ```json "inputKeys": { "paramName": { "type": "string", // string, number, boolean, array, object "description": "Description", "required": true, "sensitive": false, // true masks in logs "defaultValue": "value", "minValue": 1, // for numbers "maxValue": 100 } } ``` Additional optional fields exist: `allowedValues` (fixed set of valid options), `suggestedValues` (hints shown in UI), `allowedValuesFromInputKeys` and `suggestedValuesFromInputKeys` (dynamic lists from an input reference). Omit them when not needed. **`defaultValue` is always a JSON string on the wire** regardless of the declared `type`. For non-string types, stringify the JSON: `"defaultValue": "5"` for a number, `"defaultValue": "true"` for a boolean, `"defaultValue": "[\"a\",\"b\"]"` for an array, `"defaultValue": "{\"key\":\"val\"}"` for an object. **Region inputs** must always use `allowedValuesFromInputKeys` to constrain the value to the SAP-provided region list: - Cloud Foundry: `"allowedValuesFromInputKeys": ["metadata-sapcp:CfRegionData:1"]` - Neo: `"allowedValuesFromInputKeys": ["metadata-sapcp:NeoRegionData:1"]` This ensures only valid Automation Pilot regions can be entered. ### Output Keys Define command outputs: ```json "outputKeys": { "result": { "type": "string", "description": "The result", "sensitive": false } } ``` ## Composite Commands Commands with `configuration` orchestrate multiple steps: ```json "configuration": { "values": [], // Pre-computed values from input references "output": {}, // Final output mapping "executors": [], // Steps to execute "listeners": [] // Event handlers } ``` ### Input References (values) Load reusable credentials or metadata at execution time. Three forms of `inputKey`: ```json "values": [ { "alias": "regionData", "valueFrom": { "inputReference": "metadata-sapcp:CfRegionData:1", "inputKey": "$(.execution.input.region)" } }, { "alias": "fullInputObject", "valueFrom": { "inputReference": "mycatalog-<<<TENANT_ID>>>:MyCredentials:1", "inputKey": null } }, { "alias": "ServiceAccountPassword", "valueFrom": { "inputReference": "mycatalog-<<<TENANT_ID>>>:MyCredentials:1", "inputKey": "password" } } ] ``` - **Expression** (`"$(.execution.input.region)"`) — dynamically selects which key to load based on input - **`null`** — loads the entire input reference as an object (access its fields via `$(.alias.fieldName)`) - **Plain string** (`"password"`) — loads a single named key directly ### Executors Each executor runs a command with mapped inputs. ```json { "execute": "http-sapcp:HttpRequest:1", "alias": "getResource", "input": { "url": "$(.regionData.cfApiUrl)/v3/apps", "method": "GET", "user": "$(.execution.input.user)", "password": "$(.execution.input.password)", "tokenUrl": "$(.regionData.uaaTokenUrl)", "clientId": "cf", "timeout": "20" }, "description": null, "progressMessage": null, "initialDelay": null, "pause": null, "when": null, "validate": null, "autoRetry": null, "repeat": null, "errorMessages": [], "dryRun": null } ``` ## Dynamic Expressions Expressions use jq 1.6 syntax wrapped in `$()`. Access data with: - `.execution.input.key` - Input values - `.stepAlias.output.key` - Previous step outputs - `.regionData.field` - Values from input references - `$` - Global scope (use inside pipes) See **[`references/expressions.md`](references/expressions.md)** for the full expression reference — patterns, string/array/object operations, type conversions, and utilities. ## IMPORTANT: Expression Complexity Limits Expressions have a complexity limit. If you get "Expression contains too many elements" error, break complex object construction into intermediate `Void` steps: Too complex — avoid this: ```json "output": { "counts": "$({\"a\": .x, \"b\": .y, \"c\": .z, \"d\": .w, \"e\": .v, ...})" } ``` Use a `Void` step instead: ```json "executors": [ { "execute": "utils-sapcp:Void:1", "alias": "buildCounts", "input": { "message": "{\"a\": $(.x), \"b\": $(.y), \"c\": $(.z)}" } } ], "output": { "counts": "$(.buildCounts.output.message | toObject)" } ``` **Rule of thumb**: If building an object with more than 5-6 fields from different step outputs, use a `Void` step. ## Conditional Execution (when) Skip steps based on conditions: ```json "when": { "semantic": "OR", "conditions": [ { "semantic": "OR", "cases": [ { "expression": "$(.execution.input.skipStep)", "operator": "EQUALS", "semantic": "OR", "values": ["false"] } ] } ] } ``` Operators: `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH` ## Validation Assert conditions on step output: ```json "validate": { "semantic": "OR", "conditions": [ { "semantic": "OR", "cases": [ { "expression": "$(.step.output.status)", "operator": "EQUALS", "semantic": "OR", "values": ["200", "201"] } ] } ] } ``` ## Auto Retry Retry on transient failures. Valid `logic` values: `FIXED` (constant delay) or `INCREMENTAL` (increasing delay). ```json "autoRetry": { "maxCount": 3, "delay": "5s", "logic": "FIXED", "applyOnValidation": false, "when": { "semantic": "OR", "conditions": [ { "semantic": "OR", "cases": [ { "expression": "$([408, 429, 500, 502, 503, 504, -1] | filter(. == $.step.output.status) | length)", "operator": "EQUALS", "semantic": "OR", "values": ["1"] } ] } ] } } ``` ## Repeat (Polling) Poll until condition is met: ```json "repeat": { "maxCount": 100, "delay": "15s", "failOnMaxCount": true, "until": { "semantic": "OR", "conditions": [ { "semantic": "OR", "cases": [ { "expression": "$(.step.output.body | toObject.state)", "operator": "EQUALS", "semantic": "OR", "values": ["COMPLETE"] } ] } ] } } ``` ## Error Messages Provide custom error messages: