Skip to main content

Call

The Call task allows you to make calls to external services.

When to use this​

Use Call when your workflow needs to:

  • Make an HTTP request to an external API
  • Invoke a Temporal activity on another task queue
  • Call a gRPC service

Properties​

NameTypeRequiredDescription
callstringyesThe name of the function to call. One of activity or http.
withmapnoA name/value mapping of the parameters to call the function with

Activity​

Call an external Temporal activity running on a separate Task Queue within the same namespace.

To use this, the call property must equal activity.

Properties​

NameTypeRequiredDescription
namestringyesThe activity name to call.
argumentsany[]noThe arguments to pass to the activity. These are interpolated through the state.
taskQueuestringyesThe task queue where the activity is running.

Example​

document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: external-activity-call
  version: 0.0.1
do:
  - captureInput:
      set:
        requestedUserId: ${ $input.userId }
        requestId: ${ uuid }
  - fetchProfile:
      call: activity
      with:
          name: activitycall.FetchProfile
          arguments:
            - ${ $data.requestedUserId }
            - ${ $data.requestId }
          taskQueue: activity-call-worker

gRPC​

Call an external resource via gRPC. To use this, the call property must equal grpc.

Properties​

NameTypeRequiredDescription
proto.endpointstringyesThe proto resource that describes the gRPC service to call..
service.namestringyesThe name of the gRPC service to call.
service.hoststringyesThe hostname of the gRPC service to call.
service.portintegernoThe port number of the gRPC service to call.
methodstringyesThe name of the gRPC service method to call.
argumentsmapnoA name/value mapping of the method call's arguments, if any.

Example​

document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: external-activity-call
  version: 0.0.1
do:
  - greet:
      call: grpc
      with:
        proto:
          endpoint: file:///go/app/examples/external-calls/grpc/basic/proto/basic/v1/basic.proto
        service:
          name: providers.v1.BasicService
          host: grpc
          port: 3000
        method: Command1
        arguments:
          input: hello world

HTTP​

Call an external resource via HTTP. To use this, the call property must equal http.

Properties​

NameTypeRequiredDescription
methodstringyesThe HTTP request method.
endpointstring|endpointyesAn URI or an object that describes the HTTP endpoint to call.
headersmapnoA name/value mapping of the HTTP headers to use, if any.
bodyanynoThe HTTP request body, if any. Encoded to match the declared Content-Type — see Gotchas.
querymap[string, any]noA name/value mapping of the query parameters to use, if any.
outputstringnoThe http call's output format.
Supported values are:
- raw, which output's the base-64 encoded http response content, if any.
- content, which outputs the content of http response, possibly deserialized.
- response, which outputs the http response.
Defaults to content.
redirectbooleannoSpecifies whether redirection status codes (300–399) should be treated as errors.
If set to false, runtimes must raise an error for response status codes outside the 200–299 range.
If set to true, they must raise an error for status codes outside the 200–399 range.
Defaults to false.

Example​

document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: call-http
  version: 0.0.1
do:
  - getUser:
      call: http
      with:
        method: get
        endpoint: https://jsonplaceholder.typicode.com/users/2

Gotchas​

The request body is encoded for the declared Content-Type. A body given as a mapping is form-encoded when the headers declare application/x-www-form-urlencoded, and sent as JSON otherwise. A body given as a string is sent verbatim under any non-JSON media type, so pre-encoded and XML payloads are not JSON-quoted.

Header lookup is case-insensitive, and form keys are sorted so the output is deterministic.

HTTP errors raise by default. Responses outside the success range raise an error.

By default, Zigflow classifies HTTP response codes as follows:

  • 200–299: success
  • 300–399: non-retryable error when redirect: false
  • 408 and 429: retryable error
  • 400–499: non-retryable error by default
  • 500–599: retryable error by default
  • 501: non-retryable error

When redirect: true, redirects are followed by the HTTP client, so 3xx responses are typically not returned to the workflow.

Retryable errors use the task's Temporal retry policy. Non-retryable errors fail immediately unless handled in a try task.

When a retryable HTTP response includes a valid Retry-After header, Zigflow delays the next retry until the requested time instead of using the normal retry backoff.

Retry-After delays are not capped by Zigflow. Use Temporal timeout settings, such as ScheduleToCloseTimeout, to enforce a maximum execution time.

SDK metrics​

Activity-dispatching tasks (call: http, call: grpc, and run: tasks of type Container, Script and Shell) are each registered on their worker under a name derived from the task's path from the workflow root. For a task at the top of a workflow's do: list, the registered name is <workflowType>.<taskName> (for example call-http.getUser). For nested tasks, the path includes each parent's name, so a task step inside a for: task loop registers as <workflowType>.loop.step. Try bodies use try and catch as path segments to disambiguate the two scopes.

Temporal's SDK metrics use the registered name for the activity_type label, so individual tasks can be attributed in dashboards and alerts without colliding when sibling scopes happen to reuse a leaf name. run.workflow is a child workflow and is not affected.

Activity names are case-sensitive. The name field in an activity call must exactly match the name the activity was registered with on the remote worker.

gRPC proto files must be accessible. The proto.endpoint path must be readable by the Zigflow worker process at runtime.