Contact sales: +1 (833) 441 7687

Deploying process builder flows and flow definitions via the metadata API

Matt Dickens on August 28th 2016

Have you ever ran into any of the following error messages whilst attempting to deploy flows and flow definitions?

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

Rest assured, you’re not alone - there’s a healthy amount of discussion around best practises for deploying flows via Ant and the metadata API in the usual corners of the internet, and deploying via Change Sets comes with its own sizeable list of recommendations and caveats. Deploying flows is tricky.

As we’ve mentioned before, one of our core tenets at Gearset is to make sure that your deployments succeed first time. In fact, deployment success rate is one of our key metrics, and a quick look at the changelog shows we’ve recently been releasing a lot of updates towards this end, tracking all kinds of dependencies and detecting a host of potential problems with users’ deployments before pushing the packages to Salesforce.

Thanks to feedback from some of our fantastic users, we've spent some time addressing the major challenges faced when deploying flows. Let's take a look at what's changed one error at a time.

The version of the flow you're updating is active and can't be overwritten

Cause: This is theoretically quite difficult to trigger - it requires that an obsolete or active flow be different between source and target, and Salesforce won’t allow you to change an obsolete or active flow via the UI. The most common cause then, is usually when a flow has existed in a different state on both source and target, and then been activated on both independently.

How Gearset helps: Gearset retrieves additional metadata about your metadata (metametadata, if you will!) to establish whether each flow version is either a draft, active or obsolete. We use this to detect whether you’re trying to update an active or obsolete flow, and show you a warning with a suggested fix.

Detecting a change to an obsolete flow

The fix is to remove the changed active or obsolete flow from the deployment package, and we’ll automatically apply this for you if you proceed with the deployment. The warning and fix also apply to deleted active flows.

You can't create a flow definition directly through the API. A flow definition is created automatically when you create a new flow version

Cause: This one’s quite self-explanatory, although misleading. It's true that you can’t deploy a new flow definition on its own directly through the API, but you can create flow definition directly through the API if you’re deploying any version of the corresponding flow along with it.

How Gearset helps: We detect this change prior to deployment and show you a warning, advising you to either add a version of the flow to the deployment package or remove the flow definition from the deployment.

Detecting a new flow definition without a corresponding flow

We won’t automatically add a version of the flow to deployment package for you, because we don’t want to make assumptions about which version(s) you’d like to deploy. That is, unless your flow definition references a specific version of the flow, which brings us on to the next error.

Invalid version number: [insert version number]

Cause: You can’t deploy a flow definition referencing a version of a flow that won’t be present on the target after the deployment. This is surprisingly easy to do, usually by forgetting to include the new, active flow version in the deployment package.

How Gearset helps: If Gearset detects that you’re missing a referenced flow version, we’ll show you a warning and offer to add the missing version into your deployment package for you.

Detecting a flow definition referencing a missing flow version

This fix is enabled by default, so if you click straight through the deployment warnings, we’ll include the referenced flow version in your deployment package automatically and your deployment should go ahead as intended.

Insufficient access rights on cross-reference id

Cause: This error is fairly general-purpose with a variety of possible causes, but in the instance we’re interested in it’s triggered by the deletion of a flow definition.

How Gearset helps: We detect attempted deletions of flow definitions and offer to remove those deletions from the deployment package for you.

Detecting a deleted flow definition

And once again, we'll automatically include this fix unless you choose not to.


That covers the most common ways we see flows making bad things happen to good deployments. Hopefully Gearset’s intelligent handling of flows will bring you one step closer to the holy grail of deployments working first time, every time.

If there’s anything we’ve missed, or if you have any feedback about any aspect of Gearset, then don’t hesitate to drop us an email at [email protected], or just send us a quick message via the chat widget - we’d love to hear from you!

Ready to get started with Gearset?

Start free trial