Getting Started

Installation

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
• A free API client like HTTPie.io or Postman.

1. Get Your UI Update URL

TIP

This is the URL you'll use to create and update the UI for all your apps.

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.
   • Choose App Maker from tab menu underneath the Custom Apps heading.
2. Locate your unique UI Update URL underneath the UI URLs heading at the top of the page.
3. Click the field to copy the URL. Save it for later use.

App Maker Settings: This page contains all of your URLs for App Maker.

2. Create Your First App

NOTE

While we use HTTPie.io in our examples below, any tool capable of API requests can be used.

1. Head to HTTPie.io and login.
2. Click the + icon in the top-left corner to create a new request.
3. Set the request type to POST.
4. Add the UI Update URL to the URL field.
5. Underneath the URL field, select Params and change this to Body.
6. Ensure the body type is set to Text.
7. Ensure the data type is set to JSON.
8. Paste the JSON below into the body field.

{
  "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"
      }
    ]
  }
}

9. Finally, press Send.
10. All done! You should now see a 200 OK success response. If using HTTPie.io, your screen should look like this:

API Client: A 200 OK successful response, meaning that your app is now deployed!

3. View Your New App in Jira

1. Navigate to Jira.
2. Open an Issue in any project.
3. Notice the panel on the right side of the Issue.
   • This is the Issue Context Panel, where your app will be displayed.

TIP

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

{
  "resourceType": "site",
  "module": "jira:issueContext", 
  "title": "my-first-app",
  "action": "set",
  "componentData": {
    "type": "StackedInformationGroup",
    "title": "My Stacked Info Group",
    "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.

Jira Issue Context: An example of your new app.

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 your chosen API client or HTTPie.io where you completed building your first app.
2. In the request body, add a second object under children with a:
   • type of "FieldValue"
   • key of "Field Two"
   • value of "Value Two"
3. Your request body should now look like this:

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

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

Jira Issue Context: An example of your new app displaying the additional content.

Deleting Your First App

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 your chosen API client or HTTPie.io where you completed building and updating your first app.
2. In the request body, change the value to the action field from set to delete.
3. Leave the rest of the request body the same.
4. Your request body should now look like this:

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

5. Press Send.
6. Return to your Jira Issue and refresh the page.
7. You should see that your app has now been removed!

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.