DOCS-16049-user-roles-modify-and-update (#4087)

* DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update * DOCS-16049-user-roles-modify-and-update --------- Co-authored-by: jason-price-mongodb <[email protected]>
mongodb · Jul 25, 2023 · 5e78ac6 · 5e78ac6
1 parent 0ad8ff5
commit 5e78ac6
Show file tree

Hide file tree

Showing 14 changed files with 263 additions and 6 deletions.
diff --git a/build/docs-tools b/build/docs-tools
diff --git a/source/includes/user-roles-system-variable-example-description-start.rst b/source/includes/user-roles-system-variable-example-description-start.rst
@@ -1,3 +1,2 @@
 To use a system variable, add ``$$`` to the start of the variable name.
-The ``USER_ROLES`` system variable is specified as ``$$USER_ROLES`` as
-shown in the following example.
+Specify the ``USER_ROLES`` system variable as ``$$USER_ROLES``.
diff --git a/source/includes/user-roles-system-variable-example-login-james.rst b/source/includes/user-roles-system-variable-example-login-james.rst
@@ -0,0 +1,5 @@
+Run:
+
+.. code-block:: javascript
+
+   db.auth( "James", "js008" )
diff --git a/source/includes/user-roles-system-variable-example-login-michelle.rst b/source/includes/user-roles-system-variable-example-login-michelle.rst
@@ -0,0 +1,5 @@
+Run:
+
+.. code-block:: javascript
+
+   db.auth( "Michelle", "me009" )
diff --git a/source/includes/user-roles-system-variable-examples-list.rst b/source/includes/user-roles-system-variable-examples-list.rst
@@ -1,4 +1,8 @@
-For examples that include ``USER_ROLES``, see the :ref:`find example
-<find-user-roles-system-variable-example>`, :ref:`aggregation example
-<setIntersection-user-roles-system-variable-example>`, and the
-:ref:`view example <create-view-user-roles-system-variable-example>`.
+For use cases that include ``USER_ROLES``, see the :ref:`find
+<find-user-roles-system-variable-example>`, :ref:`aggregation
+<setIntersection-user-roles-system-variable-example>`, :ref:`view
+<create-view-user-roles-system-variable-example>`, :ref:`updateOne
+<updateOne-example-user-roles-system-variable>`, :ref:`updateMany
+<updateMany-example-user-roles-system-variable>`, and
+:ref:`findAndModify <findAndModify-example-user-roles-system-variable>`
+examples.
diff --git a/source/includes/user-roles-system-variable-find-and-modify-example.rst b/source/includes/user-roles-system-variable-find-and-modify-example.rst
@@ -0,0 +1,28 @@
+Run:
+
+.. code-block:: javascript
+   :emphasize-lines: 12
+
+   // Attempt to find and modify document
+   db.medical.findAndModify( {
+      query:
+         { $and: [
+            {
+               // Only update the document for Mary Smith
+               patientName: { $eq: "Mary Smith" }
+            },
+            {
+               // User must have the Provider role to perform the update
+               $expr: { $ne: [ {
+                  $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
+               }, [] ] }
+            }
+         ]
+      },
+      // Update document
+      update: {
+         patientName: "Mary Smith",
+         diagnosisCode: "ACH 03",
+         creditCard: "6541-7534-9637-3456"
+      }
+   } )
diff --git a/source/includes/user-roles-system-variable-update-example-end.rst b/source/includes/user-roles-system-variable-update-example-end.rst
@@ -0,0 +1 @@
+The previous example does not update any documents.
diff --git a/source/includes/user-roles-system-variable-update-example-introduction.rst b/source/includes/user-roles-system-variable-update-example-introduction.rst
@@ -0,0 +1,80 @@
+Starting in MongoDB 7.0, you can use the new :variable:`USER_ROLES`
+system variable to return user :ref:`roles <roles>`.
+
+The example in this section shows updates to fields in a collection
+containing medical information. The example reads the current user roles
+from the ``USER_ROLES`` system variable and only performs the updates if
+the user has a specific role.
+
+.. include:: /includes/user-roles-system-variable-example-description-start.rst
+
+The example creates these users:
+
+- ``James`` with a ``Billing`` role.
+- ``Michelle`` with a ``Provider`` role.
+
+Perform the following steps to create the roles, users, and collection:
+
+.. procedure::
+   :style: normal
+
+   .. step:: Create the roles
+
+      Create roles named ``Billing`` and ``Provider`` with the required
+      privileges and resources.
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
+            collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
+         db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
+            collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
+
+   .. step:: Create the users
+
+      Create users named ``James`` and ``Michelle`` with the required
+      roles.
+
+      .. code-block:: javascript
+
+         db.createUser( {
+            user: "James",
+            pwd: "js008",
+            roles: [
+               { role: "Billing", db: "test" }
+            ]
+         } )
+
+         db.createUser( {
+            user: "Michelle",
+            pwd: "me009",
+            roles: [
+               { role: "Provider", db: "test" }
+            ]
+         } )
+
+   .. step:: Create the collection
+
+      Run:
+
+      .. code-block:: javascript
+
+         db.medical.insertMany( [
+            {
+               _id: 0,
+               patientName: "Jack Jones",
+               diagnosisCode: "CAS 17",
+               creditCard: "1234-5678-9012-3456"
+            },
+            {
+               _id: 1,
+               patientName: "Mary Smith",
+               diagnosisCode: "ACH 01",
+               creditCard: "6541-7534-9637-3456"
+            }
+         ] )
+
+Log in as as ``Michelle``, who has the ``Provider`` role, and perform an
+update:
diff --git a/source/includes/user-roles-system-variable-update-example-middle.rst b/source/includes/user-roles-system-variable-update-example-middle.rst
@@ -0,0 +1,7 @@
+The previous example uses :expression:`$setIntersection` to return
+documents where the intersection between the ``"Provider"`` string and
+the user roles from ``$$USER_ROLES.role`` is not empty. ``Michelle`` has
+the ``Provider`` role, so the update is performed.
+
+Next, log in as as ``James``, who does not have the ``Provider`` role,
+and attempt to perform the same update:
diff --git a/source/includes/user-roles-system-variable-update-many-example.rst b/source/includes/user-roles-system-variable-update-many-example.rst
@@ -0,0 +1,14 @@
+Run:
+
+.. code-block:: javascript
+   :emphasize-lines: 5
+
+   // Attempt to update many documents
+   db.medical.updateMany(
+      // User must have the Provider role to perform the update
+      { $expr: { $ne: [ {
+         $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
+      ] } },
+      // Update diagnosisCode
+      { $set: { diagnosisCode: "ACH 02"} }
+   )
diff --git a/source/includes/user-roles-system-variable-update-one-example.rst b/source/includes/user-roles-system-variable-update-one-example.rst
@@ -0,0 +1,14 @@
+Run:
+
+.. code-block:: javascript
+   :emphasize-lines: 5
+
+   // Attempt to update one document
+   db.medical.updateOne( {
+      // User must have the Provider role to perform the update
+      $expr: { $ne: [
+         { $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
+      ] } },
+      // Update diagnosisCode
+      { $set: { diagnosisCode: "ACH 01"} }
+   )
diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt
@@ -785,3 +785,36 @@ Use Variables in ``let``
       update: { flavor: "orange" },
       let: { targetFlavor: "cherry" }
    } )
+
+.. _findAndModify-example-user-roles-system-variable:
+
+User Roles and Document Updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/user-roles-system-variable-update-example-introduction.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``Michelle``
+
+      .. include:: /includes/user-roles-system-variable-example-login-michelle.rst
+
+   .. step:: Perform update
+
+      .. include:: /includes/user-roles-system-variable-find-and-modify-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-middle.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``James``
+
+      .. include:: /includes/user-roles-system-variable-example-login-james.rst
+
+   .. step:: Attempt to perform update
+
+      .. include:: /includes/user-roles-system-variable-find-and-modify-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-end.rst
diff --git a/source/reference/method/db.collection.updateMany.txt b/source/reference/method/db.collection.updateMany.txt
@@ -821,3 +821,36 @@ To view the indexes used, you can use the :pipeline:`$indexStats` pipeline:
 .. code-block:: javascript
 
    db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )
+
+.. _updateMany-example-user-roles-system-variable:
+
+User Roles and Document Updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/user-roles-system-variable-update-example-introduction.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``Michelle``
+
+      .. include:: /includes/user-roles-system-variable-example-login-michelle.rst
+
+   .. step:: Perform update
+
+      .. include:: /includes/user-roles-system-variable-update-many-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-middle.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``James``
+
+      .. include:: /includes/user-roles-system-variable-example-login-james.rst
+
+   .. step:: Attempt to perform update
+
+      .. include:: /includes/user-roles-system-variable-update-many-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-end.rst
diff --git a/source/reference/method/db.collection.updateOne.txt b/source/reference/method/db.collection.updateOne.txt
@@ -933,6 +933,39 @@ To view the indexes used, you can use the :pipeline:`$indexStats` pipeline:
 
    db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )
 
+.. _updateOne-example-user-roles-system-variable:
+
+User Roles and Document Updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/user-roles-system-variable-update-example-introduction.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``Michelle``
+
+      .. include:: /includes/user-roles-system-variable-example-login-michelle.rst
+
+   .. step:: Perform update
+
+      .. include:: /includes/user-roles-system-variable-update-one-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-middle.rst
+
+.. procedure::
+   :style: normal
+
+   .. step:: Log in as ``James``
+
+      .. include:: /includes/user-roles-system-variable-example-login-james.rst
+
+   .. step:: Attempt to perform update
+
+      .. include:: /includes/user-roles-system-variable-update-one-example.rst
+
+.. include:: /includes/user-roles-system-variable-update-example-end.rst
+
 .. seealso::
 
    To update multiple documents, see
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The previous example does not update any documents.