Basic Concepts

Before we dive into the details of building apps with App Maker, it's important to understand some core concepts.

Apps

Apps are the fundamental building blocks in App Maker. They are the top-level entities that contain everything about your creations, including their structure, data, and logic.

Managing Apps

You create and update apps by making an API call to a special API we add to your Atlassian product. This API call contains the JSON object that describes your app.

• You can do this manually using a tool like HTTPie.
• Alternatively, you can automate the process by using tools such as Automation for Jira, 3rd party automation tools, or your own custom scripts.

In the future, we plan to add the ability to create apps directly within App Maker's user interface.

App Scoping

When we say "scoping", we're talking about where and when your app is or isn't displayed within the Atlassian product. For example, you might want to show a custom UI widget only on Issues within a specific Jira project or on particular Jira Issues themselves.

App Maker provides very powerful tooling for scoping your apps, ensuring they appear exactly where you want them. This helps prevent cluttering the UI of your tools with unnecessary or irrelevant junk.

Apps have two primary levels that they are scoped at:

• "site": This is the highest level of scoping, meaning the app is shown everywhere in the product. Consider this a "Global" scope.
• "project": This intermediate level of scoping means the app is shown only within a specific project in the product (defined by its Project key).

Modules

TIP

Take a look at the modules reference for information on the different modules available in App Maker.

Modules are Atlassian's term for the locations within the UI where Apps can be displayed, such as issue sidebars, dialogs, or full-page views.

Each App you create with App Maker exists within a single Module, but each Module supports multiple Apps. We manage how all the different apps are displayed within each Module, so you don't need to worry about it.

Components

Apps in App Maker consist of Components added to the UI of your Atlassian product. These Components can be integrated into numerous areas of the product using the Modules we mentioned previously.

Component Structure

Components are organised in a hierarchical structure, with many Components supporting their own child components. You build the App you want by assembling Components like lego blocks, and App Maker handles the rest.

Components are defined using a JSON structure that describes their properties and the hierarchy of child Components that comprise them.

Pre-defined Components

App Maker has a pre-defined list of Components that can be used for building Apps, including guidelines on their structure and how they can be used. These Components are pre-styled by our team to seamlessly match the Atlassian Design System.

This approach makes it so easy for you to build apps that perfectly match the surrounding product, without worrying about styling or design. You can focus solely on the structure and logic of your app, confident that it will always look great and align with the rest of the product.

Heads Up

Want more information on the Components available in App Maker? Check out our Components reference!

Built-in Validation and Error Handling

Components also feature built-in validation and error handling to ensure proper usage. If you attempt to create a Component that doesn't make sense, App Maker will let you know and help you fix it in real-time.

Dynamic Content

Apps wouldn't be very useful if they were just static content that never changed. App Maker offers multiple ways to make the content shown to your users dynamic, allowing you to provide them with up-to-date information and real-time functionality.

Dynamic content can include:

• Data from Jira, Confluence, or other Atlassian products
• Information from 3rd party services
• Data from your own internal systems

Dynamic Content Scope

Similar to Apps themselves, dynamic content can also be scoped to ensure that different content is displayed in different contexts.

Examples of content scoping:

1. Site-level scope:
   • Show content to all users within an entire Atlassian product, such as a company-wide information banner or notification.
   • Every user across the site would see the same content.
2. Project-level scope:
   • Display content to all users within a specific project, like a release notification for upcoming or recent releases from that specific project.
   • Every user within the same project would see the same content.
3. Issue-level scope:
   • Present content to individual users based on the specific Jira Issue they're viewing, such as information retrieved from your CRM relating to the customer who raised a particular support ticket.
   • Every user would see content relating to different customers, depending on which Issue they're looking at.