Getting Started

---

Installation

App Maker for Jira is available with a 30-day free trial for all Jira sites.

1. Head to the App Maker For Jira listing on the Atlassian Marketplace.
2. Click the "Try it free" button in the top-right of the page.
3. Follow the prompts to install App Maker into your Jira Cloud instance.

Once you've installed App Maker into your Atlassian product, you're ready to start building your first app!

Build Your First App

What You Will Need

• Admin access to your Jira site

Create Your First UI Component

1. Navigate to the App Maker page in your Jira Settings section.
   • Click the settings cog icon at the top-right of your screen.
   • Select Apps under the Jira Settings heading and wait for the page to load.
   • Select Custom Apps from the left-side menu.
   • Click UI Components from tab menu underneath the Custom Apps heading.

App Maker settings page

2. Click New in the bottom-right of the page.

New UI Component Button

3. Take a look at the UI Component Editor.
   • On the left is the JSON editor, where you define the structure and content of your UI Component.
   • On the right is a live preview of the UI Component you're building.
   • Notice that there is a basic example JSON object already in the editor that you can use to get you started.

UI Component Editor

4. In the editor on the left, replace the example JSON with the JSON snippet below.

New UI Component JSON

{"resourceType": "site", "module": "jira:issueContext", "title": "my-first-app", "componentData": {"type": "StackedInformationGroup", "title": "My First App", "children": [{"type": "FieldValue", "key": "App Name", "value": "My First App"}]}}

---

5. Notice that there is an error displaying under the JSON Editor.
   • App Maker gives you real-time feedback to help you structure your Apps correctly.
   • This makes it easy to adopt and learn how to use the tool.
6. It's also a bit hard to read the JSON in the editor because it's all on one line.
   • Click the Format button at the top-left of the editor to format the JSON for easier reading.

Format JSON Button

6. Add an action property to the top-level of the JSON object with a value of "set" (see example below).
   • Note that the error should now disappear.

Code Snippet

{
   "action": "set",
   "resourceType": "site",
   "module": "jira:issueContext",
   "title": "my-first-app",
   "componentData": {
      "type": "StackedInformationGroup",
      "title": "My First App",
      "children": [
         {
            "type": "FieldValue",
            "key": "App Name",
            "value": "My First App"
         }
      ]
   }
}

9. Finally, press the Save button at the top-right of the Editor.
10. All done! You should now be redirected back to the UI Components page, where you can see your new UI Component called my-first-app listed.

UI Component List

View Your New App in Jira

1. Open a Jira Issue in any project.
2. Notice the panel on the right side of the Issue.
   • This is the Issue Context Panel, where your UI Component will be displayed.

TIP

Remember our JSON from before? The Module value sets where your UI Component will display!

{
  "resourceType": "site",
  "module": "jira:issueContext", 
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "My First App",
    "children": [
      {
        "type": "FieldValue",
        "key": "App Name",
        "value": "My First App"
      }
    ]
  }
}

4. You should see a section called Custom Apps.
5. Within that section, locate your new app called My First App.

Custom App in Jira

Updating Your First App

Now that you've finished building your first app, let's go and add some more content to it!

1. Return to the App Settings page where you completed building your first UI Component.
2. Select the UI Components tab, and click the "Edit" button on the row in the table for your app.

Edit UI Component Button

3. This will load the UI Component editor, with the JSON for your component on the left, and live preview on the right.

Editing existing UI Component

4. In the children list under componentData, add a second object with a:
   • type of "FieldValue"
   • key of "Field Two"
   • value of "Value Two"
5. Your UI Component JSON should now look like this:
   • The live-preview on the right should also update to show the new content.

Heads Up

• Each item in a JSON list needs to be seperated by a comma.
• Make sure you add a comma after the first object in the children list before adding the second object.

Code Snippet

{
  "resourceType": "site",
  "module": "jira:issueContext",
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "My First App",
    "children": [ 
      {
        "type": "FieldValue",
        "key": "App Name",
        "value": "My First App"
      },
      { 
        "type": "FieldValue", 
        "key": "Field Two", 
        "value": "Value Two"
      } 
    ] 
  }
}

---

6. Press Save again.
7. Return to your Jira Issue and refresh the page.
8. You should see that your app has now updated to include the new content!

Updated app in Jira

Deleting Your First UI Component

You probably don't want to have this demonstration app hanging around in your Jira forever, as fancy as it may be ✨, so let's do some cleaning.

1. Return to the App Settings page where you completed building your first UI Component.
2. Select the UI Components tab, and click the "Delete" button on the row in the table for your UI Component.

Delete UI Component Button

3. The table should refresh after a few seconds, and your UI Component should no longer be listed.
4. Return to your Jira Issue and refresh the page.
5. You should see that your app has now been removed!

Deleted app in Jira

Next Steps

Congratulations! ✨ You've just built, updated, and removed your first app using App Maker.

Now that you've got the basics down, you can start building more complex apps with multiple components, additional modules, and dynamic content.