Custom Entity Store

The Custom Entity Store 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
2
import { 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.

For a detailed tutorial on storing and querying structured data through custom entities, see Use custom entities to store structured data.

Limitations

Stored entity values must adhere to the following type requirements:

Partitioning

All data stored within the app storage API is namespaced. The namespace includes which Atlassian site, product, and Forge environment your app is installed on. As a result:

• Only your app can read and write your stored data.
• An app can only access its data for the same environment.
• Your keys only need to be unique for an individual installation of your app.
• Data stored by your app for one product is not accessible from other products. For example, data stored in Jira is not accessible from Confluence or vice versa.
• Your app cannot read data from different sites, products and app environments.
• Quotas and limits are not shared between individual installations of your app.

Data residency

The Atlassian cloud provides features that allow admins to control and verify where their Jira and Confluence data is hosted. These features allow them to meet company requirements or regulatory obligations relating to data residency.

The Storage API uses this same cloud infrastructure to store data. This allows Forge to extend similar data residency features to your app. All data stored on the Storage API automatically inherit these features.

Specifically, if your app stores data through the Storage API, an admin can control where that data is stored. For more details about how this works, see Data residency.

Eventual consistency

The read and query APIs within the app storage APIs are eventually consistent. This means that the data returned from the API may be slightly out of date.

Conflict resolution

Writes to keys using set or delete use a "last write wins" conflict resolution strategy. Writes to individual keys are atomic - For example, the value is either updated in full or not.

Supported values

The app storage API is able to persist any JSON data type except null. For example:

• arrays
• booleans
• numbers
• objects
• strings

The JavaScript storage API serializes your objects using JSON.stringify, and as such removes functions and the value undefined from any object you attempt to serialize.

Cursors

The Key-Value Store and Custom Entity Store use cursors for paginated data access. Queries (both through the Query builder and Complex Query builder) return a cursor in the results. This cursor can be provided to subsequent queries to paginate over larger data sets than you would otherwise be able to fetch.

1
2
// Fetch a page of 10 results
const { nextCursor } = await storage.query().getMany();

// Fetch the next 10 results
await storage.query().cursor(nextCursor).getMany();

You will have to use the same parameters as the initial query. See the example below.

1
2
// Fetch 15 results
const { nextCursor } = await storage
    .query()
    .limit(15)
    .where('key', startsWith('account.'))
    .getMany();

// This is expected usage
await storage.query()
    .limit(15)
    .where('key', startsWith('account.'))
    .cursor(nextCursor)
    .getMany();

// This will produce undefined results
await storage.query()
    .cursor(nextCursor)
    .getMany();

Key ordering

Keys are lexicographically ordered; this means, for example, that the Query builder and Complex Query builder) will return entities ordered by their key. This property can be used to group related entities or build ad-hoc indexes.

The Key-Value Store and Custom Entity Store don't support indexing of arbitrary attributes. However, it is possible to support this sort of access pattern if your keys are constructed in such a way as to support indexed reads.

Hierarchical keys can be constructed to allow for nested entities to be fetched in a single list operation such as the example below.

1
2
import { storage, startsWith } from '@forge/api';

// Nested entities
await storage.set('survey-responses#1#{UUID}', { });
await storage.set('survey-responses#1#{UUID}', { });
await storage.set('survey-responses#1#{UUID}', { });
await storage.set('survey-responses#1#{UUID}', { });

const results = await storage
  .query()
  .where('key', startsWith('survey-response#1#'))
  .limit(10)
  .getMany();