What is Context Definition?
ContextDefinition is part of Salesforce’s Context Service. In the context of Revenue Cloud Advanced (RCA), it helps different parts of the process talk to each other by passing along important context, like what quote a user is working on or which product they’re interacting with.
You can think of it as a way for Salesforce to keep track of what’s going on as someone moves through steps like quoting, pricing, or renewals. Each ContextDefinition defines what kind of information needs to be carried around and how it should be used.
Custom vs Standard Context Definition
Salesforce provides some standard ContextDefinition out of the box these are built-in and can't be retrieved or deployed using metadata tools.
You can only retrieve and deploy custom ContextDefinition ones that have been created or extended specifically for your org.
How to retrieve Context Definition
You need to include ContextDefinition metadata in your metadata filter and run a comparison as below to be able to retrieve them from your source and target.
The specific example shown here below is from a Revenue Cloud Org.
How to deploy Context Definition
From the comparison above, select your items and click on "Next".
When deployed individually, it usually comes without Problem analyser suggestions which you'll find onto the next page.
To deploy ContextDefinition click on "Deploy now" when arrived on this step.
Errors we have seen while deploying Context Definition
We have found a couple of common errors when deploying ContextDefinition.
Error 1
An error has occurred retrieving the metadata from Salesforce: Could not retrieve metadata: UNKNOWN_EXCEPTION - DML operation on setup object is not permitted after you have updated a non-setup object (or vice versa): AsyncRequestFFXResult, original object: ContextDefinitionSync
Error 2
inheritedFromVersion changed for definition Rev_SalesTransactionContext new value: XX previous value: YY
The sample XML will show similar to this below when encountering this error:
For both errors though, the ContextDefinition in the target org was out of sync.
The resolution to this was therefore to go to the Context Service page in the target org, click Sync, and then try the deployment again.
Please refer to this Salesforce article for step-by-step instructions.
After syncing, the validation was successful as below.
And voilà! Congratulations on successfully deploying your ContextDefinition!
Limitations when deploying Context Definition
Salesforce only supports some changes to ContextDefinition metadata made through Metadata API.
These limits come from Salesforce, and are not Gearset enforced by Gearset. They apply regardless of how the deployment is made - whether that is via Compare and deploy, a CI job, or a pull request validation (and then promotion) via Gearset Pipelines (which is also linked to CI job deployment).
The limitations apply depending on whether you're creating a new definition or updating one that already exists in the target org.
Limitations for creating a new Context Definition
The table below shows what deployment types Salesforce supports when the definition doesn't exist in the target org yet.
Change you're deploying | Is it supported via Metadata API? | What to do instead |
A new custom definition, with its custom nodes, attributes, context tags and mappings | Yes | N/A |
A new definition extended from a standard definition | Yes - if the standard definition in the target org is in sync | Sync the definition on the Context Service page in the target org before deploying. |
Duplicate context tag names, or more than one mapping to the same sObject field | Not supported, as it causes conflicts | Make each tag name and each sObject field mapping unique within the definition before deploying. |
Activate the definition as part of the deployment | Not supported | Activate the definition manually in the target org after the deployment. |
Set a mapping as default or non-default as part of the deployment | Not supported | Set the default mapping manually in the target org after the deployment. |
Deploy from an org on the current Salesforce release to one on an older release | Not supported | Deploy only between orgs on the same release, or wait until the target org is upgraded (to match the source org's release). |
Limitations for updating an existing Context Definition
The table below shows which changes Salesforce applies when the definition already exists in the target org, and what changes it cannot support.
Change you're deploying | Target definition state | Is it supported via Metadata API? | What to do instead |
Adding new custom nodes, attributes and their mappings | Any | Yes | N/A |
Updating or deleting existing custom mappings | Active or inactive | Yes | N/A |
Modifying existing custom nodes or attributes | Inactive | Not supported | Replicate the change manually on the definition in the target org, or delete the definition from the target org and deploy it again. |
Modifying standard nodes or attributes | Active | Not supported | Deactivate the definition in the target org, make the change, then activate it again. |
Activating or deactivating the definition | Any | Not supported | Change the activation status manually in the target org, before or after the deployment |
Changing which mapping is the default | Any | Not supported | Change the default mapping manually in the target org |
For standard definitions, Salesforce also versions each definition. Any change you deploy must have a higher version than the one already in the target org.
Tip: For the full list of limitations, check Salesforce's documentation on Context Service Additional Information and Migrate Context Definitions.







