Skip to main content

Group Functions

To manage Epicenter groups, use the functions exported by the Group adapter.

Importing the adapter​

To use the functions of the Group adapter, import it as shown:
import { groupAdapter } from 'epicenter-libs';

The groupAdapter namespace exports functions that make calls to the Group API.

learn more

For descriptions of the objects used by the Group adapter functions, read Group entities.

Create a group​

To create a group, use the create() function.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The create() function:

  • Constructs a request body with the property values of the group parameter.
  • Executes a POST request to the /group endpoint.
  • Extracts and returns the body property of the HTTP response as a Group object.
Function signature
export async function create(
    group: Group,
    optionals: RoutingOptions = {}
): Promise<Group>

Parameters​

Return value​

A promise that resolves to a Group object with the properties of the new group.

Usage example​

epicenter.groupAdapter.create({runLimit: 10, name: 'my-group-name'});

Retrieve groups​

These functions return a group or a list of groups.

Get group details​

To retrieve the details of a group by groupKey, use the get() function.

tip

To include a list of the group's members, set the augment parameter to 'MEMBERS'.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The get() function:

  • Constructs a request URL based on the provided augment value:
    • /group/quantized/{groupKey}
    • /group/member/{groupKey}
    • /group/{groupKey}
  • Uses the groupKey parameter if provided. Otherwise, defaults to the user's session group key.
  • Executes a GET request.
  • Extracts and returns the body property of the HTTP response as a Group object.
Function signature
export async function get(
    optionals: {
        augment?: keyof typeof AUGMENT,
        groupKey?: string,
    } & RoutingOptions = {}
): Promise<Group>

Parameters​

  • optionals (Type: { augment?: keyof typeof AUGMENT, groupKey?: string } & RoutingOptions = {}): An optional object that allows customization of the request. It includes:
    • augment (keyof typeof AUGMENT): an enum that identifies the URL.
      • AUGMENT.MEMBERS: Appends /member to the request URL to include group members.
      • AUGMENT.QUANTIZED: Appends /quantized to the request URL for a quantized view.
    • groupKey (string): the key identifying the group to retrieve. Defaults to the user's session group if not provided.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to a Group object.

Usage example​

import { authAdapter, groupAdapter } from 'epicenter-libs';
const session = authAdapter.getLocalSession();

// include members of the group in the response
const group = await groupAdapter.get(session.groupKey, { augment: 'MEMBERS' });

// include metrics relating to the group in the response
const group = await groupAdapter.get(session.groupKey, { augment: 'QUANTIZED' });

List groups for project​

Get an array of groups for a specific project, optionally including expired groups.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The gather() function:

  • Constructs a request URL with includeExpired as a query parameter if provided.
  • Executes a GET request to the /group endpoint.
  • Extracts and returns the body property of the HTTP response as an array of Group objects.
Function signature
export async function gather(
    optionals: { includeExpired?: boolean } & RoutingOptions = {}
): Promise<Group[]>

Parameters​

  • optionals (Type: { includeExpired?: boolean } & RoutingOptions = {}): an optional object that includes:

Return value​

A promise that resolves to an array of Group objects.

Usage example​

import { groupAdapter } from 'epicenter-libs';
const groups = await groupAdapter.gather();

Query for groups​

To search for groups based on specified filters, sorting options, and pagination settings, use the query() function. The response is paginated.

learn more

For reference on search filters, read Filter and sort syntax.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The query() function:

  • Constructs a request URL based on quantized selection.
  • Applies pagination options (first, max).
  • Executes a GET request to the /group/search or /group/quantized/search endpoint.
  • Extracts and returns the body property of the HTTP response as a paginated list of Group objects.
Function signature
export async function query(
    searchOptions: { quantized?: boolean } & GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Page<Group>>

Parameters​

  • searchOptions (Type: { quantized?: boolean } & GenericSearchOptions): an object defining search criteria. It includes:
    • quantized (boolean): If true, modifies the endpoint to /group/quantized/search for a quantized view.
    • filter (string[]): An array of filter parameters.
    • sort (string[]): An array of sorting parameters.
    • first (number): the starting index for pagination.
    • max (number): the maximum number of results to return.
  • optionals (Type: RoutingOptions = {}): an optional object providing a routing configuration.

Return value​

A promise that resolves to a paginated list of Group objects.

Usage example​

import { groupAdapter } from 'epicenter-libs';

const filter = [
     'name|=group1|group2',                              // look for groups whose name is 'group1' or 'group2'
     'groupKey=0000017dd3bf540e5ada5b1e058f08f20461',    // look for groups with the specific group key
     'approximateMemberCount>30',                        // look for groups larger than 30
     'startDate<2022-01-03T20:30:53.054Z',               // look for groups with start date before Jan 3rd 2022
     'expirationDate<2022-01-03T20:30:53.054Z',          // look for groups with expiration date before Jan 3rd 2022
];

groupAdapter.query({
     filter,
     sort: ['+group.name']   // sort all findings by group name ascending (lexigraphically)
     first: 3,               // page should start with the 4th item found (will default to 0)
     max: 10,                // page should only include the first 10 items
});

Retrieve a group by name​

To get the details of a group by its name, use the withGroupName() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The withGroupName() function:

  • Appends the group name to the endpoint: /group/with/{name}.
  • Executes a GET request to retrieve group details.
  • Extracts and returns the body property of the HTTP response as a Group object.
Function signature
export async function withGroupName(
    name: string,
    optionals: RoutingOptions = {}
): Promise<Group>

Parameters​

  • name (Type: string): the name of the group to retrieve.
  • optionals (Type: RoutingOptions = {}): an optional object providing a routing configuration.

Return value​

A promise that resolves to a Group object.

Usage example​

import { groupAdapter } from 'epicenter-libs';
epicenter.groupAdapter.withGroupName('my-group-name');

Get groups by user​

To retrieve a list of groups that a specific user belongs to, call the forUser() function.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The forUser() function:

  • Constructs a request URL based on the userKey parameter.
  • Includes optional filters such as includeExpired, includeAllMembers, and role.
  • Executes a GET request to the /group/member/for/{userKey} endpoint.
  • Extracts and returns the body property of the HTTP response as an array of Group objects.
Function signature
export async function forUser(
    userKey: string,
    optionals: {
        includeAllMembers?: boolean,
        includeExpired?: boolean,
        role?: string | string[],
    } & RoutingOptions = {},
): Promise<Group[]>

Parameters​

  • userKey (Type: string): the unique identifier of the user whose groups should be retrieved.
  • optionals (Type: { includeAllMembers?: boolean, includeExpired?: boolean, role?: string | string[] } & RoutingOptions = {}): an optional object allowing customization of the request. It includes:
    • includeAllMembers (boolean): If true, includes all members of the retrieved groups.
    • includeExpired (boolean): If true, includes expired groups in the response.
    • role (string | string[]): A role or list of roles to filter groups by user role.
    • A RoutingOptions object with a routing configuration can be included.

Return value​

Promise<Group[]>: a promise that resolves to an array of Group objects.

Usage example​

import { groupAdapter } from 'epicenter-libs';
epicenter.groupAdapter.forUser(
     '000001796733eef6492f4d6d960997016s9i', // get groups where this user is a member of
     { role: ['FACILITATOR'] }               // where this user is a facilitator in the group
);

List groups for session​

Retrieve groups associated with the current user session.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The getSessionGroups() function:

  • Constructs search parameters from the values of includeAllMembers, includeExpired, and role.
  • Executes a GET request to /group/member with the search parameters appended.
  • Extracts and returns the body property of the HTTP response as an array of Group objects.
Function signature
export async function getSessionGroups(
    optionals: {
        includeAllMembers?: boolean,
        includeExpired?: boolean,
        role?: string | string[],
    } & RoutingOptions = {},
): Promise<Group[]>

Parameters​

  • optionals (Type: { includeAllMembers?: boolean, includeExpired?: boolean, role?: string | string[] } & RoutingOptions = {}): an optional object allowing customization of the request. It includes:
  • includeAllMembers (boolean): If true, includes all members of the retrieved groups.
  • includeExpired (boolean): If true, includes expired groups in the response.
  • role (string | string[]): A role or list of roles to filter groups by user role.
  • RoutingOptions can be included: additional routing options.

Return value​

A promise that resolves to an array of Group objects.

Usage example​

import { groupAdapter } from 'epicenter-libs';
const groups = await epicenter.groupAdapter.getSessionGroups();

Update a group​

To update a group, call the update() function providing the groupKey. An admin role of OWNER, AUTHOR, or SUPPORT is required.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The update() function:

  • Constructs a request body with the property values of the update parameter.
  • Executes a PATCH request to the /group/{groupKey} endpoint.
  • Extracts and returns the body property of the HTTP response as a Group object.
Function signature
export async function update(
    groupKey: string,
    update: GroupUpdate,
    optionals: RoutingOptions = {}
): Promise<Group>

Parameters​

Return value​

A promise that resolves to a Group object with the properties of the updated group.

Usage example​

epicenter.groupAdapter.update('0000017dd3bf540e5ada5b1e058f08f20461', { event: 'Orientation Day' });

Delete a group​

To delete a group, call the destroy() function providing the groupKey. An admin role of OWNER, AUTHOR, or SUPPORT is required.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The destroy() function executes a DELETE request to the /group/{groupKey} endpoint.

Function signature
export async function destroy(
    groupKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters​

Return value​

A promise that resolves to a void.

Usage example​

epicenter.groupAdapter.destroy('0000017dd3bf540e5ada5b1e058f08f20461');

Update group status​

You can set two string properties for the group to inform facilitators about the group status during a simulation run:

  • code: A status code. Cannot contain any of these characters: 
    `$%^*()+={}[]|;'\"<>? \t\r\n
  • message: A status message. Cannot contain any of these characters: 
    `$%^*={}[]|;\"<>?\r\n

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The statusUpdate() function:

  • Executes a PATCH request to /group/status/{groupKey}.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Sends the code and message parameters in the body of the request.
Function signature
export async function statusUpdate(
    code: string,
    message: string,
    optionals: { groupKey?: string } & RoutingOptions = {}
): Promise<Group>

Parameters​

  • code (Type: string): the new status code. Cannot contain white space.
  • message (Type: string): the new status message.
  • optionals (Type: { groupKey?: string } & RoutingOptions = {}): an optional object that includes:
    • groupKey (string, optional): the unique identifier of the group. If not provided, the session’s group key is used.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to a Group object.

Managing group members​

These functions help you manage group membership.

Whitelist users​

Mark a list of user email addresses as allowed or disallowed for self-registration.

For this function call to be successful, the group has to have allowSelfRegistration set to true.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The whitelistUsers() function:

  • Constructs a request to /group/self/{groupKey}.
  • Sends a POST request containing allow and emails in the request body.
    • If allow is not provided, it defaults to true. To disallow self-registration, set allow to false.
    • If emails is not provided, it defaults to ['*'], meaning all users.
  • Extracts and returns the body property of the HTTP response.
Function signature
export async function whitelistUsers(
    groupKey: string,
    optionals: {
        allow?: boolean,
        emails?: string[]
    } & RoutingOptions = {}
): Promise<void>

Parameters​

  • groupKey (Type: string): the unique identifier of the group.
  • optionals (Type: { allow?: boolean, emails?: string[] } & RoutingOptions = {}):an optional object with the request parameters:
    • allow (boolean, default: true): Determines whether to allow (true) or deny (false) access to the specified users.
    • emails (string[], default: ['*']): A list of email addresses to be whitelisted. The default value ['*'], meaning all users.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves when the request completes successfully.

Usage example​

epicenter.groupAdapter.whitelistUsers('0000017dd3bf540e5ada5b1e058f08f20461', {
                                        allow: true, emails: ['user1@test.com', 'user2@test.com'],});

List whitelisted users​

The getWhitelistedUsers() function returns the whitelisted users for a group.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

The getWhitelistedUsers():

  • Sends a GET request to /group/self/{groupKey} endpoint.
  • Extracts and returns the body property of the HTTP response as an array of User objects.
Function signature
export async function getWhitelistedUsers(
    groupKey: string,
    optionals: RoutingOptions = {}
    ): Promise<User[]>

Parameters​

  • groupKey (Type: string): the unique identifier of the group whose whitelisted users should be retrieved.
  • optionals (Type: RoutingOptions = {}): additional routing options.

Return value​

A promise that resolves to an array of User objects containing the whitelisted users of the specified group.

Usage example​

epicenter.groupAdapter.getWhitelistedUsers('0000017dd3bf540e5ada5b1e058f08f20461');

Send group registration email​

To send a registration email to a user, call the sendRegistrationEmail() function.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The sendRegistrationEmail() function:

  • Constructs a request to /registration/self/{groupKey}.
  • Sends a POST request with email, linkURL, redirectURL, and subject in the request body. If linkURL, redirectURL, or subject is not provided, they are omitted.
Function signature
export async function sendRegistrationEmail(
    groupKey: string,
    email: string,
    optionals: {
        linkURL?: string,
        redirectURL?: string,
        subject?: string,
    } & RoutingOptions = {}
): Promise<void>

Parameters​

  • groupKey (Type: string): the unique identifier of the group.
  • email (Type: string): the email address of the of the registration email.
  • optionals (Type: { linkURL?: string, redirectURL?: string, subject?: string } & RoutingOptions = {}): an optional object allowing customization of the registration email request, including:
    • linkURL (string, optional): relative path for the link to complete the registration (<forio scheme>://<forio host>/app/<account>/<project><linkURL>).
    • redirectURL (string, optional): Relative path to redirect to after completing registration (<forio scheme>://<forio host>/app/<account>/<project><redirectURL>).
    • subject (string, optional): the subject line for the registration email.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to void when the registration email is successfully sent.

Usage example​

epicenter.groupAdapter.sendRegistrationEmail('0000017dd3bf540e5ada5b1e058f08f20461', 'user1@test.com', {
                                            redirectURL: '/login',
                                            linkURL: '/register',
                                            subject: 'Complete your registration!',
                                            });

Complete self-registration​

The selfRegister() function finalizes self-registration for a group after the user clicked the registration link in an email invitation.

Important

Requires the project to have deployment.autoCreatePlayer set to true.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The selfRegister() function:

  • Constructs a request to /registration/self/{token}.
  • Sends a PATCH request with password, displayName, givenName, familyName, and handle in the request body.
Function signature
export async function selfRegister(
    token: string,
    password: string,
    optionals: {
        displayName?: string,
        givenName?: string,
        familyName?: string,
        handle?: string,
    } & RoutingOptions = {}
): Promise<SelfRegistrationResult>

Parameters​

  • token (Type: string): a unique token used to identify and authenticate the self-registration request.
  • password (Type: string): the password to be set for the new user account.
  • optionals (Type: { displayName?: string, givenName?: string, familyName?: string, handle?: string } & RoutingOptions = {}): an optional object that includes:
    • displayName (string, optional): the user's display name.
    • givenName (string, optional): the user's first name.
    • familyName (string, optional): the user's last name.
    • handle (string, optional): the user handle for logging in.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to a SelfRegistrationResult object containing the details of the registered user.

Usage example​

epicenter.groupAdapter.selfRegister('myregistrationtoken', 'pass', {
   displayName: 'My Display Name',
   givenName: 'Leonard',
   familyName: 'Nimoy',
   handle: 'the_real_spock',
});

Add users to group​

To add one or multiple users to a group, call the addUser() function.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The addUser() function:

  • Constructs a request to /group/member/{groupKey}.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Converts usersInput into an array if a single user is provided.
  • Executes a POST request to add users to the specified group.
Function signature
export async function addUser(
    usersInput: UserInput | UserInput[],
    optionals: { groupKey?: string } & RoutingOptions = {}
):Promise<Group>

Parameters​

  • usersInput (Type: UserInput | UserInput[]): a single user or an array of users to be added to the group. Each user can be provided as:
    • A string representing the userKey.
    • An object of type UserInput, which includes:
      • userKey (string): The unique identifier for the user.
      • role (string, optional): The role assigned to the user. Defaults to PARTICIPANT.
      • available (boolean, optional): If true, the user can log in and be assigned to worlds. Defaults to true.
  • optionals (Type: { groupKey?: string } & RoutingOptions = {}): an optional object that includes:
    • groupKey (string, optional): the unique identifier of the group. If not provided, the session’s group key is used.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to a Group object.

Usage example​

epicenter.groupAdapter.addUser('000001796733eef6492f4d6d960997016s9i');

epicenter.groupAdapter.addUser([{
     userKey: '000001796733eef6492f4d6d960997016s9i',
     role: 'REVIEWER',
     available: false,
}]);

Update a group member​

To update a user's role and/or availability in a group, call the updateUser() function.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Extracts role and availability from the update object.
  • Constructs a request to /group/member/{groupKey}/{userKey}.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Executes a PATCH request to modify user details in the specified group.
Function signature
export async function updateUser(
    userKey: string,
    update: { role?: keyof typeof ROLE, available?: boolean },
    optionals: { groupKey?: string } & RoutingOptions = {}
):Promise<GroupPermission>

Parameters​

  • userKey (Type: string): the unique identifier of the user whose details are being updated.
  • update (Type: { role?: keyof typeof ROLE, available?: boolean }): an object specifying the updates to apply:
    • role (keyof typeof ROLE, optional): the new role to assign to the group member.
    • available (boolean, optional): if true, the user can log in and be assigned to worlds.
  • optionals (Type: { groupKey?: string } & RoutingOptions = {}): an optional that includes:
    • groupKey (string, optional): the unique identifier of the group. If not provided, the session’s group key is used.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to a GroupPermission object.

Usage example​

epicenter.groupAdapter.updateUser('000001796733eef6492f4d6d960997016s9i', { role: 'LEADER' });

Remove a group member​

To remove user(s) from a group, call the removeUser() function.

Permissions​

Requires a role of SUPPORT or higher.

Function description​

  • If multiple users are being removed, the request is sent with search parameters instead of a URI component.
  • Constructs a request to /group/member/{groupKey}/{userKey}.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Executes a DELETE request to remove users from the specified group.
Function signature
export async function removeUser(
    userKey: string | string[],
    optionals: { groupKey?: string } & RoutingOptions = {}
): Promise<void>

Parameters​

  • userKey (Type: string | string[]): a single user key or an array of user keys representing the users to be removed from the group.
  • optionals (Type: { groupKey?: string } & RoutingOptions = {}): an optional object allowing customization of the request. It includes:
    • groupKey (string, optional): The key of the group from which users will be removed. If not provided, the session’s group key is used.
    • RoutingOptions: additional routing options.

Return value​

A promise that resolves to void when the user(s) have been successfully removed from the group.

Usage example​

epicenter.groupAdapter.removeUsers('000001796733eef6492f4d6d960997016s9i');