Skip to main content

How to deploy Context Definitions

A guide on how to compare and deploy Context Definition metadata with Gearset

Written by Jacob Joshua

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.
​

Sync extended definitions

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
(if applicable)

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
(if applicable)

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.

Did this answer your question?