Skip to content

docs: Add fallback docs #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 21 commits into from
Jun 11, 2025
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
d33cd91
Update IDM docs
tilenkavcic May 28, 2025
720c6c6
Update supported object types
tilenkavcic May 28, 2025
c8cff51
Add fallback description
tilenkavcic May 28, 2025
cd59b36
Address comments
tilenkavcic May 30, 2025
d86fce2
Don't capitalize titles in supported object types
tilenkavcic May 30, 2025
b7508d5
Add hint for integrating DevRev documentation into MCP server
tilenkavcic May 30, 2025
b6825a3
Introduce Chef UI, better explain fallbacks
tilenkavcic Jun 5, 2025
ef75077
Update fern/docs/pages/airdrop/initial-domain-mapping.mdx
tilenkavcic Jun 5, 2025
3c38923
Nits
tilenkavcic Jun 5, 2025
63880a2
Address comments
tilenkavcic Jun 9, 2025
2a909dd
frontend user-identity method (#232)
shalomgk May 30, 2025
4c27818
changed the position of note (#243)
AvinashSingh10-1 May 31, 2025
31296a4
chore: Update OpenAPI specs (#245)
bdbyrne Jun 2, 2025
03251e7
Point to customization API docs from identity SDK docs (#246)
shivansh Jun 4, 2025
33c6cf2
chore: Include 'Bearer' in authorization header documentation (#247)
bdbyrne Jun 4, 2025
a3da99f
Document `unit` and `is_read_only` customization UI hints (#248)
shivansh Jun 5, 2025
e65a82b
style rules for marketplace (#214)
bc-devrev Jun 5, 2025
eedd51c
add instructions for local instance (#171)
bc-devrev Jun 5, 2025
b4d0788
Update supported objects for Airdrop (#250)
arturo-aparicio Jun 5, 2025
8784be6
Merge branch 'main' into tilenk/fallbacks
tilenkavcic Jun 9, 2025
ec3938a
Merge branch 'main' into tilenk/fallbacks
tilenkavcic Jun 11, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 43 additions & 13 deletions fern/docs/pages/airdrop/initial-domain-mapping.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,29 +100,59 @@ You can now use the chef-cli web UI to create initial domain mappings.

## 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.
The chef-cli UI generates an `initial_domain_mapping.json` file that must be embedded in your extractor. This defines the options that the end-user will see when they are mapping the data.

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.
Initial domain mappings differ from user mappings in two key ways:

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.
1. **Multiple mapping options**: The developer can choose how external record types map to DevRev records (e.g., external *task* can map to either *issue* or *ticket*).
2. **Category-based defaults**: Mappings can apply to entire record type categories, automatically handling new record types.

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

### Map record types and fields

Use the chef-cli UI to map record types and fields.
The UI will show you the record types that are available in the org and allow you to map them to the external record types.
You should map one record type at a time.

### Specify fallback mappings

For most required DevRev fields we require a fallback. This is used on object creation if the extractor doesn't provide a value.

The fallback should be a DevRev value that is valid for the field.
For enum fields, the fallback should be the enum **value** as specified in [Supported object types](./supported-object-types.mdx).

### Install the blueprint

Click **Install in this org** to access the initial domain mapping creation screen.
Follow the instructions to create your initial domain mapping.

### Merge configurations

You can repeat the process for different record types and fields to create multiple mappings.
In the install screen, you can merge your mappings with existing initial mappings.

### Export the mapping file

When all fields are mapped correctly, click **Export** to download `initial_domain_mapping.json`.

</Steps>

### Advanced configuration

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 provide a local metadata file for enhanced functionality:

<Tip>
You can also provide a local metadata file to the command using the `-m` flag, for example:
```bash
chef-cli configure-mappings --env prod -m metadata.json
```

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.
This enables:
- Raw jq transformations using external fields as input (experimental)
- Example input data for testing transformations

In this case, it's not validated that the local file is the same as the one submitted by the snap-in.
</Tip>
<Warning>
The local metadata file is not validated against the snap-in submission.
</Warning>

### Test an import with initial mapping using the in-app UI

Expand Down
Loading
Loading