If you’ve worked with the Salesforce metadata API for any period of time, you’ve probably seen a message along these lines:
Property 'valueSet' not valid in version 37.0 - versioning and the mdapi
This sort of error is likely fairly familiar to those teams opting to source control their metadata. The details my 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 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.
Metadata API versions
As you’re probably already aware, Salesforce introduces a new API version with each release. Version 37 came along with Summer ’16, and more recently we saw version 38 introduced with Winter ’17. In some releases, there aren’t major or breaking changes between API versions, and this transition goes unnoticed. In other instances, such as the most recent one, 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.
One such change in the recent release is the introduction is the change from picklists to value sets. Attempting to deploy metadata containing a value set via the v37 API will cause your deployment to fail, with the error above.
How Gearset helps
There are two main situations where this sort of version mismatch can cause problems — when migrating changes between orgs that vary in their support for different API versions, and when version controlling your metadata.
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 DE org used by a developer on the new API version, while sandboxes and prod are still on the previous version. Working with, for example, the Force.com migration tool, developers must ensure that the version used matches the lower of the two available. This ensures that the retrieves and the deployment 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. To do this, we follow a “highest common denominator” strategy. For example, if the source org supports v38 and the target is still languishing on v37, then Gearset will automatically choose v37 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 v37 and the org has subsequently been upgraded to v38, Gearset will automatically use v37 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 v37 and v38 metadata.
Version controlling metadata
When version controlling metadata, it’s important to choose which version of the metadata API to use when retrieving the metadata, and to be consistent in this choice. By default, Gearset currently assumes metadata under source control or in a folder on disk is v37 — this is because until recently most orgs were still on v37, and there are still a lot of repositories that contain v37 metadata. That said, Gearset also offers an API version override in the Manage custom filters dialog:
This means Gearset won’t attempt to change the version of your on-disk metadata by default, but when you’re ready to upgrade that on-disk representation, Gearset has you covered — just run a comparison between your org and your git repo with v38 selected instead of the default, and we’ll run the retrieve with v38, showing you all of the changes caused by the version upgrade. Deploying the resulting differences will effectively upgrade the metadata in your repository from v37 to v38. In subsequent comparisons and deployments from and to that git repo, just make sure that v38 is selected in your comparison options.
Conclusion
Metadata API versioning is a common cause of deployment consternation when Salesforce start their upgrade cycle. Gearset intelligently chooses 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, should you need it.
Had an issue with API versioning? Wish that Gearset’s handling of it could be better still? We’re constantly looking for feedback, so let us know at [email protected], or through the live chat! Happy New Year from all of us here on the Gearset team!