Version: v4.5

IafUserGroup

Use the IafUserGroup API to create and manage user groups, user group invites, users, and user configs in the Passport and Item Service.

addAllAccess#

Give all access permissions to a UserGroup and its Users when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	The UserGroup object
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Permission - A Permission object with all access permissions.

Examples

const permission = await IafUserGroup.addAllAccess(userGroup);

addAllAccessToGroup#

Give all access permissions to a UserGroup and its users when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	Pass the UserGroup's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Permission - A Permission object with all access permissions.

Examples

const permission = await IafUserGroup.addAllAccessToGroup(userGroup._id);

addResourceByUserType#

Adds a resource of a given userType to a UserGroup.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
resource	Yes	Object	Pass the resource object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup -

Examples

const resource = {  _name: "example_project_workspace",    _shortName: "example_proj_ws",   _namespaces: "ProjB_HEpftR8X"};
const addedResource = await IafUserGroup.addResourceByUserType(userGroup, resource);

addUserConfigs#

Adds UserConfig class object's to a UserGroup when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
userConfigs	Yes	UserConfig	Pass a UserConfig object with the properties and values you want to define the user config.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Array<UserConfig> - The array of UserConfig objects you create.

Examples

const userConfigs = [  {    _name: "Project A setupe user config",    _shortName: "prjASetup",    _userType: "projectA_setup_userconfig"  },  {    _name: "Project B setupe user config",    _shortName: "prjBSetup",    _userType: "projectB_setup_userconfig"  }];
const userConfigs = await IafUserGroup.addUserConfigs(userGroup, userConfigs);

addUserConfigsToGroup#

Adds UserConfig class objects to a UserGroup when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	Pass the UserGroup's id.
userConfigs	Yes	Array<UserConfig>	Pass an array of UserConfig objects that contain the properties and values you want to define the user configuration.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Array<UserConfig> - The array of UserConfig objects you create.

Examples

const userConfigs = [  {    _name: "Project A setupe user config",    _shortName: "prjASetup",    _userType: "projectA_setup_userconfig"  },  {    _name: "Project B setupe user config",    _shortName: "prjBSetup",    _userType: "projectB_setup_userconfig"  }];
const createdUserGroups = await IafUserGroup.addUserConfigsToGroup(userGroup, userConfigs);

addUserToGroup#

Adds a User to an existing UserGroup when you pass a UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object you want to add the user to.
user	Yes	User	Pass a User object with the properties and values you want to define the user.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Array<User> - An array that contains only the added User object.

Examples

const updatedUserGroup = await IafUserGroup.addUserToGroup(userGroup, user);

addUserToGroupById#

Adds a User to an existing UserGroup when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id
user	Yes	User	The User object
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup -

Examples

const updatedUserGroup = await IafUserGroup.addUserToGroup(userGroup._id, user._id);

addUserToGroupByInvite#

Adds a User to a UserGroup when they accept the invite.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
invitation	Yes	Invite	Pass the Invite object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup -

Examples

await IafUserGroup.addUserToGroupByInvite(userGroup, invitation);

addUserToGroupByInviteId#

Invites a User to a UserGroup when you pass the Invite's id. The invitee is added to the user group when they accept the invite.

Parameter	Required	Type	Description
userGroupId	Yes	String	Pass the UserGroup's id.
invitationId	Yes	String	Pass the Invite's id.
ctx	Yes	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The UserGroup object

Examples

await IafUserGroup.addUserToGroupByInviteId(userGroup._id, invite._id);

cancelInvite#

Cancels a sent Invite to a UserGroup.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass a UserGroup object.
inviteId	Yes	String	Pass the id of the Invite you want to cancel.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<String> - {ok:204} response

Examples

const res = await IafUserGroup.cancelInvite(userGroup, invite._id);

create#

Creates a new UserGroup.

Parameter	Required	Type	Description
userGroup	Yes	Object	Pass a UserGroup JSON object with the properties and values you want to define the user group.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The created UserGroup object.

Examples

const userGroup = {  _name: "user_group_for_testing_purposes",  _shortName: "test_user_group",  _namespaces: "ProjA_HEpftR8X",  _userType: "example_user_group"};
const userGroup = await IafUserGroup.create(userGroup);

createUserGroupPermForUser#

Creates a Permission for a UserGroup for a User when you pass User and UserGroup objects.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object you want to give the User permissions to.
user	Yes	User	Pass a User object. You can pass a variable that points to the object, or an object that contains at least the "_id" property and value.
permission	Yes	Permission	Pass a Permission object with the properties and values you want to define the permsission.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Permission - The created Permission object

Examples

const permission = {   _actions: [ IafPermission.PermConst.Action.Read, IafPermission.PermConst.Action.Share, IafPermission.PermConst.Action.Delete ],   _namespace: userGroup._namespaces[0],};
const userGroupPerm = await IafUserGroup.createUserGroupPermissionForUser(userGroup, user, permission);

createUserGroupPermissionForUser#

Creates a UserGroup permission for a user when you pass the user and UserGroup ids.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id.
userId	Yes	String	The User's id.
permission	Yes	Permission	Pass a Permission object with the properties and values you want to define the user permsission.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Permission - The created Permission for a UserGroup.

Examples

const permission = {   _actions: [ IafPermission.PermConst.Action.Read, IafPermission.PermConst.Action.Share, IafPermission.PermConst.Action.Delete ],   _namespace: userGroup._namespaces[0],};
const userGroupPerm = await IafUserGroup.createUserGroupPermissionForUser(  userGroup._id,   currentUser._id,   permission);

delete#

Deletes a UserGroup when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	A UserGroup object. Pass either a variable that points to the object, or a UserGroup object that contains at least an "_id" property and value.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

String - 'ok: 204'

Examples

const result = await IafUserGroup.delete(userGroup);

deleteById#

Deletes a UserGroup when you pass its id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

String - 'ok: 204'

Examples

const result = await IafUserGroup.deleteById(userGroup._id);

deleteUserFromGroup#

Deletes a User from an UserGroup when you pass a UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object you want to add the user to.
user	Yes	User	Pass a User object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object without the user.

Examples

const updatedUserGroup = await IafUserGroup.deleteUserFromGroup(userGroup, user);

deleteUserFromUserGroup#

Deletes a User from an existing UserGroup when you pass a UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id.
user	Yes	User	The User object. Pass either a variable that points to the object, or a User object that contains at least an "_id" property and value.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object without the user.

Examples

const updatedUserGroup = await IafUserGroup.deleteUserFromUserGroup(userGroup._id, user);

get#

Gets a user group when you pass a UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object. Pass either a variable that points to the object, or a UserGroup object that contains at least an "_id" property and value.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The UserGroup object you request

Examples

const userGroup = await IafUserGroup.get(userGroup);

getById#

Gets a UserGroup when you pass the its id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The requested UserGroup object

Examples

const userGroup = await IafUserGroup.getById(userGroup._id);

getInvites#

Gets all the sent invites for a UserGroup.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	UserGroup object
criteria	Yes	InviteCriteria	Pass an InviteCriteria object to filter invites by status.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	InviteOptions	Pass an InviteOptions object to set the pagination, offset, and pagesize.

Returns

Promise<Page<Invite>> - A Page object with the Invite objects

Examples

let sentInvites = await IafUserGroup.getInvites(userGroup, criteria);

getResourcesByUserType#

Gets a UserGroup's resources that match the userType you pass.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass a UserGroup object.
userType	Yes	String	Pass the name of the userType that defines the resources you want to get.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Object - Returns the resource objects you request

Examples

const resources = await IafUserGroup.getResourcesByUserType(userGroup, "example_user_type");

getUserConfigs#

Gets a UserGroup's UserConfig objects when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
filters	No	Object	Pass a simple filter query.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Array<UserConfig> - Returns an array of the UserGroup's UserConfig.

Examples

const filters = { _userType: "example_user_config" };
const userConfigs = await IafUserGroup.getUserConfigs(userGroup, filters);

getUserConfigsInUserGroup#

Gets a UserGroup's UserConfig objects when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	Pass the UserGroup's id.
filters	No	Object	Pass a simple filter query.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserConfig - An array of the UserGroup's UserConfig objects.

Examples

let filters = { _shortName: "example_user_config" };
const userConfigs = await IafUserGroup.getUserConfigsInUserGroup(  userGroup._id,   filters);

getUserInvite#

Gets a Invite for a UserGroup invite when you pass the Invite's id.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass a UserGroup object.
invitation	Yes	Invite	Pass an Invite object. Pass either a variable that points to the object, or a Invite object that contains at least an "_id" property and value.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Invite - The Invite object

Examples

const userGroupInvite = await IafUserGroup.getUserInvite(userGroup, invitation);

getUserInviteById#

Gets an Invite for a User in a given UserGroup.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id
invitationId	Yes	String	The Invite id
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Invite - The Invite object

Examples

const userGroupInvite = await IafUserGroup.getUserInviteById(userGroup._id, invite._id);

getUsers#

Gets a UserGroup's User class object when you pass a UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	No	JSON	Pass a JSON object with the options parameters you want, such as "_offset", and "_pageSize".

Returns

Page<User> - A Page object with the User objects you request

Examples

const users = await IafUserGroup.getUsers(userGroup, ctx);

getUsersInGroup#

Gets a UserGroup's users when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id
ctx	No	Ctx	Context, such as namespaces and authentication token information.
options	Yes	JSON	Optional parameters such as _offset and _pageSize, which are by default 0 and 10 respectively

Returns

Array<User> - An array with the User objects you request

Examples

const users = await IafUserGroup.getUsersInGroup(userGroup._id, ctx);

hardDelete#

Hard deletes a UserGroup when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass a UserGroup object. Pass either a variable that points to the object, or a UserGroup object that contains at least an "_id" property and value.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

String - 'ok: 204' - set purge=true

Examples

const result = await IafUserGroup.hardDelete(userGroup);

inviteUsersToGroup#

Invites users by email to a UserGroup when you pass a UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	The UserGroup object.
data	Yes	Array<Invite>	Pass an array of Invite objects. Either define a new object or reference the "_id" value of an existing Invite object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Invite - Created Invite object

Examples

const data = [ { _email: "[email protected]" }, { _email: "[email protected]" } ];
const invites = await IafUserGroup.inviteUsersToGroup(userGroup, data);

inviteUsersToGroupById#

Invites users to a UserGroup when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id.
data	Yes	Array<Invite>	Pass an array of Invite objects. Either define a new object or reference the "_id" value of an existing Invite object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Invite - The Invite class object

Examples

const data = [ { _email: "[email protected]" }, { _email: "[email protected]" } ];
const invites = await IafUserGroup.inviteUsersToGroupById(userGroup._id, data);

rejectInvite#

Rejects a specific Invite to a UserGroup.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
inviteId	Yes	String	Pass the id of the Invite you want to reject.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

Promise<String> - {ok:204} response

Examples

const res = await IafUserGroup.rejectInvite(userGroup, invite._id);

removeResourceByUserType#

Removes a UserGroup resource of a given userType.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass a UserGroup object.
resource	Yes	Object	Pass the resource object.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - Returns the updated UserGroup object without the removed resource.

Examples

let resource = {  _name: "example_project_workspace",    _shortName: "example_proj_ws",   _namespaces: "ProjB_HEpftR8X"};
await IafUserGroup.removeResourceByUserType(userGroup, resource);

removeUserConfig#

Removes a UserConfig object from a UserGroup when you pass the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass the UserGroup object.
userConfig	Yes	UserConfig	Pass the UserConfig object you want to remove.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object without the UserConfig.

Examples

const updatedUsergroup = await IafUserGroup.removeUserConfig(userGroup, userConfig);

removeUserConfigInUserGroup#

Removes a UserConfig from a UserGroup when you pass the UserGroup's id.

Parameter	Required	Type	Description
userGroupId	Yes	String	Pass the UserGroup's id.
userConfigId	Yes	String	The UserConfig's id.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object without the UserConfig.

Examples

const updatedUsergroup = await IafUserGroup.removeUserConfigInUserGroup(userGroup._id, userGroup._id);

update#

Updates a UserGroup in the database when you pass an updated version of the UserGroup object.

Parameter	Required	Type	Description
userGroup	Yes	UserGroup	Pass an updated UserGroup object that maintains the correct "_id" property. The UserGroup object you pass overwrites the values of the stored user group.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object

Examples

const userGroup = {  _id: <user-group-id>,  _shortName: "updated_user_group",  _userType: "updated_user_group"};
const updatedUserGroup = await IafUserGroup.update(userGroup);

updateById#

Updates a UserGroup when you pass its id and an updated UserGroup object with the properties you want to update.

Parameter	Required	Type	Description
userGroupId	Yes	String	The UserGroup's id
userGroup	Yes	UserGroup	Pass a UserGroup object with the properties and values you want to update.
ctx	No	Ctx	Context, such as namespaces and authentication token information.

Returns

UserGroup - The updated UserGroup object

Examples

userGroup._userType = "updated_user_group";
const updatedUserGroup = await IafUserGroup.updateById(userGroup._id, userGroup);