If you’ve worked with Salesforce’s Metadata API for any period of time, you’ve probably seen an error message along these lines:
Property ‘namesegment’ not valid in version 57.0
The details may differ slightly, but the outcome is the same — a mismatched API version has caused a failed deployment, by trying to push metadata that was retrieved using a newer version to an older version of the API. This sort of error is likely fairly familiar to those teams opting to source control their metadata.
This raises the questions: what version should you use for the metadata in your repo, and at what point should you upgrade it? Read on to hear how Gearset makes this error message a thing of the past.
What is API versioning in Salesforce?
APIs are a set of rules and protocols that allow two software systems to talk to each other. As a software platform like Salesforce changes, its APIs must be updated along with it to reflect those changes.
With each platform release, Salesforce introduces a new API version which is given its own version number. Each version maintains backward compatibility within a specific version – meaning existing functionality and integrations built on an older version of the API should continue to work as expected, even if a newer version is released.
What version of the API am I using?
To find which version of the API your org is currently using, follow these simple steps in your org:
- Navigate to Setup and enter API into the ‘Quick Find’ search box. Then select API.
- Under Metadata WSDL click Generate Metadata WSDL. This will open a new tab and your metadata version will be shown at the top.
There’s one single value that controls the Metadata API version you use when deploying or retrieving. It typically lives in the file called package.xml. If you’re using Salesforce DX then this value will be in your sfdx-project.json file. You can read more about these files and how to manage Metadata API versions in this blog post.
When working with Salesforce source code and metadata, you need to make sure that the version of the Metadata API that’s being used is compatible between source and target. This is where sourceAPIVersion comes in. By setting this value, you’re telling Salesforce which version of the API to use when interacting with your source code and metadata.
Metadata API versions
When Salesforce releases a new version of the API it can cause some mismatching issues with the metadata in your orgs. In some releases, there aren’t major or breaking changes between API versions, and this transition goes unnoticed. But with other releases, there are more significant changes that require you to make a careful decision about which version of the API you want to use during your retrieve, validate and deploy calls.
When metadata types are phased out and deprecated over time, this can cause your deployments to start failing. One of the most notable version releases that caused issues was v44 that changed the way Flow metadata worked by starting to phase out the use of Flow Definitions. One of the ways that Salesforce encouraged teams to move away from using Flow Definitions was to introduce a status field in the Flow. This means that you no longer need Flow Definitions and can now incorporate it into the Flow’s status field. If you happen to be affected by this particular version update then Gearset has a number of problem analyzers specifically for Flows and Flow Definitions.
Commonly searched Metadata API version errors
This problem comes up time and time again so it’s no surprise that the error messages are widely searched. Some of the most common metadata mismatch errors that you might come across include:
- Property ‘allownullvalues’ not valid in version
- Property ‘componentinstances’ not valid in version
- Property ‘enableapexcdncaching’ not valid in version
- Property ‘filterformula’ not valid in version
- Property ‘headlessforgotpasswordtemplate’ not valid in version
- Property ‘identifier’ not valid in version
- Property ‘isclientcredentialenabled’ not valid in version
- Property ‘isgoto’ not valid in version
- Property ‘isnavtabpersistencedisabled’ not valid in version
- Property ‘namesegment’ not valid in version
- Property ‘regioncontainertype’ not valid in version
- Property ‘valueSet’ not valid in version
How Gearset helps
There are two main situations where this sort of version mismatch can cause problems — when migrating changes between orgs that use different API versions, and when your metadata is being managed through a version control system.
Migrating changes
This scenario is most common when some, but not all, orgs have been upgraded to a new API version. This often manifests as a Developer sandbox on the new API version, while your production org is still on the previous version. Developers must ensure that both orgs are using the highest common version. This ensures that metadata retrieval and deployments are performed with the same API version, and that the API version is supported by both orgs.
Gearset automatically chooses the correct API version to use in comparison, validation, deployment, CI and monitoring jobs, and rollback. For example, if the source org supports v44 and the target is still on v43, then Gearset will automatically choose v43 for any snapshots and deployments.
Versioning becomes even more important when handling rollbacks. Consider a deployment made prior to an API version upgrade — attempting to roll back this deployment could be problematic, given that a rollback relies on the snapshot of that org prior to the upgrade, meaning the metadata will have been retrieved using an older API version.
Because Gearset records the API version used in each operation, it will automatically choose the original API version used when rolling back an earlier deployment. This means that if a deployment was made with a retrieve and deploy at v43 and the org has subsequently been upgraded to v44, Gearset will automatically use v43 when rolling back. As a result, the differences you see in the rollback comparison will accurately reflect the change that will be made, rather than showing a diff between v43 and v44 metadata.
Using version control
By default, Gearset currently assumes metadata under source control or in your Git repo is v57 — this is because until recently most orgs were still on v57, and there are still a lot of repositories that contain v57 metadata. That said, Gearset also offers an API version override in the Manage custom filters dialog:
This means you can choose the exact version of the metadata API to use and Gearset won’t attempt to change the version of metadata in your Git repo by default. When you’re ready to upgrade, you can run a comparison between your org and your Git repo with v58 selected instead of the default, and Gearset will run the retrieve with v58, showing you all of the changes caused by the version upgrade.
Deploying the resulting differences will effectively upgrade the metadata in your repository from v57 to v58. In subsequent comparisons and deployments from and to that Git repo, make sure that v58 is selected in your comparison options.
The easy way to manage API versions
By offering multiple versions of the API and allowing backward compatibility, Salesforce helps developers maintain stable and reliable connections between their software systems and the Salesforce platform.
Metadata API versioning is a common cause of deployment frustration and we are often troubleshooting these mismatch versioning issues for teams. Gearset will intelligently choose the best API version for comparisons and deployments where possible, and gives you the power to override that decision in just a couple of clicks. If you haven’t already, start your free trial of the full platform today to see for yourself how Gearset intelligently manages API versions, so your deployments run successfully.