Creating and Managing iMIS Groups in code
This article contains sample code and discussion of creating Groups via the iMIS .NET APIs.
Groups Overview
There are two kinds of groups in iMIS: Simple Groups and Detail Groups. Simple groups are, for lack of a better term, pretty simple: they are essentially a collection of contacts, each with a Join Date and (optional) Drop Date. Detail groups are similar to Simple Groups, but they add the concept of Roles; each Group Type can have a specific set of roles defined, and members within each group can have zero, one, or many roles within the group. Either group type can be used for iMIS security assignments.
Every group has a Group Type, which helps conceptually organize groups as well as indicate whether the group is a Simple or Detail group. Group Types are defined in the GroupTypeRef table. The "default" type of group displayed in the User Credential page, to which users can easily be added or removed, is the iMISModuleUsers type.
Creating a new Group
Groups themselves are stored in the GroupMain table. There are two methods to create a new Group: SQL or the iMIS .NET API. The API is generally recommended, when possible, because it helps insulate code from changes to the DB schema as well as manage some features (such as the Updated/Created information, etc) automatically. Performing SQL inserts/updates should be pretty straightforward: get the GroupTypeKey of the type of group from GroupTypeRef and insert a new row into GroupMain with that GroupTypeKey. To add/delete members, add/delete rows in GroupMember where the GroupKey is the GroupKey of the group's row in GroupMain and the MemberContactKey is the ContactKey (or UserKey; they are identical) of the vBoNetContact, ContactKey or UserMain row for that contact/user. Set the JoinDate to GETDATE() when inserting a new row; you can either delete the row entirely or set DropDate to remove a user from the group.
Note: changing the type of a group that has members may lead to unexpected behavior (especially if the group is changed from a Detail to a Simple Group, or from a Detail Group to another kind of Detail Group).
The .NET code to create a new Simple Group goes something like this. You'll need to add a reference to Asi.dll (from an application server's install) to compile the code.
BusinessContainer container = new BusinessContainer();
Guid groupTypeKey = Asi.Business.Common.GroupType.iMISModuleUsers;
GroupController controller = GroupController.NewGroupController(container);
Group newGroup = controller.Add(groupTypeKey);
newGroup.Name = "My New Group";
newGroup.Description = "Group for managing contacts";
newGroup.Commit();
At this point, the group exists in the GroupMain table and can be used in the Access Settings panel of objects to provide access.
Managing Contacts in a Group
Okay, so we have a group. Now we need to add contacts to that group. You can do this via the User Credential screen (since we defined our group as an iMIS Module Users group, it will show up in the Add dialog for the Groups list), but that's kind of tedious. Let's add all of the users of a chapter who aren't already in the group, to the group:
BusinessContainer container = new BusinessContainer();
Group chapterGroup = GroupController.GroupByName("My New Group", container);
string chapterName = "TRAVIS";
// NetContact doesn't have a typed controller, so we just use BusinessController
// Can't use CsContact because we need ContactKey.
BusinessController contactController = BusinessController.NewBusinessController("NetContact");
BusinessFilter[] filters = new BusinessFilter[] {
new BusinessFilter("MemberStatus", ComparisonType.Equal, "A"),
new BusinessFilter("Chapter", ComparisonType.Equal, chapterName),
};
DataRow[] rows = contactController.SelectWithFilter(filters, true);
if (rows != null && rows.Length > 0)
{
foreach (BusinessItem contact in rows)
{
Guid contactKey = contact.GetGuid("ContactKey");
if (!chapterGroup.IsActiveGroupMember(contactKey))
{
chapterGroup.AddGroupMember(contactKey);
}
}
chapterGroup.Commit();
}
Well, that wasn't bad. We can remove members from the group, too:
BusinessContainer container = new BusinessContainer();
Group chapterGroup = GroupController.GroupByName("My New Group", container);
BusinessController contactController = BusinessController.NewBusinessController("NetContact");
BusinessFilter[] filters = new BusinessFilter[] {
new BusinessFilter("MemberStatus", ComparisonType.Equal, "I"),
};
DataRow[] rows = contactController.SelectWithFilter(filters, true);
if (rows != null && rows.Length > 0)
{
foreach (BusinessItem contact in rows)
{
Guid contactKey = contact.GetGuid("ContactKey");
chapterGroup.RemoveGroupMember(contactKey);
}
chapterGroup.Commit();
}
Note that if you want to track member join/drop dates instead of actually deleting the membership, you can use the GroupMember BusinessController to set the Drop date; that will result in the user's membership being inactive after that date, but the information will remain in the database for tracking purposes.
Removing members
I found that I could not just call RemoveGroupMember (or RemoveAllMembers) and have it work.
What worked for me is the following:
group.BeginEdit();
group.RemoveGroupMember(contactKey);
group.EndEdit();
group.Commit();
Now, my group is associated with a ContentManagerAuthorityGroup, so I don't know if that makes a difference.
Regardless, I hope this helps someone else.
C