Getting started with users and groups

Sometimes you may need to get or edit the data of a group or a user. This article describes common ways to work with users and groups using scripts.

Get the user object

You can get the user object to work with fields from a user’s profile or use methods that the user object provides. To do that, use the UserItemRef.fetch method.

    if (Context.data.user) {
\t\t// Getting user data using the `fetch()` method
        const userData = await Context.data.user.fetch();
    
        // Writing the user’s date of birth to a Date type field
        Context.data.birthDate = userData.data.birthDate;
\t}

Search for users

To find a user and write them to a variable, use the Users.search method that returns the UserSearch object.

Using the UserSearch method, you can request:

Number of search results Search.count.
First result in the search Search.first.
A page with search results Search.all. For a query divided into pages, use the following methods:
Search.from to define the number of items to skip from the start.
Search.size to define the number of results on a page (the maximum value is 10,000, the default is 10).
Search.sort to determine how results need to be sorted.

You can set up filtering using Search.where.

For example, you can find a user by their email address:

    /* Finding the user and writing them to a variable using the `search()` method
    with the `where()` filter */
    
    Context.data.user = await System.users.search().where(f => f.email.eq('admin@mail.com')).first();

Lock or unlock a user

Using a script, you can lock (UserItemRef.block) or unlock (UserItemRef.unblock) a user. For example, you can include locking a user in the employment termination business process.

async function blockUser(): Promise<void> {
    // You don’t need to request the user object to lock a user
    if (Context.data.user) {
        await Context.data.user.block();
    }
}

Get superiors of a user

To get superiors of a user, you can use the UserItemRef.getChiefs method.

    /* Getting a data array with all superiors of a user
    according to the org chart hierarchy */
    const chiefs = await ViewContext.data.user!.getChiefs();
    
    // Adding the user’s line manager (the first element of the array of superiors)
    ViewContext.data.superviser = chiefs[0];

To get a list of a user’s positions, use the UserItem.positions method. If a user doesn’t need to hold a position any longer, use the UserItem.removeFromPosition method to remove the user from a position.

    const user = await Context.data.user.fetch();
    // Getting the user’s positions
    const positions = await user.positions();
    // Finding the necessary position
    const requiredPosition = positions.find(p => p.data.name === \"Head of Marketing\");
    // Processing an error if the position is not found
    if(!requiredPosition) {
        throw new Error ('position not found');
    }
    // Removing the user from the position
    user.removeFromPosition(requiredPosition!);
    // Saving the user object
    await user.save();

Create a user, change user data, and save a user

To create a user (send an invitation using a script), change a user’s data, or save a user, use the System object. To send an invitation to a new user, you need to initialize them:

\tlet user = System.users.create();\t
\t
\t// Filling out user fields
    user.data.email = \"example@example.com\";
    user.data.fullname = {
        lastname: \"Johnson\",
        firstname: \"David\",
        middlename: \"Patrick\
    };
\t
\t// Saving the user object
    await user.save();

Search for user groups

You can find all user groups using the UserGroups.search method:

async function userMethods(): Promise<void> {

    // Assigning all groups in the system to a variable
    const group = await System.userGroups.search().size(10000).all();
}

Here is how you can find the “External users” group:

async function userMethods(): Promise<void> {

    // Assigning the “External users” group to a variable
    const group = await System.userGroups.search().where(f => f.__name.like('External users')).first();
}

The StringFieldOperand.like method is used to filter results by a String type field of a collection.

Get all users in a group and check whether a user belongs to a group

If a widget needs to be displayed only for users belonging to a certain group, you can use UserGroupItem.users and array.some().

    // Getting the current user
    const currUser = await System.users.getCurrentUser();
    // Searching for the group that we need to check
    const allowedGroup = await System.userGroups.search().where(a => a.__name.like('External users')).first();
    // Getting users from the group using the `users()` method
    const usersInAllowedGroup = await allowedGroup!.users();
    // Checking whether the current user is in the list
    if(usersInAllowedGroup.some(user => user.id === currUser.id)) {
        ViewContext.data.hideWidget = false;
    }

Get positions, parent groups, and child groups

All methods described in this sections return arrays.

The UserGroupItem.parentGroups method returns a list of groups that have the selected group as a child item.

const parentGroups = await group.parentGroups();

The UserGroupItem.positions method gets a list of positions included in a user group.

const groupName = 'Workspace administrators';
const group = await System.userGroups.search().where(g => g.__name.eq(groupName)).first();
const positions = await group.positions();

The UserGroupItem.subGroups method returns all child groups of a group.

const parentGroups = await group.subGroups();

Edit data and save a group

The UserGroupItem.save method allows you to save a user group. After you make changes to a group, you need to save it.

await NeededGroup.save();