Atlassian (Jira) Integration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/module/atlassian/atlassian.service.ts
• apps/api/src/services/atlassian/atlassian.api.service.ts
• apps/extensions/src/app/services/api/messages.ts
• apps/portal/app/services/api/messages.ts
• apps/extensions/src/content/components/shared/CreateJiraTicketModal.tsx
• apps/portal/components/shared/CreateJiraTicketModal.tsx
• apps/extensions/src/content/panel/screens/imagesScreen/pages/integrations/JiraPage.tsx
• apps/portal/components/pagesComponents/integrations/Jira.tsx
• apps/api/src/module/atlassian/atlassian.controller.ts

The Atlassian integration for Ever Rec allows users to connect their Jira account to the platform. This enables them to create Jira issues directly from screen captures and recordings within the Ever Rec web portal and browser extension. The integration handles OAuth 2.0 authentication, fetches user-specific Jira project data (like projects and issue types), and facilitates the creation of issues with attached images or videos.

This functionality streamlines the workflow for users who use Jira for project management and bug tracking, allowing them to report issues or share visual context without leaving the Ever Rec application. The integration also includes Trello functionality, which is part of the Atlassian suite.

Architecture Overview

The Atlassian integration is built upon a client-server architecture involving the Ever Rec frontend (Portal/Extension), the backend API, Firebase for data storage, and the external Atlassian API.

• Frontend (apps/portal, apps/extensions): Provides the user interface for connecting/disconnecting a Jira account and a modal for creating Jira issues from images or videos.
• Backend API (apps/api): A NestJS module that orchestrates the entire integration. It manages the OAuth flow, securely stores credentials, and communicates with the Atlassian REST API.
• Firebase: Used as the database to store user-specific Atlassian API credentials (access and refresh tokens).
• Atlassian API: The external service that provides authentication and endpoints for interacting with Jira data.

The following diagram illustrates the high-level component interaction.

Backend Services

The backend logic is split into two main services to separate business logic from direct API interaction.

Authentication Flow (OAuth 2.0)

Connecting a Jira account uses the standard OAuth 2.0 authorization code grant flow. The backend initiates the process and handles the callback from Atlassian to securely store the user's tokens.

The sequence diagram below details the authentication steps.

User Data Storage

Upon successful authentication, the user's Atlassian credentials and profile information are stored in the Firebase Realtime Database under the path users/{uid}/jiraAPISCredentials.

The stored object has the following structure:

{
  "credentials": {
    "access_token": "...",
    "refresh_token": "..."
  },
  "email": "user@example.com",
  "account_id": "...",
  "picture": "..."
}

Sources: apps/api/src/module/atlassian/atlassian.service.ts:198-207

Creating a Jira Issue

Once authenticated, users can create a Jira issue with an Ever Rec image or video as an attachment.

Data Fetching for Modal

Before creating an issue, the frontend fetches all necessary data to populate the "Create Jira Ticket" modal. This includes the user's accessible Jira resources, projects within those resources, and available issue types for each project.

This is handled by the GET /api/v1/atlassian/jira/project/data endpoint. The backend retrieves the user's access token, checks for expiration, and makes a series of calls to the Atlassian API to gather this hierarchical data.

Sources: apps/api/src/module/atlassian/atlassian.service.ts:241-294, apps/extensions/src/content/components/shared/CreateJiraTicketModal.tsx:43-47

Issue Creation and Attachment Flow

The following diagram shows the process of creating a Jira issue with an attachment.

API Endpoints

The AtlassianController exposes several endpoints under the /api/v1/atlassian prefix to manage the integration.

Method	Path	Description
GET	/jira/sign-in	Generates and returns the Atlassian OAuth URL to initiate the authentication flow.
GET	/jira/complete-oauth	The callback URL for Atlassian to redirect to after user authorization. Handles token exchange.
DELETE	/jira/sign-out	Disconnects the user's Jira account by deleting their credentials from the database.
GET	/jira/project/data	Fetches all accessible Jira resources, projects, and issue types for the authenticated user.
POST	/jira/create/issue	Creates a new Jira issue and attaches a corresponding image or video.
GET	/trello/sign-in	Generates and returns the Trello OAuth URL.
POST	/trello/complete-oauth	Handles the Trello OAuth callback to save the user's token.
DELETE	/trello/sign-out	Disconnects the user's Trello account.
GET	/trello/project/data	Fetches Trello boards and lists for the authenticated user.
POST	/trello/create/issue	Creates a new Trello card with an attachment or link.

Sources: apps/api/src/module/atlassian/atlassian.controller.ts, apps/extensions/src/app/services/api/messages.ts:79-107

Configuration

The Atlassian integration requires the following environment variables to be set in the backend (apps/api/.env.dev or .env.prod).

Variable	Description
JIRA_CLIENT_ID	The Client ID of the Atlassian OAuth 2.0 application.
JIRA_CLIENT_SECRET	The Client Secret of the Atlassian OAuth 2.0 application.
API_BASE_URL	The base URL of the Ever Rec API, used to construct the redirect URI.
WEBSITE_URL	The base URL of the Ever Rec web portal.
TRELLO_KEY	The API key for the Trello integration.

Sources: apps/api/src/services/atlassian/atlassian.api.service.ts:33-43