Instructions for comparing and deploying flows using Gearset, and some common issues that can arise when deploying flows

Claudia McPhail avatar
Written by Claudia McPhail
Updated over a week ago

What are flows?

A flow is an application that automates a business process; they gather information and use it to do something in your Salesforce org. Flows are one of the many tools on the Salesforce platform that have been developed to assist an existing business process. Flows are complex, can be built declaratively and can be used for a behind the scenes automated process or a guided visual experience.

To learn more about developing flows, there is a Salesforce Trailhead module here, which can get you started learning the basics, or provide a refresher.

There are a few pieces of terminology used to refer to flows, but these are the official Salesforce terms:

  • Flow - With flow metadata, you can create an application that navigates users through a series of screens to query and update records in the database.

  • Flow Builder - A point-and-click tool for building flows.

  • Lightning Flow - The product that encompasses building, managing, and running flows and processes.

  • FlowDefinition - Represents the flow definition’s description and active flow version number, however this is no longer used since v44 of the Metadata API. You can find other changes from that version here.

  • FlowCategory - Represents a list of flows that are grouped by category. Flows aren’t added directly to a Lightning Bolt Solution. Instead, add the category the flows are in to the Lightning Bolt Solution

  • FlowSettings - Represents the org’s settings for processes and flows, such as whether Lightning runtime for flows is enabled.

  • FlowAccessess - A subcomponent of Profile metadata that appeared in 2020, flowAccesses metadata allows you to choose exactly which flows your users can or can't run, by restricting access to certain flows.

What do you need to include in your metadata filter to see flows in your comparison?

As we know, flows are automated processes that can query and update other parts of your org. So as well as the Flow and Flow category metadata types you should also include the Custom object metadata that the flow depends on.

Note: Older Metadata API versions might not include recently updated sections of flows. To avoid missing crucial information, we recommend using the latest version available.

If the flow depends on managed package metadata, you should also include managed packages.

When retrieving a flow, the metadata API only provides the most recent version of the flow, if you need to deploy an older version of a flow, then saving that as a new flow is a possible workaround.

Flow Navigator can help you understand what's changed in a Flow, making it easier to spot any unwanted changes.

How to deploy a new flow

To deploy a new flow, you need to find the metadata in the comparison results and select it.

Because flows are a metadata type that depend on the rest of the org, if there are significant differences between the source and target, they may fail validation. However, this also means that validation errors related to flows can be resolved by making another deployment to resolve the differences between the two environments, and then deploying the flow in a second smaller deployment.

For example, if the flow depends on custom objects or fields that exist in the source and not the target, you should deploy these first, to avoid validation errors.

Can I deploy flows as active to my Prod org?

By default, flows are deployed as inactive in a production environment. You can either change this behaviour for all flows, or you can activate flows on deployment to production.

What needs to be present in your target environment for a flow deployment to be successful?

Gearset has the ability to map dependencies of metadata in a way that makes them clearly visible in your comparison results.

To find out what your flow depends on, you can click the dropdown arrow next to the API name, and then the drop down next to the Depends on information.

If you do not see any dependencies here it may be because your comparison filter is too restrictive. You can update your metadata selection and refresh the comparison by clicking on Refresh comparison in the bottom left of the comparison results.

Deploying a flow with multiple versions

It is common to have more versions of your flow in your source than your target, as this will have been where changes have been made and saved as new versions of the flow. Deploying a flow will transfer the latest version of the flow from the source into the target.

Retrieving flows via Metadata API only delivers the latest version. If you need to deploy an older version, saving it as a new flow is an alternative.

Can you deploy flows to a version control system?

Yes, you can deploy flows to and from your version control systems in the same way as any other metadata. Because flows are prone to validation errors, you may want to set up automatic validation of pull requests against the orgs in your CI workflow.

Common gotchas

  • The state of the deployed flow will depend on its status field, however a flow with the draft status will deploy as inactive.

  • If you are deploying a change to a flow version which is already active, or was once active, in the target, you might hit a validation error as a deactivated version might still have running or paused executions. The solution is to deploy your changes as a new flow version.

  • If the comparison is too restrictive, key junction items may not be retrieved, which may exclude some of the elements you're expecting to see. Refreshing the comparison with the Compare all metadata filter selected will confirm whether the filter is the issue.

  • If you are deploying Scheduled Paths, please make sure to use API v52 or higher in the comparison Metadata Filter as these were only introduced in v52 and won't deploy correctly on a lower version.

Did this answer your question?