The BYOD macro works on any Confluence page.
Users will get sent to the integration's permissions page to authorize BYOD.
Each integration has modules that users can add to their dashboard and customize.
(Press play on video above) Modules can be resized and moved around for each team to customize their dashboard.
BYOD (BYOD) is a Confluence macro built on the Forge platform that allows business teams to create customizable dashboards within a Confluence page, by pulling in data from their company's 3rd party integrations like Stripe, Quickbooks, and more. The best part: no coding required!
You can try BYOD on our Confluence demo site using the login details in the "Testing instructions for application" section of the Devpost submission form.
The Problem: Business Data is Siloed
For this hackathon we talked to dozens of business teams that use Confluence (including ourselves!) and we heard the same thing again and again:
"Confluence is our team's central repository of information, but we also need to access revenue data from Stripe, cashflow data from Quickbooks, and customer lead data from Salesforce."
Since there isn't an easy way to aggregate all that data, each team member needs to log in to each of those external sites, and email each other when they need to communicate about the data. This is a huge friction to team collaboration!
Our Solution: Bring the Business Data into Confluence
BYOD allows users to authorize and integrate all these external data sources through APIs, and pull that data into Confluence in a customizable, personalized dashboard.
With BYOD on Confluence:
- Better collaboration: The entire team can view the same data at the same time (including updates) so collaboration becomes much more efficient and less error-prone.
- Less logins needed: Since one team member can setup the integration on BYOD, teams don't need individual logins for each team member, greatly reducing security vulnerabilities.
- No more stale data! The data in the BYOD dashboard updates in realtime from those external sources, meaning the Confluence page with the BYOD macro is always up to date.
How to use BYOD
Step 1: Insert BYOD on any Confluence page
Once the macro is installed on the team's Confluence site, it's available as a simple slash command on any Confluence page. An added benefit of being a Confluence macro is that site admins can restrict access to specific people to see a page that BYOD is on, so only authorized team members can view the data on BYOD's dashboard.
Step 2: Connect 3rd party integrations
Once the BYOD macro is on a Confluence page, team members can simply click the "+ Add" button to connect BYOD to an external data source like their Stripe account.
BYOD is built on the OAuth 2.0 framework to securely integrate with each 3rd party app. When the user wants to connect an integration, they're taken to the app's website to login and authorize BYOD to access their data on those services.
Step 3: Add modules to the dashboard!
Once an integration is connected, BYOD has built-in modules that users can add to their dashboard. Each module can be dragged, resized, and moved around to create a truly personalized dashboard for each team.
The app currently supports integrations from Stripe and Quickbooks, but we have many more integrations planned, each with even more module types to add to the BYOD dashboard.
How we built it (technical overview)
Without Forge, BYOD truly could not have been built within the timeframe of this hackathon. Under the hood, BYOD uses multiple Forge APIs:
|Custom UI (@forge/bridge)
|The frontend of the app uses Forge's Custom UI framework, and communicates with Forge's backend FaaS functions through a Resolver (more below).
|The resolver functions handle saving/retrieving from Storage, handling redirects from OAuth authorization flows, and calling API endpoints for integrations.
|OAuth authorization URL
|When a user wants to add an integration, the
router.open() API opens the authorization url in a new tab.
|OAuth authorization callback URL
|webTrigger API (@forge/api)
|When a user authorizes BYOD, the integration provider (e.g. Stripe) sends an authorization code to a redirect url, which is a Forge webtrigger that exchanges that code for an access token.
|Dashboard layout saving/loading
|Storage API (@forge/api)
|Whenever the user adds a module to the dashboard, changes a module's configuration, or removes a module, BYOD uses the Storage API to save the dashboard layout state so it can be restored on a new page load.
|Storing OAuth access tokens
|Storage API (@forge/api)
|When BYOD receives an access token for a user from an integration, it encrypts the token and saves it to storage, and decrypts it for use in an API call. We could have stored the tokens on our own external database, but we decided to keep the app more secure by storing the encrypted tokens internally. We are excited to see how the upcoming External Auth feature will help facilitate this in a more secure way!
The real power of Forge
There is no way we could have built such a complex application this quickly without leveraging Forge!
Here are just a few ways we supercharged our development speed using Forge:
- Skip worrying about infrastructure: We didn’t have to think about hosting our app or performing compute, and with the Storage API we didn’t even have to worry about setting up an external database!
- Reduce security vulnerabilities: Since our app ran in the Forge platform, we could rest assured that much of the security for our app would be taken care of by Atlassian. By utilizing the manifest.yml file and its permissions framework, we were able to whitelist only the URLs that we needed and nothing more.
- Quick iteration speed: By using Forge’s tunnel feature, we didn’t need to redeploy the app after each change, so we could develop the app very quickly before shipping to production.
- Tight integration with the Atlassian ecosystem: We wanted to include a “Create Jira issue” feature for BYOD, and it was insanely simple given Forge’s requestJira API. We’re excited to see how Forge’s extensibility capabilities grow going forward.
Challenges we ran into
Once we got the hang of Forge, it was incredibly easy to work with, but it did have a bit of a learning curve.
Since one of Forge's value propositions is maintaining app security, and the basis of our app is working with external integrations, most of our challenges were around getting the Forge platform to work with those 3rd party sources:
- Registering proper endpoint permissions: Using OAuth requires touching a lot of external endpoints: sending a user to each integration's authorization page, hitting each integration's token exchange URL to get an access token, and hitting each integration's API endpoint(s) for getting data once the user authorized BYOD. We had to keep track of all these endpoints and register them appropriately in the
manifest.ymlfile, which took a while to get used to.
- Persisting state: Since the backend is based on FaaS, and we didn't want to add a security risk by using our own backend database, we had to figure out how to persist state using the
storage api. Our app needs to save and load the dashboard configuration for each user as well as save access tokens for use in API calls; once we developed the proper schema to use with
storage, we were off to the races.
- Security around API secret keys: To use each external integration, we needed to set up a developer account and app with each integration provider (e.g. a Stripe developer account, Quickbooks developer account, etc), and we had API secrets for each of those providers to use in our app. We eventually were able to use the
environment variablesAPI from Forge to encrypt our secrets and deploy the app with those variables.
- Real-time dashboard updating: We wanted BYOD to update the data in its dashboard whenever it changed on the external integration (e.g., whenever a new customer was created on Stripe). Ideally, we could have a websocket connection to our backend FaaS functions to "listen" for updates from webhook events from each API provider, but since we were told that it wouldn't be possible, we had a workaround to constantly 'poll' our backend at a set interval.
Again, the External Auth feature will greatly help with handling these challenges, so we can't wait to use it!
What's next for BYOD
This hackathon was an inspiration for us and we’re eager to get BYOD ready for the Atlassian marketplace so Confluence users can use the app and develop powerful dashboards for their teams!
To that end, we’re focusing on:
- Building more integrations: For the hackathon we were able to build out integrations with Stripe and Quickbooks, but we’re focused on building even more.
- Locking down security: Security is top-of-mind for us, and we want to build out the infrastructure to safely store and use API secrets and OAuth access tokens for our users.
- Write access for modules: BYOD is currently a read-only dashboard, but since it’s an OAuth-based app, we want to allow Confluence users to write to their integrations as well. For example, teams can respond to Zendesk support tickets right inside the BYOD macro, or they can build internal tools to authorize expense reports through Expensify.
- Using webhooks + webtriggers: Right now the app polls each integration's API to update its dashboard, but we are working on setting up webhooks with each integration to be notified of data changes when they happen.
The External Auth feature will be incredibly useful for BYOD, so we're excited to incorporate that to greatly speed up integration development!