DOCS-2246 add updateRole method

bin/builddata/htaccess-next.yaml

@@ -609,6 +609,14 @@ redirect-path: '/reference/method/db.revokePrivilegesFromRole'
 url-base: '/reference/security'
 type: 'redirect'
 code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/reference/method/db.updateRole'
+url-base: '/reference/security'
+type: 'redirect'
+code: 303
 outputs:
   - 'manual'
   - 'before-v2.4'

source/includes/access-update-role.rst

@@ -0,0 +1,18 @@
+A user must have the :authaction:`revokeRole` :ref:`action
+<security-user-actions>` on all databases in order to update a role.
+
+A user must have the :authaction:`grantRole` :ref:`action
+<security-user-actions>` on the database of each role in the ``roles`` array
+to update the array.
+
+A user must have the :authaction:`grantRole` action on the database of each
+privilege in the ``privileges`` array to update the array. If a privilege's
+resource spans databases, the user must have :authaction:`grantRole` on the
+``admin`` database. A privilege spans databases if the privilege is any of
+the following:
+
+- a collection in all databases
+
+- all collections and all database
+
+- the ``cluster`` resource

source/includes/ref-toc-method-role-management.yaml

@@ -3,11 +3,11 @@
 # description: |
 #   Creates a role and specifies its privileges.
 # ---
-# name: :method:`db.updateRole()`
-# file: /reference/method/db.updateRole
-# description: |
-#   Updates a user-defined role.
-# ---
+name: :method:`db.updateRole()`
+file: /reference/method/db.updateRole
+description: |
+  Updates a user-defined role.
+---
 name: :method:`db.dropRole()`
 file: /reference/method/db.dropRole
 description: |

source/reference/command/updateRole-field.yaml

@@ -1,3 +1,4 @@
+#content from this page is included in /reference/method/db.updateRole-update-fields.yaml
 object:
   name: updateRole
   type: dbcommand

source/reference/command/updateRole.txt

@@ -9,33 +9,43 @@ Definition
 
 .. dbcommand:: updateRole
 
-   Updates the role on the database on which you run the command. An
-   update to a field **completely replaces** the previous field's
-   values.
+   Updates a ref:`user-defined role <user-defined-roles>`. The
+   :dbcommand:`updateRole` command must run on the role's database.
+
+   An update to a field **completely replaces** the previous field's values.
+   To grant or remove roles or privileges without replacing all values, use
+   one or more of the following commands:
+
+   - :command:`grantRolesToRole`
+   - :command:`grantPrivilegesToRole`
+   - :command:`revokeRolesFromRole`
+   - :command:`revokePrivilegesFromRole`
 
    .. warning::
 
-      When you update the ``privileges`` or ``roles`` arrays, you
-      completely replace the previous array's values. To add roles
-      without replacing the existing roles, use the
-      :dbcommand:`grantRolesToRole` command.
+      An update to the ``privileges`` or ``roles`` array
+      completely replaces the previous array's values.
 
    The :dbcommand:`updateRole` command uses the following syntax. To
    update a role, you must provide the ``privileges`` array, ``roles``
    array, or both:
 
    .. code-block:: javascript
 
-      { updateRole: "<role>",
-        privileges: [
-          { resource: { <resource> }, actions: [ "<action>", ... ] },
-          ...
-        ],
-        roles: [
-          { role: "<role>", db: "<database>" },
-          ...
-        ],
+      {
+        updateRole: "<role>",
+        privileges:
+            [
+              { resource: { <resource> }, actions: [ "<action>", ... ] },
+              ...
+            ],
+        roles:
+            [
+              { role: "<role>", db: "<database>" },
+              ...
+            ],
         writeConcern: <write concern document>
+      }
 
    The :dbcommand:`updateRole` command has the following fields:
 
@@ -47,20 +57,7 @@ Definition
 Required Access
 ---------------
 
-To run the :dbcommand:`updateRole` command, a user must have privileges
-that include the :authaction:`revokeRole` action on all databases,
-as well as:
-
-- To update the ``roles`` array, a user must have privileges that
-  include the :authaction:`grantRole` action on the database for
-  every role in the updated array.
-
-- To update the ``privileges`` array, a user must have
-  :authaction:`grantRole` on the database for each privilege in the
-  updated array. If the resource for the privilege is a collection in
-  all databases, or all collections and all database, or the
-  ``cluster`` resource, you must have :authaction:`grantRole` on
-  the ``admin`` database.
+.. include:: /includes/access-update-role.rst
 
 Example
 -------
@@ -72,13 +69,20 @@ the two is required:
 
 .. code-block:: javascript
 
-   { updateRole: "myClusterwideAdmin",
-     privileges: [
-       { resource: { db: "", collection: "" },
-         actions: [ "find" , "update", "insert", "remove" ] }
-     ],
-     roles: [
-       { role: "dbAdminAnyDatabase", db: "admin" }
-     ],
-     writeConcern: { w: "majority" , wtimeout: 5000 }
+   {
+     updateRole: "myClusterwideAdmin",
+     privileges:
+         [
+           {
+             resource: { db: "", collection: "" },
+             actions: [ "find" , "update", "insert", "remove" ]
+           }
+         ],
+     roles:
+         [
+           { role: "dbAdminAnyDatabase", db: "admin" }
+         ],
+     writeConcern: { w: "majority" }
    }
+
+To view a role's privileges, use the :dbcommand:`rolesInfo` command.

source/reference/method/db.updateRole-param.yaml

@@ -0,0 +1,28 @@
+object:
+  name: db.updateRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: rolename
+type: string
+position: 1
+description: |
+  The name of the role to update.
+---
+object:
+  name: db.updateRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: update
+type: document
+position: 2
+description: |
+  A document containing the role data to replace with new data.
+---
+file: /reference/command/updateRole-field.yaml
+name: writeConcern
+position: 3
+...

source/reference/method/db.updateRole-update-fields.yaml

@@ -0,0 +1,8 @@
+file: /reference/command/updateRole-field.yaml
+name: privileges
+position: 1
+---
+file: /reference/command/updateRole-field.yaml
+name: roles
+position: 2
+...

source/reference/method/db.updateRole.txt

@@ -0,0 +1,103 @@
+===============
+db.updateRole()
+===============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.updateRole( rolename, update, writeConcern )
+
+   Updates a ref:`user-defined role <user-defined-roles>`. The
+   :method:`db.updateRole()` method must run on the role's database.
+
+   An update to a field **completely replaces** the previous field's values.
+   To grant or remove roles or privileges without replacing all values, use
+   one or more of the following methods:
+
+   - :method:`db.grantRolesToRole()`
+   - :method:`db.grantPrivilegesToRole()`
+   - :method:`db.revokeRolesFromRole()`
+   - :method:`db.revokePrivilegesFromRole()`
+
+   .. warning::
+
+      An update to the ``privileges`` or ``roles`` array completely replaces
+      the previous array's values.
+
+   The :method:`updateRole()` method uses the following syntax:
+
+   .. code-block:: javascript
+
+      db.updateRole(
+          "<rolename>",
+          {
+            privileges:
+                [
+                  { resource: { <resource> }, actions: [ "<action>", ... ] },
+                  ...
+                ],
+            roles:
+                [
+                  { role: "<role>", db: "<database>" },
+                  ...
+                ]
+          },
+          { <writeConcern> }
+      )
+
+   The :method:`db.updateRole()` method takes the following arguments.
+
+   .. include:: /reference/method/db.updateRole-param.rst
+
+   The ``update`` document specifies the fields to update and the new
+   values. Each field in the ``update`` document is optional, but the
+   document must include at least one field. The ``update`` document has the
+   following fields:
+
+   .. include:: /reference/method/db.updateRole-update-fields.rst
+
+   .. |local-cmd-name| replace:: :method:`db.updateRole()`
+   .. include:: /includes/fact-roles-array-contents.rst
+
+   The :method:`db.updateRole()` method wraps the :dbcommand:`updateRole`
+   command.
+
+Required Access
+---------------
+
+.. include:: /includes/access-update-role.rst
+
+Example
+-------
+
+The following :method:`db.updateRole()` method replaces the
+:data:`~admin.system.roles.privileges` and the
+:data:`~admin.system.roles.roles` for the ``inventoryControl`` role. The
+method runs on the database that contains ``inventoryControl``:
+
+.. code-block:: javascript
+
+   db.updateRole(
+       "inventoryControl",
+       {
+         privileges:
+             [
+               {
+                 resource: { db:"products", collection:"clothing" },
+                 actions: [ "update", "createCollection", "createIndex"]
+               }
+             ],
+         roles:
+             [
+               {
+                 role: "read",
+                 db: "products"
+               }
+             ]
+       },
+       { w:"majority" }
+   )
+
+To view a role's privileges, use the :dbcommand:`rolesInfo` command.