Schedules

Schedules are a built-in mechanism in OrgFlow for automatically running pre-configured jobs at a certain time and frequency. They can be used to automate common recurring tasks in your stack, such as running Apex tests or merging new changes upstream from production to all other environments (sometimes referred to as back-promotion).

A schedule consists of:

• A name and description
• The type of job to run and which settings to run it with
• A recurrence pattern
• A switch to enable/disable the schedule

Job types

Currently, the following types of jobs can be used with schedules:

Job type	Description
Flow in	Retrieve metadata changes from Salesforce orgs and commit them to backing Git branches
Flow out	Deploy metadata changes from backing Git branches to Salesforce orgs
Flow merge	Retrieve, merge and deploy metadata changes from a source environment to one or more target environments
Run Apex tests	Run Apex tests in Salesforce orgs and collect and visualize test result
Delete environment	Delete environments and optionally their Git branches and Salesforce orgs

More supported job types may be added in future releases, such as creating or refreshing sandbox environments.

Environment selection

When starting jobs interactively, you typically select one or more environments from a list. OrgFlow then starts one job for each selected environment.

In a schedule, environment selection is more dynamic and flexible, based not only on specific environments but also on environment tags. When configuring the schedule, you specify environment selection using an include filter followed by an exclude filter to achieve the desired result:

1. Include environments - either all, from a list or based on tags
2. From the included environments, exclude environments - either from a list, based on tags, or none

This screenshot shows an example where a schedule has been configured to run a job for all environments except those tagged with isInactive:

The filters are evaluated against the environment in the stack at the time of each execution of the schedule and the job template is expanded to start one job instance for every matching environment, each with the settings configured on the schedule. This allows you to create schedules that adapt dynamically as environments are continuously created and deleted.

Job settings

Depending on the selected job type, job-specific settings must be configured in the schedule. The configured settings are used as input for every job started by the schedule. The same settings and options available when you start a job interactively, are also available when you configure that job in a schedule.

Default settings in schedules

Because schedules are commonly configured to run outside working hours, we optimize the default job settings for unattended execution. This means that, for some job types, the default settings are slightly different in a schedule, compared to when you start the same type of job interactively.

Some examples of different defaults:

• The skip deployment confirmation option is set by default
• Merge conflict options are set to abort on merge conflicts rather than wait for a user to resolve them

You can override these defaults if you prefer your scheduled jobs to be configured for user interaction.

Recurrence pattern

The schedule's recurrence pattern determines at which times and how often the schedule should execute (i.e. start an instance of its configured job type for each of its selected environments).

The recurrence pattern is specified using a CRON expression — a common way to express recurrence patterns using a simple text-based format. When you enter a CRON expression in the web app, you get instant feedback on how the expression was interpreted:

• The recurrence pattern expressed in plain English
• The next few upcoming occurrences

This allows you to quickly and intuitively verify that you entered the CRON expression correctly and that it is interpreted the way you intended it:

CRON expressions are in UTC

Please note that the CRON expression is interpreted and applied in the UTC time zone.

As a convenient alternative to full CRON expressions, a set of simple macros are also supported. A macro is a string starting with @ that provides a shortcut for simple cases like every day at midnight or once per hour.

Macro	Equivalent	Description
@hourly	0 * * * *	Run once an hour at the beginning of the hour
@daily	0 0 * * *	Run once a day at midnight
@midnight	0 0 * * *	Run once a day at midnight
@weekly	0 0 * * 0	Run once a week at midnight on Sunday morning
@monthly	0 0 1 * *	Run once a month at midnight of the first day of the month
@yearly	0 0 1 1 *	Run once a year at midnight of 1 January
@annually	0 0 1 1 *	Run once a year at midnight of 1 January

OrgFlow uses the open-source library Cronos for parsing and executing CRON expressions. For a full reference on the CRON syntax and macros supported by OrgFlow schedules, see the CRON format reference for Cronos.

Common scenarios

Nightly upstream merge

To keep sandbox environments up to date with production metadata, a common and recommended practice is to perform an upstream merge on a regular basis. As the name implies, an upstream merge merges metadata changes up the change stream, for example from production to development environments higher up the stream. This is sometimes also referred to as back-promotion of changes.

Upstream merge (or back-promotion) into a sandbox environment applies both to changes made directly in production, and to changes merged and deployed to production from other environments, since the sandbox was created.

A schedule can easily be created for this purpose:

1. Choose the job type Flow merge
2. For the source environment, specify your production environment
3. For target environments, specify all except your production environment using the following filters:
   • Include: ALL
   • Exclude: SPECIFIC (select your production environment)
4. For execution, specify @midnight or a CRON expression that suits your needs

As part of a flow merge job, a flow in (retrieve) of both the source environment and each target environment are enabled by default, which means this schedule also ensures that all environments will have new metadata changes in their orgs committed to their backing Git branches every night as a nice side-effect of this schedule. If you prefer to create separate schedules for flowing in changes (perhaps more frequently than once per day) you can disable the inbound flows of this schedule in the job settings.

Nightly Apex tests

Failing Apex tests can completely block a production deployment. It's important to discover failing tests as early as possible so developers have enough time to fix them before release day. A common and recommended practice is to run Apex tests in all environments on a regular basis.

This applies also to your production environment. Even for highly disciplined teams that never make metadata changes directly in production, other changes normally made by admins or users to your production org's settings or data, or changes introduced by underlying platform updates, can cause Apex tests to fail in production.

A schedule can easily be created for this purpose:

1. Choose the job type Run Apex tests
2. For environments, specify all enviroments:
   • Include: ALL
   • Exclude: NONE
3. For execution, specify @midnight or a CRON expression that suits your needs