Console
    Contact Us Start free

    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 Workflowspage:

      Go to Workflows

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

    3. On the Workflow Detailspage, 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 detailspage, 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:

    gcloud  
workflows  
run  
 WORKFLOW_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-19T13: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-19T13: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 
  
 { 
  
 const 
  
 createExecutionRes 
  
 = 
  
 await 
  
 client 
 . 
 createExecution 
 ({ 
  
 parent 
 : 
  
 client 
 . 
 workflowPath 
 ( 
 projectId 
 , 
  
 location 
 , 
  
 workflow 
 ), 
  
 execution 
 : 
  
 { 
  
 argument 
 : 
  
 JSON 
 . 
 stringify 
 ({ 
 "firstName" 
 : 
 "Workflows" 
 , 
 "lastName" 
 : 
 "User" 
 }) 
  
 } 
 }); 
 const 
  
 executionName 
  
 = 
  
 createExecutionRes 
 [ 
 0 
 ]. 
 name 
 ;

    Or, using Java:

      // Creates the execution object. 
 CreateExecutionRequest 
  
 request 
  
 = 
  
 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  
--request  
POST  
 \ 
  
--header  
 "Authorization: Bearer " 
 $( 
gcloud  
auth  
application-default  
print-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-09T23:51:31.765761331Z",
  "state": "ACTIVE",
  "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",
  "workflowRevisionId": "000001-08c"
}
 ```

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

       curl  
--request  
GET  
 \ 
  
--header  
 "Authorization: Bearer " 
 $( 
gcloud  
auth  
application-default  
print-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
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: