Schedule a workflow using Cloud Scheduler

This page shows you how to use Cloud Scheduler to run a workflow on a particular schedule, such as every Monday at 9 AM or every 15 minutes. You can configure the schedule either in the Google Cloud Console or by using the gcloud command-line tool.

Before you begin

  1. If you do not already have a workflow that you want to schedule, create and deploy one.

  2. Enable the Cloud Scheduler API.

    Enable the API

  3. Or, in a terminal, enter the following command:
    gcloud services enable cloudscheduler.googleapis.com

  4. To use Cloud Scheduler your Cloud project must contain an App Engine app that is located in one of the supported regions. If your project does not have an App Engine app, you must create one.

Schedule a workflow

  1. Create a service account so that Cloud Scheduler can make requests to the Workflows API:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name that is between 6 and 30 characters. It can contain lowercase alphanumeric characters and dashes. After you create a service account, you cannot change its name.

  2. To allow the principal that will run your Cloud Scheduler commands the ability to act as an Identity and Access Management (IAM) service account, grant a role that allows the principal to impersonate the service account.

  3. Grant your new service account the workflows.invoker role so that the account has permission to trigger your workflow:

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --role roles/workflows.invoker

    Replace the following:

    • PROJECT_ID: the ID of your Google Cloud project.
    • SERVICE_ACCOUNT_NAME: the name of the service account that you previously created.
  4. Create a Cloud Scheduler job that triggers your workflow, using the service account you previously created to authenticate:

    Console

    1. To schedule 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 Edit.

    4. On the Edit Workflow page, select Add new trigger > Scheduler.

      The Create a Scheduler job pane opens.

    5. Define the schedule:

      1. In the Name field, enter a name for your Cloud Scheduler job. It must be unique across the jobs in the same region.

      2. In the Frequency field, specify a time interval that you define in a unix-cron format. For example, to schedule your workflow to execute every 5 minutes, type */5 * * * *.

      3. In the Timezone list, select the time zone that Cloud Scheduler should use to interpret the schedule you provide.

    6. Click Continue.

    7. Configure the execution:

      1. In the Body field, specify any runtime arguments to pass to your workflow before execution. Arguments must be in JSON format. The double quotation marks inside the quoted string are escaped using backslashes (\). For example: {"argument": "{\"firstName\":\"Sherlock\", \"lastName\":\"Holmes\"}"}. If your workflow doesn't use runtime arguments, accept the default of "argument": "{}", or leave the field blank.

      2. In the Body field, specify the level of call logging that you want to apply during the execution of the workflow. You can accept the default of CALL_LOG_LEVEL_UNSPECIFIED or select one of:

        • 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.
      3. In the Service account list, select the service account that you previously created.

    8. Click Create.

      Note that you do not need to redeploy the workflow.

    The Cloud Scheduler job is now listed on the Triggers tab of the Workflows Details page. If you want to update or delete the job, you must edit the workflow; however, you do not need to redeploy it.

    gcloud

    1. Open a terminal and enter the following command:

      gcloud scheduler jobs create http JOB_NAME \
      --schedule="FREQUENCY" \
      --uri="https://workflowexecutions.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_NAME/workflows/WORKFLOW_NAME/executions" \
      --message-body="{\"argument\": \"DOUBLE_ESCAPED_JSON_STRING\"}" \
      --time-zone="TIME_ZONE" \
      --oauth-service-account-email="SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Replace the following:

      • JOB_NAME: the name you are giving to your Cloud Scheduler job.
      • FREQUENCY: a time interval you define using a unix-cron format. For example, to schedule your workflow to execute every 5 minutes, type */5 * * * *.
      • PROJECT_ID: the ID of your Google Cloud project.
      • REGION_NAME: the region your Workflow is in, such as us-central1.
      • WORKFLOW_NAME: the name of the workflow you want to schedule execution of.
      • DOUBLE_ESCAPED_JSON_STRING: a JSON encoding of any arguments you are passing. The double quotation marks inside the quoted string are escaped using backslashes (\). For example: --message-body="{\"argument\": \"{\\\"foo\\\": \\\"bar\\\"}\"}"
      • TIME_ZONE: the time zone that Cloud Scheduler should use to interpret the schedule you provide. For example: America/New_York.
      • SERVICE_ACCOUNT_NAME: the name of the service account that you previously created.
    2. To list all jobs in a project:

      gcloud scheduler jobs list

    3. To delete a job:

      gcloud scheduler jobs delete JOB_NAME

Your workflow now executes according to the frequency you have defined.

What's next