Last updated Jul 22, 2024

Get started building Compass apps

Welcome, developers! Ready to extend the power of Compass by writing your own integrations? Have an another tool or data source you want to connect to Compass? You've come to the right place.

There are two ways to get started:

  • Use the Atlassian Forge developer platform to write and deploy apps in Compass. Forge apps run on Atlassian infrastructure and can call Compass APIs and customize the Compass user interface.

  • Call the Compass GraphQL API directly from your own application.

Need help? Checkout these helpful links or reach out on the Compass community.

Get started with the Forge platform for Compass

Here, we'll explore of creating Forge apps for Compass. Refer to the Forge documentation for a compete reference guide.

Get Compass

If you don't already have a Compass site, get started for free.

Install the Forge CLI

Follow the Forge getting started guide to install the Forge CLI in your local environment. This guide will walk you through getting an API token for your Compass site and help you with the forge login process which needs to be done before you can do the below.

Create your first Forge app

  1. Open a terminal and go to the directory where you'd like to put your source code.
  2. Run the following command:
1
2
forge create
  1. Enter a name for your app, e.g. "demo app".
  2. Choose the UI kit category and then Compass for the product.
  3. compass-component-page template. Once your app has been created, you'll see confirmation that it's ready in a newly created directory.
  4. Go to the newly created directory and deploy your app with this command:
1
2
forge deploy
  1. When the deployment completes, install the app on your Atlassian site with this command:
1
2
forge install
  1. Follow the instructions and enter the site you want to install the app on.
  2. To see your app in action, open your Atlassian site in a browser and go to a Compass component page.
  3. Click the tab with your app's name in the left navigation and you'll see a new page displaying the text "Hello world!"
  4. Now try updating the file src/component-page.js and changing the "Hello world!" text to something else.
  5. Update your deployed app by running forge deploy again.
  6. Refresh your browser to see the updated text.

Extend your app with modules

Forge modules let you extend the user interface and functionality of your app. Modules are defined in the file manifest.yml at the root of your project.

The module definition refers to a handler function for the module. For example, in the example app you created above, the handler component-page.run refers to the run function exported in the file src/component-page.js. Each time you add a module to your manifest, you'll add a corresponding handler function to your project.

Here are a few examples of useful modules for Compass:

  • Compass component page adds content to the Compass component details page. This is the module in the example app you created. Use this module for component-centric functionality or views.
  • Compass team page adds content to the Compass team page. Use this module for team-centric functionality or views.
  • Compass admin page adds a configuration page for your app where Compass admins can change app settings.
  • Compass data provider listens for link changes on Compass components and can be used to initialize metrics and events
  • Web trigger adds a unique webhook URL by which your app can receive and reply to HTTP requests. Use this with our events and metrics APIs to get activity from your other tools and systems into Compass!

See the Forge modules reference for a list of all the available modules.

The ability to access UI extensions in Compass depends on your user role. Product admins can access all extensions, while full users can access some extensions. Basic users can't access any extensions in Compass.

Add permissions to your app

Before your app can call Compass APIs, you'll need to add permissions to the manifest.yml file. For example, to enable your app to read and write Compass component data, you'll need to add these lines to your manifest:

1
2
permissions:
  scopes:
    - "read:component:compass"
    - "write:component:compass"

See the Forge permissions reference for a list of all the available permissions; Compass scopes here.

After updating the manifest to include new permissions, update your existing app installation with this command:

1
2
forge install --upgrade

Call Compass APIs from your app

Your app can read and write data from the Compass API if it has the correct permissions. Compass provides a GraphQL API Toolkit to simplify common operations like creating, updating, and deleting components. Get it with npm install @atlassian/forge-graphql.

For an example of how to use the GraphQL API Toolkit, see the Compass metrics and events ingestor sample app.

As an alternative, you can also make calls directly to the GraphQL API using the requestGraph method in the Forge product fetch API.

Store app data

Your app can store and retrieve its own data using Forge's Storage API. You'll need to declare this additional permission in your manifest.yml to use the Storage API:

1
2
permissions:
  scopes: "storage:app"

After updating the manifest to include new permissions, update your existing app installation with this command:

1
2
forge install --upgrade

Learn more about Forge

Now that you've learned the basics about the Forge platform, here are more helpful resources:

Get started with the GraphQL API

As an alternative to building a Forge app that runs within Compass, you may want to call the GraphQL API directly from your own application. The GraphQL API reference provides a comprehensive guide to Compass queries and mutations. You can use the API explorer to get acquainted with the Compass API.

Example GraphQL query

As a starting point, here's an example query that fetches data about a Compass component. In the API explorer, paste this code into the main query window:

1
2
query getComponent($componentId: ID!) {
  compass {
    component(id: $componentId) {
      __typename
      ... on CompassComponent {
        name
        type
      }
    }
  }
}

In the query variables window, paste this code, substituting an existing Compass component ID:

1
2
{ "componentId": "your-component-id-here" }

Now you can press the execute query button (triangle icon) at the top of the page. Details about your component will appear in the righthand window.

Contact our developer support team

Have a question? Need help developing your app? Working on an integration that you'd like to distribute more broadly? We'd love to hear from you! Hit the "Give Feedback" button at the top of Compass.

Rate this page: