Merge pull request #49 from ianf-mongodb/DOCSP-32370

DOCSP-32370 Add Field Customization Content

Author: mdb-ashley

config/redirects

@@ -1,6 +1,14 @@
-define: prefix docs/relational-migrator
-define: base https://www.mongodb.com/docs/
+define: prefix relational-migrator
+define: base https://www.mongodb.com/docs
 define: versions master
 
 # raw: <source file> -> ${base}/<destination>
 
+# Redirect calculated fields to new drawer introduced in DOCSP-32370 - Field Customizations
+# Field Customizations begin
+[*]: ${prefix}/mapping-rules/calculated-fields/calculated-fields -> ${base}/relational-migrator/mapping-rules/fields/calculated-fields/calculated-fields/
+[*]: ${prefix}/mapping-rules/calculated-fields/calculated-fields/add-calculated-fields -> ${base}/relational-migrator/mapping-rules/fields/calculated-fields/calculated-fields/add-calculated-fields
+[*]: ${prefix}/mapping-rules/calculated-fields/calculated-fields/view-calculated-fields -> ${base}/relational-migrator/mapping-rules/fields/calculated-fields/calculated-fields/view-calculated-fields
+[*]: ${prefix}/mapping-rules/calculated-fields/calculated-fields/edit-calculated-fields -> ${base}/relational-migrator/mapping-rules/fields/calculated-fields/calculated-fields/edit-calculated-fields
+[*]: ${prefix}/mapping-rules/calculated-fields/calculated-fields/delete-calculated-fields -> ${base}/relational-migrator/mapping-rules/fields/calculated-fields/calculated-fields/delete-calculated-fields
+# Field Customizations end

snooty.toml

@@ -19,7 +19,8 @@ toc_landing_pages = [
 "projects/projects",
 "mapping-rules/mapping-rules",
 "mapping-rules/mapping-rule-options/mapping-rule-options",
-"mapping-rules/calculated-fields/calculated-fields",
+"mapping-rules/fields/calculated-fields/calculated-fields",
+"mapping-rules/fields/field-customizations",
 "mapping-rules/synthetic-foreign-key/synthetic-foreign-keys",
 "table-filters/table-filters",
 "diagrams/diagrams",

source/img/mapping-rules/mapping-rule-edit-overview-2.png

@@ -0,0 +1,3 @@
+When defining :ref:`rm-calculated-fields` and :ref:`rm-id-field-customizations`, 
+Relational Migrator shows an initial data type of :guilabel:`default`. 
+When you run a sync job, Relational Migrator updates this data type.

source/includes/fact-calculated-fields-type.rst

@@ -18,30 +18,57 @@ effect the next time a sync job is run.
 About this Task
 ---------------
 
-Options available on the ``edit`` pane depend on the type of 
+Options available on the :guilabel:`edit` pane depend on the type of 
 mapping rule you are editing. For an overview of each mapping rule 
-option see:
+option, see:
 
 - :ref:`New Documents <rm-new-documents>`
-  
+
 - :ref:`Embedded Array <rm-embedded-array>`
 
 - :ref:`Embedded Documents <rm-embedded-documents>`
 
 Steps
 -----
 
-1. Open a project.
+#. From the :guilabel:`Mapping` screen, click a table or collection name
+   on the :guilabel:`Schema model` pane or :guilabel:`Diagram` view.
+
+#. From the :guilabel:`Mappings` pane, 
+   click the :icon-fa5:`pencil-alt` icon.
+
+#. Define the options for the mapping rule. When defining the 
+   mapping rule, you can:
+
+   - Change the collection name. 
+   - Change field names.
+   - Include or exclude a field from your sync job by clicking the
+     :icon-fa5:`check-square` icon next to the field name.
+
+#. Optionally, if you want to select a BSON type or set null handling 
+   rules for your mapping rule:
+
+   I. Click the :icon-fa5:`chevron-left` icon next to the field 
+      you want to customize.
+
+   II. Select a :guilabel:`BSON type`.
+
+   III. Select a :guilabel:`Null handling` option.
+
+   - :guilabel:`Insert as null`: preserves null values, and nulls 
+     are inserted into your destination collection.
+   - :guilabel:`Omit`: skips any null values, and nulls are not 
+     inserted into the destination collection.
 
-#. Click the ``Pencil`` icon to open the ``Edit mapping`` pane. 
+   You can view a field's :guilabel:`Original name` and 
+   :guilabel:`Original type` in the expanded customized field menu.
 
-#. Edit the mapping rule.
+   .. note::
 
-   .. image:: /img/mapping-rules/mapping-rule-edit-overview-2.png
-      :figwidth: 450 px
-      :alt: Mapping Rule Edit Overview
+      For additional details on field customization and data type conversions,
+      see :ref:`field customizations <rm-field-customizations>`.
 
-#. Click ``Save and close`` button to save your edits.
+#. Click :guilabel:`Save and close` to save your edits.
 
 Learn More
 ----------

source/mapping-rules/edit-rules.txt

@@ -34,11 +34,13 @@ About this Task
 Calculated field expressions access values from the current source
 database row using the syntax ``columns["<COLUMN_NAME>"]``.
 
+.. include:: /includes/fact-calculated-fields-type.rst
+
 Steps
 -----
 
 #. From the :guilabel:`Mapping` screen, click a table or collection name
-   on the :guilabel:`schema model` pane or diagram view.
+   on the :guilabel:`Schema model` pane or diagram view.
 
 #. Add a new mapping rule or edit an existing mapping rule.
 
@@ -57,6 +59,8 @@ Steps
 
 The new field is visible in MongoDB after your next sync job runs.
 
+.. _calculated-field-examples:
+
 Examples
 --------
 

source/mapping-rules/calculated-fields/add-calculated-fields.txt renamed to source/mapping-rules/fields/calculated-fields/add-calculated-fields.txt

@@ -60,7 +60,8 @@ Get Started
    :titlesonly:
    :hidden:
 
-   /mapping-rules/calculated-fields/add-calculated-fields
-   /mapping-rules/calculated-fields/view-calculated-fields
-   /mapping-rules/calculated-fields/edit-calculated-fields
-   /mapping-rules/calculated-fields/delete-calculated-fields
+   /mapping-rules/fields/calculated-fields/add-calculated-fields
+   /mapping-rules/fields/calculated-fields/view-calculated-fields
+   /mapping-rules/fields/calculated-fields/edit-calculated-fields
+   /mapping-rules/fields/calculated-fields/delete-calculated-fields
+   /mapping-rules/fields/calculated-fields/customized-id-fields

source/mapping-rules/calculated-fields/calculated-fields.txt renamed to source/mapping-rules/fields/calculated-fields/calculated-fields.txt

@@ -0,0 +1,61 @@
+.. _rm-id-field-customizations:
+
+====================
+Customize ID Fields
+====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+You can customize an ``_id`` field as part of your sync job.
+Customized ``_id`` fields allow you to change a field's BSON data type 
+and write custom JavaScript expressions instead of using a project's
+:ref:`Key Handling Option <rm-key-handling-setting>`.
+Customized ``_id`` fields **must** evaluate to a unique value.
+
+About this Task
+---------------
+
+- You may want to use customized ``_id`` fields to make your ``_id`` field
+  more expressive. For example, you can concatenate multiple fields to form
+  a unique ``_id``.
+
+- You can revert the custom ID changes at any time. The ``_id`` field 
+  returns to the project's :ref:`Key Handling Option <rm-key-handling-setting>`.
+
+Steps
+-----
+
+#. From the :guilabel:`Mapping` screen, click a table or collection name
+   on the :guilabel:`Schema model` pane or diagram view.
+
+#. From the :guilabel:`Schema model` pane, 
+   click the :icon-fa5:`pencil-alt` icon next to a mapping rule.
+
+#. Click the :icon-fa5:`ellipsis-v` icon next to the :guilabel:`_id` field
+   and select :guilabel:`Transform to calculated field`.
+
+#. (Optional) Select a :guilabel:`BSON type`.
+
+#. (Optional) Select a :guilabel:`Null handling` option.
+
+   - :guilabel:`Omit`: Null values are not inserted into your 
+     destination collection.
+   - :guilabel:`Insert as null`: Null values are inserted into the destination
+     collection. 
+
+#. Enter a valid JavaScript expression. For examples, see 
+   :ref:`valid JavaScript expressions<calculated-field-examples>`.
+
+#. Click :guilabel:`Done` and then click :guilabel:`Save and close`.
+
+
+Learn More
+----------
+
+- :ref:`rm-add-calculated-fields`
+- :ref:`rm-edit-calculated-fields`
+- :ref:`rm-view-calculated-fields`

source/mapping-rules/fields/calculated-fields/customized-id-fields.txt

@@ -28,7 +28,7 @@ Steps
 -----
 
 #. From the :guilabel:`Mapping` screen, click a table or collection name on the
-   :guilabel:`schema model` pane or diagram view.
+   :guilabel:`Schema model` pane or diagram view.
 
 #. Click the pencil icon next to the mapping rule you want to view.