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

⚠️ 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

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

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

Status Codes for autoRetry

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