NEWS: Launch of Weavy + HubSpot Developer ResourcesRead more
Quickstart

Add Weavy to Jira using Atlassian Forge

This quickstart tutorial will show how to use our UIKit Web and add our building blocks as a Jira Issue Context template to your Jira installation using the Atlassian Forge platform.

Have Forge CLI ready, set the parameters to unlock the tutorial, and get started.

Don't have the parameters? Sign up for free, or sign in and set up your environment to get the parameters.

 Looking for Confluence?

1. Create a Forge app

This example creates a Forge app for Jira; the template used here is a Jira Issue Context.

Open a terminal and create new Forge app
forge create
  • Enter a name for the Forge app (preferably something with Weavy so it's easy to find later)
  • Select Custom UI as Category
  • Select Jira as Product
  • Select jira-issue-context as the template

2. Install the Weavy UIKit

Open up your project in VS Code or similar. The project consists of a server part (src/index.js) and a client part written in React (static/hello-world).

Open up a terminal and go to the /static/hello-world folder. Install the Weavy UI kit.

Run this in the /static/hello-world folder
npm install @weavy/uikit-web

3. Modify App.js

Open the App.js file located in the /static/hello-world/src folder. Paste and replace with the following code:
Modify App.js
import React, { useEffect, useState } from 'react';
import { invoke } from '@forge/bridge';
import { Weavy } from "@weavy/uikit-web";

function App() {  
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    const init = async () => {      
      const weavy = new Weavy();
      weavy.url = "WEAVY_URL";
      weavy.tokenFactory = async (refresh) => {
        return "USER_TOKEN";
      };

      setLoaded(true);      
    }

    init();
  }, []);

  if (!loaded) {
    return 'Loading...';
  }
  
  return (
    <div style={{height: '500px', overflow: 'auto'}}>            
      <wy-chat uid="wyuidchat"></wy-chat>      
    </div>
  );
}
export default App;
  • Line 3 - we import the Weavy UIKit
  • Line 11 - we set the URL to our Weavy backend; in this case WEAVY_URL. You can find this URL in your environment on your Weavy Account.
  • Line 13 - we have a pre-generated access token for a user, strictly for demo purposes.
  • Line 28 - we render the Weavy building block. You can easily change this to any building block in the parameters in the header of this page. See our docs for more information.

4. Modify manifest.yml

Forge requires some configuration in the manifest.yml for the app to have the correct permissions. Add the following at the end of the current manifest.yml file:
Add this to the end of the manifest.yml file
permissions:
  external:
    frames: 
      - "*.weavy.io"
    scripts:
      - "*.weavy.io"
    images:
      - "*.weavy.io"
    fetch:
      backend:
        - "*.weavy.io"
        - wss://*.weavy.io
      client:
        - "*.weavy.io"
        - wss://*.weavy.io
  content:
    scripts:
      - 'unsafe-hashes'
      - 'unsafe-eval'
      - 'unsafe-inline'
      - 'blob:'
    styles:
      - 'unsafe-inline'
  scopes:
    - read:jira-user

5. Build and Deploy

First, we need to build the React project. Go to /static/hello-world folder and run:
Run in the /static/hello-world folder
npm run build

If you make any changes to the React part, you must build every time before you re-deploy the Forge app.

The next step is to deploy the package to Atlassian. Go to the root folder of the project and run:

Run in the root folder of your project
forge deploy
When successfully deployed, the last part is to install it - if the macro is already installed add --upgrade to the install command. Select Jira when asked where to install it. Then enter your Atlassian URL - for example your-domain.atlassian.net.
forge install

6. Take it for a test run

Navigate to the Jira site - your-domain.atlassian.net - and verify that the app is working.

The jira-issue-context can be tested by creating a new issue (or selecting an existing one). The Weavy building block should be visible in the right-hand panel.

Unlock the tutorial by setting the parameters.
jira
NEXT

What's next?

This quickstart focused on the front end only, with a pre-generated access token impersonating a demo user.

The next step is to fetch the logged-in user in Jira, sync it with Weavy, and generate an access token so all of your users can start using our building blocks.