# HistoryPro documentation ## HistoryPro for Confluence **Take control of your page evolution with detailed changelogs and seamless Jira integration.** HistoryPro is a powerful macro designed for teams that need more than just standard versioning. It bridges the gap between your documentation in Confluence and your tasks in Jira, providing a clear, readable, and professional record of every significant change made to your pages. ### 🚀 Key Features #### 📝 Smart Version History Maintain a high-level record of all page changes. Unlike standard Confluence history, HistoryPro focuses on *why* changes were made, not just *when*. #### ✍️ Custom Changelogs Add descriptive notes to every version. Explain the context of updates so teammates and stakeholders can understand the evolution of the document at a glance. #### ⚡ Instant Version Comparison (Diff) Stop guessing *what* changed inside a document. HistoryPro replaces the tedious process of opening multiple comparison tabs with a lightning-fast, built-in difference viewer that work on simple click on a version number. * ⚡️ Zero Context Switching: View changes without leaving the history table or reloading the page. * 🎨 Visual Clarity: Instantly spot added content (highlighted in green) and removed content (highlighted in red). * zoom-in: Focus on specific paragraphs or code blocks that were modified, rather than scanning the whole document. #### 🔗 Deep Jira Integration Link your documentation changes directly to Jira issues. * **Automatic Status Tracking:** Displays real-time Jira task status (To Do, In Progress, Done) directly in the history table. * **Smart Preview:** See the issue summary instantly while creating a new entry. * **Bi-directional Reference:** Automatically creates a "mentioned in" remote link in your Jira issue back to the Confluence page. #### 👤 Author & Timestamp Tracking Every entry automatically records the contributor with a clickable link to their Confluence profile and a precise timestamp. #### 👁 View live baseline View a version of the page (requirement) that describes the behavior of a system in production based on the status of a Jira task. #### ⚡ High Performance & UX * **Instant Loading:** Optimized technology shows you the history table immediately, loading Jira details in the background. * **Theme Aware:** Fully supports both Light and Dark Confluence modes for a native look and feel. * **Responsive Design:** Works perfectly on any screen size, from large monitors to mobile devices. *** ### 🚀 Installation & Setup HistoryPro is a Confluence Cloud app available directly through the Atlassian Marketplace. Installation is simple and secure, requiring standard administrative privileges. #### Prerequisites * You must be a Confluence Administrator to install apps. * Your Confluence instance must be on the Cloud hosting plan (Server and Data Center are not supported). #### Step-by-Step Installation Guide There are two ways to install HistoryPro: directly from your Confluence instance or via the Atlassian Marketplace website. #### Option 1: Install via Confluence (Recommended) 1. Log in to your Confluence instance. 2. In the top navigation bar, click on Apps and select Explore apps. 3. In the search bar type `HistoryPro`. 4. Locate the HistoryPro tile in the search results. 5. Click on the Try it free button (to start a 30-day trial) or Get it now. 6. A confirmation modal will appear listing the required permissions. Click Start free trial to proceed. 7. Wait for the "Installed and ready to go!" message. #### Option 2: Install via Atlassian Marketplace 1. Visit the [HistoryPro Marketplace Listing](https://marketplace.atlassian.com/apps/587003798/historypro) 2. Click the yellow Get it now or Try it free button. 3. If you are logged into multiple Atlassian sites, select the specific cloud site where you want to install the app. 4. Click Install. *** #### Enabling Jira Integration To unlock full traceability and link Jira issues to specific document versions, you must authorize the connection between the application and your Jira instance. 1. Access App Management: Navigate to the Confluence administration menu by selecting Apps > Manage your apps in the top navigation bar. 2. Locate the Application: Find HistoryPro in the list of "Connected apps" 3. Open App Details by clicking on "View app details" 4. Go to the "Connections" section 5. Authorize the Connection: Click the Connect to Jira button and follow the prompts to grant the necessary permissions for data synchronization. #### Post-Installation Verification Once installed, HistoryPro is immediately available to all users in your Confluence instance. No global configuration is required. To verify the installation: 1. Go to any Confluence page. 2. Type `/historypro` in the editor or select Insert (`+`) > View More > Search for HistoryPro. 3. Insert the macro. 4. If the macro loads and displays the version history table, the installation was successful. *** #### App Permissions & Security HistoryPro is built on Atlassian Forge, meaning it runs within Atlassian's secure infrastructure. We adhere to the principle of "Least Privilege". The app requires the following scopes to function: | **Permission Scope** | **Why we need it** | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read:confluence-content` | Required. To fetch page history, versions, and existing content metadata for comparison. | | `read:jira-work` | Optional but recommended. To search for Jira issues and display their current status (e.g., "Done", "In Progress") in the history table. | | `write:jira-work` | Optional. To create remote links between Jira issues and specific Confluence page versions. | | `storage:app` | Required. To securely store your custom changelogs (comments) and metadata. Note: We do not store the actual page content, only the metadata associated with the history. | #### Troubleshooting * "I don't see the app in the menu": Ensure your Confluence plan allows third-party apps and that your subscription is active. * "Jira data is missing": If you cannot see Jira issue details, please ensure your Jira and Confluence instances are linked, and you have granted the app access to your Jira site during the initial prompt. *** ### 📖 User Guide #### 1. Adding the Macro 1. Edit your Confluence page. 2. Type / and search for **HistoryPro**. 3. Insert the macro at the top or bottom of your document. #### 2. Recording a New Change 1. Enter **Edit mode** on the Confluence page. 2. In the HistoryPro macro block, you will see a highlighted **"NEW"** row:
3. **Changes:** Enter a brief description of what you updated.
4. **Task:** (Optional) Type a Jira issue key (e.g., PROJ-123). The macro will show a preview of the task.
5. Click **"Save History"**.
6. **Publish** your page using standard confluence function. The macro will automatically assign the correct version number to your entry. #### 3. Viewing & Comparing Versions * **Compare Changes:** Click on any version number (e.g., v5) to open the standard Confluence "Diff" view, comparing that version with the previous one saved via macro (not previous by number).
* **View Task:** Click on the Jira task key to open the issue in a new tab.
* **User Profile:** Click on an author's name to view their profile. #### 4. View live baseline Click on the corresponding button and a new tab will open with the version of the page that corresponds to what is in production.
#### 5. Managing Entries * **Delete:** If you made a mistake, enter Edit mode and click the **×** button next to the entry to remove it.
* **Import:** Use the "Import" button in Edit mode to bulk-load historical data using a simple JSON format.
### 🎨 Screenshots #### Light Theme
#### Dark Theme
#### Confluence page linking to Jira task
*** **Made with ❤️ for better Confluence documentation** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://denlad.gitbook.io/historypro/historypro-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.