DOCSP-30635 Mapping Rules migration (#24)

* DOCSP-30635 delete edit view

* DOCSP-30635 delete edit view

* DOCSP-30635 delete fix ref

* DOCSP-30635 rule relational mongodb

* DOCSP-30635 rule mongodb suggested

* DOCSP-30635 sfk

* DOCSP-30635 schema mapping

* DOCSP-30635 toc tree

* DOCSP-30635 nit fix

* DOCSP-30635 feedback updates

* DOCSP-30635 fix ref build error

* DOCSP-30635 fix ref build error

* DOCSP-30635 mapping rules

* DOCSP-30635 title fix

Author: jocelyn-mendez1

snooty.toml

@@ -18,6 +18,7 @@ toc_landing_pages = [
 "mapping-rules/mapping-rules",
 "mapping-rules/mapping-rule-options/mapping-rule-options",
 "mapping-rules/calculated-fields/calculated-fields",
+"mapping-rules/synthetic-foreign-key/synthetic-foreign-keys",
 "table-filters/table-filters",
 "diagrams/diagrams",
 "diagrams/navigate-diagrams/navigate-diagrams",
@@ -29,4 +30,4 @@ toc_landing_pages = [
 ]
 
 # [constants]
-# constant = "value"
+# constant = "value"

source/mapping-rules/delete-rules.txt

@@ -1,3 +1,59 @@
+.. _delete-rules: 
+
 ============
 Delete Rules
-============
+============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Deleting a mapping rule removes the mapping rule from your project. 
+Deleting a mapping rule does not remove existing collections from your 
+MongoDB cluster.
+
+To remove a collection from your cluster:
+
+- Delete the mapping rule in Relational Migrator. This avoids the collection 
+  being recreated by the next sync job.
+
+- Manually delete the MongoDB collection. This removes the collection from your 
+  cluster.
+
+About this Task
+---------------
+
+Deleting a parent mapping rule also deletes any child mapping rules.
+
+For example, if you delete a :guilabel:`New Documents` rule that defines a 
+collection and a :guilabel:`Array in Parent` rule for the same collection, the 
+:guilabel:`Array in Parent` rule is also deleted.
+
+Steps
+-----
+
+1. Open a project.
+
+#. In the left :guilabel:`Schema model` pane, click the table or collection
+   for the mapping you want to delete. 
+   
+   This prompts the :guilabel:`Mappings` pane to open on the right of the screen.
+
+#. On the :guilabel:`Mappings` pane, click the :guilabel:`Trash Can` icon.
+
+#. Click :guilabel:`Delete` to confirm.
+
+Learn More
+----------
+
+- :ref:`Create Rules From Relational <create-rule-relational>`
+
+- :ref:`Create Rules To MongoDB <create-rule-mongodb>`
+
+- :ref:`View mapping rules <view-rules>`
+
+- :ref:`Edit mapping rules <mapping-rules-edit>`

source/mapping-rules/edit-rules.txt

@@ -3,3 +3,55 @@
 ==========
 Edit Rules
 ==========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+You can update a mapping rule after it is created. Edited mapping rules take 
+effect the next time a sync job is run.
+
+About this Task
+---------------
+
+Options available on the ``edit`` pane depend on the type of 
+mapping rule you are editing. For an overview of each mapping rule 
+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.
+
+#. Click the ``Pencil`` icon to open the ``Edit mapping`` pane. 
+
+#. Edit the mapping rule.
+
+   .. image:: /img/mapping-rules/mapping-rule-edit-overview-2.png
+      :figwidth: 450 px
+      :alt: Mapping Rule Edit Overview
+
+#. Click ``Save and close`` button to save your edits.
+
+Learn More
+----------
+
+To learn more about managing mapping rules, see:
+
+- :ref:`Create Rules From Relational <create-rule-relational>`
+
+- :ref:`Create Rules To MongoDB <create-rule-mongodb>`
+
+- :ref:`Delete mapping rules <delete-rules>`
+
+- :ref:`View mapping rules <view-rules>`

source/mapping-rules/mapping-rules.txt

@@ -4,8 +4,79 @@
 Mapping Rules
 =============
 
+.. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
 
+A mapping rule specifies where data from each relational table should be
+migrated to and how the columns should be mapped to fields in 
+MongoDB documents. Mapping rules are created inside a project after you have provided a 
+valid :ref:`relational database connection string and credentials <rm-relational-database-connection-strings>`.
+
+Mapping Direction Preference
+----------------------------
+
+The source relational model is static and unchanging while the target MongoDB model
+is dynamic and customizable.
+
+You can create a mapping rule based on a source :ref:`relational model <create-rule-relational>`
+or based on a destination :ref:`MongoDB model <create-rule-mongodb>`.
+
+Relationships
+-------------
+
+Mapping rules help define a ``one-to-one``, ``one-to-many``, or ``many-to-many`` 
+relationship between your tables and collections.
+
+You can define mapping rules for the following configurations: 
+
+- A single table that maps to a single MongoDB collection. 
+
+- A single table that maps to multiple MongoDB collections. 
+
+- Multiple tables that map into a single collection.
+
+Default Rules
+-------------
+
+Relational Migrator automatically creates a :ref:`New Documents mapping rule <rm-new-documents>`
+for each source table. This initial rule produces a MongoDB schema that
+is identical to the relational database. You can edit the initial rule 
+before running any data migration jobs.
+
+Data Type Detection
+-------------------
+
+Relational Migrator automatically selects the best MongoDB data type for each 
+source column.
+
+For example, SQL Server source data of types ``text``, ``varchar``,
+``nvarchar`` or ``char``  will become the MongoDB ``string`` data type. 
+
+Migrate as Options
+------------------
+
+Mapping rules can be defined with the following ``Migrate as`` options:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Option
+     - Behavior
+
+   * - :ref:`Migrate rows as New Documents <rm-new-documents>`
+     - Translates each relational database row to a new document.
+
+   * - :ref:`Migrate rows as Embedded array <rm-embedded-array>`
+     - Translates each row into an array element within a parent document identified by a foreign key   
+       relationship.
+
+   * - :ref:`Migrate rows as Embedded documents <rm-embedded-documents>`
+     - Translates each row as a set of fields or an embedded object in a child document identified by a foreign key relationship.
 
 .. toctree::
    :titlesonly:
@@ -20,4 +91,4 @@ Mapping Rules
    /mapping-rules/delete-rules
    /mapping-rules/mapping-rule-options/mapping-rule-options
    /mapping-rules/calculated-fields/calculated-fields
-   /mapping-rules/synthetic-foreign-keys
+   /mapping-rules/synthetic-foreign-key/synthetic-foreign-keys

source/mapping-rules/new-rules-from-relational.txt

@@ -1,5 +1,62 @@
 .. _create-rule-relational:
 
-===========================
-Create Rule From Relational
-===========================
+============================
+Create Rules From Relational
+============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Creating mapping rules is how you translate your relational tables into
+MongoDB collections. You can create mapping rules from either the 
+:guilabel:`Relational` or :guilabel:`MongoDB` headers of the schema model pane.
+
+About this Task
+---------------
+
+Options available on the :guilabel:`Add mapping` pane depend on the type of 
+mapping rule you are adding. For a full overview of each mapping rule 
+option see:
+
+- :ref:`New Documents <rm-new-documents>`
+
+- :ref:`Embedded Array <rm-embedded-array>`
+
+- :ref:`Embedded documents <rm-embedded-documents>`
+
+You can also create mapping rules based on a destination MongoDB model. For more 
+information, see :ref:`Create Rules to MongoDB <create-rule-mongodb>`.
+
+Steps
+-----
+
+1. Open a project.
+
+#. In the left :guilabel:`Schema model` pane, click on a collection under the 
+   :guilabel:`MongoDB` header. 
+   
+   This prompts the :guilabel:`Mappings` pane to open on the right of the screen.
+
+#. On the :guilabel:`Mappings` pane, click :guilabel:`+ Add` to create a new mapping rule.
+
+#. Define the name of the target MongoDB collection.
+
+#. Define the options for the new mapping rule.
+
+#. Click :guilabel:`Save and close`.
+
+Learn More
+----------
+
+To learn more about managing mapping rules, see:
+
+- :ref:`Edit mapping rules <mapping-rules-edit>`
+
+- :ref:`Delete mapping rules <delete-rules>`
+
+- :ref:`View mapping rules <view-rules>`

source/mapping-rules/new-rules-suggested-mappings.txt

@@ -3,3 +3,76 @@
 ====================================
 Create Rules From Suggested Mappings
 ====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Relational Migrator can automatically suggest mapping rules based upon 
+your relational schema. Using suggested mappings can help you develop 
+your MongoDB data model faster.
+
+About this Task
+---------------
+
+In the :guilabel:`Mappings` pane, you have the option to either apply all the suggested 
+mapping rules, choose specific suggestions individually, or ignore all of the 
+suggested mapping rules. The :guilabel:`Suggested mappings` button remains visible, 
+allowing you to modify your selection at a later point.
+
+Before you Begin
+----------------
+
+- You need to enable :guilabel:`Suggested mappings` from the :guilabel:`Project Settings`. 
+  If you created a project with a recommended schema, the suggested mappings 
+  feature is disabled by default.
+
+- In order for Relational Migrator to generate suggested mappings for a specific 
+  table, you need to create a :ref:`New Documents <rm-new-documents>` 
+  mapping rule that maps the table to a collection. You can then select that 
+  collection to see the suggested mapping rules.
+
+Steps
+-----
+
+1. On the :guilabel:`Mapping` screen, click one of the following:
+
+   - A MongoDB collection on the :guilabel:`Schema model` pane.
+
+   - A collection on the MongoDB side of the project diagram.
+
+#. On the :guilabel:`Mappings` pane on the right-hand side of the screen, click 
+   the :guilabel:`Suggested mappings` button.
+   
+   The suggested mapping rules are generated from your relational schema.
+
+   .. note::
+
+      The suggested mapping rules display with a blue rectangle in the MongoDB diagram. 
+      These mapping rules are not added to your project until you click the 
+      :guilabel:`Apply` button.
+
+#. Deselect the suggested mapping rules you do not want applied to your MongoDB schema.
+
+#. Click the green :guilabel:`Apply` button at the bottom of the :guilabel:`Mappings` 
+   pane.
+
+   The suggested mapping rules are added to your project.
+
+Next Steps
+----------
+
+- :ref:`Create a Sync job <rm-create-jobs>`
+
+Learn More
+----------
+
+You can also manually create your mapping rules:
+
+- :ref:`Create Rules From Relational <create-rule-relational>`
+
+- :ref:`Create Rules To MongoDB <create-rule-mongodb>`