Pass runtime arguments in an execution request

You can pass runtime arguments in a workflow execution request and access those arguments using workflow variables.

Set up a workflow that receives runtime arguments

To set up a workflow to receive runtime arguments that you pass to it as part of an execution request, do the following:

  1. Follow the steps to create a new workflow, or choose an existing workflow to update, but don't deploy it yet.

  2. Add a params field to the main workflow's definition. Ensure that the argument name is placed inside square brackets, and that the main workflow is placed in a main block:

    YAML

    main:
params:[ARG_NAME]
steps:
...

    JSON

    {
"main":{
"params":["ARG_NAME"],
"steps":[
...
]
...
}
}

    The main block accepts a single argument that is the name of any valid JSON data type; for example, an array, an object, or a string.

    As a best practice, passing in an object with multiple, named arguments makes it easier to understand their purpose, and to add arguments. You can also then use dot notation to access the arguments.

    Other subworkflows can have multiple arguments.

    For example, the following workflow returns a "Hello" greeting to a person whose first and last name you pass as runtime arguments:

    YAML

    main:
params:[args]
steps:
-step1:
assign:
-outputVar:${"Hello, " + args.firstName + " " + args.lastName + "!"}
-step2:
return:${outputVar}

    JSON

    {
"main":{
"params":[
"args"
],
"steps":[
{
"step1":{
"assign":[
{
"outputVar":"${\"Hello \" + args.firstName + \" \" + args.lastName}"
}
]
}
},
{
"step2":{
"return":"${outputVar}"
}
}
]
}
}

  3. Deploy your workflow to finish creating or updating it.

Pass data in an execution request

Once your workflow is set up to receive runtime arguments, you can pass a string in JSON format, such as {"firstName":"Workflows","lastName":"User"}, to the workflow in an execution request.

Console

  1. To execute a workflow, in the Google Cloud console, go to the Workflows page:

    Go to Workflows

  2. On the Workflows page, select a workflow to go to its details page.

  3. On the Workflow Details page, click Execute.

  4. On the "Execute workflow" page that displays, enter a JSON string containing your parameter names and argument values, such as {"firstName":"Workflows","lastName":"User"}, into the "Input" area:

    Input area populated with the example JSON string

  5. Click Execute.

    On the Execution details page, you can view the results of the execution including the output Hello, Workflows User!, the execution ID and state, and the current or final step of the workflow execution. For more information, see Access workflow execution results.

gcloud

Add the --data flag to the gcloud workflows execute command that you use to execute your workflow. This flag takes a JSON string of your data. For example, to pass a firstName and lastName to the previous example workflow:

gcloudworkflowsrunWORKFLOW_NAME\
--data='{"firstName":"FIRST","lastName":"LAST"}'

Replace the following:

  • WORKFLOW_NAME: the workflow's name
  • FIRST: the string you want to pass to your workflow for firstName
  • LAST: the string you want to pass to your workflow for lastName

The output should be similar to the following:

Waiting for execution [9379b067-306a-4db1-a58d-c9fc99aebfd4] to complete...done.
argument: '{"firstName":"Workflows","lastName":"User"}'
endTime: '2022年07月19日T13:52:47.659199466Z'
name: projects/1051295516635/locations/us-central1/workflows/workflow-6/executions/9379b067-306a-4db1-a58d-c9fc99aebfd4
result: '"Hello, Workflows User!"'
startTime: '2022年07月19日T13:52:47.623862835Z'
state: SUCCEEDED
status:
 currentSteps:
 - routine: main
 step: step2
workflowRevisionId: 000002-138

Client libraries

Depending on the client library language, you can pass a runtime argument in an execution request.

For example, using JavaScript:

// Execute workflow
try{
constcreateExecutionRes=awaitclient.createExecution({
parent:client.workflowPath(projectId,location,workflow),
execution:{
argument:JSON.stringify({"firstName":"Workflows","lastName":"User"})
}
});
constexecutionName=createExecutionRes[0].name;

Or, using Java:

// Creates the execution object.
CreateExecutionRequestrequest=
CreateExecutionRequest.newBuilder()
.setParent(parent.toString())
.setExecution(Execution.newBuilder().setArgument("{\"firstName\":\"Workflows\",\"lastName\":\"User\"}").build())
.build();

For more information about executing a workflow using the Google API Client Libraries, see Execute a workflow.

REST API

  1. Append the data flag to the command that you use to execute your workflow. The value of data is a JSON formatted string with an argument whose value is one or more escaped parameter-value pairs. For example, to pass a firstName and lastName to the previous example workflow:

    curl--requestPOST\
--header"Authorization: Bearer "$(gcloudauthapplication-defaultprint-access-token)\
--header'Content-Type: application/json'\
--data'{"argument":"{\"firstName\":\"FIRST\",\"lastName\":\"LAST\"}"}'\
"https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions"

    Replace the following:

    • PROJECT_NUMBER: your Google Cloud project number
    • WORKFLOW_NAME: the workflow's name
    • FIRST: the string you want to pass to your workflow for firstName
    • LAST: the string you want to pass to your workflow for lastName

    The output should be similar to the following:

    {
 "name": "projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID",
 "startTime": "2020年11月09日T23:51:31.765761331Z",
 "state": "ACTIVE",
 "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",
 "workflowRevisionId": "000001-08c"
}
 ```

  2. To get the execution results, run the following command:

    curl--requestGET\
--header"Authorization: Bearer "$(gcloudauthapplication-defaultprint-access-token)\
--header'Content-Type: application/json'\
"https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID"

    Replace EXECUTION_ID with the ID from the output your first command returned.

    This output contains lines similar to the following:

    "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",
"result": "\"Hello, Workflows User!\"",

For more information about executing a workflow using the REST API, see Execute a workflow.

Access runtime arguments

This sample accesses runtime arguments passed to the workflow as part of the execution request. All arguments are stored in the same map, declared as a parameter of the main workflow.

When running this workflow, pass in runtime arguments using the following format:

{"firstName":"Sherlock","lastName":"Holmes"}

YAML

main:
params:[args]
steps:
-step1:
assign:
-outputVar:${"Hello " + args.firstName + " " + args.lastName}
-step2:
return:${outputVar}

JSON

{
"main":{
"params":[
"args"
],
"steps":[
{
"step1":{
"assign":[
{
"outputVar":"${\"Hello \" + args.firstName + \" \" + args.lastName}"
}
]
}
},
{
"step2":{
"return":"${outputVar}"
}
}
]
}
}

You can use default with the standard library function, map.get, to access optional runtime arguments, and return a default value if the key is not found. In the following example, if a region is not specified, northamerica-northeast1 is used:

YAML

main:
params:[input]
steps:
-init:
assign:
-region:${default(map.get(input, "region"), "northamerica-northeast1")}

JSON

{
"main":{
"params":[
"input"
],
"steps":[
{
"init":{
"assign":[
{
"region":"${default(map.get(input, \"region\"), \"northamerica-northeast1\")}"
}
]
}
}
]
}
}

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年11月11日 UTC.