Class UiModificationsAppsService

UI modifications is a feature available for Forge apps only. It enables Forge apps to control how selected Jira and Jira Service Management fields behave on the following views:

Jira global issue create
Jira issue view
Jira issue transition
Jira Service Management request portal create.

For example: hide specific fields, set them as required, etc.

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-ui-modifications-apps-

Hierarchy

CommonHttpService
- UiModificationsAppsService

Index

Constructors

constructor

Methods

createUiModification deleteUiModification getUiModifications updateUiModification initialize

Constructors

constructor

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

Methods

createUiModification

createUiModification(params): Promise<UiModificationIdentifiers>
Creates a UI modification. UI modification can only be created by Forge apps.

Each app can define up to 3000 UI modifications. Each UI modification can define up to 1000 contexts. The same context can be assigned to maximum 100 UI modifications.

Context types:
- Jira contexts: For Jira view types, use projectId and issueTypeId. One field can act as a wildcard. Supported Jira views:
  - GIC - Jira global issue create
  - IssueView - Jira issue view
  - IssueTransition - Jira issue transition
- Jira Service Management contexts: For Jira Service Management view types, use portalId and requestTypeId. Wildcards are not supported. Supported JSM views:
  - JSMRequestCreate - Jira Service Management request create portal view
Permissions required:
- None if the UI modification is created without contexts.
- Browse projects project permission for one or more projects, if the UI modification is created with contexts.
The new write:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.
Parameters
- params: {
  createUiModificationDetails: CreateUiModificationDetails;
  }
  - createUiModificationDetails: CreateUiModificationDetails
    Details of the UI modification.
    Example
    { "contexts": [ { "issueTypeId": "10000", "projectId": "10000", "viewType": "GIC" }, { "issueTypeId": "10001", "projectId": "10000", "viewType": "IssueView" }, { "issueTypeId": "10002", "projectId": "10000", "viewType": "IssueTransition" }, { "issueTypeId": "10003", "projectId": "10000", "viewType": null }, { "issueTypeId": null, "portalId": "1", "projectId": null, "requestTypeId": "10", "viewType": "JSMRequestCreate" } ], "data": "{field: 'Story Points', config: {hidden: false}}", "description": "Reveals Story Points field when any Sprint is selected.", "name": "Reveal Story Points" }
Returns Promise<UiModificationIdentifiers>
Returned if the UI modification is created.

example:
```
{
  "id": "d7dbda8a-6239-4b63-8e13-a5ef975c8e61",
  "self": "`https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d7dbda8a-6239-4b63-8e13-a5ef975c8e61`"
}
```
Path
POST /rest/api/3/uiModifications @scopes-current read:jira-work @scopes-beta read:jira-work, write:app-data:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-ui-modifications-apps-#api-rest-api-3-uimodifications-post

deleteUiModification

deleteUiModification(params): Promise<void>
Deletes a UI modification. All the contexts that belong to the UI modification are deleted too. UI modification can only be deleted by Forge apps.

Permissions required: None.

The new write:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.
Parameters
- params: {
  uiModificationId: string;
  }
  - uiModificationId: string
    The ID of the UI modification.
Returns Promise<void>
Returned if the UI modification is deleted.

Path
DELETE /rest/api/3/uiModifications/{uiModificationId} @scopes-current @scopes-beta write:app-data:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-ui-modifications-apps-#api-rest-api-3-uimodifications-uimodificationid-delete

getUiModifications

getUiModifications(params?): Promise<PageBeanUiModificationDetails>

Gets UI modifications. UI modifications can only be retrieved by Forge apps.

Permissions required: None.

The new read:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.

Parameters

params: {
    expand?: string;
    maxResults?: number;
    startAt?: number;
} = {}
- Optionalexpand?: string
  Use expand to include additional information in the response. This parameter accepts a comma-separated list. Expand options include:
  - data Returns UI modification data.
  - contexts Returns UI modification contexts.
- 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<PageBeanUiModificationDetails>

Returned if the request is successful.

example:

{
  "isLast": true,
  "maxResults": 100,
  "startAt": 0,
  "total": 3,
  "values": [
    {
      "id": "d7dbda8a-6239-4b63-8e13-a5ef975c8e61",
      "name": "Reveal Story Points",
      "description": "Reveals Story Points field when any Sprint is selected.",
      "self": "`https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d7dbda8a-6239-4b63-8e13-a5ef975c8e61`",
      "data": "{field: 'Story Points', config: {hidden: false}}",
      "contexts": [
        {
          "id": "1533537a-bda3-4ac6-8481-846128cd9ef4",
          "projectId": "10000",
          "issueTypeId": "10000",
          "viewType": "GIC",
          "isAvailable": true
        },
        {
          "id": "c016fefa-6eb3-40c9-8596-4c4ef273e67c",
          "projectId": "10000",
          "issueTypeId": "10001",
          "viewType": "IssueView",
          "isAvailable": true
        },
        {
          "id": "1016defa-7ew3-40c5-8696-4c1efg73e67s",
          "projectId": "10000",
          "issueTypeId": "10002",
          "viewType": "IssueTransition",
          "isAvailable": true
        }
      ]
    },
    {
      "id": "e4fe8db5-f82f-416b-a3aa-b260b55da577",
      "name": "Set Assignee",
      "description": "Sets the Assignee field automatically.",
      "self": "`https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/e4fe8db5-f82f-416b-a3aa-b260b55da577`",
      "contexts": [
        {
          "id": "8b3740f9-8780-4958-8228-69dcfbda11d9",
          "projectId": "10000",
          "issueTypeId": "10000",
          "viewType": "GIC",
          "isAvailable": true
        }
      ]
    },
    {
      "id": "d3f4097e-8d8e-451e-9fb6-27c3c8c3bfff",
      "name": "Wildcard example",
      "description": "This context is applied to all issue types",
      "self": "`https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d3f4097e-8d8e-451e-9fb6-27c3c8c3bfff`",
      "contexts": [
        {
          "id": "521f2181-5d5e-46ea-9fc9-871bbf245b8b",
          "projectId": "10000",
          "issueTypeId": null,
          "viewType": "GIC",
          "isAvailable": true
        }
      ]
    },
    {
      "id": "1453f993-79ce-4389-a36d-eb72d5c85dd6",
      "name": "JSM Context",
      "description": "JSM context doesn't support wildcards.",
      "self": "`https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/1453f993-79ce-4389-a36d-eb72d5c85dd6`",
      "contexts": [
        {
          "id": "521f2181-8780-4958-9fc9-871bbf245b8b",
          "projectId": null,
          "portalId": "5",
          "issueTypeId": null,
          "requestTypeId": "100",
          "viewType": "JSMRequestCreate",
          "isAvailable": true
        }
      ]
    }
  ]
}

Path

GET /rest/api/3/uiModifications @scopes-current read:jira-work @scopes-beta read:jira-work, read:app-data:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-ui-modifications-apps-#api-rest-api-3-uimodifications-get

updateUiModification

updateUiModification(params): Promise<void>
Updates a UI modification. UI modification can only be updated by Forge apps.

Each UI modification can define up to 1000 contexts. The same context can be assigned to maximum 100 UI modifications.

Context types:
- Jira contexts: For Jira view types, use projectId and issueTypeId. One field can act as a wildcard. Supported Jira views:
  - GIC - Jira global issue create
  - IssueView - Jira issue view
  - IssueTransition - Jira issue transition
- Jira Service Management contexts: For Jira Service Management view types, use portalId and requestTypeId. Wildcards are not supported. Supported JSM views:
  - JSMRequestCreate - Jira Service Management request create portal view
Permissions required:
- None if the UI modification is created without contexts.
- Browse projects project permission for one or more projects, if the UI modification is created with contexts.
The new write:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.
Parameters
- params: {
  uiModificationId: string;
  updateUiModificationDetails: UpdateUiModificationDetails;
  }
  - uiModificationId: string
    The ID of the UI modification.
  - updateUiModificationDetails: UpdateUiModificationDetails
    Details of the UI modification.
    Example
    { "contexts": [ { "issueTypeId": "10000", "projectId": "10000", "viewType": "GIC" }, { "issueTypeId": "10001", "projectId": "10000", "viewType": "IssueView" }, { "issueTypeId": "10002", "projectId": "10000", "viewType": "IssueTransition" }, { "issueTypeId": null, "portalId": "5", "projectId": null, "requestTypeId": "100", "viewType": "JSMRequestCreate" } ], "data": "{field: 'Story Points', config: {hidden: true}}", "name": "Updated Reveal Story Points" }
Returns Promise<void>
Returned if the UI modification is updated.

Path
PUT /rest/api/3/uiModifications/{uiModificationId} @scopes-current read:jira-work @scopes-beta read:jira-work, write:app-data:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-ui-modifications-apps-#api-rest-api-3-uimodifications-uimodificationid-put

`Protected` `Static`initialize

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

Returns void
Overrides CommonHttpService.initialize

Class UiModificationsAppsService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns UiModificationsAppsService

Methods

createUiModification

Parameters

createUiModificationDetails: CreateUiModificationDetails

Example

Returns Promise<UiModificationIdentifiers>

Path

See

deleteUiModification

Parameters

uiModificationId: string

Returns Promise<void>

Path

See

getUiModifications

Parameters

Optionalexpand?: string

OptionalmaxResults?: number

OptionalstartAt?: number

Returns Promise<PageBeanUiModificationDetails>

Path

See

updateUiModification

Parameters

uiModificationId: string

updateUiModificationDetails: UpdateUiModificationDetails

Example

Returns Promise<void>

Path

See

Protected Staticinitialize

Returns void

Settings

On This Page

`Optional`expand?: string

`Optional`maxResults?: number

`Optional`startAt?: number

`Protected` `Static`initialize