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