This document outlines the Forge-hosted persistent storage data lifecycle for apps. It focuses on data managed through Forge-hosted storage and explains how data is provisioned, retained, and deleted at different stages of the app lifecycle. Understanding these stages helps you effectively plan your app's behavior and ensures it meets data handling requirements.
This guide covers every Forge-hosted persistent storage capability: the Key-Value Store, the Custom Entity Store, Forge SQL, and the Forge Object Store. It doesn't cover remote or other types of storage. While this guide details how Atlassian manages Forge-hosted data, you may find these practices useful for managing remote storage as well to ensure consistency and effective data handling.
Each stage affects how data is managed and stored by Atlassian. Below is an overview of each stage and how it affects data.
| Stage | Data status |
|---|---|
| Creation / Deployment | When a developer creates or deploys an app, no storage is set up at these stages. The system defines the app and makes it ready for use, but it does not create or store any data until a customer installs it on a site. |
| Installation | When a customer installs the app, the system provisions storage in the site's Atlassian app partition to manage the app's data for that specific site. |
| Upgrade | If new features require storage, the system provisions additional storage in the site’s Atlassian app partition during an app upgrade to meet new storage needs without affecting existing site data. |
| Uninstallation | When a customer uninstalls the app, they will either retain access for 60 days following the end of the billing or trial period, or remove the app immediately, forfeiting any remaining time. |
| Deletion | To delete an app, customers or Atlassian support must first uninstall all installations. The system then deletes data, following the same uninstallation retention period as described above. |
How data is stored or deleted depends on what happens to the app. Forge follows Atlassian's internal Standard Data Retention and Disposal policy. You can find more information in the Atlassian SOC 2 report. Below are the key actions that affect data retention or deletion:
When an app is uninstalled, the data is first 'soft deleted' and then retained for the rest of the retention period as outlined in the Atlassian SOC 2 report.
If an app is reinstalled, it is treated as a new installation. However, if a request is made within 21 days of uninstallation, the new installation can be relinked to the old data. For more details on the process, refer to Data recovery for apps with hosted storage.
Before an app is deleted, all installations must be removed first. Partners need to ask customers or contact Atlassian support to uninstall the app so the data can be deleted. Given these are normal uninstallations, they will fall under the same retention period as described above.
When your app deletes data through a storage API, that data is removed from primary storage and your app can no longer read it. Atlassian keeps a soft-deleted copy so the data can be restored after an accidental deletion, then destroys it at the end of the retention period described in the Atlassian SOC 2 report. Backups taken before the deletion are destroyed on the same schedule.
To ask Atlassian to restore data your app deleted by mistake, raise a support ticket within 21 days of the deletion, following the steps in Data recovery for apps with hosted storage.
Tell your customers that deletion is final from the app's point of view. The retention window exists so Atlassian can recover from accidental deletion; it isn't an archive your app can read from.
Every Forge-hosted persistent storage capability is data residency-enabled. Data an app stores in the Key-Value Store, the Custom Entity Store, Forge SQL, or the Forge Object Store is held in the same location as the host Atlassian app, and moves with it when an admin migrates that app to another location. See Data residency for the details and for the conditions an app must meet to be shown as PINNED.
Changes in app licenses or Atlassian app cancellations can also affect how data is managed. Below is how different licensing events impact data.
For more information on what happens when a subscription is canceled, see Cancel a subscription.
The system handles site suspension, deactivation, and deletion based on Atlassian's data retention policies. This affects all apps installed on the site.
Rate this page: