/
๐Ÿง‘โ€๐Ÿ’ป Technical Specifications

๐Ÿง‘โ€๐Ÿ’ป Technical Specifications

Engineered for simplicity. Powered by Jira APIs.

โš™๏ธ Core Technologies

Flow Time Report is built using:

  • Atlassian Forge (Cloud Runtime)

  • React with Forge UI Kit

  • Jira REST API v3 for issue data

  • Issue Properties API for metadata persistence

  • Changelog Expansion API for full status history

๐Ÿงฌ Architecture Overview

A lightweight app built with Forge, fetching issue history and rendering interactive UI directly in Jira.

๐Ÿ” How It Works (Step by Step)

  1. App opens in Jira issue view
    โ†ณ The app loads inside the issue panel using Forge UI (@forge/react)

  2. Gets context of the current issue
    โ†ณ Reads the issue key from the page

  3. Fetches issue data from Jira
    โ†ณ Uses REST API to get issue details and changelog (/issue?expand=changelog)

  4. Parses the status history
    โ†ณ Builds a timeline of status transitions with timestamps

  5. Calculates duration for each status
    โ†ณ Measures time between entering and leaving each status

  6. Renders the UI
    โ†ณ Shows the status flow, table with times, and badge selector

  7. Saves badge selections (optional)
    โ†ณ Stores custom control badges (On Track, At Risk, Overdue) in issue properties

๐Ÿ“ก APIs Used

API Endpoint

Purpose

API Endpoint

Purpose

/rest/api/3/issue/{key}

Fetch issue data and status

/rest/api/3/issue/{key}?expand=changelog

Get full transition history

/rest/api/3/issue/{key}/properties/badge-metadata

Read/write badge data

๐Ÿ’พ Data Storage

Flow Time Report does not store any data externally.
All metadata is stored securely inside the issue via the Jira Issue Property API:

{ "badge-metadata": { "To Do-0": "ontrack", "In Progress-1": "atrisk" } }

๐Ÿš€ Performance

  • Loads changelog on demand (only once per issue)

  • Uses efficient in-memory state for calculations

  • Virtualized DynamicTable for large transitions

  • Lightweight badge updates via PUT requests

๐Ÿ›ก Security

  • Complies with Atlassian Forge security sandbox

  • Only interacts with the issue where the app is loaded

  • Read-only access except for saving badge metadata

  • Fully OAuth2-authorized within your Jira instance

๐Ÿงช Test Coverage

  • Status parsing logic (unit tested)

  • Duration calculations (edge case tested)

  • Badge save/load logic (verified via REST)

  • Export format functions (CSV, JSON, MD, TXT)

๐Ÿงฐ Dev Environment

  • Forge CLI v11+

  • Node.js 18+

  • Linting with ESLint

  • UI preview in forge tunnel