automation-pilot-executor-httprequest

name	automation-pilot-executor-httprequest
description	Master the HTTP executor for Automation Pilot commands. Covers HTTP executor parameters, expression sanitization, timeout/retry configuration, response transformers, and HTTP-specific error handling. Use when building commands that make HTTP/REST API calls.

HTTP Executor Guide

The HTTP executor (http-sapcp:HttpRequest:1) is the most commonly used executor in Automation Pilot. This guide covers everything you need to build robust HTTP-based commands.

Parameters Reference

Parameter	Type	Required	Default	Notes
url	string	✅	-	Use toUrlEncoded for dynamic parts
method	string	✅	-	GET, POST, PUT, PATCH, DELETE
headers	object	❌	-	JSON object: {"Content-Type": "application/json"}
body	string	❌	-	Use toEscapedJson for dynamic JSON values
timeout	number	❌	5	Seconds (1-90, recommend ≤10)
responseBodyTransformer	string	❌	-	toObject, toString, toNumber, .nested.path
user	string	❌	-	Basic auth username OR OAuth client ID
password	string	❌	-	Basic auth password OR OAuth client secret
tokenUrl	string	❌	-	OAuth token endpoint
clientId	string	❌	-	OAuth client ID for client credentials flow
clientSecret	string	❌	-	OAuth client secret for client credentials flow
clientCert	string	❌	-	X509 certificate + key (PEM) for mTLS/cert-based OAuth; use with certurl-based tokenUrl
refreshToken	string	❌	-	OAuth refresh token; when provided, user/password are ignored
successResponseCodes	string	❌	-	JSON array of HTTP status codes treated as success, e.g. "[\"503\"]". Overrides default success check.

---

⚠️ Valid Expression Functions

CRITICAL: Only use expression functions that exist in the codebase. Common functions:

• URL/JSON Sanitization: toUrlEncoded, toEscapedJson (MANDATORY for dynamic values)
• Response Parsing: toObject, toNumber, toString
• Header Access: getCaseInsensitive (MANDATORY for headers - case-insensitive)
• Validation: length, contains, isGuid, valueIn
• Array/Object: filter, map, select, any, all, keys, values

Do not invent functions like type, isBool, isString - they don't exist in Automation Pilot.

Only use functions listed in ../automation-pilot-command-generation/references/expressions.md or the official SAP documentation.

---

Expression Sanitization (CRITICAL)

URL Parameters - Always Use toUrlEncoded

"url": "$(.execution.input.serviceKey.endpoints.service_url)/v1/resources/$(.execution.input.resourceId | toUrlEncoded)"

Dynamic URL path/query parts must be wrapped in toUrlEncoded. Without it, special characters break the URL.

Patterns:

"url": "https://example.com/v1/items/$(.execution.input.name | toUrlEncoded)"
"url": "https://example.com/v1/search?q=$(.execution.input.query | toUrlEncoded)"
"url": "https://example.com/v1/items?name=$(.execution.input.name | toUrlEncoded)&type=$(.execution.input.type | toUrlEncoded)"

---

JSON Body Values - Always Use toEscapedJson

String values embedded in a JSON body must use toEscapedJson. Numbers and booleans: no escaping, no quotes.

"body": "{\"name\": \"$(.execution.input.name | toEscapedJson)\", \"count\": $(.execution.input.count), \"enabled\": $(.execution.input.enabled)}"

---

Response Headers - Use getCaseInsensitive

HTTP headers in the response must be accessed with getCaseInsensitive — header names are case-insensitive.

"expression": "$(.apiCall.output.headers | getCaseInsensitive(\"content-type\"))"
"expression": "$(.apiCall.output.headers | getCaseInsensitive(\"location\"))"
"expression": "$(.apiCall.output.headers | getCaseInsensitive(\"x-api-version\") | length)"

---

Response Transformers

Transformer	Example	Result
toObject	{"name":"test"} → {name: "test"}	Parse JSON
toObject.data.id	{"data":{"id":"123"}} → "123"	Extract nested
toObject.resources[0].guid	{"resources":[{"guid":"abc"}]} → "abc"	Extract from array
toString	123 → "123"	Convert to string
toNumber	"123" → 123	Convert to number
(none)	Raw response	No transformation

---

Timeout Configuration

Default Rules

Recommended: ≤ 10 seconds Default: 5 seconds (if not specified)

{
  "timeout": "5"
}

Note: value is a STRING (seconds), not a number and not milliseconds.

When to Adjust Timeout

Scenario	Recommended Timeout
Simple GET	3-5s
POST/PUT	10s
Long-running async trigger	5-10s
File upload / heavy processing	60-90s

Maximum allowed: 90 seconds. For operations that take longer, use repeat polling instead.

---

Retry Logic (autoRetry)

📘 UNIVERSAL PROPERTY: autoRetry works with ALL executor types (HTTP, Script, ForEach, etc.), not just HTTP requests. The examples below use HTTP, but the same configuration applies to any executor.

Retry Configuration Structure

"autoRetry": {
  "maxCount": 3,
  "delay": "5s",
  "logic": "INCREMENTAL",
  "applyOnValidation": false,
  "when": {
    "semantic": "OR",
    "conditions": [{
      "semantic": "OR",
      "cases": [{
        "expression": "$([408, 429, 500, 502, 503, 504, -1] | filter(. == $.aliasName.output.status) | length)",
        "operator": "EQUALS",
        "semantic": "OR",
        "values": ["1"]
      }
    
  

Fields:

• maxCount: Maximum retry attempts (number)
• delay: Wait between retries (string with unit, e.g., "5s")
• logic: INCREMENTAL | FIXED (only these two exist)
• applyOnValidation: If true, also retries when validate fails. Default: false
• when: Condition for when to retry (typically checks status codes)

⚠️ CRITICAL: Use "logic" NOT "delayType". Use "when" block with filter expression, NOT "statusCodes" array.

Unconditional Retry

Set "when": null to retry on any failure, regardless of status code:

"autoRetry": {
  "maxCount": 3,
  "delay": "5s",
  "logic": "FIXED",
  "applyOnValidation": false,
  "when": null
}

Delay Types

Type	Behavior	Example (5s base, 3 retries)	Best For
INCREMENTAL	Adds delay each time	5s, 10s, 15s	General use, backoff
FIXED	Same delay each time	5s, 5s, 5s	Rate limiting, polling

Status Codes for autoRetry

Method	Retry on
GET, DELETE, HEAD	408, 429, 500, 502, 503, 504, -1
POST, PUT, PATCH	429, 502, 503, 504

-1 = network error / no response.

---

Authentication

User/Password with OAuth:

{
  "url": "$(.regionData.cfApiUrl)/v3/spaces",
  "method": "GET",
  "user": "$(.execution.input.user)",
  "password": "$(.execution.input.password)",
  "tokenUrl": "$(.regionData.uaaTokenUrl)"
}

Service Key (client credentials):

{
  "url": "$(.execution.input.serviceKey.endpoints.service_url)/v1/resources",
  "method": "GET",
  "clientId": "$(.execution.input.serviceKey.uaa.clientid)",
  "clientSecret": "$(.execution.input.serviceKey.uaa.clientsecret)",
  "tokenUrl": "$(.execution.input.serviceKey.uaa.url)/oauth/token"
}

Service Key with mTLS (clientCert):

{
  "url": "$(.execution.input.serviceKey.endpoints.service_url)/v1/resources",
  "method": "GET",
  "clientCert": "$(.execution.input.serviceKey.uaa.certificate + .execution.input.serviceKey.uaa.key)",
  "clientId": "$(.execution.input.serviceKey.uaa.clientid)",
  "clientSecret": "$(.execution.input.serviceKey.uaa.clientsecret)",
  "tokenUrl": "$((if (.execution.input.serviceKey.uaa.certificate == null) and (.execution.input.serviceKey.uaa.key == null) then .execution.input.serviceKey.uaa.url else .execution.input.serviceKey.uaa.certurl end) + \"/oauth/token\")"
}

Refresh token:

{
  "user": "$(.execution.input.user)",
  "password": "$(.execution.input.password)",
  "refreshToken": "$(.execution.input.refreshToken)",
  "tokenUrl": "$(.regionData.uaaTokenUrl)"
}

---

Error Handling

📘 UNIVERSAL PROPERTY: errorMessages works with ALL executor types, not just HTTP.

Error Message Structure

"errorMessages": [
  {
    "message": "Resource '$(.execution.input.resourceName)' does not exist",
    "when": {
      "semantic": "OR",
      "conditions": [
        {
          "semantic": "OR",
          "cases": [
            {
              "expression": "$(.aliasName.output.status)",
              "operator": "EQUALS",
              "semantic": "OR",
              "values": ["404"]
            }
          ]
        }
      ]
    }
  }
]

Error body access: Use toObject.error.message for single-error APIs, toObject.errors[0].detail for array-style APIs (e.g. CF API v3). Always check the actual response shape.