A newer version of this documentation is available.

View Latest

role()

      +

      Assigning Sync Gateway roles

      Related Topics:    access()   |   channel()   |   expiry()   |   requireAccess()   |   requireAdmin()   |   requireRole()   |   requireUser()   |   role()   |   throw()

      Function

      role(username, rolename)

      Purpose

      Use the role() function to add a role to a user. This indirectly gives them access to any channels assigned to that role.

      Roles, like users, have to be explicitly created by an administrator.

      Arguments

      Argument Description

      rolename

      Must be a string identifying a role, or an array of strings identifying multiple roles; the function is applied to each role in the array.

      If the value resolves to null the function result is a no-op.

      Note — Role names must always be prefixed with role:; an exception is thrown if a role name doesn’t conform with this rule..

      username

      Must be a string identifying a user, or an array of strings identifying multiple users; the function is applied to each user in the array.

      If the value resolves to null the function result is a no-op.

      Context

      This function affects the user’s ability to revise documents, if the access function requires role membership to validate certain types of changes. Its use is similar to access.

      Nonexistent roles don’t cause an error, but have no effect on the user’s access privileges.

      You can create roles retrospectively. As soon as a role is created, any pre-existing references to it take effect.

      Use

      Example 1. role(username, rolename)
      role ("jchris", "role:admin"); (1)
      role ("jchris", ["role:portlandians", "role:portlandians-owners"]); (2)
      role (["snej", "jchris", "traun"], "role:mobile"); (3)
      role ("ed", null);  (4)
      1 The role admin is assigned to the user
      2 Both the named roles are assigned to the user
      3 The role mobile is assigned to all the named users
      4 No op