Building a custom app for Confluence with PandaDoc API

How I built PandaDoc for Confluence in 24 hours and won the Atlassian Codegeist Hackathon

I am Soumi, a Software Engineer and Technical Writer. 3 months ago together with my teammate, Souvik Biswas, we participated in the Atlassian Codegeist Hackathon to build Forge apps for Jira and Confluence.

Confluence and Jira are both commonly used at my workplace for updating technical documentation and generating bug reports. These two Atlassian products were quintessential for organized software development and collaboration inside and among different teams.

Together with Souvik, we agreed to build an app for Confluence as we both had used it a lot. And we wanted to integrate it with a product that solved a key problem combined with Confluence and also had good APIs and comprehensive documentation.

After some research, we picked PandaDoc to add eSignature capabilities and make it easy to sign documents without ever leaving Confluence.

So here is our story of how we built a custom app for Confluence using PandaDoc API in 24 hours and won the Most valuable Storytelling category prize in the Atlassian Hackathon. I have also added detailed instructions, using which you can also create your PandaDoc-Confluence app or any other such app in no time. Let’s go!

Codegeist Begins!

We first started by taking the tutorial to create a sample PandaDoc Forge app. The documentation and tutorials were good. We followed the tutorial to login, create and deploy our first Forge application. This was smooth, and the setup instructions were very clear as well. I published my first Confluence page on my site with the Forge app. I will walk through the steps I followed while creating the app. This is how you can create a Forge app too!

First, I created an Atlassian account and installed Node.js. I already had Docker installed on my system. I also created an API token to log into the forge CLI. You can get your token here and save it.

I installed the forge CLI by running nvm install -g @forge/cli from the terminal. I checked the version was 1.9.0 by running forge — version on my terminal. If you run into any errors, use forge — version to troubleshoot.

Next, I logged in by running forge login from the terminal. I proceeded to create an Atlassian Cloud developer site from here. This lets you install and test your custom app with Confluence. I created an app using a macro template from Confluence. Once you are in the directory where you want to create the app, type in forge create from the terminal. Specify a name, UI kit category and select the confluence-macro template. Enter the app directory and type in ls in the terminal to check the files created in a structure like this :

PandaDoc-app
| — src
| ` — index.jsx
| — package.json
| — README.md
| — package-lock.json
| — manifest.yml

PandaDoc API Reference

Once the initial app structure was created, it was time to go through the PandaDoc API thoroughly to understand how to integrate with Confluence to enable creating a document directly from the Confluence page with a slash command. The Postman API workspace was instrumental in understanding and executing the code and making API calls in the backend. A simple frontend was created to display the app ID and the document creation status.

The PandaDoc API reference was available here. There are three collections available :

1. Authentication — To get, create and update access tokens.
2. Documents API — To create and send documents.
3. Templates API — Get a list of templates.

Img source

Next, we used the API endpoints in our Forge app to create a PandaDoc document directly from Confluence. We will go through the existing files that were created during app creation and what changes we made to them here :

Index.jsx : You can add the app behaviour here. This is referenced from the PandaDoc Postman API docs. Modify and add your request body. This is our index.js code :

import ForgeUI, { render, Fragment, Macro, Text, Badge, Strong, useState } from “@forge/ui”;
import { fetch } from ‘@forge/api’;
const createDocFromTemplate = async () => {
 const body = {
 “name”: “Signature Doc”,
 “template_uuid”: “fQ9MKS9fuyb5ps38V5DZzW”,
 “recipients”: [
 {
 “email”: <MAIL ID>,
 “first_name”: <name>,
 “last_name”: <title>
}
 ],
 “tokens”: [
 {
 “name”: “Favorite.Pet”,
 “value”: “Panda”
 }
 ],
 “fields”: {
 “Favorite.Color”: {
 “value”: “PandaDoc green”
 }

Full code available on github.

Manifest.yml : Update your app name. In the modules, under macro, mention the appropriate key, title and function.

modules:
 macro:
 — key:PdandaDoc-app
 function: main
 title: PandaDoc
 description: Integrate PandaDoc with Confluence!
 function:
 — key: main
 handler: index.run
app:
 id: ari:cloud:ecosystem::app/8f4963ff-428c-4db5–8bb8-bb0871930b61
permissions:
 scopes: []
 external:
 fetch:
 backend:
 — api.pandadoc.com

Package.json : The Node.js metadata is to be mentioned here.

{
 “name”: “forge-ui-starter”,
 “version”: “1.0.0”,
 “main”: “index.js”,
 “license”: “MIT”,
 “private”: true,
 “scripts”: {
 “lint”: “./node_modules/.bin/eslint src/**/* || npm run — silent hook-errors”,
 “hook-errors”: “echo ‘\\x1b[31mThe build failed because a Forge UI hook is being used incorrectly. Forge UI hooks follow the same rules as React Hooks but have their own API definitions. See the Forge documentation for details on how to use Forge UI hooks.\n’ && exit 1”
 },
 “devDependencies”: {
 “eslint”: “⁶.5.1”,
 “eslint-plugin-react-hooks”: “².1.2”
 },
 “dependencies”: {
 “@forge/api”: “².3.0”,
 “@forge/ui”: “⁰.13.1”
 }
}

Updated the README.md file accordingly as well.

Install the PandaDoc app

To build and deploy the code use : forge deploy . We installed the app onto our Atlassian site by typing the command forge install into the terminal. Next, I selected the product and added our site URL. You can delete your app by running the forge uninstall command.

Testing the App

I opened the site and edited a Confluence page. I typed /Panda on the page. The macro appeared on the quick insert menu. I added it to my page and published it. Our PandaDoc app was successfully installed into our development site. Here is an image of the app displayed on the page:

Slash Command Usage (Img by author)

New Document created ( Img by author)

Then we went to our PandaDoc account and saw that a new document was successfully created.

Our App Development Plan

My teammate Souvik and I will be working on PandaDoc integration to improve and test it further. We also want to add more functionalities to the app. Once we are satisfied with the results, we will be launching it on the Atlassian marketplace.

Conclusion

Participating in Codegeist was a very interesting experience. We learned a lot throughout the hackathon. The Atlassian developer documentation was instrumental in getting the Forge app done and deployed on time. In addition, PandaDoc API documentation was straightforward, and it was very easy to integrate with the forge app.

If you need an app or integration that doesn’t exist, go ahead and create a custom app or let the developer community know by opening a Feature Request ticket in Jira. Cheers!

Important links

• Atlassian Documentation:Getting Started
• Atlassian Documentation: API tokens
• Atlassian Documentation: Cloud Developer Bundle
• PandaDoc Documentation
• PandaDoc Postman Collection
• PandaDoc Documentation: API Key Authentication Process
• PandaDoc Documentation: List Documents
• PandaDoc Documentation: List Templates