Overview

Backend apps are apps that are run in response to backend events. Example backend events include Freshdesk product events such as ticket create, ticket update, contact create, and contact update. When these events occur, the appropriate backend app is executed in a sandboxed mode on a Freshdesk backend server. This is in contrast to our existing apps that run in response to front end events such as a ticket page load, or a button click and are executed on the client side i.e. in the browser.


Note:
1. You need to have SDK v2.3.1 or higher in order to use this feature. You can find instructions on how to get the latest version here.
2. All outgoing requests from backend apps originate from AWS servers whose IP addresses adhere to the range mentioned in this list.


Take a look at the simple backend app for a demonstration of this feature.

Usecases

Custom Dispatch'rs and Observers

Freshdesk enables workflow automations through dispatcher and observer rules. Dispatchers run every time a ticket is created while observers run anytime a ticket is updated. They are powerful but they do have certain restrictions. For example, you cannot have an automation to add a note to the ticket. Back end apps enable you to bypass these restrictions.

You can now bring in data from external sources to customise your workflow even further. For instance, imagine you are a company with SaaS business model. When a ticket is created, a backend app can check if the requester’s renewal date is in the next 30 days and set the ticket priority accordingly.

Furthermore, the current automation suite in Freshdesk is limited to ticket events. With backend apps, you can build workflows for events on contacts, and in future several others.


Data Synchronisation

Events such as contact create and contact update are typically used to synchronise data across multiple products. For example, every time a contact is created/updated in Freshdesk, the same contact will be created/updated in your CRM. With Backend apps, the changes can be acted upon in real time.


Alerts and Notifications

Backend apps can also be used to apply custom logic to alerts and notifications. You can get notified when a ticket or contact with certain characteristics is either created or updated. This notification can be through your desired notification channel (email, chat, sms, etc.,).


Server Method Invocation

Server Method Invocation is a feature that allows code written in server.js to be executed in response to frontend events. You can utilize this feature to use node libraries (that only run on the backend) or to hide your app’s logic or any other sensitive information that is part of your code.


Note:
1. Backend apps will be executed in sandbox mode where functions such as setTimeout , require cannot be used.
2. A backend app must complete its execution within 20 seconds or it will timeout.


Create

If you want to create a new backend app, run the following command: $ frsh init <project-directory-name> -f backend Or, if you want to include the backend feature in an existing app, run the following command from your project directory: $ frsh update -a backend

You will notice that in the manifest.yml file, the following section has been added:

Copied Copy
1
2
features: - backend

Backend App with Data Storage

To include data storage feature in your backend app, navigate to your project directory and run the following command:$ frsh update -a db

The manifest.yml file will be updated to include db as shown below:

Copied Copy
1
2
3
features: - backend - db

Alternately, you can also edit the manifest.yml file and manually include db in the features section.

For more information on the data storage and supported APIs, see Data Storage.



Folder structure

A backend app consists of the following folders/files:

Note:
User interface elements are optional in a backend app and hence the contents of the files within the app folder are optional.


Folder/File Description
README.md Any additional instructions or specifications the developer may want to outline can be mentioned here.
app/app.js The brains of your app. The app will react to user input and data based on what you've defined in this file. If your app does not have any UI component, you can remove the content of this file.
app/style.scss Contains the style sheets for the app. If your app does not have any UI component, you can remove the content of this file.
app/template.html Contains the HTML elements required for building the UI of the app. If your app does not have any UI component, you can remove the content of this file.
assets This folder will contain the logos and other image assets your app may need. Supported file formats are:
  • PNG
  • JPG
  • GIF
  • CSS
  • JS
You can reference files from the asset folder in the app.js, style.scss, and template.html files by using the following format: {{'filename.png' | asset_url}} Where, filename.png is a file in the assets folder.
backend/lib Contains external script files with functions that can be used in server.js. In the above example “handle-response.js” is the external script file. loadLib('locallib'); Where, locallib is a lib file under project-folder/lib/locallib.js which will be accessed when the method in the above example is invoked from server.js.
backend/server.js Declaration of backend event functions.
backend/test_data Contains sample event payload to be passed during local testing.
test_data/onContactCreate.json Contains the payload that will be passed while testing onContactCreate event.
test_data/onContactUpdate.json Contains the payload that will be passed while testing onContactUpdate event.
test_data/onConversationCreate.json Contains the payload that will be passed while testing onConversationCreate event.
test_data/onTicketCreate.json Contains the payload that will be passed while testing onTicketCreate event.
test_data/onTicketUpdate.json Contains the payload that will be passed while testing onTicketUpdate event.
config This folder contains at least two files:
  • iparam_en.yml
  • iparam_test_data.yml
An additional iparam file will be required for each language that you support. Based on the language in the support portal of the customer, the relevant iparam file will be used.
manifest.yml Contains some details about your app and its characteristics.

Dependencies

Dependencies are npm packages that can be used by the server.js file and files in the backend/lib folder. Using them enables you to reuse their functionality as per your app’s requirement. For example, you can use popular npm packages such as underscore to take advantage of its utility methods or request to easily make HTTP calls.

Note:
1. If you are using a windows machine, please refer to the prerequisites to ensure that your machine is correctly set up.
2. Ensure that the package you are including has at least 50 downloads in the last month.


You should list the packages in the manifest.yml with the corresponding versions in the following format:

manifest.yml Copied Copy
1
2
dependencies: request: 2.72.0

You can now load the dependencies by including loadDependency() method in the server.js file. You can follow the format given in the below example:

Copied Copy
1
2
var _ = loadDependency("underscore"); _.first([5, 4, 3, 2, 1]);

Where underscore is the package that will be loaded when this method is invoked from server.js.

Before local testing, dependencies have to be installed. Refer to the Local Testing section for details.

Local Libraries

You can use local library files that contain helper methods for your server.js file to use. This will enable you to make your code modular and maintainable. You can load your local library from backend/lib directory by including the loadLib() method in the server.js file. You can follow the format given in the below example:

server.js Copied Copy
1
var handler = loadLib("handle-response");

Where handle-response is a library file in the backend/lib directory.

Local Testing

You can easily test your app from your developer machine by simulating the backend events. For example, you can simulate a ticket being created which will trigger your backend app and send it a ticket create payload. A sample payload for each backend event can be found inside the app’s backend/test_data folder. You can test different scenarios by modifying the payload inside the appropriate JSON file.


Note:
Since the testing is only simulating events, an actual event will not be recorded in the back end. If you need an actual ticket/contact to be created, then it is recommended that you create a test account and perform the operation manually.


To simulate backend events for local testing, follow the procedure outlined below (applicable for SDK v3.0.0 onwards):

  • Install dependencies. You can skip this step if you have not included dependencies. $ frsh install Once this command is run successfully, the node modules will be installed in the server/node_modules directory.
  • In your console, navigate to your project directory, and execute the following command: $ frsh run
  • Open your browser and enter the following URL to start testing your app - http://localhost:10001/web/events.
  • If your app does not include the backend feature, you will see the following error message: You will need to update your existing app to include the backend feature by running the following command: $ frsh update -a backend
  • Select the backend event that you want to simulate:
  • Once you select an event, the corresponding event payload will be displayed. You can choose to edit the values and click Simulate. If you are editing the payload, ensure that you adhere to the JSON format.
  • If the event was successfully simulated, you will see Success as shown in the below image:
  • If there was a problem, you will see Failed as shown in the below image:

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

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