Domain Group

Configuration

Domain Groups maintain a configuration that you can adjust or consult as you create, update and query for them.

The following table presents you the configuration properties.

            <br/>
            <br/>

            Cloud CMS makes this available for use with such frameworks as Spring Security or Ruby on Rails
            where the list of authorities can be consulted to determine rights against specific controllers
            or services at invocation time.
        </td>
    </tr>
</tbody>

Create a Domain Group

You create a Domain Group by passing in a configuration object that contains, at minimum, the name of the group being created. The name of the group must be unique across all principals in the domain. You cannot have two groups with the same name in the same domain. Similarly, you cannot have a user and a group with the same name in the same domain.

Here is how you create a Domain Group:

// create a group domain.createGroup({ "name": "brewers" });

// we can also create a group using a more generalized method domain.createPrincipal({ "name": "brewers", "type": "group" });

<p>
    You can provide additional properties and also custom properties at the point of creation.
    Here is an example of you'd do that:
</p>

// assume we have a domain var domain = ...;

// create a group domain.createGroup({ "name": "brewers", "title": "The Milwaukee Brewers", "description": "American League Champions 1982", "league": "national" });

<h2 id="update">Update a Domain Group</h2>
<p>
    To update, all you have to do is make changes to your Domain Group and fire away.
</p>

// assume we have a domain group var group = ...;

// update group.set("league", "national"); group.update();

<p>
    You can update any property you'd like from the domain group except for the <code>type</code>.  You cannot
    switch a group into a user or vice-versa.  While both Domain Groups and Domain Users are Domain Principals,
    they're not interchangeable.
</p>




<h2 id="delete">Delete a Domain Group</h2>
<p>
    You can delete a Domain Group at any time provided that the group does not have any members.  An error
    will be raised if you attempt to delete a group that has members.
    <br/>
    <br/>
    Here is an example of group deletion:
</p>

group.del();

<h2 id="read">Read a Domain Group</h2>
<p>
    You can read a Domain Group by its <code>_doc</code> ID field.
</p>

// assume we have a domain var domain = ...;

// assume we have a group Id var groupId = "4b5b685c980c10f98beb";

domain.readPrincipal(groupId).then(function() { console.log("Found Domain Group with ID: " + this.getId()); });

<h2 id="list">List Domain Groups</h2>
<p>
    You can retrieve a list of Domain Groups for your domain quite easily.
    The following code hands back the full list.
</p>

domain.listGroups();

<p>
    You can then iterate over the list to pick at what you'd like.
</p>

domain.listGroups().each(function() { console.log("Domain User title: " + this.get("title")); });

<p>
    Retrieving the full list is potentially an expensive operation, depending how many items you have.
    The more your retrieve, the more data goes over the wire and so forth.  Thus, you might wish to
    <i>paginate</i> your call and retrieve a subset of the total list at a time.
    <br/>
    <br/>
    Here is an example that retrieves in pages of size 10.
    It starts on the second page (by skipping to starting index 20).
    It also sorts by the <code>title</code> field in a descending sequence.
</p>

domain.listGroups({ "limit": 10, "skip": 20, "sort": { "title": -1 } }).each(function() { console.log("Domain User title: " + this.get("title")); });

<p>
    You don't have to have all of the pagination parameters (<code>limit</code>, <code>skip</code> and <code>sort</code>).
    You might only want to include one or two.  It's up to you.
</p>




<h2 id="query">Query Domain Groups</h2>
<p>
    You can run custom queries against your Domain Groups to find exactly what you're looking for.
    Here is a query that looks for Domain Users which are disabled.
</p>

domain.queryGroups({ "league": "national" });

<p>
    Here is that same query followed by an iteration over the result map.
</p>

domain.queryGroups({ "league": "national" }).each(function(id) { console.log("Found an Domain Group: " + id + " with title: " + this.get("title")); });

<p>
    Finally, you can mix queries with pagination to reduce data over the wire and speed up performance.
    Here is that same query with some pagination thrown in.
    We limit to pages of size 10 and sort by <code>title</code>.
</p>

domain.queryGroups({ "league": "national" },{ "limit": 10, "skip": 20, "sort": { "title": -1 } }).each(function(id) { console.log("Found an Domain Group: " + id + " with title: " + this.get("title")); });

<h2 id="listmembers">List Members of a Group</h2>
<p>
    You can retrieve a list of the members of a group:
</p>

// assume we have a group var group = ...;

// retrieve a list of members group.listMembers().then(function() { console.log("Found a member: " + this.getId()); });

<p>
    You can also elect to filter to retrieve only the members of type <code>USER</code> or <code>GROUP</code>.
</p>

// assume we have a group var group = ...;

// retrieve a list of users group.listMembers("user").then(function() { console.log("Found a member: " + this.getId()); });

// retrieve a list of groups group.listMembers("group").then(function() { console.log("Found a member: " + this.getId()); });

<p>
    When you retrieve membership for a group, you can either retrieve direct membership (just those members
    who are direct first-level members of the group) or you can retrieve indirect membership.  Indirect
    memberships include principals who belong to intermediary groups which may belong to your group, at any
    depth in the hierarchy.
</p>

// assume we have a group var group = ...;

// all direct members group.listMembers(false).then(function() { console.log("Found a member: " + this.getId()); });

// all indirect members group.listMembers(true).then(function() { console.log("Found a member: " + this.getId()); });

// all indirect groups group.listMembers("group", true).then(function() { console.log("Found a member: " + this.getId()); });

<p>
    You can also take advantage of pagination on retrieval.  This reduces the payload of the requests and amount
    of data over the wire.  Pagination serves to make your applications more efficient.
</p>

// assume we have a group var group = ...;

// pagination var pagination = { "limit": 10, "skip": 20, "sort": { "title": -1 } };

// all indirect groups group.listMembers("group", true, pagination).then(function() { console.log("Found a member: " + this.getId()); });

<p>
    You may wish to use the following convenience functions when working with users or groups.
</p>

// assume we have a group var group = ...;

// list users group.listUsers().then(function() { console.log("Found a member: " + this.getId()); });

// list groups group.listUsers().then(function() { console.log("Found a member: " + this.getId()); });

// list all indirect groups group.listGroups(true, pagination).then(function() { console.log("Found a member: " + this.getId()); });

<p>
    You can also list membership from the domain directly:
</p>

// assume we have a domain var domain = ...;

// the group var groupId = "4b5b685c980c10f98bec";

// pagination var pagination = { "limit": 10, "skip": 20, "sort": { "title": -1 } };

// all indirect groups domain.listMembers(groupId, "group", true, pagination).then(function() { console.log("Found a member: " + this.getId()); });

<h2 id="addmember">Add Member to Group</h2>
<p>
    You can add a member to a group:
</p>

// assume we have a group var group = ...;

// assume we have a user var user = ...;

// add as a member group.addMember(user);

<p>
    You can also do this from the domain:
</p>

// assume we have a domain var domain = ...;

// assume we know what user and group we're interested in var groupId = "4b5b685c980c10f98bec"; var userId = "4b5b685c980c10f98beb";

domain.addMember(groupId, userId);

<h2 id="removemember">Remove Member from Group</h2>
<p>
    Or you can remove a member from a group:
</p>

// assume we have a group var group = ...;

// assume we have a user var user = ...;

// add as a member group.removeMember(user);

<p>
    You can also do this from the domain:
</p>

// assume we have a domain var domain = ...;

// assume we know what user and group we're interested in var groupId = "4b5b685c980c10f98bec"; var userId = "4b5b685c980c10f98beb";

domain.removeMember(groupId, userId);