How Flows and Flow Definitions changed with the Salesforce Metadata API v44

Flows are every admin’s friend until it gets to deployment time. Whether it’s a missing dependency or an error message that leaves you scratching your head, Flows can make deployments fail more often than other metadata types.

To make things a little bit more complicated, deploying Flows via the Metadata API has also changed over the years. This post covers that story and explains how to overcome a raft of Flow deployment errors you might be battling with:

• Insufficient access rights on cross-reference id
• You can’t create a flow definition directly through the API
• Invalid version number: <insert version number>
• The version of the flow you’re updating is active and can’t be overwritten

How did Flows change with v44 of the Metadata API?

Salesforce made changes to the way Flow metadata works in its Winter ‘19 release (v44 of the Metadata API). Previously, Flow versions had been managed using filenames, and Flow Definitions were critical bits of metadata because they defined which Flow was the active version. In 2019, Salesforce recognized that this approach was at odds with using version control, so it transformed Flows — making Flow deployments quite different in the process.

Let’s take a look at the two main changes and their implications for how to deploy Flow versions in Salesforce.

1. Flow version numbers are no longer in the Flow name

Saving a set of changes in Flow Builder always creates a new version of the Flow, so you have to think about Flow versions during deployments. Before v44 of the Metadata API, version numbers were part of the Flow name, e.g. MyFlow-<version-number>.flow. From v44 onwards, version numbers have been stripped out, e.g. MyFlow.flow.

This change means that you can now only retrieve and deploy the latest version of your Flow from Salesforce via Metadata API, if you use v44 or later. When you deploy that Flow, it will be created in the target as a new version — and the version number may not match the version in the source.

Prior to v44, if you tried to deploy a change to an active or obsolete flow, you’d get a deployment error. From v44 onwards, Salesforce will simply create a new version of the Flow in the target.

2. Salesforce encourages you not to use Flow Definitions

Instead of relying on Flow Definitions to define which version of a Flow is active, from v44 onwards Flows have a status field which determines whether a Flow is active, inactive, or a draft. When you deploy a Flow, it will generally be given the inactive status, although you can change that default behavior in Salesforce and deploy Flows as active.

Flow Definitions haven’t been retired — you can still retrieve and deploy them via any version of the Metadata API. And it’s still possible to use a Flow Definition to switch which Flow is active. But care is needed, because Flow version numbers between orgs are no longer linked. A Flow Definition might even end up pointing at a version that doesn’t exist in your target org!

Are Flow Definitions still needed?

It’s definitely a good idea to move on from Flow Definitions, especially if you’ve adopted version control.

There are possible use cases for Flow Definitions. For example, imagine you’ve begun working on a Flow, and so you’ve got a new latest version as a draft, but then you want to deploy the active version of the Flow. Using v44 onwards, Salesforce will only retrieve the latest version of the Flow. If you need to deploy a version of a Flow that isn’t the latest version, you can use v43 of the Metadata API and specify the active Flow with a Flow Definition. Of course, any post-v44 features of your Flows may not be deployable that way.

It’s also worth noting that you need to retrieve Flow Definitions in order to deploy Flow Access permissions metadata.

How to graduate from Flow Definitions to v44

Salesforce’s Metadata API guide has advice for upgrading Flows to v44. With Gearset, the process is even simpler: just compare your org and Git branch using v44 of the API or higher. All versioned Flows will be marked as ‘deleted’, leaving one unversioned Flow marked as ‘changed’ or ‘new’. Select all of these changes and commit them to your branch.

Flow deployment errors — and how Gearset solves them

Even when you’ve got your head around all of the changes made by v44 of the Metadata API, Flows are still a common cause of deployment errors. Gearset has almost 100 problem analyzers that highlight anything in your deployment packages that’s likely to make it fail — and in most cases it’s able to fix the issue for you. For example, any missing dependencies (and those are easy to forget with Flows in particular!) are flagged by a problem analyzer, and Gearset will offer to include the missed items for you.

Since there are various ways Flow deployments can fail, Gearset also has a number of problem analyzers specifically for Flows and Flow Definitions.

Warning when deploying Flow Definitions after v44

Because deploying Flow Definitions on v44 or higher of the Metadata API can be problematic, one of Gearset’s problem analyzers will automatically warn you about a deployment package that does this. You can decide whether or not to remove the Flow Definition.

‘Insufficient access rights on cross-reference id’

This is a fairly general-purpose Salesforce error message that can crop up in a few different ways during a Flow deployment.

Post-v44, if you’re trying to deploy a deleted Flow, all versions of that Flow in the target must be identified for deletion. But as the API no longer returns versions of Flows, this isn’t normally possible over the Metadata API. Some folks report seeing the Problem: setup object in use error when attempting destructive changes. Gearset unblocks these deployments by identifying all the versions in the target that need to be deleted, and adding those into your deployment package for you.

If you’re using pre-v44 of the API, the error Insufficient access rights on cross-reference id can be triggered when you’ve deleted a Flow Definition, and are trying to deploy that destructive change. Gearset will automatically recommend removing these destructive changes from your deployment package.

‘You can’t create a Flow Definition directly through the Metadata API. A Flow Definition is created automatically when you create a new Flow version’

This Salesforce error message seems self-explanatory, but can be misleading. It’s true that you’re unable to deploy a new Flow Definition on its own directly through the API, but you can if you’re deploying any version of the corresponding Flow along with it. Gearset detects any lone Flow Definitions and suggests you either add the relevant Flow or remove the Flow Definition from the deployment.

‘Invalid version number: [insert version number]’

This error is specific to deploying via pre-v44 API. You can’t deploy a Flow Definition referencing a version of a Flow that won’t be present in the target after the deployment. If Gearset detects that you’re missing a referenced Flow, it’ll offer to add the missing version to the deployment package.

‘The version of the Flow you’re updating is active and can’t be overwritten’

This is another pre-v44 error, triggered when an active or obsolete Flow in the target has been changed in the source. In theory this should be unlikely, but it’s surprisingly easy to end up with a Flow that has existed in a different state on both source and target, and then been activated on both independently with the appearance of being the same version. Using a more recent version of the API, Salesforce will add the Flow as a new version anyway, which resolves the issue.

Go with the Flow

Flows have never been super easy to deploy, and there are both pros and cons to the ways they’ve changed over time. Find out how Gearset’s comparison and deployment engine helps you overcome the challenges of deploying Flows, or get started today on a free 30-day trial.