Storing, downloading, and deleting large objects

 

The Forge Object Store API lets you upload, download, and manage large items (like data objects and media files) directly from your app. This API also lets you create pre-signed URLs for download and upload requests.

To start using the Forge Object Store, add the required package (@forge/os) to your project first:

1
2
npm install @forge/os 

Then, import the package to your app, as follows:

1
2
import os from '@forge/os' 

Limitations

The Forge Object Store has the following limitations during the EAP:

• Storage limits: Objects can be up to 50 MB each, with a total storage cap of 1 GB across all objects.

• Time-to-Live (TTL): Objects have a default TTL of 90 days. Custom TTLs can be set but must be greater than 1 second and can't exceed 90 days. This limitation will only be in effect for the EAP.

  All objects will be deleted at the end of the EAP. Atlassian will provide notice before the end of the EAP to ensure you have time to download any stored data.

• Accessing objects in UI: Direct object upload and download links for UI components are not supported and must be managed through Forge functions. File uploads or downloads in UI Kit must be handled through a Frame component, which acts as a container for a Custom UI application.

• Pre-signed URLs: Pre-signed URLs are only available in the UI Kit Frame component or Custom UI. Support for resolver/Lambda is in progress and will be available soon.

• Production deployments: The EAP is only for testing purposes and deployment to production will not be available.

Upload/Update object

Store large files or media efficiently from your app using the Forge-hosted storage. Use the put method to upload an object with the following parameters:

• objectId (string): A unique identifier for the object being stored. If an object already exists with the same objectId, the new upload will add a new version of the object, effectively functioning as an update operation.
• object (any): The data to be stored, which is buffered internally for efficient handling.
• ttlSeconds (number): Allows you to set a custom TTL for an object. If no TTL is set, the object's TTL will default to 90 days. Custom TTLs must be greater than 1 second and can't exceed 90 days.

Method signature

1
2
os.put(objectId: string, object: any, ttlSeconds?: number): Promise<void>;

Example

1
2
export const uploadObject = async (objectId: string, object: any, ttlSeconds?: number): Promise<void> => {
  try {
    const bufferedObject = Buffer.from(object)
    await os.put(objectId, bufferedObject, ttlSeconds)
  } catch (error) {
    console.error('Error uploading object', JSON.stringify(error))
  }
}

Get metadata

Retrieve the metadata for objects stored in the Forge-hosted object store using the get method.

This method works as follows:

• objectId (string): The unique identifier for the object metadata to retrieve.
• Returns: The objectReference if found, or undefined if the object does not exist.

Method signature

1
2
os.get(objectId: string): Promise<ObjectReference | undefined>;

interface ObjectReference {
  key: string;
  checksum: string;
  size: number;
  createdAt?: string;
  currentVersion?: string;
} 

Example

1
2
export const getObjectRef = async (objectId: string): Promise<ObjectReference | undefined> => {
  try {
    const objectRef = os.get(objectId);
    if (objectRef === undefined) {
      console.info('Object was not found',  { objectId })
    }
    return objectRef
  } catch (error) {
    console.error('Error getting object reference', JSON.stringify(error))
  }
};

Download

Retrieve the data of the latest version of an object stored in the Forge Object Store using the download method.

The download method works as follows:

• objectId (string): The unique identifier for the object to download.
• Returns: A Buffer containing the latest object data if it exists, or undefined if the object is not found.

Method signature

1
2
os.download(objectId: string): Promise<Buffer | undefined>;

Example

1
2
export const downloadObject = async (objectId: string): Promise<Buffer | undefined> => {
try {
    const object = os.download(objectId);
    if (object === undefined) {
      console.info('Object was not found',  { objectId })
    }
    return object
  } catch (error) {
    console.error('Error downloading object', JSON.stringify(error))
  }
}

Delete

Remove objects from the Forge-hosted object store using the delete method.

The delete method works as follows:

• objectId (string): The unique identifier for the object to delete.

Method signature

1
2
os.delete(objectId: string): Promise<void>;

Example

1
2
export const deleteObject = async (objectId: string): Promise<void> => {
  try {
    await os.delete(objectId)
  } catch (error) {
    console.error('Error deleting object', JSON.stringify(error))
  }
}

Create pre-signed download URL

Create a URL with temporary permissions to download a specific object to a client using the createDownloadUrl method.

Method signature

When generating a pre-signed download URL, you need to include the objectId (string) in your request. The createDownloadUrl method uses this as a unique identifier for your URL.

The method will then return a PresignedUrlResponse.

1
2
os.createDownloadUrl(objectId: string): Promise<PresignedUrlResponse | undefined>

interface PresignedUrlResponse {
  url: string;
}

Example

1
2
export const createDownloadUrl = async (objectId: string): Promise<PresignedUrlResponse | undefined> => {
  try {
    return await os.createDownloadUrl(objectId);
  } catch (error) {
    console.error('Error creating pre-signed download URL', JSON.stringify(error))
  }
};

Create pre-signed upload URL

Create a URL with temporary permissions to upload a single object using the createUploadUrl method. Pre-signed upload URLs can only be used for objects under 1GB.

Method signature

When generating a pre-signed upload URL through createUploadUrl, your request must include an UploadUrlBody containing the properties of the file you’re uploading. These properties are:

• key: The unique identifier for the object.
• length: The byte size of the object.
• checksum: Hash digest of the file content, encoded as base64. Used to verify data integrity.
• checksumType: Algorithm used to generate the checksum.
• ttlSeconds (optional): Allows you to set a custom TTL for and object.
• overwrite (optional): Indicates whether to replace an existing object with the same key. This defaults to true.

The method will then return a PresignedUrlResponse.

1
2
os.createUploadUrl(body: UploadUrlBody): Promise<PresignedUrlResponse>

interface UploadUrlBody {
  key: string;
  length: number;
  checksum: string;
  checksumType: 'SHA1' | 'SHA256' | 'CRC32' | 'CRC32C';
  ttlSeconds?: number;
  overwrite?: boolean;
}

interface PresignedUrlResponse {
  url: string;
}

Example

1
2
export const createUploadUrl = async (objectId: string, object: any, objectLength: number, ttlSeconds?: number): Promise<PresignedUrlResponse | undefined> => {
  try {
    const bufferedObject = Buffer.from(object)
    // Create SHA256 checksum from buffer
    const checksum = crypto.createHash('sha256').update(bufferedObject).digest('base64');
    const body: UploadUrlBody = {
      key: objectId,
      length: objectLength,
      checksum,
      checksumType: 'SHA256',
      ttlSeconds,
      overwrite: true,
    };
    const resp = await os.createUploadUrl(body);
    return resp;
  } catch (error) {
    console.error('Error creating pre-signed upload URL', JSON.stringify(error))
  }
};

EAP Feedback

As part of the EAP, your feedback is invaluable in shaping the future of this feature. We encourage you to explore Forge Object Store's capabilities and share your insights to help us refine and enhance this service.

• Report any bugs and issues
• Submit any feedback and improvement suggestions