gRPC

The gRPC task constructs a request using the specified method, host, and request body, and sends it to the gRPC server. The task captures the response and makes it available for use in workflows.

Note

The gRPC task is not enabled by default. Contact Orkes support to enable it for your cluster.

Task parameters

Configure these parameters for the gRPC task.

If you use a gRPC service registered in Remote Services, you can populate the task from it. This fills in the service, method, method type, host, port, headers, input type, output type, and a sample request. For CLIENT_STREAMING and BIDI_STREAMING methods, replace request with requests.

Parameter	Description	Required/ Optional
inputParameters.service	The name of the gRPC service registered in Remote Services. The task uses it to load the service's message types.	Required.
inputParameters.method	The full name of the gRPC method to invoke, in the format package.Service/Method. For example, `hello.HelloService/SayHello`.	Required.
inputParameters.host	The hostname or IP address of the gRPC server.	Required.
inputParameters.port	The port on which the gRPC server is running.	Required.
inputParameters.request	The request message as a JSON object.	Required for UNARY and SERVER_STREAMING.
inputParameters.requests	A list of request messages, each as a JSON object.	Required for CLIENT_STREAMING and BIDI_STREAMING.
inputParameters.methodType	The gRPC method type. Supported values: UNARY CLIENT_STREAMING SERVER_STREAMING BIDI_STREAMING If not set, defaults to UNARY.	Optional.
inputParameters.useSSL	Determines the connection security. Set to true to secure the connection using SSL.	Optional.
inputParameters.trustCert	Specifies whether the client should trust the server’s certificate. Set to true to allow connections to servers with self-signed or unverified certificates. Used only when useSSL is true.	Optional.
inputParameters.hedgingConfig.maxAttempts	The maximum number of parallel requests to send. The system uses the response from the first successful attempt, helping reduce tail latencies in remote services. Note: Hedging makes parallel requests, so use it only for idempotent services.	Optional.
inputParameters.headers	A map of metadata keys and values to send with the request. Supported types: Accept-Language Authorization Cache Control Content-MD5 From If-Match If-Modified-Since If-None-Match Max-Forwards Pragma If-Range If-Unmodified-Since Proxy-Authorization Range Warning x-api-key Accept-Charset Accept-Encoding Accept-Control-Request-Headers Accept-Control-Request-Method Content-Transfer-Encoding Expect Transfer-Encoding Trailer	Optional.
inputParameters.inputType	The full name of the protobuf message type for the request, such as `hello.HelloRequest`. When you populate the task from a registered service, this is filled in automatically.	Required.
inputParameters.outputType	The full name of the protobuf message type for the response, such as `hello.HelloResponse`. When you populate the task from a registered service, this is filled in automatically.	Required.
inputParameters.compressionCodec Available since: v5.5.2 and later	Compresses request and response messages on the wire. Set to `gzip` to enable compression. Useful for reducing transfer size on large payloads. The gRPC server must support gzip, or the task fails.	Optional.

The following are generic configuration parameters that can be applied to the task and are not specific to the gRPC task.

Caching parameters

You can cache the task outputs using the following parameters. Refer to Caching Task Outputs for a full guide.

Parameter	Description	Required/ Optional
cacheConfig.ttlInSecond	The time to live in seconds, which is the duration for the output to be cached.	Required if using cacheConfig.
cacheConfig.key	The cache key is a unique identifier for the cached output and must be constructed exclusively from the task’s input parameters. It can be a string concatenation that contains the task’s input keys, such as `${uri}-${method}` or `re_${uri}_${method}`.	Required if using cacheConfig.

Other generic parameters

Here are other parameters for configuring the task behavior.

Parameter	Description	Required/ Optional
optional	Whether the task is optional. If set to `true`, any task failure is ignored, and the workflow continues with the task status updated to `COMPLETED_WITH_ERRORS`. However, the task must reach a terminal state. If the task remains incomplete, the workflow waits until it reaches a terminal state before proceeding.	Optional.

Task configuration

This is the task configuration for a gRPC task.

  { 
     "name": "gRPC",
     "taskReferenceName": "gRPC_ref",
     "type": "GRPC",
     "inputParameters": {
       "service": "<SERVICE-NAME>",
       "method": "hello.HelloService/LotsOfReplies",
       "host": "grpcb.in",
       "port": 9001,
       "methodType": "SERVER_STREAMING",
       "useSSL": true,
       "trustCert": true,
       "hedgingConfig": {
         "maxAttempts": 4
       },
       "inputType": "hello.HelloRequest",
       "outputType": "hello.HelloResponse",
       "request": {
         "greeting": "world"
       },
       "headers": {
         "x-api-key": "${workflow.secrets.api}"
       },
       "compressionCodec": "gzip"
     }
   }

Task output

The gRPC task returns the server’s response as task output, making it available for use in subsequent workflow steps.

For UNARY and CLIENT_STREAMING methods, the output contains the fields of the response message. For example:

{
  "reply": "hello docs"
}

For SERVER_STREAMING and BIDI_STREAMING methods, the output contains a result list with one entry per response message. For example:

{
  "result": [
    { "reply": "hello a" },
    { "reply": "hello b" }
  ]
}

If the call fails, the task status is FAILED and the gRPC error is shown in reasonForIncompletion.

Examples

Here is an example of using the gRPC task.

Sending a stream of requests to a gRPC service

This example calls a client-streaming method on the public gRPC test server grpcb.in. The method receives several greetings and returns one reply.

First, register a gRPC service in Remote Services with host grpcb.in and port 9001, with SSL enabled. Then discover its endpoints. In this example, the service is named hello_service.

Next, create a workflow with the following gRPC task:

{
  "name": "send_greetings",
  "taskReferenceName": "send_greetings_ref",
  "type": "GRPC",
  "inputParameters": {
    "service": "hello_service",
    "method": "hello.HelloService/LotsOfGreetings",
    "host": "grpcb.in",
    "port": 9001,
    "methodType": "CLIENT_STREAMING",
    "useSSL": true,
    "inputType": "hello.HelloRequest",
    "outputType": "hello.HelloResponse",
    "requests": [
      { "greeting": "Alice" },
      { "greeting": "Bob" }
    ]
  }
}

In this configuration:

methodType is CLIENT_STREAMING, so the task sends each item in requests as a separate message.
inputType and outputType are the message types from the registered service.

When you run the workflow, the task sends each greeting to the server as a separate message in one stream. After receiving all of them, the server sends back a single reply, and the task completes with this output:

{
  "reply": "hello Alice, Bob"
}