Class ProjectRolesService

This resource represents the roles that users can play in projects. Use this resource to get, create, update, and delete project roles.

See

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

Hierarchy

CommonHttpService
- ProjectRolesService

Index

Constructors

constructor

Methods

createProjectRole deleteProjectRole fullyUpdateProjectRole getAllProjectRoles getProjectRole getProjectRoleById getProjectRoleDetails getProjectRoles partialUpdateProjectRole initialize

Constructors

constructor

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

Methods

createProjectRole

createProjectRole(params): Promise<ProjectRole>
Creates a new project role with no default actors. You can use the Add default actors to project role operation to add default actors to the project role after creating it.

Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.<

Permissions required: Administer Jira global permission.
Parameters
- params: {
  createUpdateRoleRequestBean: CreateUpdateRoleRequestBean;
  }
  - createUpdateRoleRequestBean: CreateUpdateRoleRequestBean
    Example
Returns Promise<ProjectRole>
Returned if the request is successful.

example:
```
{
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}
```
Path
POST /rest/api/3/role @scopes-current manage:jira-configuration @scopes-beta read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira, read:project-category:jira, read:project-role:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-role-post

deleteProjectRole

deleteProjectRole(params): Promise<void>
Deletes a project role. You must specify a replacement project role if you wish to delete a project role that is in use.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  id: number;
  swap?: number;
  }
  - id: number
    The ID of the project role to delete. Use Get all project roles to get a list of project role IDs.
  - Optionalswap?: number
    The ID of the project role that will replace the one being deleted. The swap will attempt to swap the role in schemes (notifications, permissions, issue security), workflows, worklogs and comments.
Returns Promise<void>
Path
DELETE /rest/api/3/role/{id} @scopes-current manage:jira-configuration @scopes-beta delete:project-role:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-role-id-delete

fullyUpdateProjectRole

fullyUpdateProjectRole(params): Promise<ProjectRole>

Updates the project role's name and description. You must include both a name and a description in the request.

Permissions required: Administer Jira global permission.

Parameters

params: {
createUpdateRoleRequestBean: CreateUpdateRoleRequestBean;
id: number;
}
- createUpdateRoleRequestBean: CreateUpdateRoleRequestBean
  Example
- id: number
  The ID of the project role. Use Get all project roles to get a list of project role IDs.

Returns Promise<ProjectRole>

Returned if the request is successful.

example:

{
  "actors": [
    {
      "actorGroup": {
        "displayName": "jira-developers",
        "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2",
        "name": "jira-developers"
      },
      "displayName": "jira-developers",
      "id": 10240,
      "name": "jira-developers",
      "type": "atlassian-group-role-actor",
      "user": "jira-developers"
    },
    {
      "actorUser": {
        "accountId": "5b10a2844c20165700ede21g"
      },
      "displayName": "Mia Krystof",
      "id": 10241,
      "type": "atlassian-user-role-actor"
    }
  ],
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "scope": {
    "project": {
      "id": "10000",
      "key": "KEY",
      "name": "Next Gen Project"
    },
    "type": "PROJECT"
  },
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}

Path

PUT /rest/api/3/role/{id} @scopes-current manage:jira-configuration @scopes-beta read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira, read:project-category:jira, read:project-role:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-role-id-put

getAllProjectRoles

getAllProjectRoles(): Promise<ProjectRole[]>
Gets a list of all project roles, complete with project role details and default actors.

About project roles
Project roles are a flexible way to to associate users and groups with projects. In Jira Cloud, the list of project roles is shared globally with all projects, but each project can have a different set of actors associated with it (unlike groups, which have the same membership throughout all Jira applications).

Project roles are used in permission schemes, email notification schemes, issue security levels, comment visibility, and workflow conditions.

Members and actors
In the Jira REST API, a member of a project role is called an actor. An actor is a group or user associated with a project role.

Actors may be set as default members of the project role or set at the project level:
- Default actors: Users and groups that are assigned to the project role for all newly created projects. The default actors can be removed at the project level later if desired.
- Actors: Users and groups that are associated with a project role for a project, which may differ from the default actors. This enables you to assign a user to different roles in different projects.
Permissions required: Administer Jira global permission.
Returns Promise<ProjectRole[]>
Returned if the request is successful.

example:
```
[
  {
    "actors": [
      {
        "actorGroup": {
          "displayName": "jira-developers",
          "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2",
          "name": "jira-developers"
        },
        "displayName": "jira-developers",
        "id": 10240,
        "name": "jira-developers",
        "type": "atlassian-group-role-actor",
        "user": "jira-developers"
      },
      {
        "actorUser": {
          "accountId": "5b10a2844c20165700ede21g"
        },
        "displayName": "Mia Krystof",
        "id": 10241,
        "type": "atlassian-user-role-actor"
      }
    ],
    "description": "A project role that represents developers in a project",
    "id": 10360,
    "name": "Developers",
    "scope": {
      "project": {
        "id": "10000",
        "key": "KEY",
        "name": "Next Gen Project"
      },
      "type": "PROJECT"
    },
    "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
  }
]
```
Path
GET /rest/api/3/role @scopes-current manage:jira-configuration @scopes-beta read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira, read:project-category:jira

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

getProjectRole

getProjectRole(params): Promise<ProjectRole>
Returns a project role's details and actors associated with the project. The list of actors is sorted by display name.

To check whether a user belongs to a role based on their group memberships, use Get user with the groups expand parameter selected. Then check whether the user keys and groups match with the actors returned for the project.

This operation can be accessed anonymously.

Permissions required: Administer Projects project permission for the project or Administer Jira global permission.
Parameters
- params: {
      excludeInactiveUsers?: boolean;
      id: number;
      projectIdOrKey: string;
  }
  - OptionalexcludeInactiveUsers?: boolean
    Exclude inactive users.
  - id: number
    The ID of the project role. Use Get all project roles to get a list of project role IDs.
  - projectIdOrKey: string
    The project ID or project key (case sensitive).
Returns Promise<ProjectRole>
Returned if the request is successful.

example:
```
{
  "actors": [
    {
      "actorGroup": {
        "displayName": "jira-developers",
        "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2",
        "name": "jira-developers"
      },
      "displayName": "jira-developers",
      "id": 10240,
      "name": "jira-developers",
      "type": "atlassian-group-role-actor",
      "user": "jira-developers"
    },
    {
      "actorUser": {
        "accountId": "5b10a2844c20165700ede21g"
      },
      "displayName": "Mia Krystof",
      "id": 10241,
      "type": "atlassian-user-role-actor"
    }
  ],
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "scope": {
    "project": {
      "id": "10000",
      "key": "KEY",
      "name": "Next Gen Project"
    },
    "type": "PROJECT"
  },
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}
```
Path
GET /rest/api/3/project/{projectIdOrKey}/role/{id} @scopes-current read:jira-work @scopes-beta read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira, read:project-category:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-project-projectidorkey-role-id-get

getProjectRoleById

getProjectRoleById(params): Promise<ProjectRole>

Gets the project role details and the default actors associated with the role. The list of default actors is sorted by display name.

Permissions required: Administer Jira global permission.

Parameters

params: {
id: number;
}
- id: number
  The ID of the project role. Use Get all project roles to get a list of project role IDs.

Returns Promise<ProjectRole>

Returned if the request is successful.

example:

{
  "actors": [
    {
      "actorGroup": {
        "displayName": "jira-developers",
        "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2",
        "name": "jira-developers"
      },
      "displayName": "jira-developers",
      "id": 10240,
      "name": "jira-developers",
      "type": "atlassian-group-role-actor",
      "user": "jira-developers"
    },
    {
      "actorUser": {
        "accountId": "5b10a2844c20165700ede21g"
      },
      "displayName": "Mia Krystof",
      "id": 10241,
      "type": "atlassian-user-role-actor"
    }
  ],
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "scope": {
    "project": {
      "id": "10000",
      "key": "KEY",
      "name": "Next Gen Project"
    },
    "type": "PROJECT"
  },
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}

Path

GET /rest/api/3/role/{id} @scopes-current manage:jira-configuration @scopes-beta read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira, read:project-category:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-role-id-get

getProjectRoleDetails

getProjectRoleDetails(params): Promise<ProjectRoleDetails[]>
Returns all project roles and the details for each role. Note that the list of project roles is common to all projects.

This operation can be accessed anonymously.

Permissions required: Administer Jira global permission or Administer projects project permission for the project.
Parameters
- params: {
      currentMember?: boolean;
      excludeConnectAddons?: boolean;
      projectIdOrKey: string;
  }
  - OptionalcurrentMember?: boolean
    Whether the roles should be filtered to include only those the user is assigned to.
  - OptionalexcludeConnectAddons?: boolean
  - projectIdOrKey: string
    The project ID or project key (case sensitive).
Returns Promise<ProjectRoleDetails[]>
Returned if the request is successful.

example:
```
[
  {
    "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360",
    "name": "Developers",
    "id": 10360,
    "description": "A project role that represents developers in a project",
    "admin": false,
    "default": true,
    "roleConfigurable": true,
    "translatedName": "Developers"
  }
]
```
Path
GET /rest/api/3/project/{projectIdOrKey}/roledetails @scopes-current read:jira-work @scopes-beta read:project-category:jira, read:project-role:jira, read:project:jira, read:avatar:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-project-projectidorkey-roledetails-get

getProjectRoles

getProjectRoles(params): Promise<{
[key: string]: string;
}>
Returns a list of project roles for the project returning the name and self URL for each role.

Note that all project roles are shared with all projects in Jira Cloud. See Get all project roles for more information.

This operation can be accessed anonymously.

Permissions required: Administer Projects project permission for any project on the site or Administer Jira global permission.
Parameters
- params: {
  projectIdOrKey: string;
  }
  - projectIdOrKey: string
    The project ID or project key (case sensitive).
Returns Promise<{
[key: string]: string;
}>
Returned if the request is successful.

example:
```
{
  "Administrators": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10002",
  "Developers": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10000",
  "Users": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10001"
}
```
Path
GET /rest/api/3/project/{projectIdOrKey}/role @scopes-current read:jira-work @scopes-beta read:project-role:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-project-projectidorkey-role-get

partialUpdateProjectRole

partialUpdateProjectRole(params): Promise<ProjectRole>

Updates either the project role's name or its description.

You cannot update both the name and description at the same time using this operation. If you send a request with a name and a description only the name is updated.

Permissions required: Administer Jira global permission.

Parameters

params: {
createUpdateRoleRequestBean: CreateUpdateRoleRequestBean;
id: number;
}
- createUpdateRoleRequestBean: CreateUpdateRoleRequestBean
  Example
- id: number
  The ID of the project role. Use Get all project roles to get a list of project role IDs.

Returns Promise<ProjectRole>

Returned if the request is successful.

example:

{
  "actors": [
    {
      "actorGroup": {
        "displayName": "jira-developers",
        "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2",
        "name": "jira-developers"
      },
      "displayName": "jira-developers",
      "id": 10240,
      "name": "jira-developers",
      "type": "atlassian-group-role-actor",
      "user": "jira-developers"
    },
    {
      "actorUser": {
        "accountId": "5b10a2844c20165700ede21g"
      },
      "displayName": "Mia Krystof",
      "id": 10241,
      "type": "atlassian-user-role-actor"
    }
  ],
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "scope": {
    "project": {
      "id": "10000",
      "key": "KEY",
      "name": "Next Gen Project"
    },
    "type": "PROJECT"
  },
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}

Path

POST /rest/api/3/role/{id} @scopes-current manage:jira-configuration @scopes-beta read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira, read:project-category:jira, read:project-role:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles#api-rest-api-3-role-id-post

`Protected` `Static`initialize

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

Returns void
Overrides CommonHttpService.initialize

Class ProjectRolesService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns ProjectRolesService

Methods

createProjectRole

Parameters

createUpdateRoleRequestBean: CreateUpdateRoleRequestBean

Example

Returns Promise<ProjectRole>

Path

See

deleteProjectRole

Parameters

id: number

Optionalswap?: number

Returns Promise<void>

Path

See

fullyUpdateProjectRole

Parameters

createUpdateRoleRequestBean: CreateUpdateRoleRequestBean

Example

id: number

Returns Promise<ProjectRole>

Path

See

getAllProjectRoles

About project roles

Members and actors

Returns Promise<ProjectRole[]>

Path

See

getProjectRole

Parameters

OptionalexcludeInactiveUsers?: boolean

id: number

projectIdOrKey: string

Returns Promise<ProjectRole>

Path

See

getProjectRoleById

Parameters

id: number

Returns Promise<ProjectRole>

Path

See

getProjectRoleDetails

Parameters

OptionalcurrentMember?: boolean

OptionalexcludeConnectAddons?: boolean

projectIdOrKey: string

Returns Promise<ProjectRoleDetails[]>

Path

See

getProjectRoles

Parameters

projectIdOrKey: string

Returns Promise<{ [key: string]: string; }>

Path

See

partialUpdateProjectRole

Parameters

createUpdateRoleRequestBean: CreateUpdateRoleRequestBean

Example

id: number

Returns Promise<ProjectRole>

Path

See

Protected Staticinitialize

Returns void

Settings

On This Page

`Optional`swap?: number

`Optional`excludeInactiveUsers?: boolean

`Optional`currentMember?: boolean

`Optional`excludeConnectAddons?: boolean

Returns Promise<{
[key: string]: string;
}>

`Protected` `Static`initialize