Security Bulk Update via API

2024-03-29

Creation and updates of security groups and role assignments may be scripted and performed automatically using the LabKey Security API. New user IDs are automatically created as needed.

Bulk Update

Operations available:

  • Create and Populate a Group
  • Ensure Group and Update, Replace, or Delete Members
Group members can be specified in one of these ways:
  • email - specifies a user; if the user does not already exist in the system, it will be created and will be populated with any of the additional data provided
  • userId - specifies a user already in the system. If the user does not already exist, this will result in an error message for that member. If both email and userId are provided, this will also result in an error.
  • groupId - specifies a group member. If the group does not already exist, this will result in an error message for that member.
public static class GroupForm
{
private Integer _groupId; // Nullable; used first as identifier for group;
private String _groupName; // Nullable; required for creating a group
private List<GroupMember> _members; // can be used to provide more data than just email address; can be empty;
// can include groups, but group creation is not recursive
private Boolean _createGroup = false; // if true, the group should be created if it doesn't exist;
//otherwise the operation will fail if the group does not exist
private MemberEditOperation _editOperation; // indicates the action to be performed with the given users in this group

}

public enum MemberEditOperation {
add, // add the given members; do not fail if already exist
replace, // replace the current members with the new list (same as delete all then add)
delete, // delete the given members; does not fail if member does not exist in group;
//does not delete group if it becomes empty
};

Sample JSON

{
‘groupName’: ‘myNewGroup’,
‘editOperation’: ‘add’,
‘createGroup’: ‘true’,
‘members’: [
{‘email’ : ‘me@here.org’, ‘firstName’:’Me’, ‘lastName’:’Too’}
{‘email’ : ‘you@there.org’, ‘firstName’:’You’, ‘lastName’:’Too’}
{‘email’ : ‘@invalid’, ‘firstName’:’Not’, ‘lastName’:’Valid’},
{‘groupId’ : 1234},
{‘groupId’: 314}
]

}

If you want to provide only the email addresses for user members, it would look like this:

{
‘groupName’: ‘myNewGroup’,
‘editOperation’: ‘add’,
‘createGroup’: ‘true’,
‘members’: [
{‘email’ : ‘me@here.org’}
{‘email’ : ‘you@there.org’}
{‘email’ : ‘invalid’}
]
}

A response from a successful operation will include the groupId, groupName, a list of users that were added to the system, lists of members added or removed from the group, as well as a list of members if any, that had errors:

{
‘id’: 123,
‘name’: ‘myNewGroup’,
‘newUsers’ : [ {email: ‘you@there.org’, userId: 3123} ],
‘members’ : {
‘added’: [{‘email’: ‘me@here.org’, ‘userId’: 2214}, {‘email’: ‘you@there.org’, ‘userId’: 3123},
{‘name’: ‘otherGroup’, ‘userId’ : 1234}],
‘removed’: []
}
‘errors’ :[
‘invalid’ : ‘Invalid email address’,
‘314’ : ‘Invalid group id. Member groups must already exist.’
]
}

This mimics, to a certain degree, the responses from the following actions:

  • CreateGroupAction, which includes in its response just the id and name in a successful response
  • AddGroupMemberAction, which includes in its response the list of ids added
  • RemoveGroupMemberAction, which includes in its response the list of ids removed
  • CreateNewUserAction, which includes in its response the userId and email address for users added as well as a possible message if there was an error

Error Reporting

Invalid requests may have one of these error messages:
  • Invalid format for request. Please check your JSON syntax.
  • Group not specified
  • Invalid group id <id>
  • validation messages from UserManager.validGroupName
  • Group name required to create group
  • You may not create groups at the folder level. Call this API at the project or root level.
Error message for individual members include, but may not be limited to:
  • Invalid user id. User must already exist when using id.
  • Invalid group id. Member groups must already exist.
  • messages from exceptions SecurityManager.UserManagementException or InvalidGroupMembershipException