Rate this page:
This tutorial walks through creating a Forge app to display content on a Confluence page.
Complete Getting started before working through this page.
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.
Create your app by running:
1
forge create
Change to the app subdirectory to see the app files.
1
cd hello-world-app
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.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.
manifest.yml
file.title
entry under the macro
module.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
Any time you make changes to the code, deploy your app using the forge deploy
command.
This command builds, compiles, and deploys 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.
Navigate to the app's top-level directory and deploy your app by running:
1
forge deploy
Install your app by running:
1
forge install
Select your Atlassian product using the arrow keys and press the enter key.
Note: Running the forge install
command only installs your app onto the selected product.
To install onto multiple products, repeat these steps again, selecting another product each time.
Enter the URL for your development site. For example, example.atlassian.net.
View a list of your active sites at Atlassian administration.
Once the successful installation message appears, your app is installed and ready to use on the specified site.
Note, you need to run forge deploy
before running forge install
in any of the Forge environments.
With your app installed, it’s time to see the app on a page.
Your hello world app is now installed into your development site. The app should display on the page like the image below.
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.
See Part 2: Call a Confluence API to learn how to call a product API from your app.
Rate this page: