Data Storage

Some apps need to store data and retrieve it at a later stage. For example, consider the workflow for a project management app such as JIRA. When an agent links a ticket to an issue in JIRA, the association between the ticket ID and the issue ID needs to be stored. This association is then retrieved when an agent views the ticket so that we can display the details of the relevant JIRA issue along with the ticket.

To enable the development of such apps, we provides a data store for apps to set (store) and get (retrieve) data. This data can also deleted when no longer required. Please make note of the following limitations:

  • The data is stored on a per account AND per app basis i.e the scope is on a per installation basis. This means that if two apps have been installed by an account, the data stored by one app is not accessible by the other app.
  • A rate limit of 50 requests per minute and 500 request per hour applies with each set, get, and delete counting as one request. This rate limit is applied separately for each installed app which means that if two apps have been installed by an account, the rate limit will apply separately to each app. This limit is not affected by the number of agents in the account.

Note:
You need to have CLI v4.1.2 or higher in order to use this feature. You can find instructions on how to get the latest version here.


Store

client.db.set(key, value) - This API is used to store the key,value pair in the data store. UTF-8 characters are supported. If an entry with the key is already present, then the value will be updated. Ensure that the following conditions are met while performing a set operation:

  • The key should not be blank and its length should not exceed 30 characters.
  • The combined size of the key and value should not exceed 4 KB.
  • The value should not be blank and should be of type JSON.
  • The following values in the JSON will be converted to null - empty strings, NaN, "+/- Infinity".
template.html Copied Copy
1
2
3
4
5
6
7
8
9
client.db.set( "ticket:101", { "jiraIssueId": 15213 }).then ( function(data) { // success operation // "data" value is { "Created" : true } }, function(error) { // failure operation console.log(error) });

Note:
During local testing, you may need to click the shield icon in your browser’s address bar and click Load unsafe scripts. For more information, refer to the Local Testing section.


Retrieve

client.db.get(key) - Stored data can be retrieved using this API. If the retrieval was successful, the JSON value can be accessed using 'data' parameter in the .then function.


Copied Copy
1
2
3
4
5
6
7
8
9
client.db.get("ticket:101").then ( function(data) { // success operation // "data" value is { "jiraIssueId": 15213 } }, function(error) { console.log(error) // failure operation });

Delete

client.db.delete(key) - When the data that is stored is no longer needed, it can be deleted using this API.

Note:
When an app is uninstalled all the data stored by it will automatically be deleted and cannot be recovered.


Copied Copy
1
2
3
4
5
6
7
8
9
client.db.delete("ticket:101").then ( function(data) { // success operation // "data" value is { "Deleted" : true } }, function(error) { console.log(error); // failure operation });

Local Testing

Open your console, navigate to your project folder, and execute the following command: $ fdk run

During local testing, when you attempt to store data for the first time, you may see a shield icon in the browser address bar. Clicking on the icon will display a warning message.

This warning message is displayed as the support portal runs on HTTPS while the server that is used for local testing runs on HTTP. Please click "Load unsafe scripts" to continue testing.

The data that is stored during your local testing is stored in the .frsh/localstore file inside the app project directory.

Errors

In case of failure, a status code will be displayed along with the message to troubleshoot the issue.

Below is an example of a status code and message:

1
2
3
4
{ "status":400, "message":"Key length should not exceed 30 characters" }

The following table lists all the supported status codes.


STATUS DESCRIPTION
400 This status code is returned due to invalid input. For example, in the "set" request if you provide an invalid input for "value" you may receive this status code.
401 This status code is returned if you have performed an unauthorized request.
404 This status code is returned if the record is not found.
422 The status code is returned if the server does not recognize your request. This may occur due to incorrect syntax.
429 This status code is returned when the number of requests exceeds the threshold.
500 This status code is returned if the server encountered an unexpected condition which prevented it from fulfilling the request.
502 This status code is returned if the server cannot process the request due to request overload.

Log in with your Freshservice account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.