Execute a workflow

Executing a workflow runs the current workflow definition associated with the workflow.

Before you begin

Some of the steps in this document might not work correctly if your organization applies constraints to your Google Cloud environment. In that case, you might not be able to complete tasks like creating public IP addresses or service account keys. If you make a request that returns an error about constraints, see how to Develop applications in a constrained Google Cloud environment.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  6. If a workflow accesses other Google Cloud resources, make sure it is associated with a service account that has the correct permissions to do so. To learn what service account is associated with an existing workflow, see Verifying a workflow's associated service account.
  7. To send logs to Cloud Logging, make sure the service account executing the workflow has been granted a role that includes the logging.logEntries.create permission (for example, the Logs Writer role).

Execute a workflow

You can execute a workflow using the client libraries, in the Cloud Console, using the gcloud command-line tool, or by sending a request to the Workflows REST API.

Client libraries

The following samples assume you have already deployed a workflow, myFirstWorkflow, using the Cloud Console or the gcloud tool.

  1. Install the client library and set up your development environment. For details, see the Workflows client libraries overview.

  2. 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.

  3. 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/

  4. Take a look at the sample code:

    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();
    
    /**
     * 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);
      });
    }
    
    // Execute workflow
    try {
      const createExecutionRes = await client.createExecution({
        parent: client.workflowPath(projectId, location, workflow),
      });
      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}`);
    }

    Python

    import time
    
    from google.cloud import workflows_v1beta
    from google.cloud.workflows import executions_v1beta
    from google.cloud.workflows.executions_v1beta.types import executions
    
    # TODO(developer): Uncomment these lines and replace with your values.
    # project = 'my-project-id'
    # location = 'us-central1'
    # workflow = 'myFirstWorkflow'
    
    if not project:
        raise Exception('GOOGLE_CLOUD_PROJECT env var is required.')
    
    # Set up API clients.
    execution_client = executions_v1beta.ExecutionsClient()
    workflows_client = workflows_v1beta.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 every second 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)
            backoff_delay *= 2  # Double the delay to provide exponential backoff.
        else:
            print(f'Execution finished with state: {execution.state.name}')
            print(execution.result)
            return execution.result

    The program 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.
  5. To run the sample, first install dependencies:

    Java

    mvn compile

    Node.js

    npm install

    Python

    pip3 install -r requirements.txt

  6. 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

    node . PROJECT_ID CLOUD_REGION WORKFLOW_NAME

    Python

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

    Replace the following:

    • PROJECT_ID: (required) the Project ID of the Google Cloud project
    • CLOUD_REGION: the location for the workflow (default: us-central1)
    • WORKFLOW_NAME: the ID of the workflow (default: myFirstWorkflow)

    The output is similar to the following:

    Execution finished with state: SUCCEEDED
    ["Sunday","Sunday in the Park with George","Sunday shopping","Sunday Bloody Sunday","Sunday Times Golden Globe Race","Sunday All Stars","Sunday Night (South Korean TV series)","Sunday Silence","Sunday Without God","Sunday Independent (Ireland)"]
    

Console

  1. To execute a workflow, go to the Workflows page in the Cloud Console:
    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, in the Input pane, you can enter optional runtime arguments to pass to your workflow before execution. Arguments must be in JSON format; for example, {"animal":"cat"}. If your workflow doesn't use runtime arguments, leave this blank.

  5. Optionally, specify the level of call logging that you want to apply during the execution of the workflow. In the Log calls drop-down list, select one of:

    • none: No call logging. This is the default level.
    • log-all-calls: Log all calls to subworkflows or library functions and their results.
    • log-errors-only: Log only when a call is stopped due to an exception.

    For more information, see Send Logs to Cloud Logging.

  6. Click Execute.

  7. View the results of the workflow in the Output pane:

    Workflows quickstart output

gcloud

  1. Open a terminal.

  2. Find the name of the workflow you want to execute. If you don't know the workflow's name, you can enter the following command to list all your workflows:

    gcloud workflows list
    
  3. You can execute the workflow in two ways:

    • Execute the workflow and wait for the execution to complete:

      gcloud workflows run WORKFLOW_NAME \
          --call-log-level=CALL_LOGGING_LEVEL \
          --data=DATA
      
    • Execute the workflow without waiting for the execution attempt to finish:

      gcloud workflows execute WORKFLOW_NAME \
          --call-log-level=CALL_LOGGING_LEVEL \
          --data=DATA
      

      Replace the following:

      • WORKFLOW_NAME: The name of the workflow.
      • CALL_LOGGING_LEVEL: Optional. Level of call logging to apply during execution. For more information, see Send Logs to Cloud Logging. Can be one of:

        • none: No call logging. This is the default level.
        • log-all-calls: Log all calls to subworkflows or library functions and their results.
        • log-errors-only: Log only when a call is stopped due to an exception.
      • DATA: Optional. Runtime arguments for your workflow in JSON format.

  4. If you ran gcloud workflows execute, the unique ID of the workflow execution attempt is returned and the output is similar to the following:

     To view the workflow status, you can use following command:
     gcloud workflows executions describe b113b589-8eff-4968-b830-8d35696f0b33 --workflow workflow-2 --location us-central1

    To view the status of the execution, enter the command returned by the previous step.

If the execution attempt is successful, the final output is similar to the following:

argument: 'null'
endTime: '2020-06-23T16:21:35.266171131Z'
name: projects/123456789012/locations/us-central1/workflows/myFirstWorkflow/executions/f72bc6d4-5ea0-4dfb-bb14-2dae82303120
result: '["Tuesday","Tuesday Weld","Tuesday Night Music Club","Tuesday (ILoveMakonnen
  song)","Tuesdays with Morrie","Tuesday Group","Tuesday Knight","Tuesday (Burak Yeter
  song)","Tuesday Morning Quarterback","Tuesday Maybe"]'
startTime: '2020-06-23T16:21:34.826993288Z'
state: SUCCEEDED
workflowVersionId: '1'

REST API

  1. Open a terminal.

  2. Find the name of the workflow you want to execute. If you don't know the workflow's name, you can enter the following command to list all your workflows:

    gcloud workflows list
    
  3. To authenticate, you will need a service account with sufficient privileges to execute the workflow. For more information on using a service account to authenticate from the command line, see Get started with authentication.

  4. Enter the following command to execute the workflow, modifying the variables as necessary:

    curl \
    --request POST \
    --header "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    --header 'Content-Type: application/json' \
    "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/workflows/WORKFLOW_NAME/executions"
    

    If the workflow you are executing takes arguments, add the data flag. The value of data is a JSON formatted string with an argument whose value is one or more escaped parameter-value pairs. For example:

    --data '{"argument":"{\"PARAMETER\":\"VALUE\"}"}'
    

Check the status of long running executions

There are several commands to help you check the status of a workflow execution.

  • To retrieve a list of a workflow's execution attempts and their IDs, enter the following command:

    gcloud workflows executions list WORKFLOW_NAME
    

    Replace WORKFLOW_NAME with the name of the workflow.

  • To check the status of an execution attempt and wait for the attempt to finish, enter the following command:

    gcloud workflows executions wait EXECUTION_ID
    

    Replace EXECUTION_ID with the execution attempt's ID.

    The command waits for the execution attempt to finish and then returns the results.

  • To check the status of the last execution attempt, enter the following command:

    gcloud workflows executions wait-last
    

    If you made a previous execution attempt in the same gcloud session, the command waits for the prior execution attempt to finish and then returns the results. If no previous attempt exists, gcloud returns the following error:

    ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
    
  • To get the status of the last completed execution, enter the following command:

    gcloud workflows executions describe-last
    

    If you made a previous execution attempt in the same gcloud session, the command returns the results of the last completed execution. If no previous attempt exists, gcloud returns the following error:

    ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
    

What's next