Learn
Integrations

The Confluence page picker

The Confluence page picker is a powerful integration feature within the Weavy framework, designed to enhance the user experience by enabling seamless interaction with content stored on a Confluence site.

By integrating the Confluence page picker into Weavy, users gain the ability to preview and edit Confluence pages in an embedded view, without the need to navigate away from their current workspace.

Setup guide

Setting up the Confluence page picker involves a few configuration steps. You need to Create an OAuth app in the Atlassian Developer Console, Configure the Weavy environment, Enable the feature in the @weavy\uikit-react, and optionally Enable the Embedded Pages component from Confleunce to fully integrate with the embedded preview and edit capabilities.

1. Create and configure the OAuth client for the Confluence page picker

Adding an OAuth 2.0 integration for Atlassian involves creating an OAuth 2.0 app in the Atlassian Developer Console, configuring the app, and obtaining the necessary credentials. Below is a step-by-step guide on how to add it:

1.1 Create a Developer Account:

If you don't have an Atlassian Developer Account, create one by visiting the Atlassian Developer website.

1.2 Log in to the Developer Console:

Once you have an account, log in to the Atlassian Developer Console.

1.3 Create a New App:

Click on the "Create" button and select "OAuth 2.0 integration" to start creating a new app. Give your app a name and agree to the terms.

1.4 Add scopes:

Go to "Permissions" and click the "Add" button for the "Confluence API". Then click "Configure".
Click "Granular scopes" and "Edit Scopes", then select the following scopes:
- View detailed contents read:content:confluence
- View content details read:content-details:confluence
- View space details read:space-details:confluence
- View pages read:page:confluence
- View space details read:space:confluence

1.5 Configure Authorization:

Go to "Authorization" and click "Add" for the "OAuth 2.0 (3LO)" authorization type.
Fill in the Callback URL which would be https://[your-weavy-environment-url.io]/confluence/auth

1.6 Gather necessary configuration properties

On the "Settings" page, copy the following properties: ClientId, Secret
On the "Authorization" page, click "Configure" for the "OAuth 2.0 (3LO)" authorization type and copy the Granular Confluence API authorization URL. Remove the state parameter from the url. i.e remove state=${YOUR_USER_BOUND_VALUE}

2. Configure your environment in the Weavy Account Portal

Sign in to https://get.weavy.com
Select your environment
From the three-dot-menu, click on Configure environment
Add the copied property values from step 1.6 to the Integrations - Confluence fields.

3. Configure the front-end

The uikit-react weavy properties needs to be configured with the Confluence authentication url. Adding the url will enable the Confluence page picker button in the Weavy editor (Chat and Posts) and as an 'Add Files' option in the Files app.

...

export function App() {

    useWeavy({
        url: new URL(WEAVY_URL),
        tokenUrl: WEAVY_TOKEN_URL,
        confluenceAuthenticationUrl: 'https://authentication_url_from_step_2'        
    })

  ...
}

export default App;

4. Configure the Confluence embedded pages for Weavy (optional)

The Embedded Pages component from Confluence is a React component that allows 3rd party products to integrate Confluence pages in a product. It allows 3rd party product users to view and edit the page content within the same product context that they are working in. This promotes a “more powerful together” product experience and eliminates context-switching between the 3rd party product and Confluence.

The Weavy React UI kit can be configured to use this component by following these steps:

4.1 Prerequisites

Before you can use the Embedded Pages component, you need to reach out to the Atlassian support team and provide the domains you want to use the component on. You will also need to supply a product name that is an identifier requested from the Atlassian team. You will need this product name in step 2. For more information how to reach out to the Atlassian support team, please click here.

4.2 Configure Weavy

Update the Weavy options and specify the product name from step 1 in the confluenceProductName setting.

...

export function App() {

    useWeavy({
        url: new URL(WEAVY_URL),
        tokenUrl: WEAVY_TOKEN_URL,
        confluenceAuthenticationUrl: 'https://authentication_url_from_step_2',
        confluenceProductName: 'my_product_name'
    })

  ...
}

export default App;

5. Take it for a test run

Attach a Confluence page to either the Files, Chat or Feeds app and click on it for an embedded preview/edit experience.

Troubleshooting

When clicking on a Confluence page to preview it, I get a "No preview available" message. Make sure you have set the confluenceProductName option in step 2. When this setting is not set, the preview will not work and a link to the Confluence site will be avaialable instead.
When clicking on a Confluence page to preview it, I get an error saying "Refused to connect". Atlassian requires you to supply the domains where the Embedded Pages component should be displayed. Make sure you are testing the preview on a verified domain.