Initial domain mapping
Initial domain mapping is a process that establishes relationships between external data schemas and DevRev’s native record types. This mapping is configured once and then becomes available to all users of your snap-in, allowing them to import data while maintaining semantic meaning from their source systems.
The initial domain mapping is installed with your snap-in. On each snap-in version update, function to upload these mappings to the Airdrop system is triggered.
Approaches
You can create initial domain mappings using two methods:
- Chef-cli UI: Interactive web interface for comprehensive mapping creation
- Model Context Protocol (MCP): AI-assisted mapping creation for developers (experimental)
Choose the chef-cli UI for manual control or use MCP for rapid prototyping with AI assistance. MCP is an experimental feature and works locally without requiring a sync to be created.
For AI-assisted mapping creation, see the Model Context Protocol integration guide.
Chef-cli initial domain mapping setup
Prerequisites
- Snap-in is set up, deployed, and activated.
- An import has been created and is in the mapping stage.
It’s also required that you have the DevRev CLI authenticated appropriately.
This can be done either with devrev profiles authenticate -e prod -o <your_org_slug> -u <your_email>
or by running make auth in your snap-in repository.
Add your token as an environment variable
Obtain a PAT-token from the Settings > Account tab of the dev org where you deploy your snap-in,
and export it as DEVREV_TOKEN.
You can also run the following command if you are authenticated with the CLI:
Initialize the context of the sync
To allow the CLI to work in the context of that sync, you need to provide its identifying properties in an environment variable. The recommended method is to run:
This prints the list of Airdrop imports in the org. Select the one you want by running:
If this method doesn’t work, you can manually export the variable (replacing the values based on the logs of your running import):
Or you can use the interactive helper of the CLI:
Use the local UI to create a recipe blueprint for your initial import
If you are also creating a bidirectional sync (DevRev to external system), to enable mapping in both directions, use:
If your org is not in US-East-1, you have to override an environment variable to make sure the tool reaches the right server. For example:
The options are: dvrv-us-1, dvrv-eu-1, dvrv-in-1, and dvrv-de-1.
The first function of the local UI is to assemble a blueprint for a concrete import running in the test-org, allowing the mapping to be tested out and evaluated. After it is used for the import, the mappings become immutable, but the chef-cli UI offers a button to make a draft clone, which can be edited again for refinements.
Use the local UI to create initial domain mappings
The final artifact of the recipe creation process is the initial_domain_mapping.json, which has to be embedded in the extractor.
This mapping, unlike the recipe blueprint of a concrete import, can contain multiple options for each external record type from which the end-user might choose (for example, allow task from an external system to map either to issue or ticket in DevRev), and it can also contain mappings that apply to a record type category. When the user runs a new import, and the extractor reports in its metadata record types belonging to this category that are not directly mapped in the initial domain mappings, the recipe manager applies the per-category default to them.
After the blueprint of the test import is completed, the Install in this org button takes you to the initial domain mapping creation screen, where you can merge the blueprint to the existing initial mappings of the org.
By repeating this process (run a new import, create a different configuration, merge to the initial mappings), you can create an initial mapping that contains multiple options for the user to choose from.
Finally, when all the fields are mapped without deficiencies and the blueprint is installed, the Export button allows you to retrieve the initial_domain_mapping.json.
You can also provide a local metadata file to the command using the -m flag, for example:
This enables the following features:
- Raw jq transformations using an external field as input (experimental feature).
- Filling in example input data for trying out the transformation.
In this case, it’s not validated that the local file is the same as the one submitted by the snap-in.
Test an import with initial mapping using the in-app UI
Once the initial mappings are prepared, any new import in the org (with the same snap-in slug and import slug) where they are installed will use them. The end-users can influence the recipe blueprint that gets created for the sync unit through the mapping screen in the UI, where they can make record-type filtering, mapping, fine-grained filtering, low-code field and value mapping, and finally custom field filtering.
Their decisions are constrained by the choices provided in the initial domain mappings. Currently, the low-code UI offers limited insight into the mappings and their reasons, and in some cases, mismatches arise when something that worked in chef-cli doesn’t offer the right options to the user, or not all fields that should be resolved are solved. To assist debugging such cases, chef-cli provides a command to extract the description of the low-code decisions that are asked in the UI. Please provide this to us when reporting an issue with how the end-user mapping UI behaves.