Last updatedSep 18, 2020

Rate this page:

Part 1: Build a Confluence hello world app

This tutorial walks through creating a Forge app to display content on a Confluence page.

There are three parts to the tutorial:

  1. This page: describes creating, changing, and installing a simple hello world app. The focus is on learning the CLI commands needed to work with apps.
  2. Call a Confluence API: describes how to make API calls to Confluence with Forge and use the tunnel command.
  3. Change the frontend with Forge UI: describes how to use the Forge UI components.

We recommend you work through all three parts to get a good understanding of how to develop apps with Forge.

Before you begin

Complete Getting started before working through this page.

Create your app

Create an app based on the Confluence macro template.

Note, Forge provides multiple environments where you deploy the app. This tutorial uses the CLI default, the development environment. See Environments to learn more.

Note, the CLI uses keychain to securely store your login details. If you see a prompt for keychain access when running a command, approve it to allow the CLI to run the command.

  1. Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there.
  2. Create your app by running:

    1
    forge create
    1. Enter a name for your app. For example, hello-world-app.
    2. Select the confluence-macro template.
    3. Change to the app directory to see the app files.

The CLI displays the following error after running forge create if you don't have the permissions required to create Forge apps:

1
Error: Account does not have app creation enabled...

To get the required permissions, reach out to the #help channel in the Forge Slack and provide the error message and your email address.

confluence-macro template

The confluence-macro template uses Node.js and has the following structure:

1
2
3
4
5
6
7
hello-world-app
|-- src
|   `-- index.jsx 
|-- manifest.yml
|-- package.json
|-- package-lock.json
`-- README.md

Let’s have a look at what these files are:

  • index.jsx: Where you write the behavior of the app.
  • manifest.yml: Describes your app. The manifest contains the name and ID of the app, the app permissions, and the modules the app uses. This app displays a macro on a Confluence page and has a function that provides the contents of the macro.
  • package.json: The app’s Node.js metadata. See the Node documentation for more information.
  • package-lock.json: Records the version of the app’s dependencies.
  • README.md: Information about the app. We recommend updating this as you change the behavior of the app.

Change the macro title

This app displays content within a Confluence page using a macro. Confluence shows the title of the macro in the quick insert menu when you add the app to a page. Let's change the title to include your name.

  1. In the app’s top-level directory, open the manifest.yml file.
  2. Find the title entry under the macro module.
  3. Change the value of title to Forge app for <your name>. For example, Forge app for Mia.

Your manifest.yml file should look like the following, with your values for the title and app ID.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
permissions:
  scopes:
   - 'read:confluence-content.summary'
modules:
  macro:
    - key: hello-world-app-hello-world
      function: main
      title: Forge app for Mia
      description: Inserts hello world!
  function:
    - key: main
      handler: index.run
app:
  id: '<your app id>'
  name: hello-world-app

Deploy and install your app

Any time you make changes to the code, deploy your app using the forge deploy command. This command builds your code and reports any compilation errors.

To install your app on a new site, run the forge install command. Once the app is installed on a site, it will automatically pick up all minor app deployments, which means you don't need to run the install command again. A minor deployment includes any change that doesn't modify app permissions in the manifest.

In the Forge development environment, your app is deployed with all available OAuth scopes. Later in this tutorial, you’ll learn how to restrict your app to request just the access it needs.

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    forge deploy
  2. Install your app by running:

    1
    forge install
    1. Select your Atlassian product using the arrow keys and press the enter key.

      Note: Running forge install command installs your app in all available Atlassian products on the site. You don’t need to run the command for each product.

    2. Enter the URL for your development site. For example, example.atlassian.net.

    3. Open the authorization URL in your default browser from the CLI by pressing any key.
    4. Review the app's requested access.
    5. Select your Atlassian cloud site from the Authorize for list, then select Accept.

Note, you need to run forge deploy before running forge install in any of the Forge environments.

View your app

With your app installed, it’s time to see the app on a page.

  1. Edit a Confluence page in your development site.
  2. Open the quick insert menu by typing /your macro title on the page. Once you start typing the title /Forge app for, the macro with your name will appear in the quick insert menu.
  3. Select your macro from the menu to add it to the page.
  4. Publish the page.

Your hello world app is now installed into your development site. The app should display on the page like the image below.

The app displayed in a Confluence page

Note, while your app is deployed to either a development or staging environment, (DEVELOPMENT) or (STAGING) will appear in your app title. This suffix is removed once you've deployed your app to production.

Next step

See Part 2: Call a Confluence API to learn how to call a product API from your app.

Rate this page: