Class GroupsService

This resource represents groups of users. Use it to get, create, find, and delete groups as well as add and remove users from groups. ([WARNING] The standard Atlassian group names are default names only and can be edited or deleted. For example, an admin or Atlassian support could delete the default group jira-software-users or rename it to jsw-users at any point. See https://support.atlassian.com/user-management/docs/create-and-update-groups/ for details.)

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups

Hierarchy

CommonHttpService
- GroupsService

Index

Constructors

constructor

Methods

addUserToGroup bulkGetGroups createGroup findGroups getGroup getUsersFromGroup removeGroup removeUserFromGroup initialize

Constructors

constructor

new GroupsService(getClientInstance): GroupsService
Internal
Create a new instance of the service.
Parameters
- getClientInstance: (() => CommonHttpClient)
  - - (): CommonHttpClient
    - Returns CommonHttpClient
Returns GroupsService
Inherited from CommonHttpService.constructor

Methods

addUserToGroup

addUserToGroup(params): Promise<Group>
Adds a user to a group.

Permissions required: Site administration (that is, member of the site-admin group).
Parameters
- params: {
      groupId?: string;
      groupname?: string;
      updateUserToGroupBean: UpdateUserToGroupBean;
  }
  - OptionalgroupId?: string
    The ID of the group. This parameter cannot be used with the groupName parameter.
  - Optionalgroupname?: string
    As a group's name can change, use of groupId is recommended to identify a group. The name of the group. This parameter cannot be used with the groupId parameter.
  - updateUserToGroupBean: UpdateUserToGroupBean
    The user to add to the group.
    Example
    { "accountId": "5b10ac8d82e05b22cc7d4ef5" }
Returns Promise<Group>
Returned if the request is successful.

Path
POST /rest/api/3/group/user @scopes-current manage:jira-configuration @scopes-beta write:group:jira, read:avatar:jira, read:group:jira, read:user:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-user-post

bulkGetGroups

bulkGetGroups(params?): Promise<PageBeanGroupDetails>
Returns a paginated list of groups.

Permissions required: Browse users and groups global permission.
Parameters
- params: {
      accessType?: string;
      applicationKey?: string;
      groupId?: string[];
      groupName?: string[];
      maxResults?: number;
      startAt?: number;
  } = {}
  - OptionalaccessType?: string
    The access level of a group. Valid values: 'site-admin', 'admin', 'user'.
  - OptionalapplicationKey?: string
    The application key of the product user groups to search for. Valid values: 'jira-servicedesk', 'jira-software', 'jira-product-discovery', 'jira-core'.
  - OptionalgroupId?: string[]
    The ID of a group. To specify multiple IDs, pass multiple groupId parameters. For example, groupId=5b10a2844c20165700ede21g&groupId=5b10ac8d82e05b22cc7d4ef5.
  - OptionalgroupName?: string[]
    The name of a group. To specify multiple names, pass multiple groupName parameters. For example, groupName=administrators&groupName=jira-software-users.
  - OptionalmaxResults?: number
    The maximum number of items to return per page.
  - OptionalstartAt?: number
    The index of the first item to return in a page of results (page offset).
Returns Promise<PageBeanGroupDetails>
Returned if the request is successful.

example:
```
{
  "isLast": true,
  "maxResults": 10,
  "startAt": 0,
  "total": 2,
  "values": [
    {
      "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
      "name": "jdog-developers"
    },
    {
      "groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487",
      "name": "juvenal-bot"
    }
  ]
}
```
Path
GET /rest/api/3/group/bulk @scopes-current read:jira-user @scopes-beta read:group:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-bulk-get

createGroup

createGroup(params): Promise<Group>

Creates a group.

Permissions required: Site administration (that is, member of the site-admin group).

Parameters

params: {
addGroupBean: AddGroupBean;
}
- addGroupBean: AddGroupBean
  The name of the group.
  Example
```
{
"name": "power-users"
}
```

Returns Promise<Group>

Returned if the request is successful.

example:

{
  "expand": "users",
  "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
  "name": "power-users",
  "self": "https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625",
  "users": {
    "end-index": 0,
    "items": [
      {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      }
    ],
    "max-results": 50,
    "size": 1,
    "start-index": 0
  }
}

Path

POST /rest/api/3/group @scopes-current manage:jira-configuration @scopes-beta read:group:jira, read:user:jira, write:group:jira, read:avatar:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-post

findGroups

findGroups(params?): Promise<FoundGroups>
Returns a list of groups whose names contain a query string. A list of group names can be provided to exclude groups from the results.

The primary use case for this resource is to populate a group picker suggestions list. To this end, the returned object includes the html field where the matched query term is highlighted in the group name with the HTML strong tag. Also, the groups list is wrapped in a response object that contains a header for use in the picker, specifically Showing X of Y matching groups.

The list returns with the groups sorted. If no groups match the list criteria, an empty list is returned.

This operation can be accessed anonymously.

Permissions required: Browse projects project permission. Anonymous calls and calls by users without the required permission return an empty list.

Browse users and groups global permission. Without this permission, calls where query is not an exact match to an existing group will return an empty list.
Parameters
- params: {
      accountId?: string;
      caseInsensitive?: boolean;
      exclude?: string[];
      excludeId?: string[];
      maxResults?: number;
      query?: string;
      userName?: string;
  } = {}
  - OptionalaccountId?: string
    This parameter is deprecated, setting it does not affect the results. To find groups containing a particular user, use Get user groups.
  - OptionalcaseInsensitive?: boolean
    Whether the search for groups should be case insensitive.
  - Optionalexclude?: string[]
    As a group's name can change, use of excludeGroupIds is recommended to identify a group. A group to exclude from the result. To exclude multiple groups, provide an ampersand-separated list. For example, exclude=group1&exclude=group2. This parameter cannot be used with the excludeGroupIds parameter.
  - OptionalexcludeId?: string[]
    A group ID to exclude from the result. To exclude multiple groups, provide an ampersand-separated list. For example, excludeId=group1-id&excludeId=group2-id. This parameter cannot be used with the excludeGroups parameter.
  - OptionalmaxResults?: number
    The maximum number of groups to return. The maximum number of groups that can be returned is limited by the system property jira.ajax.autocomplete.limit.
  - Optionalquery?: string
    The string to find in group names.
  - OptionaluserName?: string
    This parameter is no longer available. See the deprecation notice for details.
Returns Promise<FoundGroups>
Returned if the request is successful.

example:
```
{
  "groups": [
    {
      "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
      "html": "<b>j</b>dog-developers",
      "name": "jdog-developers"
    },
    {
      "groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487",
      "html": "<b>j</b>uvenal-bot",
      "name": "juvenal-bot"
    }
  ],
  "header": "Showing 20 of 25 matching groups",
  "total": 25
}
```
Path
GET /rest/api/3/groups/picker @scopes-current read:jira-user @scopes-beta read:group:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-groups-picker-get

getGroup

getGroup(params?): Promise<Group>
This operation is deprecated, use group/member.

Returns all users in a group.

Permissions required: either of:
- Browse users and groups global permission.
- Administer Jira global permission.
Parameters
- params: {
      expand?: string;
      groupId?: string;
      groupname?: string;
  } = {}
  - Optionalexpand?: string
    List of fields to expand.
  - OptionalgroupId?: string
    The ID of the group. This parameter cannot be used with the groupName parameter.
  - Optionalgroupname?: string
    As a group's name can change, use of groupId is recommended to identify a group. The name of the group. This parameter cannot be used with the groupId parameter.
Returns Promise<Group>
Returned if the request is successful.

Deprecated
Path
GET /rest/api/3/group @scopes-current read:jira-user @scopes-beta read:group:jira, read:user:jira, read:avatar:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-get

getUsersFromGroup

getUsersFromGroup(params?): Promise<PageBeanUserDetails>

Returns a paginated list of all users in a group.

Note that users are ordered by username, however the username is not returned in the results due to privacy reasons.

Permissions required: either of:

Browse users and groups global permission.
Administer Jira global permission.

Parameters

params: {
    groupId?: string;
    groupname?: string;
    includeInactiveUsers?: boolean;
    maxResults?: number;
    startAt?: number;
} = {}
- OptionalgroupId?: string
  The ID of the group. This parameter cannot be used with the groupName parameter.
- Optionalgroupname?: string
  As a group's name can change, use of groupId is recommended to identify a group. The name of the group. This parameter cannot be used with the groupId parameter.
- OptionalincludeInactiveUsers?: boolean
  Include inactive users.
- OptionalmaxResults?: number
  The maximum number of items to return per page (number should be between 1 and 50).
- OptionalstartAt?: number
  The index of the first item to return in a page of results (page offset).

Returns Promise<PageBeanUserDetails>

Returned if the request is successful.

example:

{
  "isLast": false,
  "maxResults": 2,
  "nextPage": "https://your-domain.atlassian.net/rest/api/3/group/member?groupId=276f955c-63d7-42c8-9520-92d01dca0625&includeInactiveUsers=false&startAt=4&maxResults=2",
  "self": "https://your-domain.atlassian.net/rest/api/3/group/member?groupId=276f955c-63d7-42c8-9520-92d01dca0625&includeInactiveUsers=false&startAt=2&maxResults=2",
  "startAt": 3,
  "total": 5,
  "values": [
    {
      "accountId": "5b10a2844c20165700ede21g",
      "accountType": "atlassian",
      "active": true,
      "avatarUrls": {},
      "displayName": "Mia",
      "emailAddress": "mia@example.com",
      "key": "",
      "name": "",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
      "timeZone": "Australia/Sydney"
    },
    {
      "accountId": "5b10a0effa615349cb016cd8",
      "accountType": "atlassian",
      "active": false,
      "avatarUrls": {},
      "displayName": "Will",
      "emailAddress": "will@example.com",
      "key": "",
      "name": "",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a0effa615349cb016cd8",
      "timeZone": "Australia/Sydney"
    }
  ]
}

Path

GET /rest/api/3/group/member @scopes-current manage:jira-configuration @scopes-beta read:group:jira, read:user:jira, read:avatar:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-member-get

removeGroup

removeGroup(params?): Promise<void>
Deletes a group.

Permissions required: Site administration (that is, member of the site-admin strategic group).
Parameters
- params: {
      groupId?: string;
      groupname?: string;
      swapGroup?: string;
      swapGroupId?: string;
  } = {}
  - OptionalgroupId?: string
    The ID of the group. This parameter cannot be used with the groupname parameter.
  - Optionalgroupname?: string
  - OptionalswapGroup?: string
    As a group's name can change, use of swapGroupId is recommended to identify a group. The group to transfer restrictions to. Only comments and worklogs are transferred. If restrictions are not transferred, comments and worklogs are inaccessible after the deletion. This parameter cannot be used with the swapGroupId parameter.
  - OptionalswapGroupId?: string
    The ID of the group to transfer restrictions to. Only comments and worklogs are transferred. If restrictions are not transferred, comments and worklogs are inaccessible after the deletion. This parameter cannot be used with the swapGroup parameter.
Returns Promise<void>
Path
DELETE /rest/api/3/group @scopes-current manage:jira-configuration @scopes-beta delete:group:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-delete

removeUserFromGroup

removeUserFromGroup(params): Promise<void>
Removes a user from a group.

Permissions required: Site administration (that is, member of the site-admin group).
Parameters
- params: {
      accountId: string;
      groupId?: string;
      groupname?: string;
      username?: string;
  }
  - accountId: string
    The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.
  - OptionalgroupId?: string
    The ID of the group. This parameter cannot be used with the groupName parameter.
  - Optionalgroupname?: string
    As a group's name can change, use of groupId is recommended to identify a group. The name of the group. This parameter cannot be used with the groupId parameter.
  - Optionalusername?: string
    This parameter is no longer available. See the deprecation notice for details.
Returns Promise<void>
Path
DELETE /rest/api/3/group/user @scopes-current manage:jira-configuration @scopes-beta write:group:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups#api-rest-api-3-group-user-delete

`Protected` `Static`initialize

initialize(): void
Method to initialize the class. Normally used to set up validation rules.

Returns void
Overrides CommonHttpService.initialize

Class GroupsService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns GroupsService

Methods

addUserToGroup

Parameters

OptionalgroupId?: string

Optionalgroupname?: string

updateUserToGroupBean: UpdateUserToGroupBean

Example

Returns Promise<Group>

Path

See

bulkGetGroups

Parameters

OptionalaccessType?: string

OptionalapplicationKey?: string

OptionalgroupId?: string[]

OptionalgroupName?: string[]

OptionalmaxResults?: number

OptionalstartAt?: number

Returns Promise<PageBeanGroupDetails>

Path

See

createGroup

Parameters

addGroupBean: AddGroupBean

Example

Returns Promise<Group>

Path

See

findGroups

Parameters

OptionalaccountId?: string

OptionalcaseInsensitive?: boolean

Optionalexclude?: string[]

OptionalexcludeId?: string[]

OptionalmaxResults?: number

Optionalquery?: string

OptionaluserName?: string

Returns Promise<FoundGroups>

Path

See

getGroup

Parameters

Optionalexpand?: string

OptionalgroupId?: string

Optionalgroupname?: string

Returns Promise<Group>

Deprecated

Path

See

getUsersFromGroup

Parameters

OptionalgroupId?: string

Optionalgroupname?: string

OptionalincludeInactiveUsers?: boolean

OptionalmaxResults?: number

OptionalstartAt?: number

Returns Promise<PageBeanUserDetails>

Path

See

removeGroup

Parameters

OptionalgroupId?: string

Optionalgroupname?: string

OptionalswapGroup?: string

OptionalswapGroupId?: string

Returns Promise<void>

Path

See

removeUserFromGroup

`Optional`groupId?: string

`Optional`groupname?: string

`Optional`accessType?: string

`Optional`applicationKey?: string

`Optional`groupId?: string[]

`Optional`groupName?: string[]

`Optional`maxResults?: number

`Optional`startAt?: number

`Optional`accountId?: string

`Optional`caseInsensitive?: boolean

`Optional`exclude?: string[]

`Optional`excludeId?: string[]

`Optional`maxResults?: number

`Optional`query?: string

`Optional`userName?: string

`Optional`expand?: string

`Optional`groupId?: string

`Optional`groupname?: string

`Optional`groupId?: string

`Optional`groupname?: string

`Optional`includeInactiveUsers?: boolean

`Optional`maxResults?: number

`Optional`startAt?: number

`Optional`groupId?: string

`Optional`groupname?: string

`Optional`swapGroup?: string

`Optional`swapGroupId?: string

`Optional`groupId?: string

`Optional`groupname?: string

`Optional`username?: string

`Protected` `Static`initialize