Service integrations¶

Service integrations are built-in resources a Task state calls through its Resource field, set to an integration URN.

They are global: every tenant can use them, with no setup. Build the call from the state's Parameters (JSONPath) or Arguments (JSONata); the integration result becomes the state's output.

HTTP invoke¶

urn::states:http/invoke sends an HTTP request and returns the response. It is synchronous: the state completes when the response arrives.

Access rights¶

The executing role needs the InvokeHttp permission on the state machine (see Create a role). A tenant's default role already grants it.

Input¶

Parameter	Required	Description
`Url`	yes	Absolute `http` or `https` URL.
`Method`	yes	One of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
`Headers`	no	Request headers, as `{ "Header-Name": ["value1", "value2"] }`.
`QueryParameters`	no	Query-string parameters `{ "name": ["value"] }`, URL-encoded and appended to `Url`.
`RequestBody`	no	JSON value sent as the request body with `Content-Type: application/json`.
`AuthType`	no	`NO_AUTH` (default) or `BEARER_TOKEN`.
`BearerToken`	if bearer	Sent as `Authorization: Bearer <token>`. Required when `AuthType` is `BEARER_TOKEN`.

Output¶

Field	Description
`StatusCode`	HTTP status code, as an integer.
`StatusText`	HTTP reason phrase.
`Headers`	Response headers, as `{ "Header-Name": ["value"] }`.
`ResponseBody`	Parsed as JSON when the response `Content-Type` is `application/json`, otherwise the raw body as a string.

Reaching private networks

By default, requests to private, loopback and link-local addresses are blocked to prevent SSRF. Set STEGFLOW_ENGINE__ALLOWPRIVATENETWORKHTTPTARGETS to allow them (see Configuration).

Example¶

JSONPathJSONata

"CallApi": {
  "Type": "Task",
  "Resource": "urn::states:http/invoke",
  "Parameters": {
    "Url": "https://api.example.com/orders",
    "Method": "POST",
    "Headers": { "Content-Type": ["application/json"] },
    "RequestBody": { "id.$": "$.orderId" },
    "AuthType": "BEARER_TOKEN",
    "BearerToken.$": "$.token"
  },
  "End": true
}

"CallApi": {
  "Type": "Task",
  "Resource": "urn::states:http/invoke",
  "Arguments": {
    "Url": "https://api.example.com/orders",
    "Method": "POST",
    "RequestBody": { "id": "{% $states.input.orderId %}" }
  },
  "End": true
}

Errors¶

States.Http.InvalidInput: missing or invalid input (bad URL, unsupported method, missing bearer token, blocked host).
States.Http.StatusCode.<code>: the response status was 400 or above.
States.Http.ExecutionFailed: the request could not be sent (connection, DNS, timeout).
States.Http.UnknownAction: unknown action in the resource URN.
States.Permissions: the role is not allowed to invoke HTTP.

Execute a state machine¶

Starts another state machine as a child execution. Two variants are available:

urn::states:states/startExecution: fire-and-forget. The state completes immediately with { "ExecutionUrn": "..." } and does not wait for the child.
urn::states:states/startExecution.sync: waits for the child execution to finish before the state completes.

Access rights¶

The executing role needs the StartExecution permission on the child state machine (see Create a role). A tenant's default role already grants it.

Input¶

Parameter	Required	Description
`StateMachineUrn`	yes	Identifier (ARN) of the state machine to execute.
`Input`	no	JSON passed to the child execution, as a string. Default `"{}"`. Use `States.JsonToString` to pass a computed object.
`Name`	no	Optional execution name.

Example¶

JSONPathJSONata

"RunChild": {
  "Type": "Task",
  "Resource": "urn::states:states/startExecution.sync",
  "Parameters": {
    "StateMachineUrn": "<CHILD_STATE_MACHINE_ARN>",
    "Input": "{}",
    "Name.$": "$.runName"
  },
  "End": true
}

"RunChild": {
  "Type": "Task",
  "Resource": "urn::states:states/startExecution.sync",
  "Arguments": {
    "StateMachineUrn": "<CHILD_STATE_MACHINE_ARN>",
    "Input": "{% $string($states.input) %}"
  },
  "End": true
}

Errors¶

States.InvalidInput: missing or invalid input (for example, no StateMachineUrn).
States.StartExecutionFailed: the child execution could not be started.
States.UnknownAction: unknown action in the resource URN.
States.Permissions: the role is not allowed to start the child execution.

Service integrations¶

HTTP invoke¶

Access rights¶

Input¶

Output¶

Example¶

Errors¶

Execute a state machine¶

Access rights¶

Input¶

Example¶

Errors¶

See also¶