Class ScreensService

This resource represents the screens used to record issue details. Use it to:

get details of all screens.
get details of all the fields available for use on screens.
create screens.
delete screens.
update screens.
add a field to the default screen.

See

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

Hierarchy

CommonHttpService
- ScreensService

Index

Constructors

constructor

Methods

addFieldToDefaultScreen createScreen deleteScreen getAvailableScreenFields getScreens getScreensForField updateScreen initialize

Constructors

constructor

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

Methods

addFieldToDefaultScreen

addFieldToDefaultScreen(params): Promise<unknown>
Adds a field to the default tab of the default screen.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  fieldId: string;
  }
  - fieldId: string
    The ID of the field.
Returns Promise<unknown>
Returned if the request is successful.

Path
POST /rest/api/3/screens/addToDefault/{fieldId} @scopes-current manage:jira-project @scopes-beta read:project:jira, read:screen:jira, write:screen:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-screens#api-rest-api-3-screens-addtodefault-fieldid-post

createScreen

createScreen(params): Promise<Screen>
Creates a screen with a default field tab.

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

example:
```
{
  "id": 10005,
  "name": "Resolve Security Issue Screen",
  "description": "Enables changes to resolution and linked issues."
}
```
Path
POST /rest/api/3/screens @scopes-current manage:jira-project @scopes-beta read:project:jira, read:screen:jira, write:screen:jira, read:avatar:jira, read:project-category:jira

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

deleteScreen

deleteScreen(params): Promise<void>
Deletes a screen. A screen cannot be deleted if it is used in a screen scheme, workflow, or workflow draft.

Only screens used in classic projects can be deleted.
Parameters
- params: {
  screenId: number;
  }
  - screenId: number
    The ID of the screen.
Returns Promise<void>
Path
DELETE /rest/api/3/screens/{screenId} @scopes-current manage:jira-project @scopes-beta delete:screen:jira

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

getAvailableScreenFields

getAvailableScreenFields(params): Promise<ScreenableField[]>
Returns the fields that can be added to a tab on a screen.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  screenId: number;
  }
  - screenId: number
    The ID of the screen.
Returns Promise<ScreenableField[]>
Returned if the request is successful.

Path
GET /rest/api/3/screens/{screenId}/availableFields @scopes-current manage:jira-project @scopes-beta read:screen-field:jira, read:screenable-field:jira

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

getScreens

getScreens(params?): Promise<PageBeanScreen>
Returns a paginated list of all screens or those specified by one or more screen IDs.

Permissions required: Administer Jira global permission.
Parameters
- params: {
      id?: number[];
      maxResults?: number;
      orderBy?:
          | "id"
          | "name"
          | "-id"
          | "+id"
          | "-name"
          | "+name";
      queryString?: string;
      scope?: ("GLOBAL" | "PROJECT" | "TEMPLATE")[];
      startAt?: number;
  } = {}
  - Optionalid?: number[]
    The list of screen IDs. To include multiple IDs, provide an ampersand-separated list. For example, id=10000&id=10001.
  - OptionalmaxResults?: number
    The maximum number of items to return per page.
  - OptionalorderBy?:
        | "id"
        | "name"
        | "-id"
        | "+id"
        | "-name"
        | "+name"
    Order the results by a field:
    
    id Sorts by screen ID.
    
    name Sorts by screen name.
  - OptionalqueryString?: string
    String used to perform a case-insensitive partial match with screen name.
  - Optionalscope?: ("GLOBAL" | "PROJECT" | "TEMPLATE")[]
    The scope filter string. To filter by multiple scope, provide an ampersand-separated list. For example, scope=GLOBAL&scope=PROJECT.
  - OptionalstartAt?: number
    The index of the first item to return in a page of results (page offset).
Returns Promise<PageBeanScreen>
Returned if the request is successful.

example:
```
{
  "isLast": true,
  "maxResults": 100,
  "self": "https://your-domain.atlassian.net/rest/api/3/screens",
  "startAt": 0,
  "total": 3,
  "values": [
    {
      "id": 1,
      "name": "Default Screen",
      "description": "Provides for the update all system fields."
    },
    {
      "id": 2,
      "name": "Workflow Screen",
      "description": "This screen is used in the workflow and enables you to assign issues."
    },
    {
      "id": 3,
      "name": "Resolve Issue Screen",
      "description": "Offers the ability to set resolution, change fix versions, and assign an issue."
    }
  ]
}
```
Path
GET /rest/api/3/screens @scopes-current manage:jira-project @scopes-beta read:project:jira, read:screen:jira, read:avatar:jira, read:project-category:jira

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

getScreensForField

getScreensForField(params): Promise<PageBeanScreenWithTab>
Returns a paginated list of the screens a field is used in.

Permissions required: Administer Jira global permission.
Parameters
- params: {
      expand?: string;
      fieldId: string;
      maxResults?: number;
      startAt?: number;
  }
  - Optionalexpand?: string
    Use expand to include additional information about screens in the response. This parameter accepts tab which returns details about the screen tabs the field is used in.
  - fieldId: string
    The ID of the field to return screens for.
  - 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<PageBeanScreenWithTab>
Returned if the request is successful.

example:
```
{
  "isLast": false,
  "maxResults": 1,
  "startAt": 0,
  "total": 5,
  "values": [
    {
      "id": 10001,
      "name": "Default Screen",
      "description": "Provides for the update of all system fields.",
      "tab": {
        "id": 10000,
        "name": "Fields Tab"
      }
    }
  ]
}
```
Path
GET /rest/api/3/field/{fieldId}/screens @scopes-current manage:jira-project @scopes-beta read:screen:jira, read:avatar:jira, read:project-category:jira, read:project:jira, read:screen-tab:jira

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

updateScreen

updateScreen(params): Promise<Screen>
Updates a screen. Only screens used in classic projects can be updated.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  screenId: number;
  updateScreenDetails: UpdateScreenDetails;
  }
  - screenId: number
    The ID of the screen.
  - updateScreenDetails: UpdateScreenDetails
    Example
Returns Promise<Screen>
Returned if the request is successful.

example:
```
{
  "id": 10005,
  "name": "Resolve Security Issue Screen",
  "description": "Enables changes to resolution and linked issues."
}
```
Path
PUT /rest/api/3/screens/{screenId} @scopes-current manage:jira-project @scopes-beta read:project:jira, read:screen:jira, write:screen:jira, read:avatar:jira, read:project-category:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-screens#api-rest-api-3-screens-screenid-put

`Protected` `Static`initialize

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

Returns void
Overrides CommonHttpService.initialize

Class ScreensService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns ScreensService

Methods

addFieldToDefaultScreen

Parameters

fieldId: string

Returns Promise<unknown>

Path

See

createScreen

Parameters

screenDetails: ScreenDetails

Example

Returns Promise<Screen>

Path

See

deleteScreen

Parameters

screenId: number

Returns Promise<void>

Path

See

getAvailableScreenFields

Parameters

screenId: number

Returns Promise<ScreenableField[]>

Path

See

getScreens

Parameters

Optionalid?: number[]

OptionalmaxResults?: number

OptionalorderBy?: | "id" | "name" | "-id" | "+id" | "-name" | "+name"

OptionalqueryString?: string

Optionalscope?: ("GLOBAL" | "PROJECT" | "TEMPLATE")[]

OptionalstartAt?: number

Returns Promise<PageBeanScreen>

Path

See

getScreensForField

Parameters

Optionalexpand?: string

fieldId: string

OptionalmaxResults?: number

OptionalstartAt?: number

Returns Promise<PageBeanScreenWithTab>

Path

See

updateScreen

Parameters

screenId: number

updateScreenDetails: UpdateScreenDetails

Example

Returns Promise<Screen>

Path

See

Protected Staticinitialize

Returns void

Settings

On This Page

`Optional`id?: number[]

`Optional`maxResults?: number

`Optional`orderBy?:
| "id"
| "name"
| "-id"
| "+id"
| "-name"
| "+name"

`Optional`queryString?: string

`Optional`scope?: ("GLOBAL" | "PROJECT" | "TEMPLATE")[]

`Optional`startAt?: number

`Optional`expand?: string

`Optional`maxResults?: number

`Optional`startAt?: number

`Protected` `Static`initialize