Last updated Dec 8, 2021

Rate this page:

Get started building Compass apps

Welcome, developers! Ready to extend the power of Compass by writing your own integrations? 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? Reach out to our developer support team.

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

Compass is currently in Alpha. If you don't already have a Compass site, visit go.atlassian.com/get-compass to get started.

Install the Forge CLI

Follow the Forge getting started guide to install the Forge CLI in your local environment. This guide also shows you how to create a free developer site where you can deploy and test your apps.

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
forge create
  1. Choose the UI kit category and the compass-component-page template. Once your app has been created, you'll see confirmation that it's ready in a newly created directory.
  2. Go to the newly created directory and deploy your app with this command:
1
forge deploy
  1. When the deployment completes, install the app on your Atlassian site with this command:
1
forge install
  1. To see your app in action, open your Atlassian site in a browser and go to a Compass component page.
  2. Click the tab with your app's name in the left navigation and you'll see a new page displaying the text "Hello world!"
  3. Now try updating the file src/component-page.js and changing the "Hello world!" text to something else.
  4. Update your deployed app by running forge deploy again.
  5. 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.
  • Compass admin page adds a configuration page for your app where Compass admins can change app settings.
  • Web trigger adds a unique webhook URL by which your app can receive and reply to HTTP requests.

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

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
3
4
permissions:
  scopes:
    - 'read:component:compass'
    - 'write:component:compass'

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

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

1
forge install --upgrade

Call Compass APIs from your app

Your app can read and write data from the Compass API. Compass provides a GraphQL API Toolkit enabling Forge apps to do common API interactions such as reading and writing components.

For an example of how to use the GraphQL API Toolkit, see the Compass component details example 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
3
permissions:
  scopes:
    'storage:app'

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

1
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
3
4
5
6
7
8
9
10
11
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
{ "componentId": "your-component-id-here" }

In the request headers window, paste this code. Note that you'll need to use this header with all Compass requests, since the product is in early access:

1
{ "X-ExperimentalApi": "compass-beta" }

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! Please email the Compass developer support team and we'll be in touch shortly.

Rate this page: