DOCS-2248 add db.createRole() method

bin/builddata/htaccess-next.yaml

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

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

@@ -1,8 +1,8 @@
-# name: :method:`db.createRole()`
-# file: /reference/method/db.createRole
-# description: |
-#   Creates a role and specifies its privileges.
-# ---
+name: :method:`db.createRole()`
+file: /reference/method/db.createRole
+description: |
+  Creates a role and specifies its privileges.
+---
 # name: :method:`db.updateRole()`
 # file: /reference/method/db.updateRole
 # description: |

source/reference/command/createRole-field.yaml

@@ -1,3 +1,5 @@
+#content from this page is included in /reference/method/db.createRole-param.yaml
+#content from this page is included in /reference/method/db.createRole-role-field.yaml
 object:
   name: createRole
   type: dbcommand

source/reference/command/createRole.txt

@@ -45,8 +45,8 @@ Required Access
 Example
 -------
 
-The following is an example of the :dbcommand:`createRole` command that
-creates a role ``myClusterwideAdmin`` on the ``admin`` database:
+The following :dbcommand:`createRole` command creates the
+``myClusterwideAdmin`` role on the ``admin`` database:
 
 .. code-block:: javascript
 

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

@@ -0,0 +1,16 @@
+object:
+  name: db.createRole()
+  type: method
+field:
+  optional: false
+  type: param
+name: role
+type: document
+position: 1
+description: |
+  A document containing the name of the role and the role definition.
+---
+file: /reference/command/createRole-field.yaml
+name: writeConcern
+position: 2
+...

source/reference/method/db.createRole-role-field.yaml

@@ -0,0 +1,20 @@
+object:
+  name: db.createRole()
+  type: method
+field:
+  optional: false
+  type: field
+name: role
+type: string
+position: 1
+description: |
+  The name of the new role.
+---
+file: /reference/command/createRole-field.yaml
+name: privileges
+position: 2
+---
+file: /reference/command/createRole-field.yaml
+name: roles
+position: 3
+...

source/reference/method/db.createRole.txt

@@ -0,0 +1,69 @@
+===============
+db.createRole()
+===============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.createRole ( role, writeConcern )
+
+   Creates a role and specifies its privileges. The role applies to the
+   database on which you run the method. The :method:`db.createRole()`
+   method returns a *duplicate role* error if the role already exists in the
+   database.
+
+   The :method:`db.createRole()` method takes the following arguments:
+
+   .. include:: /reference/method/db.createRole-param.rst
+
+   The ``role`` document has the following form:
+
+   .. code-block:: javascript
+
+      { role: "<name>",
+        privileges: [ { resource: { <resource> },
+                        actions: [ "<action>", ... ]
+                      },
+                      ...
+                    ],
+        roles: [ { role: "<role>", db: "<database>" }, ... ]
+      }
+
+   The ``role`` document has the following fields:
+
+   .. include:: /reference/method/db.createRole-role-field.rst
+
+   .. |local-cmd-name| replace:: :method:`db.createRole()`
+   .. include:: /includes/fact-roles-array-contents.rst
+
+   The :method:`db.createRole()` method wraps the :dbcommand:`createRole`
+   command.
+
+Required Access
+---------------
+
+.. include:: /includes/access-create-role.rst
+
+Example
+-------
+
+The following :method:`db.createRole()` method creates the
+``myClusterwideAdmin`` role on the ``admin`` database:
+
+.. code-block:: javascript
+
+   use admin
+   db.createRole({ role: "myClusterwideAdmin",
+     privileges: [
+       { resource: { cluster: true }, actions: [ "addShard" ] },
+       { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
+       { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
+       { resource: { db: "", collection: "" }, actions: [ "find" ] }
+     ],
+     roles: [
+       { role: "read", db: "admin" }
+     ],
+     writeConcern: { w: "majority" , wtimeout: 5000 }
+   })