Server Method Invocation

SMI (Server Method Invocation) is a feature that allows the front end component of the app to invoke the back end component. Typically, apps that run based on front end events (app loaded, button clicked, ticket status changed, etc.,) have code that is written in the app.js file and executed in the browser. Apps that execute based on back end events (onTicketCreate, onTicketUpdate) have code in server.js that runs on a backend server.

Some of the situations where you may find this feature useful are as follows:

  1. Node libraries that only run on the backend can be used to develop your app. For example, you can use wrapper libraries that make accessing the APIs of products such as Freshdesk, Stripe, and Salesforce extremely simple.
  2. SMI can also be used when you wish to hide your logic or sensitive information such as static API keys or other configuration settings from the end users of the app. As this code is in the server.js file, end users will not be able to access it.

Note:
1. You need to have SDK v2.3.1 or higher in order to use this feature.
2. The backend function must complete its execution within 5 seconds or it will timeout.
3. This feature is in beta and may not always work as expected. For support queries, reach out to us at support@freshdesk.com or via the chat icon at the bottom right corner of this page.


To enable the SMI feature in your app, make sure that the following is included in the manifest.yml file:

Copied Copy
1
2
features: - backend

Take a look at the simple server method invocation app for a demonstration of this feature.

Invoke

The $request.invoke method can be used in the app.js file to call a method that the developer has defined in the server.js file of the app.

$request.invoke takes two arguments:

  1. A string denoting the name of the backend function to call.
  2. A JSON object containing the arguments to be sent to the backend function.

app.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var options = { "url": "https://api.github.com/users/sample" }; this.$request.invoke("serverMethod", options) //options passed will be in json format. .done (function(data) { // data is a json object with requestID and response. // data.response gives the output sent as the second argument in renderData. console.log("server method Request ID is: " + data.requestID); console.log("server method response is: " + data.response); }) .fail (function(err) { // err is a json object with requestID, status and message. console.log("Request ID: " + err.requestID); console.log("error status: " + err.status); console.log("error message: " + err.message); })
EXPAND ↓

An additional object (“iparams”) containing the installation parameters will be automatically added to the options JSON to enable the backend function to access them.


Sample options with iparams Copied Copy
1
2
3
4
5
6
7
{ "url": "https://api.github.com/users/sample", iparams { key: value1, key: value2 } }
Response

The renderData method should be used in the server.js file to return a response to the method that called it.


Note:
If the renderData method is not used, a timeout error will occur.


renderData can be used to handle both success and failure cases as listed below:

  1. On successful execution of the server method, a JSON object can be sent back to the caller. It should be passed as the second argument.

    Sample code to render a success message: Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    exports = { serverMethod: function(options) { // write your code here. // an additional key , iparam (containing account configs) will be attached to the options. // use renderData ( err, data ) to send back the response. renderData(null, { "key": "value" }); } }

    Success Response:

    Copied Copy
    1
    2
    3
    4
    { requestID: "2edc13f8-3b81-4ade-b857-8d8e316fa87c", response: { "key": "value" } }

  2. Errors can be communicated by sending a JSON object that contains an error status and message. This object should be passed as the first argument:
    1. The status should be sent back using the “status” key. In case, this key is not present, we will add it and send a 500 status back to the caller.
    2. The message should be sent back using the “message” key.
    3. An additional key/value pair containing the request ID will be added into this object.
    Sample code to render an error message: Copied Copy
    1
    2
    3
    4
    5
    6
    exports = { serverMethod: function(options) { var error = { status: 403, message: "Error while processing the request" }; renderData(error); } }

    Failure Response:

    Copied Copy
    1
    2
    3
    4
    5
    { requestID: "2edc13f8-3b81-4ade-b857-8d8e316fa87c", status: 403, message: "Error while processing the request" }

Sample Error response in case the error object sent in renderData is not a proper JSON Object: Copied Copy
1
2
3
4
5
{ requestID: "2edc13f8-3b81-4ade-b857-8d8e316fa87c", status: 400, message: "The error should be a JSON Object with a message or a status parameter." }
Local Testing

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

With the browser extension installed and the local SDK server running, visit your Freshdesk account and go to the ticket details/contact details page where you’ve enabled your app. You will be able to see the code you wrote on your local machine running inside your account.

During local testing, you may see a shield icon in the browser address bar as shown below: 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. Click "Load unsafe scripts" to continue testing.

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.