sitemap.xml llms.txt
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:

  • Validates that the required name property is provided.
  • Constructs a request body using the properties of the group parameter.
  • Executes a POST request to the /group endpoint.
  • Extracts and returns the body property of the HTTP response as a GroupReadOutView.
Function signature
export async function create(
    group: {
        name: string;
        capacity?: number;
        runLimit?: number;
        allowSelfRegistration?: boolean;
        allowMembershipChanges?: boolean;
        allowChannel?: boolean;
        perpetual?: boolean;
        demonstration?: boolean;
        startDate?: string;
        expirationDate?: string;
        terminationDate?: string;
        reference?: string;
        organization?: string;
        event?: string;
        salesChannel?: SalesChannel;
        status?: Status;
        pricing?: Pricing;
        flightRecorder?: FlightRecorderCreateInView;
    },
    optionals: RoutingOptions = {},
): Promise<GroupReadOutView>

Parameters​

  • group (Type: object): Properties of the new group:
    • name (string, required): Name of the group.
    • runLimit? (number): The maximum number of times that a user can run a simulation before the group expires.
    • organization? (string): The organization that runs the group. Could be different from the simulation creator/owner.
    • allowSelfRegistration? (boolean): If true, a user can register themselves. Otherwise, a new user must be invited by a facilitator.
    • flightRecorder? (FlightRecorderCreateInView): Flight recorder settings.
    • event? (string): Describes the associated event.
    • allowMembershipChanges? (boolean): If false, no member can be removed or added.
    • pricing? (Pricing): The price for the group membership for a user.
    • startDate? (Date): The date when the group event or activity will start.
    • expirationDate? (Date): Users can't register for the group or run the sim after this date.
    • capacity? (number): The maximum number of members allowed.
    • allowChannel? (boolean): If true, allow push notifications. If null, inherited from higher up (project).
  • optionals (Type: RoutingOptions): Additional routing options.

Return value​

A promise that resolves to a GroupReadOutView representing the newly created group.

Usage example​

import { groupAdapter } from 'epicenter-libs';

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 GET request URL based on the provided augment value:
    • /group/quantized/{GROUP_KEY}
    • /group/member/{GROUP_KEY}
    • /group/{GROUP_KEY}
  • Uses the groupKey parameter if provided. Otherwise, defaults to the user's session group key.
  • Returns the GroupReadOutView object.
Function signature
export async function get(
    optionals: {
        augment?: Augment;
        groupKey?: string;
    } & RoutingOptions = {},
): Promise<GroupReadOutView>

Parameters​

  • optionals (Type: { augment?: Augment; groupKey?: string } & RoutingOptions):
    • augment? (Augment) – Modifies the request URL:
      • 'MEMBERS' – Appends /member to the request URL to include group members.
      • 'QUANTIZED' – Appends /quantized to the request URL for a quantized view.
    • groupKey? (string) – Unique identifier of the group. If omitted, the current session’s group is used.
    • RoutingOptions – Additional routing options.

Return value​

A promise that resolves to a GroupReadOutView object.

Usage example​

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

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

// include metrics relating to the group in the response
const groupWithMetrics = await groupAdapter.get({
    groupKey: 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 GET request to the /group endpoint.
  • Supports an optional includeExpired flag to include expired groups.
  • Returns a list of GroupReadOutView objects.
Function signature
export async function gather(
    optionals: { includeExpired?: boolean } & RoutingOptions = {},
): Promise<GroupReadOutView[]>

Parameters​

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

Return value​

A promise that resolves to an array of GroupReadOutView 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 GroupReadOutView objects.
Function signature
export async function query(
    searchOptions: { quantized?: boolean } & GenericSearchOptions,
    optionals: RoutingOptions = {},
): Promise<Page<GroupReadOutView>>

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 GroupReadOutView 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:

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

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 GroupReadOutView.

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:

  • Accepts a user key and optional filters related to membership visibility and role.
  • Constructs search parameters such as includeExpired, includeAllMembers, and role.
  • Executes a GET request to the /group/member/for/{USER_KEY} endpoint.
  • Extracts and returns the body property of the HTTP response as a list of GroupReadOutView objects.
Function signature
export async function forUser(
    userKey: string,
    optionals: {
        includeAllMembers?: boolean;
        includeExpired?: boolean;
        role?: string | string[];
    } & RoutingOptions = {},
): Promise<GroupReadOutView[]>

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​

A promise that resolves to an array of GroupReadOutView 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 GroupReadOutView objects.
Function signature
export async function getSessionGroups(
    optionals: {
        includeAllMembers?: boolean;
        includeExpired?: boolean;
        role?: string | string[];
    } & RoutingOptions = {},
): Promise<GroupReadOutView[]>

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 GroupReadOutView 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 PATCH request to the /group/{GROUP_KEY} endpoint.
  • Updates one or more group attributes based on the provided fields.
  • Returns the updated GroupReadOutView object.
Function signature
export async function update(
    groupKey: string,
    update: {
        tombstone?: string;
        capacity?: number;
        runLimit?: number;
        perpetual?: boolean;
        salesChannel?: SalesChannel;
        reference?: string;
        organization?: string;
        event?: string;
        allowSelfRegistration?: boolean;
        allowMembershipChanges?: boolean;
        allowChannel?: boolean;
        demonstration?: boolean;
        startDate?: string;
        expirationDate?: string;
        terminationDate?: string;
        status?: Status;
        pricing?: Pricing;
        flightRecorder?: FlightRecorderUpdateInView;
    },
    optionals: RoutingOptions = {},
): Promise<GroupReadOutView>

Parameters​

  • groupKey (string) – The key of the group to update.
  • update (Type: object) – Attributes to update:
    • runLimit? (number): The maximum number of times that a user can run a simulation before the group expires.
    • organization? (string): The organization that runs the group. Could be different from the simulation creator/owner.
    • allowSelfRegistration? (boolean): If true, a user can register themselves. Otherwise, a new user must be invited by a facilitator.
    • flightRecorder? (FlightRecorderUpdateInView): Contains flight recorder settings.
    • event? (string): Describes the associated event.
    • allowMembershipChanges? (boolean): If false, no member can be removed or added.
    • pricing? (Pricing): The price for the group membership for a user.
    • startDate? (Date): The date when the group event or activity will start.
    • expirationDate? (Date): Users can't register for the group or run the sim after this date.
    • capacity? (number): The maximum number of members allowed.
    • allowChannel? (boolean): If true, allow push notifications. If null, inherited from higher up (project).
  • optionals (RoutingOptions): Additional routing options.

Return value​

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

Usage example​

import { groupAdapter } from 'epicenter-libs';

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​

import { groupAdapter } from 'epicenter-libs';

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/{GROUP_KEY}.
  • 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.
  • Extracts and returns the body property of the HTTP response as a GroupReadOutView.
Function signature
export async function statusUpdate(
    code: string,
    message: string,
    optionals: { groupKey?: string } & RoutingOptions = {},
): Promise<GroupReadOutView>

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 aGroupReadOutView representing the updated group.

Usage example​

import { groupAdapter } from 'epicenter-libs';

const group = await groupAdapter.statusUpdate(
    'active',
    'Group is currently active'
);

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/{GROUP_KEY}.
  • 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.
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​

Promise<void> when the request completes successfully.

Usage example​

import { groupAdapter } from 'epicenter-libs';

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 PseudonymReadOutView objects.
Function signature
export async function getWhitelistedUsers(
    groupKey: string,
    optionals: RoutingOptions = {},
): Promise<PseudonymReadOutView[]>

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​

import { groupAdapter } from 'epicenter-libs';

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:

  • Accepts either a single user or a list of users, each defined by a UserInput object.
  • Constructs a request to /group/member/{GROUP_KEY}.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Converts the usersInput parameter 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<GroupReadOutView>

Parameters​

  • usersInput (Type: UserInput | UserInput[]): a single user or an array of users to be added to the group. Each user is represented by a UserInput object.
  • 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 GroupReadOutView.

Usage example​

import { groupAdapter } from 'epicenter-libs';

// Add a single user by key
epicenter.groupAdapter.addUser('000001796733eef6492f4d6d960997016s9i');

// Add a user with role and availability
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​

The updateUser() function:

  • Determines the target group using the provided groupKey or the current session’s group key.
  • Executes a PATCH request to the /group/member/{GROUP_KEY}/{USER_KEY} endpoint.
  • Extracts and returns the body property of the HTTP response as a GroupReadOutView.
Function signature
export async function updateUser(
    userKey: string,
    update: {
        role?: string;
        available?: boolean;
    },
    optionals: { groupKey?: string } & RoutingOptions = {},
): Promise<GroupReadOutView>

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 GroupReadOutView.

Usage example​

import { groupAdapter } from 'epicenter-libs';

const group = await groupAdapter.updateUser(
    '000001796733eef0842f4d6d960997056d5t',
    { 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​

The removeUser() function:

  • Accepts a single user key or an array of user keys.
  • Executes a DELETE request to:
    • /group/member/{GROUP_KEY} if multiple users are being removed.
    • /group/member/{GROUP_KEY}/{USER_KEY} to remove a single user.
  • If groupKey is not provided, it defaults to the current session’s group key.
  • Returns Promise<void> on success.
Note

If multiple users are being removed, the user keys are sent in a query parameter.

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​

import { groupAdapter } from 'epicenter-libs';

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