Essential guide to Atlassian Forge modules for Jira

[#1]

Atlassian Forge provides various modules designed to extend Jira’s capabilities. You can explore these modules in more detail here: Atlassian Forge Modules for Jira.

This guide explains the high-level differences between various modules and offers a classification of all the modules from both a requirements and development perspective. If you prefer a video format, you can watch it on YouTube https://youtu.be/zVy05MVbbhE 

Classification Based on Business Requirements

Let's classify the key Jira modules available in Atlassian Forge according to business needs:

Custom Fields

1. Custom Field: Adds a new custom field to Jira issues, enabling the storage and display of additional data specific to your needs.

2. Custom Field Type: Extends the Custom Field module by defining new types of custom fields with specific behaviors and validation rules. Unlike the Custom Field module, which creates a single custom field, the Custom Field Type module allows for multiple custom fields with varied configurations.

Pages

1. Admin Page: Creates custom admin pages within Jira for configuring or managing app settings, accessible only to Jira Admins.

2. Global Page: Adds global pages accessible from the Jira navigation (under the “Apps” menu), usually for app-wide settings or information.

3. Project Page: Adds custom pages to specific projects for project-specific configurations or information displays.

4. Project Settings Page: Creates new pages within the project settings area for configuring project-specific options for the app.

Issue View Extensions

1. Issue Action: Adds new actions to Jira issues to enable custom workflows or automation directly from the issue view.

2. Issue Activity: Displays custom activities in the issue activity stream, providing a record of custom events or actions taken on issues.

3. Issue Context: Adds contextual information or actions based on the issue’s state or other properties.

4. Issue Panel: Embeds custom panels within the issue view to show additional data or controls.

5. Issue View Background Script: Runs background scripts within the issue view to automate tasks or fetch data without user interaction.

Search Improvements

1. JQL Function: Introduces new functions to Jira Query Language (JQL) to enhance search capabilities.

2. Entity Property: Stores additional metadata indexed by Jira, making fields available for querying in JQL.

Dashboard Enhancements

1. Dashboard Gadget: Adds custom gadgets to Jira dashboards for new ways to visualize and interact with data. These gadgets can be refreshed manually or automatically.

2. Dashboard Background Script: Executes scripts in the background of Jira dashboards to automate tasks or process data when users visit the dashboard.

New Permissions

1. Global Permission: Introduces new Global Permissions, which do not have implementation themselves but allow defining different permission levels for your app. Permission checks should be implemented in other modules.

2. Project Permission: Similar to Global Permission, it introduces new Project Permissions without implementation, allowing configuration of different project permission levels through permission schemes. Permission checks should be implemented in other modules.

Workflow Extensions

1. Workflow Validator: Adds custom validators to Jira workflows to enforce rules or checks during transitions.

2. Workflow Condition: Defines conditions that must be met for workflow transitions to be available.

3. Workflow Post Function: Executes custom actions after workflow transitions to automate tasks or update data.

Issue Create Behavior Changes

1. UI Modifications: Alters the Create Issue/Edit Issue interface to change the look and behavior of the Global issue create and Issue view screens.

These modules offer extensive customization and extension options, enabling developers to tailor Jira to specific business needs and enhance productivity and workflow efficiency. As developers, we are also interested in understanding the implementation specifics of each module and their components.

Classification Based on Development Perspective

Different modules require varying implementations — front-end, back-end, simple declarations, or a combination of these.

Let’s classify them based on their implementation requirements:

Front-End Implementation

For front-end development, you need to:

• Implement the visual components of the module using UI Kit or Custom UI.

• Use "Forge Bridge APIs" to send requests to the Jira REST API or your back-end functions.

Back-End Implementation

Back-end development involves:

• Using Forge Functions (FaaS), which are essentially JavaScript Lambda functions.

• Making requests to the Jira REST API on behalf of the current user or the app, providing various ways to manage content.

• Interacting with Forge Storage, where you can store multiple entities and retrieve data using search queries.

Keep in mind that back-end functions have limitations regarding execution time, memory usage, and the number of invocations, so they must be planned carefully.

Declaration

This involves declaring new items in Jira without specific front-end or back-end implementation requirements.

Conclusion

Understanding the distinctions between front-end, back-end, and declaration implementations is crucial for effectively extending Jira using Atlassian Forge.

Front-end development focuses on creating user interfaces with UI Kit or Custom UI and utilizing Forge Bridge APIs to interact with Jira’s REST API or back-end functions. Back-end development, on the other hand, involves leveraging Forge Functions to perform server-side tasks, manage content, and interact with Forge Storage while adhering to limitations on execution time, memory, and invocations. Declaration, by contrast, is about defining new Jira items without delving into specific implementation details.

By recognizing these differences, you can better plan and execute custom solutions that enhance Jira’s functionality, tailored to both business needs and technical constraints.

[Łukasz Modzelewski _Lumo_]

Thanks @Andrei Pisklenov _Actonic_ , that's a well-aggregated set of information and a great graphic overview! :)