As we've discussed in previous posts, choosing which metadata API version to use when storing your metadata in git requires some thought. If you've ever seen errors like:
Property 'valueSet' not valid in version 37.0 or
Not available for deploy for this API version, then you know what we're talking about.
With Gearset, you can avoid the pain of deployment failures and fixing version mismatches through our intelligent handling of API versioning. When using source control as the source or target of a comparison, behind the scenes Gearset is taking the contents of that repository and running checks to determine the version of the metadata inside. Gearset has recently improved this handling, running even better checks to determine which API was used to generate the existing repository, and when an API version is not detected, Gearset will now default to version 42 rather than version 37. With this new default, anybody creating a new repository with Gearset will always have the latest and greatest metadata.
Detecting a source control repository's API version
When configuring your comparison, if you select source control as your source or target of your comparison, Gearset will attempt to detect the API version of the metadata in your source control repository. If Gearset finds a package.xml, it will use the version specified therein, and if there’s no package.xml, it’ll check the metadata in the repository and estimate the API version based on what’s found.
Previously, if Gearset couldn’t detect an API version, it would default to assuming version 37. We’ve recently introduced additional checks behind the scenes that use known types of metadata in your repo when identifying the API version, particularly checking for known version 37 metadata types. With this improved API version detection, we’ve been able to bump the the default API version to 42, so anyone using source control with Gearset can benefit from the most up-to-date metadata representation.
So we now know that Gearset will always default to the highest commonly-supported API version if a version cannot be detected, which is now version 42. But what if you want to override that decision? No problem - you can also perform a version override within Gearset to force a different API version, should you need to. You can do this when you’re configuring your comparison, by clicking
Manage custom filters under Metadata comparison filter and selecting your chosen API version from the dropdown.
Upgrading your repository’s metadata
When the time comes to upgrade your metadata, either because there are new metadata types you want to take advantage of, or a pesky bug in Salesforce's downgrading of newer metadata to older API versions, Gearset makes it easy.
Gearset’s intelligent detection of which API version to use makes it easy for you to manage these API version upgrades. If you specify an API version in a
package.xml in your branch, Gearset will use that API version for that branch until you update it to specify the newer version. Once the version number is updated, running a comparison from the associated org to that branch will highlight all the differences caused by the version upgrade, and give you the opportunity to review those changes and commit them back to your repository. It’s as simple as that!
Running into API versioning issues? Get in touch!
Metadata API versioning is a common cause of deployment frustration, especially when Salesforce start their upgrade cycle. Gearset detects which API version was used to generate the metadata in your repository and defaults to version 42 when an API version can’t be identified. This means you can use the latest metadata, control when to upgrade to newer API versions and avoid the hassle of version mismatches, so you can get on with the important part; the deployment!
Had an issue with API versioning? Wish that Gearset's handling of it could be even better? We're always looking for feedback, so let us know at [email protected], or through the in-app chat!