docs: ISS-179977, Add documentation for mapping custom objects and custom links

fern/docs/pages/airdrop/initial-domain-mapping.mdx

@@ -100,29 +100,65 @@ 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.
+
+#### Mapping as custom object
+The system allows importing record types and categories as custom objects. To achieve this you have to select `new_custom_object` when mapping the record type. For each external record type mapped as a custom object, a new custom **Leaf type** will be defined in DevRev and a **Subtype** will automatically be created. For more details on customization concepts, please refer to the
+[Customization](../customization.mdx) and [Custom Objects](../custom-objects.mdx)  documentation.
+
+The field mapping works the same as for the stock DevRev types, with the difference being that there are significantly fewer fields to map. All the unmapped fields of the external record type will be created as custom fields.
+
+### 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
 

fern/docs/pages/airdrop/metadata-extraction.mdx

@@ -506,4 +506,61 @@ be changed by the end user at any time, such as mandatory fields or custom field
   - The `starting_stage` defines the initial stage for new object instances. This data should always be provided if available, otherwise the starting stage is selected alphabetically.
   - In current metadata format (v0.2.0), the order and human-readable name are taken from the enum values defined on the controlling field.
   - If the `states` field is not provided, default DevRev states are used: `open`, `in_progress`, and `closed`.
+
+  ### Declare custom link types
+
+  External record types that represent links between other record types can be imported as ***custom links***, which means that each delcared link type will be recreated in DevRev with the same names. This allows closer preservation of the original data without the need to map the links to DevRev's predefined link types.
+
+  To achieve this, the external record type needs to have an enum field defined that represents the link types and you need to declare a special field called `link_naming_data` in the record type. 
+
+  ```json
+  {
+    "fields": {
+        "type": {
+            "name": "Link Type",
+            "is_required": true,
+            "type": "enum",
+            "enum": {
+                "values": [
+                    {
+                        "key": "1",
+                        "name": "Parent Of"
+                    },
+                    {
+                        "key": "2",
+                        "name": "Related"
+                    },
+                    {
+                        "key": "3",
+                        "name": "Blocks"
+                    }
+                ]
+            }
+        }
+    },
+    "link_naming_data": {
+        "link_type_field": "type",
+        "link_direction_names": {
+            "1": {
+                "forward_name": "Parent of",
+                "backward_name": "Child of"
+            },
+            "2": {
+                "forward_name": "Relates To",
+                "backward_name": "Relates To"
+            },
+            "3": {
+                "forward_name": "Blocks",
+                "backward_name": "Is Blocked By"
+            }
+        }
+    }
+  }
+  ```
+
+  In the above example:
+  - The external *type* field is declared as the `link_type_field`.
+  - The `link_direction_names` provide a mapping of each value in the `link_type_field` to their directional names. `forward_name` and `backward_name` can be the same, but both are required.
+  - In current metadata format (v0.2.0), the human-readable name of the link type is taken from the enum values defined on the `link_type_field`. The linkable object types in DevRev will be defined based on the mappings of the *source_id* and *target_id* [fields](./supported-object-types.mdx#custom_link#).
+
 </Steps>