automation-pilot-executions-api

# SAP Automation Pilot Executions API Management This skill manages command executions in SAP Automation Pilot - triggering, monitoring, controlling, and troubleshooting executions. ## Prerequisites 1. Set the following **required** environment variables: ```bash export AUTOPI_HOSTNAME="emea.autopilot.cloud.sap" export AUTOPI_USERNAME="your-username" export AUTOPI_PASSWORD="your-password" export AUTOPI_DEFAULT_CATALOG="mycommands-<<<TENANT_ID>>>" ``` 2. Ensure `curl` is available in your environment. --- # Execution Lifecycle ## Statuses | Status | Description | Active or Terminal | |--------|-------------|-------------------| | `RUNNING` | Execution is currently running. During delays (initial delay, retry backoff, repeat interval) the execution stays RUNNING while individual executors show their delay reason. | Active | | `PAUSED` | Manually paused — must be resumed to continue. | Active | | `INPUT_REQUIRED` | Waiting for a user choice (Confirm action required). | Active | | `FAILED` | Failed due to an error or failed validation. Can be retried or reset. | Active | | `FINISHED` | Completed successfully. | **Terminal** | | `ABORTED` | Canceled by the user. | **Terminal** | | `SUSPENDED` | Canceled by Automation Pilot (runtime limit exceeded, tenant execution limit reached, or execution/output size limit exceeded). | **Terminal** | **Terminal** statuses (FINISHED, ABORTED, SUSPENDED) mean the execution is complete and no further actions can be applied. Completed executions can be retriggered and deleted. **Active** statuses (RUNNING, PAUSED, INPUT_REQUIRED, FAILED) mean the execution is still live and can be acted upon. ## Actions Each action is only valid from specific statuses — applying an action from the wrong status returns HTTP 409. | Action | Valid from | Result | |--------|-----------|--------| | **PAUSE** | `RUNNING` | → `PAUSED` | | **RESUME** | `PAUSED` | → `RUNNING` | | **RETRY** | `FAILED` | → `RUNNING`. Re-attempts the execution, preserving progress for provided composite commands. | | **RESET** | `FAILED`, `PAUSED`, `INPUT_REQUIRED` | → `RUNNING` from a chosen previous child command. Not available for direct executions of provided commands. For provided composite commands, starts the whole command from the beginning (unlike RETRY which preserves progress). | | **ABORT** | `PAUSED`, `FAILED` | → `ABORTED` | | **COMMENT** | Any | Adds a comment to the execution's Action Log (max 10 comments per execution). | ```bash EXEC_ID="execution-uuid-here" # Pause curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "PAUSE", "reason": "Blocking on manual verification"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" # Resume curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "RESUME", "reason": "Resuming after verification"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" # Retry curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "RETRY", "reason": "Retrying after transient failure"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" # Abort curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "ABORT", "reason": "Superseded by a newer run"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" ``` --- # Triggering Executions **Note:** To retrieve logs after execution, include `feature:logs` in the `tags` of the trigger request. This tag is opt-in and cannot be added retroactively — an execution triggered without it will return no logs from `GET /executions/{id}/logs`. ## Trigger a Command Add `"feature:dryRun": ""` to the tags to execute without making actual changes. ```bash # Basic trigger (opt-in feature:logs tag enables log retrieval) curl -s -X POST \ -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{ "commandId": "my-catalog:MyCommand:1", "inputValues": { "param1": "value1", "param2": "value2" }, "tags": {"feature:logs": ""} }' \ "https://$AUTOPI_HOSTNAME/api/v1/executions" # With dry run mode (adds feature:dryRun tag) curl -s -X POST \ -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{ "commandId": "my-catalog:MyCommand:1", "inputValues": {"param1": "value1"}, "tags": {"feature:logs": "", "feature:dryRun": ""} }' \ "https://$AUTOPI_HOSTNAME/api/v1/executions" ``` **All `inputValues` entries must be strings on the wire**, regardless of the declared parameter type. The runtime converts each value to its declared type inside the executor: ```json "inputValues": { "appName": "my-app", "instances": "3", "enabled": "true", "regions": "[\"cf-eu10\",\"cf-us10\"]", "config": "{\"maxRetries\":5}" } ``` --- # Monitoring Executions ## List Executions ```bash # List all (up to limit) curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions?limit=100" # Filter by status curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions?status=FAILED&limit=50" # Filter by command curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions?commandId=my-catalog:MyCommand:1" # Filter by time (epoch milliseconds) curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions?startedAfter=1707000000000" ``` ## Get Execution Details ```bash EXEC_ID="execution-uuid-here" curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID" ``` ## Get Execution Summary ```bash # Get counts by status curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/summary" ``` ## Get Input/Output ```bash # Get execution input curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/input" # Get execution output (only for FINISHED) curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/output" ``` --- # Controlling Executions All actions use the same endpoint: `POST /api/v1/executions/$EXEC_ID/actions` See the Actions table in the Execution Lifecycle section for valid statuses and expected outcomes. ```bash EXEC_ID="execution-uuid-here" # Reset — resets to a previous child command (provide the executor path via "value") curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "RESET", "value": "stepAlias", "reason": "Retry after fixing the input"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" # Comment — add a note to the Action Log (max 10 per execution) curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "COMMENT", "reason": "Escalated to L2 on-call"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" # List action history curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" ``` --- # Viewing Logs ## Get Execution Logs ```bash EXEC_ID="execution-uuid-here" # Get paginated logs curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/logs?page=0&maxPageSize=20" # Get logs for specific executor EXECUTOR_PATH="step1" curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/logs/$EXECUTOR_PATH" ``` --- # Troubleshooting ## Quick Troubleshooting ```bash EXEC_ID="your-execution-id" # 1. Get status and error curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID" # 2. Check input used curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/input" # 3. Check recent logs curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/logs?page=0&maxPageSize=10" # 4. Check output (if FINISHED) curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/output" ``` ## Common Issues ### Execution Stuck in RUNNING 1. Check logs for the current step 2. Look for external dependencies (HTTP timeouts, etc.) 3. Consider aborting and retrying ```bash curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/logs?page=0&maxPageSize=20" curl -s -X POST -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" \ -H "Content-Type: application/json" \ -d '{"type": "ABORT", "reason": "Aborting stuck execution"}' \ "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/actions" ``` ### Execution Failed 1. Get execution details to see error 2. Check logs for the failed step 3. Review input parameters ```bash curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID" curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID/input" ``` ### Input Required The execution is waiting for manual input: ```bash curl -s -u "$AUTOPI_USERNAME:$AUTOPI_PASSWORD" "https://$AUTOPI_HOSTNAME/api/v1/executions/$EXEC_ID" # Inspect the response — check the suspendedStep field ``` ### No Logs Available **Cause:** The execution was triggered without the `feature:logs` tag, so logging was not enabled. **Solution:** Always include `"feature:logs": ""` in the `tags` object when triggering. Logs cannot be retrieved retroactively for executions that were triggered without this tag. Re-trigger the execution with the tag included. --- # Filtering & Pagination ## Query Parameters for List Executions | Parameter | Type | Description | |-----------|------|-------------| | `status` | array | Filter by status (RUNNING, FAILED, FINISHED, etc.) | | `commandId` | array | Filter by command ID | | `executionId` | array | Filter by execution ID | | `startedAfter` | integer | Unix epoch milliseconds | | `startedBefore` | integer | Unix epoch milliseconds |