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 a user links a contact to an issue in JIRA, the association between the contact ID and issue ID is stored. This association when retrieved displays the details of the relevant JIRA issue along with the contact.

To enable the development of such apps, we provides a data store for apps to set (store) and get (retrieve) data. Also, data can be deleted when it is no longer required. The data store has 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 users in the account.

Note:
You need to have CLI v4.4.1 or higher in order to use this feature. For more information on how to get the latest version, click here.

Store

client.db.set(key, value) - Stores 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 the 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( "contact:101", { "jiraIssueId": 15213 }).then ( function(data) { // success operation // "data" value is { "Created" : true } }, function(error) { // failure operation console.log(error) });

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

Retrieve

client.db.get(key) - Is used to retrieve stored data. If the retrieval is successful, the JSON value can be accessed using the data parameter in the .then function.

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

client.db.delete(key) - Is used to delete stored data that is no longer needed.

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("contact:101").then ( function(data) { // success operation // "data" value is { "Deleted" : true } }, function(error) { console.log(error); // failure operation });
Testing

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

During testing, when you attempt to store data for the first time, you may see a shield icon in the browser address bar. Clicking the icon displays a warning message as the support portal runs on HTTPS while the server that is used for testing runs on HTTP. Click Load unsafe scripts to continue testing.

Data stored during testing is saved in the .frsh/localstore file inside the app project directory.

Errors

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

An example of a status code and message is given.

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 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 Is returned if you performed an unauthorized request.
404 Is returned if the record is not found.
422 Is returned if the server does not recognize your request. This may occur due to incorrect syntax.
429 Is returned when the number of requests exceeds the threshold.
500 Is returned if the server encountered an unexpected condition which prevents it from fulfilling the request.
502 Is returned if the server cannot process the request due to request overload.

Log in with your Freshsales account

Enter your helpdesk URL to proceed to login

Proceed

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