UI Update Object

So far you've made several changes to your apps by making API calls to the UI Update endpoint.

In this section, we're going to briefly take a look at the structure of the JSON object used to make those requests, so that you can understand exactly how it works. To do that, we'll step through the example request object below.

{
  "action": "set",
  "resourceType": "site",
  "resourceKey": "AA",
  "module": "jira:issueActivity",
  "title": "my-first-app",
  "orderIndex": 0,
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "My First Child Component",
    "children": [
      {
        "type": "FieldValue",
        "key": "App Name",
        "value": "My Second App"
      }
    ]
  }
}

action - required

The action property is used to tell the API what you want to do with the data you're sending. There are two possible values for this property:

• "set" - This action tells App Maker you want to set the data you're sending as the new data for the specified App. This is used to both create new Apps, as well as update existing ones.
• "delete" - This action tells App Maker you want to delete the specified App from your Atlassian product.
  • Note: The "delete" action uses the combination of the resourceType, resourceKey, and module properties to identify the App you want to delete.

resourceType - required

The "resourceType" property is used to tell App Maker what level of the product you want to "scope" your App to. There are two possible values for this property:

• "site" - This resourceType tells App Maker that you want your App to be displayed to everyone across your entire site.
  • Note: If you set your resourceType to "site", you do not need to provide a resourceKey. This is because "site" is global and there is only ever one of them.
• "project" - This resourceType tells App Maker that you want your App to be displayed only within a specific Jira project.

resourceKey - required if resourceType is "project"

The resourceKey property is used to tell App Maker which specific project you want to display your App within.

• If your resourceType is "project", the "resourceKey" should be the project key.
  • For example, if the URL for one of your Jira issues is https://atlassian.net/jira/software/projects/AA/..., then your project key would be "AA".

module - required

The module property is used to tell App Maker where in the UI you want your App to be displayed. To see a full list of all the possible modules, check out the Modules reference.

title - required

The title property is used to give your App a unique name. The title of an App must be unique within the scope of the resourceType, resourceKey, and module that it is displayed in. For example:

• You cannot have two "jira:issueContext" apps called "my-app" with the same resourceType and resourceKey.
• However, if you change one of the resourceKey to a different project, or you change the resourceType, then you will not have any issues.

orderIndex - optional

The orderIndex property is used to tell App Maker which order to display Apps in when multiple Apps are added to the same area of the UI.

• The lower the number, the higher the App will be displayed in the UI. e.g. an App with an orderIndex of 0 will be displayed above an App with an orderIndex of 1.
• All Apps have a default orderIndex of 999, and Apps with the same orderIndex will be displayed in the order they were created.

componentData - optional

The componentData property is used to define the structure of your App. This is where you define the components that make up your App when displayed in the UI.

• This property is technically optional, as it is not required when the action is "delete".
• However, if you are creating or updating an App, you will need to provide a componentData object.
• Check out the Components reference to see all the different components you can use in your Apps.