Entity JSON Objects

In this section, we're going to take a look at the structure of the JSON objects used to create, update, and delete different entities in App Maker, so that you can understand exactly how they work. To do that, we'll step through several example entities below.

Many of the properties on these objects are shared across the different entity types (UI Components, Data Objects, Data Lists, Webhook Transforms). Those shared properties will be explained first, before we cover the properties that are specific to each entity type in their respective sections.

Note:

• Many of the features in App Maker use a similarly structured object for being created, updated, or deleted.
• Understanding this structure will help you to work with all the features in App Maker.

Shared Properties

There are several properties that are shared across all the different entity types in App Maker. These properties are used to identify the entity you want to create, update, or delete, as well as to define the structure of the entity.

The JSON below provides an example of those properties.

{
  "action": "set",
  "resourceType": "project",
  "resourceKey": "AA",
  "title": "my-first-app"
}

action - required

The action property is used to tell the App Maker what you want to do with the data you're sending. There are four 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 entity. This is used to both create new entities, as-well as update existing ones.
• "delete" - This action tells App Maker you want to delete the specified entity from the system.
  • Note: The "delete" action uses the combination of the resourceType, resourceKey, and module properties to identify the entity you want to delete.
• "add" - (Only for Data Lists) This action tells App Maker you want to add the data you're sending to the specified Data List.
• "remove" - (Only for Data Lists) This action tells App Maker you want to remove the data you're sending from the specified Data List.

resourceType - required

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

• "site" - This resourceType tells App Maker that you want the entity to be available 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 the entity 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 the entity to be available 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".

title - required

The title property is used to give the entity you're working with a unique name. The title of an entity must be unique within the scope of the resourceType, resourceKey, and module (if it is a UI Component) that it is displayed in. For example:

• You cannot have two "jira:issueContext" UI Components 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.

UI Components

There are several properties that are only used for UI Components.

The JSON below provides an example of those properties.

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

module - required

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

componentData - required

The componentData property is used to define the structure of your UI Component. This is where you define the sub-components that make it up 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 a UI Component, 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.

orderIndex - optional

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

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

Data Objects

There is only a single property that is unique for Data Objects, which is the actual contents of the object itself.

{
  "action": "set",
  "resourceType": "project",
  "resourceKey": "AA",
  "title": "my-first-app",
  "dataObject": { 
    "website": "Online",
    "api": "Offline"
  }
}

dataObject - required

The dataObject property is used to define the actual contents of the Data Object that you want to make available to your apps.

• This property is technically optional, as it is not required when the action is "delete".
• However, if you are creating or updating a Data Object, you will need to provide a dataObject object.

Data Lists

There are several properties that are only used for Data Lists.

The JSON below provides an example of those properties.

{
  "action": "set",
  "resourceType": "project",
  "resourceKey": "AA",
  "title": "my-first-app",
  "listItemKey": "id", 
  "listItem": { 
    "website": "Online",
    "api": "Offline"
  }
}

listItemKey - required

The listItemKey property is used to specify which property in the list items the system should use as the unique identifier for each item.

• This listItem
• However, if you are creating or updating a Data Object, you will need to provide a dataObject object.

listItem - required

The listItem property is used to define the actual contents of the Object that you want to add to the specified Data List.

• Unlike other entities, the listItem property is always required, both when adding or removing items.
• This is because App Maker needs to at least know the value of the listItemKey property to be able to remove the item from the list.

Webhook Transform

There are several properties that are only used for Webhook Transforms.

The JSON below provides an example of those properties.

{
  "action": "set",
  "resourceType": "project",
  "resourceKey": "AA",
  "title": "my-first-app",
  "transformTarget": "list", 
  "transformData": { 
    "website": "{{webhook.body.website-state}}",
    "api": "{{webhook.body.api-state}}"
  }
}

transformTarget - required

The transformTarget property is used to tell App Maker what type of entity the transformed data should be turned in to.

• There are two possible values for this property:
  • "data-list" - This value tells App Maker that you want the transformed data to be used in an "add"/"remove" operation on a Data List.
  • "data-object" - This value tells App Maker that you want the transformed data to be used in a "set"/"delete" operation as a Data Object.

transformData - required

The transformData property is used to define the structure of the transformed data.

• You use templating syntax to construct the Data List or Data Object operation that you want to run each time the Webhook Transform is triggered.