Where to Store Data in Forge Apps

In this article, we’ll explore various options for storing data in Forge apps. We’ll start with the most common choices — Entity Properties and Forge Storage — then discuss more specialized alternatives, such as Content Attachments and External Databases. We'll examine the pros, cons, limitations, and use cases for each method to help you choose the best fit for your app. While this article doesn't dive into code, future videos will feature practical code examples.

If you prefer a video format, watch the video https://www.youtube.com/watch?v=FJLfKSLfE8E

Introduction

When building a new Forge app or enhancing an existing one, you’ll often need to store configurations, templates, logs, or other core data. Depending on your app's needs, you have several storage options to consider. The two primary choices are Entity Properties and Forge Storage, which offer different benefits and limitations. For specific use cases, alternative methods like Content Attachments or External Databases may be more appropriate.

Entity Properties

Jira Entity Properties https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/.

Confluence Entity Properties https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/.

Pros:

• Direct Association: Data is closely tied to specific entities (e.g., Jira issues, projects, or Confluence pages), making retrieval straightforward.
• Simplicity: Easy to implement and well-suited for small pieces of metadata.

Cons:

• Limited Scope: Data is bound to individual entities, so it doesn’t support cross-entity or global data storage.
• Size Limitations: It’s not designed for storing large or complex datasets, with a maximum value size of 32 KB.
• Access Control: In Atlassian Cloud, Entity Properties are restricted by edit permissions, limiting who can modify the data.
• Security: Anyone with edit permissions for specific content can overwrite or delete any Entity Property associated with that content.

Limitations:

• Context-Specific: Entity Properties are directly tied to specific entities, so they can’t be used for standalone data storage outside of these entities.
• Small Data Only: Works best for small, simple pieces of metadata, such as custom field values or additional entity-related data layers.

Use Cases:

• Storing custom metadata related to Jira issues or Confluence pages.
• Adding configuration options directly to projects, issues, or users.
• Associating tracking data with specific objects, such as adding extra details to a Jira issue.

Forge Storage

Forge Storage https://developer.atlassian.com/platform/forge/runtime-reference/storage-api/.

Forge Storage quotas and limitations https://developer.atlassian.com/platform/forge/platform-quotas-and-limits/#storage-quotas.

Pros:

• Flexibility: Supports more complex data storage needs, allowing data to be stored across multiple entities or use cases.
• Broader Scope: Not tied to individual entities, providing greater versatility in what data is stored and how it is used.
• Data Persistence: Ideal for storing data that needs to persist across different contexts, such as global settings or application states.
• Querying Data: You can query specific entities from storage using search criteria.

Cons:

• Higher Complexity: More challenging to implement compared to Entity Properties. Requires deeper technical knowledge and setup.
• Performance Considerations: Depending on the complexity of your app, managing large datasets can introduce performance overhead (read about cursor usage https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-query/#query-cursor).

Limitations:

• Learning Curve: Since it's more powerful, it requires a deeper understanding of the Forge platform.
• Custom Entity Definition: Custom Entity storage doesn’t allow changes to properties, types, indexes, or deletion of entity definitions. Developers need to be cautious, even when testing custom entities. For example, if you add a new custom entity to the development environment, it will remain associated with the app permanently. Removing this entity from the manifest.yml file is no longer possible without support from the Atlassian team.

Use Cases:

• Storing complex or aggregated data that spans multiple entities (e.g., voting systems or user preferences).
• Managing application states or settings that need to be accessed across different parts of your app.
• Keeping persistent records, such as logs, statistics, or user activity data.

Content Attachments

Jira Issue attachments https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-attachments/#api-group-issue-attachments.

Confluence attachments https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-attachment/#api-group-attachment.

Pros:

• No Size Limitations: You can store large amounts of data without size restrictions (within the practical limits of attachments on the Cloud instance).
• Native Storage: Utilizes Jira or Confluence's built-in attachment system, making it simple to associate large datasets with specific entities.

Cons:

• Entity-Specific: Attachments are always linked to a specific page or issue, making it less suitable for data that needs to exist independently.
• Versioning: Every modification to an attachment creates a new version in the entity’s history, which could clutter logs.

Limitations:

• Context-Dependent: Attachments can only be used within the context of Jira issues or Confluence pages, making them unsuitable for standalone data needs.

Use Cases:

• Storing large data files or documents associated with specific issues or pages.
• Handling data that needs to remain linked to an entity but doesn't fit well within Entity Properties or Forge Storage.

Remote Databases or External Applications

Forge Remote https://developer.atlassian.com/platform/forge/remote/.

Pros:

• Unlimited Storage: You can use any external database (SQL, NoSQL, cloud storage) to store large or complex datasets without limitations.
• Full Control: You have complete control over the data structure, access, and security, allowing for highly customized solutions.

Cons:

• Security Risks: External databases require managing permissions and securing data egress, which introduces additional security challenges.
• Latency: Accessing data from external sources may introduce latency or connectivity issues, depending on the setup.

Limitations:

• Integration Complexity: Requires integration with third-party applications or services, which can be challenging to implement and maintain.
• Compliance and Security: You must ensure that the external storage complies with your organization’s security policies and data protection regulations.

Use Cases:

• Integrating with third-party applications that require external data sources, such as analytics platforms or customer databases.
• Storing large datasets or complex records that exceed the limits of Forge Storage and Entity Properties.
• Offloading critical data to an external database for enhanced performance or scalability.

Conclusion

Choosing the right data storage solution for your Forge app depends on your specific needs and the scale of the data you’re handling.

• Entity Properties are ideal for simple, small-scale data closely tied to specific entities, offering easy implementation and quick access.
• Forge Storage provides a more powerful and flexible solution for complex data needs but comes with a higher level of complexity.
• Content Attachments work well for storing large files or data tied to specific pages or issues.
• Remote Databases offer the greatest flexibility and scalability for external data needs but require careful planning around security and integration.

By understanding the strengths and limitations of each option, you can make an informed decision that best suits your app's requirements. Stay tuned for upcoming videos where we’ll dive deeper into real-world examples and show you how to implement these storage methods effectively!