In 2024, Forge hosted storage will automatically include data residency. This means that all app data in Forge hosted storage will inherit data residency, in all current and future Atlassian-supported regions.
This implementation will provide your customers with greater control over their app data’s location. For more information, read this announcement.
The Storage API lets you store data in custom entities, which are data structures you can define according to your app's needs. Custom entities let you assign multiple values (or "attributes") to a single key (or "entity") and define indexes to optimize queries against these values.
To start, import the Forge API package in your app, as follows:
1 2import { storage } from '@forge/api';
Each installation of your app is subject to the Storage API's quotas and limits. See Storage quotas and Storage limits for more details.
The app storage API requires your app to have the storage:app
scope. See
Add scopes to call an Atlassian REST API
guide to add new scopes to your app.
For a detailed tutorial on storing and querying structured data through custom entities, see Use custom entities to store structured data.
This page lists different methods for managing data stored in custom entities. For related information:
For a detailed tutorial on storing and querying structured data through custom entities, see Use custom entities to store structured data.
Stored entity values must adhere to the following type requirements:
Type | Requirements | |
---|---|---|
integer | Must be a 32-bit signed integer, with the following value limits:
| |
float | The value must either be 0, or fall within the following range limits (both inclusive):
We provide 38 digits of precision as a base-10 digit. | |
string |
| |
boolean | Can only be true or false | |
any | The
|
The Custom entity store strictly enforces attribute types. Attempting to store a value whos type doesn't
match its field will result in an error (for example, when you try to set a string
value to an attribute with an integer
type).
Stores a JSON value with a specified key, for the selected entity.
1 2storage.entity(entityName: string).set(key: string, value: object): Promise<void>;
A key should:
/^(?!\s+$)[a-zA-Z0-9:._\s-#]+$/
Sets the key example-key
for an entity named employee
.
1 2storage.entity("employee").set('example-key', { surname:"Davis", age: 30, employmentyear: 2022, gender: "male", nationality: "Australian" });
Gets a custom entity value by key. If the key doesn't exist, the API returns undefined
.
1 2storage.entity(entityName: string).get(key: string): Promise<object>;
Gets the value associated with the key example-key
.
1 2// Read the value for key `example-key` await storage.entity("employee").get('example-key');
Deletes a value by key, for the selected entity. This succeeds whether the key exists or not.
While you can use the storage.entity.delete
method to delete app data when deleting an app,
we recommend you raise a ticket with the Atlassian Marketplace team to handle this for you. See
Retiring your app
for more details.
1 2storage.entity(entityName: string).delete(key: string): Promise<void>;
Deletes the value associated with the key example-key
, if it hasn't already been deleted.
1 2// Delete the value with the key `key` await storage.entity('employee').delete('example-key');
Allows you to build complex queries against data in your Custom entity store. See Complex query for detailed information.
Rate this page: