Data Storage

Some apps need to store and retrieve data. For example, consider the workflow of a project management app such as JIRA. When an agent links a ticket to an issue in JIRA, a relation between the ticket ID and issue ID is stored, which when retrieved displays the details of the relevant JIRA issue along with the ticket.

To enable the development of such apps, we provide 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:

  • 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 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. For more information on how to get the latest version, click here.

Store

client.db.set(key, value, options) - 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. The options field is not mandatory and by default is an empty hash. 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 8 KB.
  • The value should be of type JSON and not blank or empty "{}".
  • The following values in the JSON Object 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:
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.


For Serverless Apps, you need to use the following the format.

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

Options: The following attributes can be specified in the options field.

  • Time to live (ttl): Specifies the expiration period of the key in the data store in seconds. The ttl attribute supports both integer and float data types. If you do not set the ttl value or if the value is negative, the key will exist forever.
  • template.html

    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    client.db.set( "ticket:101", { "jiraIssueId": 15213 }, {ttl: 60}) .done(function(data) { // success operation // "data" value is { "Created" : true } }) .fail(function(error_data) { // failure operation console.log(error_data.status) console.log(error_data.message) });

    This sample code sets the key to expire after 60 seconds.

  • Set If (setIf): The setIf attribute takes any one of the two values: exist or not_exist. The {setIf: "exist"} code stores the value if the key exists in the data store and throws an error if the key does not exist in the data store. Similarly, {setIf: "not_exist"} stores the value if the key does not exist in the data store and throws an error if it is an existing key.
  • template.html

    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    client.db.set( "ticket:101", { "jiraIssueId": 15213 }, {setIf: "exist"}) .done(function(data) { // success operation // "data" value is { "Created" : true } }) .fail(function(error_data) { // failure operation console.log(error_data.status) console.log(error_data.message) });
    EXPAND ↓
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.