Storing data

Some applications will require to store some information. If you have declared any settings in your application manifest you are already using the Storage API, although it is implicitly handled for you. If your application needs go beyond just storing settings then you need to be aware of the Storage API.

How does it work?

Deskpro provides a simple key-value store API available in both the Cloud and On-Premise versions. In your application manifest, you declare a list of storage keys and their access permissions when they require special access. Then from within your app, you use the Storage Client to write and read to those keys. Only your application can read the keys defined in the manifest

The Storage Client will JSON encode the values you write to the Storage API and decode them when you read so it's better to use only JSON serializable values.

Here is how you would declare three storage key, with different access levels:

{
    "storage": [
      {
        "name": "readable-key",
        "isBackendOnly": true,
        "permRead": "EVERYBODY",
        "permWrite": "OWNER"
      },
      {
        "name": "private-key",
        "isBackendOnly": true,
        "permRead": "OWNER",
        "permWrite": "OWNER"
      },
      {
        "name": "public-key"
      }
    ]
}

You would need different access levels when you store things as individual access tokens, like Oauth2 token which need to be accessed only by the authenticated user, or when you store application wide configuration like maybe an API key. Finally one way to share persistent data between application is via public storage items.

Storage key reference

The storage key properties:

• name
• isBackendOnly
• permRead
• permWrite

name

This is a required property

A string value identifying your key. Must be unique within the scope of your application

isBackendOnly

This is an optional property Default value:

  {
    "isBackendOnly": false,  
  }

If you are storing sensitive data such as API Keys or Authentication Tokens then you do not want this expose at all and instead rely on the server-side Proxy to inject the value in the request. When this property is true only the server-side Proxy can read the value:

  {
    "isBackendOnly": true,  
  }

permRead

This is an optional property

Default value:

  {
    "permRead": "EVERYBODY",  
  }

Available values:

  OWNER,
  EVERYBODY

This property is used to control who can read the value. With OWNER it can only be read by the user who created the value and with EVERYBODY there are no restrictions. With OWNER each user will have their own value for the storage key and with EVERYBODY there will be only one value.

When this property is used together with isBackendOnly turned on, it controls who can use this value, rather than who can read it.

For example:

  {
    "isBackendOnly": true,  
    "permRead": "OWNER"      
  }

This would make the value readable only be the server-side proxy and only when the user who created the value make a request

In a similar fashion, this configuration would allow everybody to make requests using private data:

  {
    "isBackendOnly": true,  
    "permRead": "EVERYBODY"      
  }

permWrite

This is an optional property

Default value:

  {
    "permWrite": "EVERYBODY",  
  }

Available values:

  OWNER,
  EVERYBODY

This property is used to control who can modify the value. With OWNER it can only be written by the user who created the value and with EVERYBODY there are no restrictions.

This property is useful for application wide configuration values which can not be modified by anyone else other than the admin

Using the Storage Client

The Storage Client allows you to use a storage context for your storage keys which will have different values for each context. This feature makes it easy to store data on a per ticket basis, without having to declare the keys in advance which would not even be possible.

Storing application data

The Application Context is one storage context available and is useful for storing values which are used across the entire application, for instance oauth tokens:

  // obtain a reference to the Storage API client from the application client

  const { 
      /**
       * @see https://deskpro.github.io/apps-sdk-core/reference/StorageApiFacade.html
       */
      storage
  } = dpapp;

  // save the token
  storage.setAppStorage('oauth-token', { token: 'my-oauth-token' });

  // read the token
  storage.getAppStorage('oauth-token').then(token => console.log(token));

Storing object data

The other storage context made available via the Storage API Client is the Entity Context. The entity is a Deskpro Object like Ticket, Organization or Person and each application target where your application runs will have one such object attached.

If you need to store different data for each ticket, for instance when linking Deskpro Tickets with other systems then you should be using this context:

  // obtain a reference to the Storage Client from the Application Client

  const { 
      /**
       * @see https://deskpro.github.io/apps-sdk-core/reference/StorageApiFacade.html
       */
      storage
  } = dpapp;

  // save the correlation id
  storage.setEntityStorage('correlationId', '867-5309');

  // read the token
  storage.getAppStorage('correlationId').then(id => console.log(id));