Data Objects

---

---

In this section we'll cover how to implement dynamic content in your Apps without requiring that data to be stored in fields on your Jira Issues or Projects.

The primary use-case we'll focus on here is wanting to display some data from an external system (e.g. your CRM) inside an App you've built for your Atlassian product.

We're not going to go through a full step-by-step walkthrough here because there is a thousand different ways you could implement this functionality, but we'll go over the high-level workflow, and give you some suggestions on ways to implement it.

Heads Up:

The topics covered in this section are going to be a little bit more technically advanced.

We recommend you have some experience with basic tech concepts like calling REST APIs and using JSON.

Data Objects Overview

Data Objects allows you to send data to your apps in Jira and store that data in the context of your Apps so that you can use that data with the templating tools covered in Basic Dynamic Content.

This means your UI Components don't need to be manually changed when the data changes, they'll automatically update to show the latest data you've sent to the Data Object API.

Core Concepts

The first thing you need to do when implementing this functionality is reverse the order you would normally think about this kind of solution.

The way an App or front-end widget would normally work is that it would make a request to an API to get the data it needs, and then display that data in the product.

Traditional Integration Style

This is nice and simple, but it has a range of issues that make it not ideal for the kind of use-case that we're dealing with here:

• Security: You don't want to expose your internal tool's API to the public internet (especially if that tool is behind a firewall),
  • Instead, you really want those internal systems to be in control of data sharing, and be the one's initiating the sharing process. For example, by pushing data OUT of your internal systems when it changes, rather than having an external system PULL it in.
• Performance & Load: If you have a lot of users, and they're all making requests to your internal systems every time they open a Jira issue, you're going to put a lot of load on those systems.
  • Instead, you want to be able to cache data, and only update it when it changes, rather than having to re-fetch it every time a user loads the page.

App Maker is built to solve these problems by allowing you to PUSH data into your Apps, rather than having your Apps PULL data from your internal systems.

---

Example Workflow:

• We're going to extend the example from Basic Dynamic Content, but we're going to tweak it a bit to provide a more realistic use-case.
• The use-case we're going to cover is displaying a live "System Status" widget in your Jira Issue Context Panel, that shows the current status of some external system.
  • For the purpose of this example, you will be playing the part of your monitoring system (e.g StatusPage), and you'll be pushing the current status of your systems into a Data Object stored in App Maker.

What You Will Need

• Admin access to your Jira site.
• Access to a basic API client (like HTTPie or Postman).

Creating the System Status UI Widget

• First, in your site, navigate to the App Maker settings page and start creating a new UI Component using the configuration below:
  • This will give us a nice "System Status" widget that we can populate data in to.

System Status UI Component

{
  "resourceType": "site",
  "module": "jira:issueContext",
  "title": "system_status_widget",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "System Status",
    "children": []
  }
}

Data Object Templating

• Next, we need to update the UI Component to allow us to template data stored in App Maker - for the example we're going to be showing the status of a set of Website and API services.
• Add two "FieldValue" components to the children array inside the "StackedInformationGroup".

Templating from Data Object into UI Component

{
  "resourceType": "site",
  "module": "jira:issueContext",
  "title": "system_status_widget",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "System Status",
    "children": [
      { 
        "type": "FieldValue", 
        "key": "Website", 
        "value": "{{dataObjects.site.system_status.website}}"
      }, 
      { 
        "type": "FieldValue", 
        "key": "API", 
        "value": "{{dataObjects.site.system_status.api}}"
      } 
    ]
  }
}

• Looking at the templated sections, you can see that we're using a new context for the data we're templating in.
  • Instead of referencing the jiraIssue context, we're now referencing the dataObjects context.
    • Within that context, we're specifying the "scope" we want to access data from (site), and then the "title" of the Data Object we want to access (system_status).
    • Finally, we're specifying the key of the field we want to access (website and api).
  • This will tell App Maker to find the site scoped Data Object with the title of system_status and inject the data stored in it into the FieldValue components.
• Press "Save" to add the UI Component in App Maker. if you open up a Jira issue you'll see the widget is created, but nothing is populated into the fields because we haven't set the Data Object yet.

Empty system status widget on Jira issue

Creating the System Status Data Object

• Now we need to create the Data Object in App Maker to store the current status of our systems.
• In Jira, head back to the App Admin page by clicking on the cog icon in the top-right of the screen, then selecting "Apps", and then "App Maker".
• On the "API's" tab, you'll see a list of URLs that are used to manage the different entities stored in your App Maker instance.
• One of those URLs will have the label Update Data Objects (POST), copy that URL and save it for later.

Managing Data Objects

• If you swap to the "Data Objects" tab, you'll see a list of all the Data Objects stored in your App Maker instance.
• As you can probably tell, it is possible to manage Data Objects via the App Maker UI, just like with UI Components.
• You can create, update, and delete Data Objects from the UI, but that is only useful when you want to manually manage the data in your Apps.
• For most use-cases, you'll be using the Data Object API to manage your Data Objects automatically.
• App Maker creates this API in your Jira site, and you can use it to manage your Data Objects automatically either from other systems, automations, or using Webhook Transforms.

• Open up your API client and create a new POST request, with the URL you just copied.
• The top level of the request body will have the following fields:
  • There is an "action": field, which should be set to "set".
  • A "resourceType": field, which should be set to "site".
  • And a "title": field, which should be set to "system_status".

POST Request Body

{
  "action": "set",
  "resourceType": "site",
  "title": "system_status"
}

TIP

Notice that the values for the "resourceType" and "title" fields match the first two values under dataObjects from our UI Component JSON (dataObjects.site.system_status)?

• This is how you tell App Maker where to store/find the data you're sending to the Data Object API.
• We'll go into more detail on all the different ways of storing data in the following sections.

• Now, create another field labelled "dataObject" and set its values as per the object below:

Adding data to the object

{
  "action": "set",
  "resourceType": "site",
  "title": "system_status",
  "dataObject": { 
    "website": "Online", 
    "api": "Offline"
  } 
}

---

• Hit "Send" to fire off the API request & update the Data Object in App Maker.
• You should get a response back from the API that includes the line "outcome": "data-object-updated".
• Now head back to the Jira issue and refresh the page.
• You should now see your "System Status" widget displaying the values you set via the Data Object API.

System Status Widget with Data

Updating the System Status Data Object

• Go back to your API client, update the "api": value to "Online", and hit "Send" again.

Updating the Data Object

{
  "action": "set",
  "resourceType": "site",
  "title": "system_status",
  "dataObject": { 
    "website": "Online", 
    "api": "Online"
  } 
}

• Now head back to Jira & refresh the page. You should see that your widget has already updated, and the "API" status is now showing as "Online".

Updated System Status Widget

Removing Data Object via API

• You might have noticed that the body of the request sent to the Data Object Update API is very similar to the one we used to create the UI Component via the UI.
• This is because all Entities in App Maker can actually be managed via the API, and the object you include in the body of the request is the exact same object as the one you would configure in the UI.
• In fact, all the UI does when managing Entities is send requests to the API on your behalf, this includes when you press the "Delete" from the lists in the UI.
• In that scenario, the UI simple sends a request to the Entity Update API with the action set to "delete".
• This is obviously something you can do yourself as well using your own API client (or an API request from another system).
• Go back to your API client request where you updated the Data Object, update the action to "delete", and then hit "Send".
• If you go back to the App Maker settings area in Jira and then open the Data Objects tab, you should see that the Data Object has been removed.

Deleting the Data Object

{
  "action": "delete",
  "resourceType": "site",
  "title": "system_status",
  "dataObject": {
    "website": "Online",
    "api": "Online"
  }
}

---

---

Advanced Use-Cases

---

---

The example we've covered here is a very simple use-case, but the power of Data Objects comes from the flexibility they provide for storing and accessing data in your Apps.

Data Object Scoping

• Data Objects can be stored and scoped at different levels within your Jira site.
  • You can scope data to the "site", "project", or "issue" level, and you can store multiple pieces of data at each level by using different "title": values.
    • Within a given resourceType each piece of data must be stored under a unique title.
    • Note that "project" and "issue" scoped data also needs a resourceKey value to specify which resource the data is scoped to.
    • The title property only needs to be unique within the context of a specific "project" or "issue".
  • When a UI Component is displayed and the Data Object templated into it, App Maker will automatically inject the correct data based on the "project" or "issue" context the UI Component is being displayed in.
    • For example, Data Objects stored with a resourceType of "project" and a resourceKey of "ABC" will only be available to a UI Component displayed in the context of a Jira Project with the key "ABC".

Scoped Data Example

Note that even though the UI Component has a "resourceType" of "site" it will still be able to access Data Objects stored at the "project" and "issue" levels, as long as the UI Component is being displayed in the context of the correct Jira project/issue.

This allows you to use a single "Site-level" UI Component and dynamically template different data into it based on the Project or Issue it's being rendered inside of (note, you can also store Data Objects at the "site" level if you want to share a single piece of data across the entire site).

Data Object scoped to the Project with a key of "ABC"

// Data Object
{
  "action": "set",
  "resourceType": "project",
  "resourceKey": "ABC",
  "title": "project_system_status",
  "dataObject": {
    "message": "I will only be accessible by UI components in the context of project ABC",
  }
}

UI Component that displays anywhere in the site, but references data from whichever project it's being displayed in

// UI Component
{
  "resourceType": "site",
  "module": "jira:issueContext",
  "title": "system_status_widget",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "Test Info Group",
    "children": [
      {
        "type": "FieldValue",
        "key": "Message",
        "value": "{{dataObjects.project.project_system_status.message}}"
      }
    ]
  }
}

Next Steps

• OK! You've learned how to use Data Objects to store and access unique pieces of structured data in your Apps.
• This is great, and can be very powerful, but it's still not enough to cover all of the use-cases you might need.
• In particular, Data Objects rely on the data being sent to App Maker already being in the right "shape" so that it can be stored in an object and then templated into a UI Component, but the reality is, that's rarely the case.
• To solve this, we're going to dig into the second-last major component of App Maker, Webhook Transforms.
• This next section will show you how you can transform the data from incoming webhooks into whatever shape you want it to be.
• This enables you to set up webhooks from other tools, aimed at App Maker, and then transform the data they send into the shape you want to store in a Data List or Object.