Class IssueFieldsService

This resource represents issue fields, both system and custom fields. Use it to get fields, field configurations, and create custom fields.

See

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

Hierarchy

CommonHttpService
- IssueFieldsService

Index

Constructors

constructor

Methods

createCustomField deleteCustomField getContextsForFieldDeprecated getFields getFieldsPaginated getTrashedFieldsPaginated restoreCustomField trashCustomField updateCustomField initialize

Constructors

constructor

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

Methods

createCustomField

createCustomField(params): Promise<FieldDetails>

Creates a custom field.

Permissions required: Administer Jira global permission.

Parameters

params: {
customFieldDefinitionJsonBean: CustomFieldDefinitionJsonBean;
}

customFieldDefinitionJsonBean: CustomFieldDefinitionJsonBean

Definition of the custom field to be created

Example

{
"description": "Custom field for picking groups",
  "name": "New custom field",
  "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher",
  "type": "com.atlassian.jira.plugin.system.customfieldtypes:grouppicker"
}

Returns Promise<FieldDetails>

Returned if the custom field is created.

example:

{
  "clauseNames": [
    "cf[10101]",
    "New custom field"
  ],
  "custom": true,
  "id": "customfield_10101",
  "key": "customfield_10101",
  "name": "New custom field",
  "navigable": true,
  "orderable": true,
  "schema": {
    "custom": "com.atlassian.jira.plugin.system.customfieldtypes:project",
    "customId": 10101,
    "type": "project"
  },
  "searchable": true,
  "untranslatedName": "New custom field"
}

Path

POST /rest/api/3/field @scopes-current manage:jira-configuration @scopes-beta write:field:jira, read:avatar:jira, read:field:jira, read:project-category:jira, read:project:jira, read:field-configuration:jira

See

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

deleteCustomField

deleteCustomField(params): Promise<void>
Deletes a custom field. The custom field is deleted whether it is in the trash or not. See Edit or delete a custom field for more information on trashing and deleting custom fields.

This operation is asynchronous. Follow the location link in the response to determine the status of the task and use Get task to obtain subsequent updates.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  id: string;
  }
  - id: string
    The ID of a custom field.
Returns Promise<void>
Path
DELETE /rest/api/3/field/{id} @scopes-current manage:jira-configuration @scopes-beta delete:field:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields#api-rest-api-3-field-id-delete

getContextsForFieldDeprecated

getContextsForFieldDeprecated(params): Promise<PageBeanContext>
Returns a paginated list of the contexts a field is used in. Deprecated, use Get custom field contexts.

Permissions required: Administer Jira global permission.
Parameters
- params: {
      fieldId: string;
      maxResults?: number;
      startAt?: number;
  }
  - fieldId: string
    The ID of the field to return contexts 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<PageBeanContext>
Returned if the request is successful.

example:
```
{
  "isLast": false,
  "maxResults": 1,
  "startAt": 0,
  "total": 5,
  "values": [
    {
      "id": 10001,
      "name": "Default Context"
    }
  ]
}
```
Deprecated
Path
GET /rest/api/3/field/{fieldId}/contexts @scopes-current manage:jira-project @scopes-beta read:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira

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

getFields

getFields(): Promise<FieldDetails[]>
Returns system and custom issue fields according to the following rules:
- Fields that cannot be added to the issue navigator are always returned.
- Fields that cannot be placed on an issue screen are always returned.
- Fields that depend on global Jira settings are only returned if the setting is enabled. That is, timetracking fields, subtasks, votes, and watches.
- For all other fields, this operation only returns the fields that the user has permission to view (that is, the field is used in at least one project that the user has Browse Projects project permission for.)
This operation can be accessed anonymously.

Permissions required: None.
Returns Promise<FieldDetails[]>
Returned if the request is successful.

example:
```
[
  {
    "clauseNames": [
      "description"
    ],
    "custom": false,
    "id": "description",
    "name": "Description",
    "navigable": true,
    "orderable": true,
    "schema": {
      "system": "description",
      "type": "string"
    },
    "searchable": true
  },
  {
    "clauseNames": [
      "summary"
    ],
    "custom": false,
    "id": "summary",
    "key": "summary",
    "name": "Summary",
    "navigable": true,
    "orderable": true,
    "schema": {
      "system": "summary",
      "type": "string"
    },
    "searchable": true
  }
]
```
Path
GET /rest/api/3/field @scopes-current read:jira-work @scopes-beta read:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira, read:field-configuration:jira

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

getFieldsPaginated

getFieldsPaginated(params?): Promise<PageBeanField>
Returns a paginated list of fields for Classic Jira projects. The list can include:
- all fields
- specific fields, by defining id
- fields that contain a string in the field name or description, by defining query
- specific fields that contain a string in the field name or description, by defining id and query
Use type must be set to custom to show custom fields only.

Permissions required: Permission to access Jira.
Parameters
- params: {
      expand?: string;
      id?: string[];
      maxResults?: number;
      orderBy?:
          | "name"
          | "contextsCount"
          | "lastUsed"
          | "projectsCount"
          | "screensCount"
          | "-name"
          | "+name"
          | "-contextsCount"
          | "+contextsCount"
          | "-lastUsed"
          | "+lastUsed"
          | "-screensCount"
          | "+screensCount"
          | "-projectsCount"
          | "+projectsCount";
      projectIds?: number[];
      query?: string;
      startAt?: number;
      type?: ("custom" | "system")[];
  } = {}
  - Optionalexpand?: string
    Use expand to include additional information in the response. This parameter accepts a comma-separated list. Expand options include:
    
    key returns the key for each field
    
    stableId returns the stableId for each field
    
    lastUsed returns the date when the value of the field last changed
    
    screensCount returns the number of screens related to a field
    
    contextsCount returns the number of contexts related to a field
    
    isLocked returns information about whether the field is locked
    
    searcherKey returns the searcher key for each custom field
  - Optionalid?: string[]
    The IDs of the custom fields to return or, where query is specified, filter.
  - OptionalmaxResults?: number
    The maximum number of items to return per page.
  - OptionalorderBy?:
        | "name"
        | "contextsCount"
        | "lastUsed"
        | "projectsCount"
        | "screensCount"
        | "-name"
        | "+name"
        | "-contextsCount"
        | "+contextsCount"
        | "-lastUsed"
        | "+lastUsed"
        | "-screensCount"
        | "+screensCount"
        | "-projectsCount"
        | "+projectsCount"
    Order the results by:
    
    contextsCount sorts by the number of contexts related to a field
    
    lastUsed sorts by the date when the value of the field last changed
    
    name sorts by the field name
    
    screensCount sorts by the number of screens related to a field
  - OptionalprojectIds?: number[]
    The IDs of the projects to filter the fields by. Fields belonging to project Ids that the user does not have access to will not be returned
  - Optionalquery?: string
    String used to perform a case-insensitive partial match with field names or descriptions.
  - OptionalstartAt?: number
    The index of the first item to return in a page of results (page offset).
  - Optionaltype?: ("custom" | "system")[]
    The type of fields to search.
Returns Promise<PageBeanField>
Returned if the request is successful.

example:
```
{
  "isLast": false,
  "maxResults": 50,
  "startAt": 0,
  "total": 2,
  "values": [
    {
      "id": "customfield_10000",
      "name": "Approvers",
      "schema": {
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker",
        "customId": 10000,
        "items": "user",
        "type": "array"
      },
      "description": "Contains users needed for approval. This custom field was created by Jira Service Desk.",
      "key": "customfield_10000",
      "stableId": "sfid:approvers",
      "isLocked": true,
      "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearcher",
      "screensCount": 2,
      "contextsCount": 2,
      "lastUsed": {
        "type": "TRACKED",
        "value": "2021-01-28T07:37:40.000+0000"
      }
    },
    {
      "id": "customfield_10001",
      "name": "Change reason",
      "schema": {
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
        "customId": 10001,
        "type": "option"
      },
      "description": "Choose the reason for the change request",
      "key": "customfield_10001",
      "stableId": "sfid:change-reason",
      "isLocked": false,
      "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher",
      "screensCount": 2,
      "contextsCount": 2,
      "projectsCount": 2,
      "lastUsed": {
        "type": "NOT_TRACKED"
      }
    }
  ]
}
```
Path
GET /rest/api/3/field/search @scopes-current read:jira-work @scopes-beta read:field:jira, read:field-configuration:jira

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

getTrashedFieldsPaginated

getTrashedFieldsPaginated(params?): Promise<PageBeanField>

Returns a paginated list of fields in the trash. The list may be restricted to fields whose field name or description partially match a string.

Only custom fields can be queried, type must be set to custom.

Permissions required: Administer Jira global permission.

Parameters

params: {
    expand?:
        | "name"
        | "projectsCount"
        | "-name"
        | "+name"
        | "-projectsCount"
        | "+projectsCount"
        | "trashDate"
        | "-trashDate"
        | "+trashDate"
        | "plannedDeletionDate"
        | "-plannedDeletionDate"
        | "+plannedDeletionDate";
    id?: string[];
    maxResults?: number;
    orderBy?: string;
    query?: string;
    startAt?: number;
} = {}
- Optionalexpand?:
      | "name"
      | "projectsCount"
      | "-name"
      | "+name"
      | "-projectsCount"
      | "+projectsCount"
      | "trashDate"
      | "-trashDate"
      | "+trashDate"
      | "plannedDeletionDate"
      | "-plannedDeletionDate"
      | "+plannedDeletionDate"
- Optionalid?: string[]
- OptionalmaxResults?: number
  The maximum number of items to return per page.
- OptionalorderBy?: string
  Order the results by a field:
  - name sorts by the field name
  - trashDate sorts by the date the field was moved to the trash
  - plannedDeletionDate sorts by the planned deletion date
- Optionalquery?: string
  String used to perform a case-insensitive partial match with field names or descriptions.
- OptionalstartAt?: number
  The index of the first item to return in a page of results (page offset).

Returns Promise<PageBeanField>

Returned if the request is successful.

example:

{
  "isLast": false,
  "maxResults": 50,
  "startAt": 0,
  "total": 1,
  "values": [
    {
      "id": "customfield_10000",
      "name": "Approvers",
      "schema": {
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker",
        "customId": 10003,
        "type": "array"
      },
      "description": "Contains users needed for approval. This custom field was created by Jira Service Desk.",
      "key": "customfield_10003",
      "trashedDate": "2022-10-06T07:32:47.000+0000",
      "trashedBy": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": true,
        "avatarUrls": {
          "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
          "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
          "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
          "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
        },
        "displayName": "Mia Krystof",
        "emailAddress": "mia@example.com",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
        "timeZone": "Australia/Sydney"
      },
      "plannedDeletionDate": "2022-10-24T07:32:47.000+0000"
    }
  ]
}

Path

GET /rest/api/3/field/search/trashed @scopes-current read:jira-work @scopes-beta read:field:jira, read:field-configuration:jira, read:user:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields#api-rest-api-3-field-search-trashed-get

restoreCustomField

restoreCustomField(params): Promise<unknown>
Restores a custom field from trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.

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

Path
POST /rest/api/3/field/{id}/restore @scopes-current manage:jira-configuration @scopes-beta write:field:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields#api-rest-api-3-field-id-restore-post

trashCustomField

trashCustomField(params): Promise<unknown>
Moves a custom field to trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.

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

Path
POST /rest/api/3/field/{id}/trash @scopes-current manage:jira-configuration @scopes-beta delete:field:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields#api-rest-api-3-field-id-trash-post

updateCustomField

updateCustomField(params): Promise<void>
Updates a custom field.

Permissions required: Administer Jira global permission.
Parameters
- params: {
  fieldId: string;
  updateCustomFieldDetails: UpdateCustomFieldDetails;
  }
  - fieldId: string
    The ID of the custom field.
  - updateCustomFieldDetails: UpdateCustomFieldDetails
    The custom field update details.
    Example
    { "description": "Select the manager and the corresponding employee.", "name": "Managers and employees list", "searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher" }
Returns Promise<void>
Returned if the request is successful.

Path
PUT /rest/api/3/field/{fieldId} @scopes-current manage:jira-configuration @scopes-beta write:field:jira

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

`Protected` `Static`initialize

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

Returns void
Overrides CommonHttpService.initialize

Class IssueFieldsService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns IssueFieldsService

Methods

createCustomField

Parameters

customFieldDefinitionJsonBean: CustomFieldDefinitionJsonBean

Example

Returns Promise<FieldDetails>

Path

See

deleteCustomField

Parameters

id: string

Returns Promise<void>

Path

See

getContextsForFieldDeprecated

Parameters

fieldId: string

OptionalmaxResults?: number

OptionalstartAt?: number

Returns Promise<PageBeanContext>

Deprecated

Path

See

getFields

Returns Promise<FieldDetails[]>

Path

See

getFieldsPaginated

Parameters

Optionalexpand?: string

Optionalid?: string[]

OptionalmaxResults?: number

OptionalorderBy?: | "name" | "contextsCount" | "lastUsed" | "projectsCount" | "screensCount" | "-name" | "+name" | "-contextsCount" | "+contextsCount" | "-lastUsed" | "+lastUsed" | "-screensCount" | "+screensCount" | "-projectsCount" | "+projectsCount"

OptionalprojectIds?: number[]

Optionalquery?: string

OptionalstartAt?: number

Optionaltype?: ("custom" | "system")[]

Returns Promise<PageBeanField>

Path

See

getTrashedFieldsPaginated

Parameters

Optionalexpand?: | "name" | "projectsCount" | "-name" | "+name" | "-projectsCount" | "+projectsCount" | "trashDate" | "-trashDate" | "+trashDate" | "plannedDeletionDate" | "-plannedDeletionDate" | "+plannedDeletionDate"

Optionalid?: string[]

OptionalmaxResults?: number

OptionalorderBy?: string

Optionalquery?: string

OptionalstartAt?: number

Returns Promise<PageBeanField>

Path

See

restoreCustomField

Parameters

id: string

Returns Promise<unknown>

Path

See

trashCustomField

Parameters

id: string

Returns Promise<unknown>

Path

See

updateCustomField

Parameters

fieldId: string

updateCustomFieldDetails: UpdateCustomFieldDetails

Example

Returns Promise<void>

`Optional`maxResults?: number

`Optional`startAt?: number

`Optional`expand?: string

`Optional`id?: string[]

`Optional`maxResults?: number

`Optional`orderBy?:
| "name"
| "contextsCount"
| "lastUsed"
| "projectsCount"
| "screensCount"
| "-name"
| "+name"
| "-contextsCount"
| "+contextsCount"
| "-lastUsed"
| "+lastUsed"
| "-screensCount"
| "+screensCount"
| "-projectsCount"
| "+projectsCount"

`Optional`projectIds?: number[]

`Optional`query?: string

`Optional`startAt?: number

`Optional`type?: ("custom" | "system")[]

`Optional`expand?:
| "name"
| "projectsCount"
| "-name"
| "+name"
| "-projectsCount"
| "+projectsCount"
| "trashDate"
| "-trashDate"
| "+trashDate"
| "plannedDeletionDate"
| "-plannedDeletionDate"
| "+plannedDeletionDate"

`Optional`id?: string[]

`Optional`maxResults?: number

`Optional`orderBy?: string

`Optional`query?: string

`Optional`startAt?: number

`Protected` `Static`initialize