Work with Users and Groups

Look up users, manage group membership, and assign users and groups to space roles.

HAPI gives you three modules for working with people: users for looking up and managing user accounts, groups for group membership, and roles for space roles. They are often used together, for example to find a user and then add them to a role.

Pattern for working with users and groups with HAPI

The pattern is the same for all three modules:

Import the module or modules you need.
Call the function inside an exported async function.
Pass an account ID for a user, a group name for a group, and a space key with a role name for a role.

import * as Users from '@scriptrunnerhq/hapi/users'
import * as Groups from '@scriptrunnerhq/hapi/groups'
import * as Roles from '@scriptrunnerhq/hapi/roles'

export default async function () {
  // Find the current user and the groups they belong to
  const me = await Users.getCurrent()
  const groups = await Users.getGroups(me.accountId)

  // Add them to a group
  await Groups.addUser('developers', me.accountId)

  // Give the developers group a role in a space
  await Roles.addGroup('SPACE_KEY', 'Developers', 'developers')

  return { user: me.displayName, groups: groups.map((g) => g.name) }
}

Note: Users are identified by their account ID, not their username or email. Use Users.getCurrent() or Users.getByAccountId() to get one, and Users.getEmail() if you need an email address.

Work with users

Import with import * as Users from '@scriptrunnerhq/hapi/users'.


Function	Description
`getCurrent()`	The user running the script
`getByAccountId(accountId)`	A single user
`getEmail(accountId)`	The user's email address, or nothing if it is not visible to your script
`getGroups(accountId)`	The groups a user belongs to
`getAll(options?)`	Every user, returned page by page
`createUser(options)`	Create a user
`deleteUser(accountId)`	Delete a user

Work with groups

Import with import * as Groups from '@scriptrunnerhq/hapi/groups'.


Function	Description
`getByName(groupName)`	A single group, or nothing if it does not exist
`getMembers(groupName)`	The users in a group
`countMembers(groupName)`	How many users are in a group, without listing them
`search(query)`	Find groups by name
`getAll(options?)`	Every group
`addUser(groupName, accountId)`	Add a user to a group
`removeUser(groupName, accountId)`	Remove a user from a group
`create(name)`	Create a group
`deleteGroup(groupName)`	Delete a group

Tip: Use countMembers rather than counting the result of getMembers. It avoids fetching every member just to get a number.

Work with space roles

Import with import * as Roles from '@scriptrunnerhq/hapi/roles'. Every function takes a space key or ID and a role name.


Function	Description
`getActors(spaceKey, roleName)`	The users and groups currently in a role
`addUser(spaceKey, roleName, accountId)`	Add a user to a role
`addGroup(spaceKey, roleName, groupName)`	Add a group to a role
`addActors(spaceKey, roleName, actors)`	Add several users and groups at once
`setActors(spaceKey, roleName, actors)`	Replace everyone in a role
`removeUser(spaceKey, roleName, accountId)`	Remove a user from a role
`removeGroup(spaceKey, roleName, groupName)`	Remove a group from a role

Warning:setActors replaces everyone currently in the role. Use addActors if you only mean to add people.

In-app example scripts

The following examples are available in-app from the Example scripts modal:

Get the current user's email: get the current user's email address regardless of their profile visibility settings, by running the lookup as the app.
Create a new user: create a new user with a specified email address and product access, by running the operation as the app.
Remove inactive users: remove users who are no longer active, for example Atlassian accounts flagged as inactive, from your instance.
List group members: retrieve all users in a specific group and return their display names as a list.
Count group members: get the number of users in a group and return a message with the count, or that the group was not found.
Add users and groups to space roles: add specific users and groups to space roles, for example a user to the Developers role and a group to the Administrators role.
Remove users and groups from space roles: remove specific users and groups from space roles.