DOCS-2246 add updateUser method

source/includes/access-update-user.rst

@@ -0,0 +1,16 @@
+To update the :data:`~admin.system.users.roles` array, a user must have
+access that includes the :authaction:`revokeRole` action on all
+databases. To add roles in an update, a user must have access that
+includes the :authaction:`grantRole` action on the database where
+the role exists.
+
+To modify their own ``pwd`` or :data:`~admin.system.users.customData`
+fields, users must have access that includes the
+:authaction:`changeOwnPassword` action and
+:authaction:`changeOwnCustomData` action respectively on the
+``cluster`` resource.
+
+To change another user's ``pwd`` or ``customData`` field, a user must
+have access that includes the :authaction:`changeAnyPassword` action
+and :authaction:`changeAnyCustomData` action respectively on that
+user's database.

source/reference/command/updateUser-field.yaml

@@ -1,4 +1,6 @@
-object:
+#content from this file is included in /reference/method/db.updateUser-param.yaml
+#content from this file is included in /reference/method/db.updateUser-doc-field.yaml
+ object:
   name: updateUser
   type: dbcommand
 field:

source/reference/command/updateUser.txt

@@ -9,15 +9,19 @@ Definition
 
 .. dbcommand:: updateUser
 
+   .. Defines a |local-cmd-name| replacement:
+   .. |local-cmd-name| replace:: :dbcommand:`updateUser`
+
    Updates the user's profile on the database on which you run the
    command. An update to a field **completely replaces** the previous
    field's values, including updates to the user's ``roles`` array.
 
    .. warning::
 
       When you update the ``roles`` array, you completely replace the
-      previous array's values. To add roles without replacing the user's
-      existing roles, use the :dbcommand:`grantRolesToUser` command.
+      previous array's values. To add or remove roles without replacing all
+      the user's existing roles, use the :dbcommand:`grantRolesToUser` or
+      :dbcommand:`revokeRolesFromUser` commands.
 
    The :dbcommand:`updateUser` command uses the following syntax. To
    update a user, you must specify the ``updateUser`` field and at least
@@ -39,49 +43,39 @@ Definition
 
    .. include:: /reference/command/updateUser-field.rst
 
-   .. |local-cmd-name| replace:: :dbcommand:`updateUser`
-   .. include:: /includes/fact-roles-array-contents.rst
-
 Considerations
 --------------
 
 .. _updateUser-pwd-field-consideration:
 
-:dbcommand:`updateUser` sends password to the MongoDB instance in
+``pwd`` Field
+~~~~~~~~~~~~~
+
+:dbcommand:`updateUser` sends the password to the MongoDB instance in
 cleartext. To encrypt the password in transit, use :doc:`SSL
 </tutorial/configure-ssl>`.
 
-Required Access
----------------
+``roles`` Field
+~~~~~~~~~~~~~~~
 
-To update the :data:`~admin.system.users.roles` array, a user must have
-access that includes the :authaction:`revokeRole` action on all
-databases. To add roles in an update, a user must have access that
-includes the :authaction:`grantRole` action on the database where
-the role exists.
+.. include:: /includes/fact-roles-array-contents.rst
 
-To modify their own ``pwd`` or :data:`~admin.system.users.customData`
-fields, users must have access that includes the
-:authaction:`changeOwnPassword` action and
-:authaction:`changeOwnCustomData` action respectively on the
-``cluster`` resource.
+Required Access
+---------------
 
-To change another user's ``pwd`` or ``customData`` field, a user must
-have access that includes the :authaction:`changeAnyPassword` action
-and :authaction:`changeAnyCustomData` action respectively on that
-user's database.
+.. include:: /includes/access-update-user.rst
 
 Example
 -------
 
-Given a user ``Erin`` in the ``products`` database with the following
+Given a user ``appClient01`` in the ``products`` database with the following
 user info:
 
 .. code-block:: javascript
 
    {
-      "_id" : "products.Erin",
-      "user" : "Erin",
+      "_id" : "products.appClient01",
+      "user" : "appClient01",
       "db" : "products",
       "customData" : { "empID" : "12345", "badge" : "9156" },
       "roles" : [
@@ -100,26 +94,26 @@ user's ``customData`` and ``roles`` data:
 .. code-block:: javascript
 
    use products
-   db.runCommand( { updateUser : "Erin",
+   db.runCommand( { updateUser : "appClient01",
                     customData : { employeeId : "0x3039" },
                     roles : [
-                              { role : "read", db : "assets"  }
+                              { role : "read", db : "assets"  } 
                             ]
                 } )
 
-The user ``Erin`` in the ``products`` database now has the following
+The user ``appClient01`` in the ``products`` database now has the following
 user information:
 
 .. code-block:: javascript
 
    {
-      "_id" : "products.Erin",
-      "user" : "Erin",
+      "_id" : "products.appClient01",
+      "user" : "appClient01",
       "db" : "products",
       "customData" : { "employeeId" : "0x3039" },
       "roles" : [
           { "role" : "read",
             "db" : "assets"
           }
       ]
-   }
+   }

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

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

source/reference/method/db.updateUser.txt

@@ -0,0 +1,122 @@
+===============
+db.updateUser()
+===============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.updateUser ( username, update, writeConcern )
+
+   .. |local-cmd-name| replace:: :method:`db.updateUser()`
+
+   Updates the user's profile on the database on which you run the method.
+   An update to a field **completely replaces** the previous field's values.
+   This includes updates to the user's ``roles`` array.
+
+   .. warning::
+
+      When you update the ``roles`` array, you completely replace the
+      previous array's values. To add or remove roles without replacing all
+      the user's existing roles, use the :method:`db.grantRolesToUser()` or
+      :method:`db.revokeRolesFromUser()` methods.
+
+   The :method:`db.updateUser()` method has the following arguments.
+
+   .. include:: /reference/method/db.updateUser-param.rst
+
+   The ``update`` document specifies the fields to update new values. All
+   fields in the ``update`` document are optional, but the document must
+   include at least one.
+
+   The ``update`` document has the following structure:
+
+   .. code-block:: javascript
+
+      { customData: { <any information> },
+        roles: [
+          { role: "<role>", db: "<database>" } | "<role>",
+          { ... },
+        ]
+      }
+
+   The <update document> has the following fields:
+
+   .. include:: /reference/method/db.updateUser-doc-field.rst
+
+   The :method:`db.updateUser()` method wraps the :dbcommand:`updateUser`
+   command.
+
+Considerations
+--------------
+
+``pwd`` Field
+~~~~~~~~~~~~~
+
+:method:`db.updateUser()` sends the password to the MongoDB instance in
+cleartext. To encrypt the password in transit, use :doc:`SSL
+</tutorial/configure-ssl>`.
+
+``roles`` Field
+~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-roles-array-contents.rst
+
+Required Access
+---------------
+
+.. include:: /includes/access-update-user.rst
+
+Example
+-------
+
+Given a user ``appClient01`` in the ``products`` database with the following
+user info:
+
+.. code-block:: javascript
+
+   {
+      "_id" : "products.appClient01",
+      "user" : "appClient01",
+      "db" : "products",
+      "customData" : { "empID" : "12345", "badge" : "9156" },
+      "roles" : [
+          { "role" : "readWrite",
+            "db" : "products"
+          },
+          { "role" : "read",
+            "db" : "inventory"
+          }
+      ]
+   }
+
+The following :method:`db.updateUser()` method **completely** replaces the
+user's ``customData`` and ``roles`` data:
+
+.. code-block:: javascript
+
+   use products
+   db.updateUser( { "appClient01",
+                    customData : { employeeId : "0x3039" },
+                    roles : [
+                              { role : "read", db : "assets"  } 
+                            ]
+                } )
+
+The user ``appClient01`` in the ``products`` database now has the following
+user information:
+
+.. code-block:: javascript
+
+   {
+      "_id" : "products.appClient01",
+      "user" : "appClient01",
+      "db" : "products",
+      "customData" : { "employeeId" : "0x3039" },
+      "roles" : [
+          { "role" : "read",
+            "db" : "assets"
+          }
+      ]
+   }