Merging Bulk Conversion Feature Branch (#171)

mmaville-mdb · web-flow · commit 39665451ccc3 · 2024-10-02T14:45:24.000-04:00
* DOCSP-43736-Bulk-Conversions-Task-Page (#168) * DOCSP-43736-Bulk-Conversions-Task-Page * Kicking off builds after changing Netlify settings (emprty commit) * Removing SQL learn more pointers, keeping it to relevant operations that apply to bulk actions. * Reordering links to match ToC. * Edits to address editorial feedback. * Internal formatting fix. * Expanding on selection step to line up with concurrent multiselection download work in separate PR. * Editorial and removing sentence that pertains mostly to inputting queries. * Adding new bulk conversion status include that modifies language to be more relevant and adds Pending status. * Adding ref to Filter topic. * Removing step for adding queries, as this is duplicated from individual query conversion. * Rewriting last steps to remove duplication and point to more relevant bulk conversion info. * Adding context to next step. * Editorial from internal feedback. * External feedback and some additional clarifications in the intro paragraph. * Editorial for Vale checks. Updating unrelated status file with similar editorial. * DOCSP-43748-Manage-Queries-Stub-Page-and-Tasks (#169) * DOCSP-43809: v1.10.0 Release Notes (#170) * DOCSP-43809-1-10-Release-notes * Editrial sweep for items in RN. * Editorial from Vale check. * General fixes and editorial from internal feedback. * Adding note for automatic deletion of migration indexes. * Minor editorial. * Updating release date. * Updating OpenSpec with generated output from application repo. * Revert "Updating OpenSpec with generated output from application repo." This reverts commit fc7cab3e0a2ceaf357ad1e65bf1599cd87e02eb7. * DOCSP-43748-Manage-Queries-Stub-Page-and-Tasks * Moving manage-queries.txt to correct directory. * Adding download task ref and content for single entry download. * Adding initial content for downloading multiple selections. * Adding description for Managing Queries page. * Modifying formatting for better visual feel. * Removing numbering from single-item steps. * Edits to address editorial feedback. * Modifying page title to match topic type. * Minor editorial from internal feedback round. * Speficying filters are by status and mentioning the name field conventions. * Moving management includes to separate tasks under Query Management page. * Renaming Manage Queries to Query Management. * Minor editorial. * Fixing new refs. * Simplifying Query Management page. * Adding Query Management to Snooty ToC Landing Pages. * Building out headings from conceptual template. * Editorial and building out task template headings. * Editorial and building out task template headings. * Update download-queries.txt * Update bulk-conversion.txt
diff --git a/snooty.toml b/snooty.toml
@@ -39,7 +39,8 @@ toc_landing_pages = [
 "jobs/prerequisites",
 "api-docs",
 "deployment-considerations",
-"code-generation/query-converter-test-queries"
+"code-generation/query-converter-test-queries",
+"code-generation/query-converter/query-management"
 ]
 
 [constants]
diff --git a/source/code-generation/query-converter.txt b/source/code-generation/query-converter.txt
@@ -25,5 +25,8 @@ your SQL code.
    Convert Stored Procedures </code-generation/query-converter/convert-stored-procedures>
    Convert Triggers </code-generation/query-converter/convert-triggers>
    Convert Views </code-generation/query-converter/convert-views>
+   Bulk Conversion </code-generation/query-converter/bulk-conversion>
+   Query Management </code-generation/query-converter/query-management>
    Refresh Database Objects </code-generation/query-converter/refresh-database-objects>
-   Test Queries </code-generation/query-converter-test-queries>
+   Test Queries </code-generation/query-converter-test-queries>
+   
diff --git a/source/code-generation/query-converter/bulk-conversion.txt b/source/code-generation/query-converter/bulk-conversion.txt
@@ -0,0 +1,103 @@
+.. _rm-bulk-conversion:
+
+===============
+Bulk Conversion
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Bulk query conversion allows you to convert many
+queries from a single UI action, avoiding the need to convert 
+each query individually. You can select and convert one 
+or more queries, stored procedures, triggers, and views in bulk 
+by enabling the multi-select toggle.
+
+Bulk conversions create a job that queues and executes each query 
+conversion in batches. You can view the status of an in-progress 
+bulk conversion or for individual queries in the 
+:guilabel:`Query Converter` pane.
+
+About this Task
+---------------
+
+.. include:: /includes/fact-query-converter-generic.rst
+
+- .. include:: /includes/fact-query-converter-disclaimer.rst
+
+- .. include:: /includes/fact-view-query-conversion-bulk-status.rst
+
+Steps
+-----
+
+.. procedure::
+   :style:  normal
+
+   .. step:: Navigate to the query converter pane
+
+      From the :guilabel:`Code Generation` tab, click the 
+      :guilabel:`Query Converter` pane.
+
+   .. step:: Enable multi-selection
+
+      Click the :guilabel:`Enable multi-selection` toggle to show the query 
+      selection pane.
+
+   .. step:: Select your conversions
+
+      - To include or exclude a query from your bulk conversion job,
+        click the :icon-fa5:`check-square` icon next to the field name.
+
+      - To include or exclude entire categories from your download,
+        click :icon-fa5:`check-square` next to the category name.
+
+      - To include or exclude queries by their current status, use 
+        the :ref:`Filter<rm-filter-queries>` to select a status.
+   
+   .. step:: Convert queries
+
+      Click the :guilabel:`Convert` button. Selected queries are 
+      queued for conversion and execute in batches. Total progress
+      of the conversion displays at the bottom-left of the page.
+         
+      - Individual query conversion status are displayed next to 
+        the query name.
+         
+      - The converted MongoDB syntax code can be viewed in the 
+        :guilabel:`Converted MongoDB Query` pane. 
+
+      - .. include:: /includes/fact-query-converter-failure-errors.rst
+
+      .. tip::
+
+         To stop a bulk conversion, click the red :guilabel:`Terminate` 
+         button in the lower-left corner of the screen and click the 
+         red :guilabel:`Terminate` button on the pop-up modal. Once a 
+         bulk job cancels, the bulk conversion status updates to 
+         ``Bulk convert job terminated``.
+
+   .. step:: (Optional) Provide feedback on the converted queries
+
+      Provide feedback on converted queries to help improve future query conversions.
+      To provide feedback, click the :icon-fa5:`thumbs-up` or :icon-fa5:`thumbs-down`
+      icon on the bottom right corner of the converted query panel. Then, you can 
+      provide feedback details and click :guilabel:`Submit`. 
+
+Next Steps
+----------
+
+After the queries have been converted, review them for 
+correctness before incorporating them into production code. You 
+can use the :ref:`Test Queries<rm-query-converter-test-bench>` 
+feature to help with validation.
+
+Learn More
+----------
+
+- :ref:`rm-convert-queries`
+- :ref:`rm-convert-stored-procedures`
+- :ref:`rm-convert-triggers`
+- :ref:`rm-convert-views`
diff --git a/source/code-generation/query-converter/query-management.txt b/source/code-generation/query-converter/query-management.txt
@@ -0,0 +1,34 @@
+.. _rm-manage-queries:
+
+================
+Query Management
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Relational Migrator provides various options for managing your 
+queries in Query Converter.
+
+Use Cases
+---------
+
+- Filter queries by name or status.
+- Download converted queries individually or in bulk.
+
+
+Get Started
+-----------
+
+- :ref:`rm-filter-queries`
+- :ref:`rm-download-queries`
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   Filter </code-generation/query-converter/query-management/filter-queries>
+   Download </code-generation/query-converter/query-management/download-queries>
diff --git a/source/code-generation/query-converter/query-management/download-queries.txt b/source/code-generation/query-converter/query-management/download-queries.txt
@@ -0,0 +1,89 @@
+.. _rm-download-queries:
+
+================
+Download Queries
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Download converted queries indivudually or in bulk to reduce effort 
+and avoid copying each result by hand.
+
+About this Task
+---------------
+
+- Individual queries are saved in a ``txt`` file.
+- Multiple queries are saved in a ``zip`` archive.
+
+Steps
+-----
+
+Individual Query
+~~~~~~~~~~~~~~~~
+
+.. procedure::
+   :style: normal
+
+   .. step:: Select your query
+
+      a. From the :guilabel:`Code Generation` tab, click the 
+         :guilabel:`Query Converter` pane.
+
+         .. note::
+
+            If you are not already logged into your Atlas account or have
+            an expired session, you must log in to proceed.
+
+      #. On the left-hand :guilabel:`Queries` pane, select a query, view,
+         or stored procedure.
+
+      #. If your query has not been converted, select a 
+         :guilabel:`Target Language` and click :guilabel:`Convert`
+         :icon-lg:`Sparkle`.
+
+   .. step:: Download the converted query
+
+      Click :icon-fa5:`download` to download the selected 
+      query conversion.
+
+Multiple Queries
+~~~~~~~~~~~~~~~~
+
+.. procedure::
+   :style:  normal
+
+   .. step:: Enable multi-selection
+
+      a. From the :guilabel:`Code Generation` tab, click the 
+         :guilabel:`Query Converter` pane.
+
+         .. note::
+
+            If you are not already logged into your Atlas account or have
+            an expired session, you must log in to proceed.
+
+      #. On the left-hand :guilabel:`Queries` pane, click the 
+         :guilabel:`Enable multi-selection` toggle to show the query 
+         selection pane.
+
+   .. step:: Select your queries
+
+      - To include or exclude a query from your download,
+        click :icon-fa5:`check-square` next to the field name.
+
+      - To include or exclude entire categories from your download,
+        click :icon-fa5:`check-square` next to the category name.
+
+
+   .. step:: Download selected query conversions
+
+      Click :icon-fa5:`download` to download the selected 
+      query conversions.
+
+Learn More
+----------
+- Test Queries </code-generation/query-converter-test-queries>
diff --git a/source/code-generation/query-converter/query-management/filter-queries.txt b/source/code-generation/query-converter/query-management/filter-queries.txt
@@ -0,0 +1,42 @@
+.. _rm-filter-queries:
+
+==============
+Filter Queries
+==============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Filter queries by text string or status to reduce amount of entries 
+displayed in the :guilabel:`query converter` pane.
+
+Steps
+-----
+
+.. procedure::
+   :style: normal
+
+   .. step:: Navigate to the query converter pane
+      
+      From the :guilabel:`Code Generation` tab, click the 
+      :guilabel:`Query Converter` pane.
+
+   .. step:: Enter or select a filter
+
+      Enter a text string to match against the query name in the 
+      :guilabel:`Filter` text box or click :icon-fa5:`ellipsis-v` 
+      to filter queries by their conversion status.
+
+      Manually input queries default to the full query syntax for 
+      the name field unless renamed at a later point.
+
+Next Steps
+----------
+- Convert Queries </code-generation/query-converter/convert-queries>
+- Convert Stored Procedures </code-generation/query-converter/convert-stored-procedures>
+- Convert Triggers </code-generation/query-converter/convert-triggers>
+- Convert Views </code-generation/query-converter/convert-views>
+- Bulk Conversion </code-generation/query-converter/bulk-conversion
diff --git a/source/includes/fact-query-converter-generic.rst b/source/includes/fact-query-converter-generic.rst
@@ -1,7 +1,7 @@
-- The query converter uses :abbr:`AI (Artificial Intelligence)` 
-  technology which may not be able to convert long or complex queries,
-  triggers, or stored procedures. Some queries may not be converted 
-  correctly while others may not be converted at all.
+- The query converter uses AI technology which may not be able to 
+  convert long or complex queries, triggers, or stored procedures. 
+  Some queries may not be converted correctly while others may not 
+  be converted at all.
 
 - The query converter uses the relational schema, the MongoDB schema,  
   and the mapping rules in your current project to determine how the 
@@ -12,4 +12,4 @@
 - Converted queries, triggers, views, and stored procedures are saved in 
   your project and persist through project import and exports.
 
-- SQL queries are limited to 10,000 text characters.
+- SQL queries are limited to 40,000 text characters.
diff --git a/source/includes/fact-view-query-conversion-bulk-status.rst b/source/includes/fact-view-query-conversion-bulk-status.rst
@@ -0,0 +1,22 @@
+You can view the status of your conversions in the left-hand 
+:guilabel:`Query Converter` pane. Each conversion has an icon 
+indicating the status of the conversion. If an object does not have 
+an icon next to it, it was not queued for bulk conversion:
+
+.. list-table::
+   :header-rows: 1
+   
+   * - Icon 
+     - Description
+
+   * - Static circle
+     - The conversion is pending.
+
+   * - Spinner
+     - The conversion is now being executed.
+
+   * - Green check mark
+     - The conversion was successful.
+
+   * - Red exclamation mark
+     - The conversion failed on last attempt.
diff --git a/source/includes/fact-view-query-conversion-history.rst b/source/includes/fact-view-query-conversion-history.rst
@@ -10,10 +10,10 @@ an icon next to it, a conversion has not been attempted yet:
      - Description
 
    * - Spinner
-     - The conversion is currently being executed.
+     - The conversion is now being executed.
 
    * - Green check mark
      - The conversion was successful.
 
    * - Red exclamation mark
-     - The conversion failed on last attempt.
+     - The conversion failed on last attempt.

Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,8 @@ toc_landing_pages = [`
`39`	`39`	`"jobs/prerequisites",`
`40`	`40`	`"api-docs",`
`41`	`41`	`"deployment-considerations",`
`42`		`-"code-generation/query-converter-test-queries"`
	`42`	`+"code-generation/query-converter-test-queries",`
	`43`	`+"code-generation/query-converter/query-management"`
`43`	`44`	`]`
`44`	`45`
`45`	`46`	`[constants]`