Execute a workflow using the Cloud Client Libraries

Deploy a sample workflow

After defining a workflow, you deploy it to make it available for execution. The deploy step also validates that the source file can be executed.

The following workflow sends a request to a public API and then returns the API's response.

1. Create a text file with the filename myFirstWorkflow.yaml with the following content:

   - getCurrentTime:
       call: http.get
       args:
         url: https://timeapi.io/api/Time/current/zone?timeZone=Europe/Amsterdam
       result: currentTime
   - readWikipedia:
       call: http.get
       args:
         url: https://en.wikipedia.org/w/api.php
         query:
           action: opensearch
           search: ${currentTime.body.dayOfWeek}
       result: wikiResult
   - returnResult:
       return: ${wikiResult.body[1]}

2. After creating the workflow, you can deploy it, but don't execute the workflow:

   gcloud workflows deploy myFirstWorkflow \
       --source=myFirstWorkflow.yaml \
       --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=CLOUD_REGION

   Replace CLOUD_REGION with a supported location for the workflow. The default region used in the code samples is us-central1.

Get the sample code

You can clone the sample code from GitHub.

1. Clone the sample app repository to your local machine:

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   Alternatively, you can download the sample as a zip file and extract it.

2. Change to the directory that contains the Workflows sample code:

   Java

   cd java-docs-samples/workflows/cloud-client/

   Node.js

   cd nodejs-docs-samples/workflows/quickstart/

   Python

   cd python-docs-samples/workflows/cloud-client/

3. Take a look at the sample code. Each sample app does the following:

   1. Sets up the Cloud Client Libraries for Workflows.
   2. Executes a workflow.
   3. Polls the workflow's execution (using exponential backoff) until the execution terminates.
   4. Prints the execution results.

   Java

   // Imports the Google Cloud client library
   
   import com.google.cloud.workflows.executions.v1.CreateExecutionRequest;
   import com.google.cloud.workflows.executions.v1.Execution;
   import com.google.cloud.workflows.executions.v1.ExecutionsClient;
   import com.google.cloud.workflows.executions.v1.WorkflowName;
   import java.io.IOException;
   import java.util.concurrent.ExecutionException;
   
   public class WorkflowsQuickstart {
   
     private static final String PROJECT = System.getenv("GOOGLE_CLOUD_PROJECT");
     private static final String LOCATION = System.getenv().getOrDefault("LOCATION", "us-central1");
     private static final String WORKFLOW =
         System.getenv().getOrDefault("WORKFLOW", "myFirstWorkflow");
   
     public static void main(String... args)
         throws IOException, InterruptedException, ExecutionException {
       if (PROJECT == null) {
         throw new IllegalArgumentException(
             "Environment variable 'GOOGLE_CLOUD_PROJECT' is required to run this quickstart.");
       }
       workflowsQuickstart(PROJECT, LOCATION, WORKFLOW);
     }
   
     private static volatile boolean finished;
   
     public static void workflowsQuickstart(String projectId, String location, String workflow)
         throws IOException, InterruptedException, ExecutionException {
       // Initialize client that will be used to send requests. This client only needs
       // to be created once, and can be reused for multiple requests. After completing all of your
       // requests, call the "close" method on the client to safely clean up any remaining background
       // resources.
       try (ExecutionsClient executionsClient = ExecutionsClient.create()) {
         // Construct the fully qualified location path.
         WorkflowName parent = WorkflowName.of(projectId, location, workflow);
   
         // Creates the execution object.
         CreateExecutionRequest request =
             CreateExecutionRequest.newBuilder()
                 .setParent(parent.toString())
                 .setExecution(Execution.newBuilder().build())
                 .build();
         Execution response = executionsClient.createExecution(request);
   
         String executionName = response.getName();
         System.out.printf("Created execution: %s%n", executionName);
   
         long backoffTime = 0;
         long backoffDelay = 1_000; // Start wait with delay of 1,000 ms
         final long backoffTimeout = 10 * 60 * 1_000; // Time out at 10 minutes
         System.out.println("Poll for results...");
   
         // Wait for execution to finish, then print results.
         while (!finished && backoffTime < backoffTimeout) {
           Execution execution = executionsClient.getExecution(executionName);
           finished = execution.getState() != Execution.State.ACTIVE;
   
           // If we haven't seen the results yet, wait.
           if (!finished) {
             System.out.println("- Waiting for results");
             Thread.sleep(backoffDelay);
             backoffTime += backoffDelay;
             backoffDelay *= 2; // Double the delay to provide exponential backoff.
           } else {
             System.out.println("Execution finished with state: " + execution.getState().name());
             System.out.println("Execution results: " + execution.getResult());
           }
         }
       }
     }
   }

   Node.js

   const {ExecutionsClient} = require('@google-cloud/workflows');
   const client = new ExecutionsClient();
   /**
    * TODO(developer): Uncomment these variables before running the sample.
    */
   // const projectId = 'my-project';
   // const location = 'us-central1';
   // const workflow = 'myFirstWorkflow';
   // const searchTerm = '';
   
   /**
    * Executes a Workflow and waits for the results with exponential backoff.
    * @param {string} projectId The Google Cloud Project containing the workflow
    * @param {string} location The workflow location
    * @param {string} workflow The workflow name
    * @param {string} searchTerm Optional search term to pass to the Workflow as a runtime argument
    */
   async function executeWorkflow(projectId, location, workflow, searchTerm) {
     /**
      * Sleeps the process N number of milliseconds.
      * @param {Number} ms The number of milliseconds to sleep.
      */
     function sleep(ms) {
       return new Promise(resolve => {
         setTimeout(resolve, ms);
       });
     }
     const runtimeArgs = searchTerm ? {searchTerm: searchTerm} : {};
     // Execute workflow
     try {
       const createExecutionRes = await client.createExecution({
         parent: client.workflowPath(projectId, location, workflow),
         execution: {
           // Runtime arguments can be passed as a JSON string
           argument: JSON.stringify(runtimeArgs),
         },
       });
       const executionName = createExecutionRes[0].name;
       console.log(`Created execution: ${executionName}`);
   
       // Wait for execution to finish, then print results.
       let executionFinished = false;
       let backoffDelay = 1000; // Start wait with delay of 1,000 ms
       console.log('Poll every second for result...');
       while (!executionFinished) {
         const [execution] = await client.getExecution({
           name: executionName,
         });
         executionFinished = execution.state !== 'ACTIVE';
   
         // If we haven't seen the result yet, wait a second.
         if (!executionFinished) {
           console.log('- Waiting for results...');
           await sleep(backoffDelay);
           backoffDelay *= 2; // Double the delay to provide exponential backoff.
         } else {
           console.log(`Execution finished with state: ${execution.state}`);
           console.log(execution.result);
           return execution.result;
         }
       }
     } catch (e) {
       console.error(`Error executing workflow: ${e}`);
     }
   }
   
   executeWorkflow(projectId, location, workflowName, searchTerm).catch(err => {
     console.error(err.message);
     process.exitCode = 1;
   });
   

   Python

   import os
   import time
   
   from google.cloud import workflows_v1
   from google.cloud.workflows import executions_v1
   from google.cloud.workflows.executions_v1 import Execution
   from google.cloud.workflows.executions_v1.types import executions
   
   PROJECT = os.getenv("GOOGLE_CLOUD_PROJECT")
   LOCATION = os.getenv("LOCATION", "us-central1")
   WORKFLOW_ID = os.getenv("WORKFLOW", "myFirstWorkflow")
   
   
   def execute_workflow(project: str, location: str, workflow: str) -> Execution:
       """Execute a workflow and print the execution results.
   
       A workflow consists of a series of steps described
       using the Workflows syntax, and can be written in either YAML or JSON.
   
       Args:
           project: The Google Cloud project id
               which contains the workflow to execute.
           location: The location for the workflow
           workflow: The ID of the workflow to execute.
   
       Returns:
           The execution response.
       """
       # Set up API clients.
       execution_client = executions_v1.ExecutionsClient()
       workflows_client = workflows_v1.WorkflowsClient()
   
       # Construct the fully qualified location path.
       parent = workflows_client.workflow_path(project, location, workflow)
   
       # Execute the workflow.
       response = execution_client.create_execution(request={"parent": parent})
       print(f"Created execution: {response.name}")
   
       # Wait for execution to finish, then print results.
       execution_finished = False
       backoff_delay = 1  # Start wait with delay of 1 second
       print("Poll for result...")
       while not execution_finished:
           execution = execution_client.get_execution(
               request={"name": response.name}
           )
           execution_finished = execution.state != executions.Execution.State.ACTIVE
   
           # If we haven't seen the result yet, wait a second.
           if not execution_finished:
               print("- Waiting for results...")
               time.sleep(backoff_delay)
               # Double the delay to provide exponential backoff.
               backoff_delay *= 2
           else:
               print(f"Execution finished with state: {execution.state.name}")
               print(f"Execution results: {execution.result}")
               return execution
   
   
   if __name__ == "__main__":
       assert PROJECT, "'GOOGLE_CLOUD_PROJECT' environment variable not set."
       execute_workflow(PROJECT, LOCATION, WORKFLOW_ID)

Run the sample code

You can run the sample code and execute your workflow. Executing a workflow runs the deployed workflow definition associated with the workflow.

1. To run the sample, first install dependencies:

   Java

   mvn compile

   Node.js

   npm install -D tsx

   Python

   pip3 install -r requirements.txt

2. Run the script:

   Java

   GOOGLE_CLOUD_PROJECT=PROJECT_ID LOCATION=CLOUD_REGION WORKFLOW=WORKFLOW_NAME mvn compile exec:java -Dexec.mainClass=com.example.workflows.WorkflowsQuickstart

   Node.js

   npx tsx index.js

   Python

   GOOGLE_CLOUD_PROJECT=PROJECT_ID LOCATION=CLOUD_REGION WORKFLOW=WORKFLOW_NAME python3 main.py

   Replace the following:

   • PROJECT_ID: your Google Cloud project name
   • CLOUD_REGION: the location of your workflow (default: us-central1)
   • WORKFLOW_NAME: your workflow name (default: myFirstWorkflow)

   The output is similar to the following:

   Execution finished with state: SUCCEEDED
   Execution results: ["Thursday","Thursday Night Football","Thursday (band)","Thursday Island","Thursday (album)","Thursday Next","Thursday at the Square","Thursday's Child (David Bowie song)","Thursday Afternoon","Thursday (film)"]
   

Pass data in an execution request

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

// Creates the execution object.
CreateExecutionRequest request =
    CreateExecutionRequest.newBuilder()
        .setParent(parent.toString())
        .setExecution(Execution.newBuilder().setArgument("{\"searchTerm\":\"Friday\"}").build())
        .build();

// Execute workflow
try {
  const createExecutionRes = await client.createExecution({
    parent: client.workflowPath(projectId, location, workflow),
    execution: {
      argument: JSON.stringify({"searchTerm": "Friday"})
    }
});
const executionName = createExecutionRes[0].name;

For more information about passing runtime arguments, see Pass runtime arguments in an execution request.