Deploying process builder flows and flow definitions via the Metadata API

Matt Dickens on

Share with

LinkedIn
Twitter

Have you run into any of the following error messages while 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 practices for deploying flows via the Metadata API, and deploying via change sets comes with its own sizable list of recommendations and caveats. Deploying flows without the right tools can be tricky.

Illustration of Flows

One of our core tenets at Gearset is making sure that your deployments succeed first time, every time. Deployment success rate is one of our key metrics and, to that end, we’ve built a deployment engine that identifies and flags or fixes potential problems with users’ deployments before pushing the packages to Salesforce.

Thanks to feedback from our fantastic users, we’ve addressed the major challenges faced when deploying flows. Let’s take a look, 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 is a flow that 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 Metadata API. A flow definition is created automatically when you create a new flow version

Cause: This error is quite self-explanatory, although it can be misleading. It’s true that you can’t deploy a new flow definition on its own directly through the API, but you can create a 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 either to add a version of the flow to the deployment package or to 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 the 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 one common culprit is 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.

Happy deploying!

That covers the common ways we see flows making bad things happen to good deployments, and how Gearset’s intelligent handling of flows will bring you one step closer to the holy grail of deployments working first time, every time. Gearset users have a 92% success rate for their metadata deployments — a huge increase from the 50% average for change set users. Find out more about how this is possible with our metadata deployment engine.

Ready to get started with Gearset?