Server Method Invocation

The Server Method Invocation (SMI) feature allows the front-end component of an app to invoke the serverless component. Typically, apps that run on front-end events (app loaded, button clicked, lead stage changed, etc.) have the app.js file executed in a browser. And, apps that run on app setup events or external events have the server.js file executed in a server.

A few use cases for this feature are listed.

  1. You can use node libraries to simplify app development.
  2. You can hide sensitive information, such as static API keys or other configuration settings, from end users.

Note:
1. You need to have CLI v5.0.0 or higher in order to use this feature. For more information on how to get the latest version, click here.
2. The serverless function must complete its execution within 5 seconds or it will timeout.

Invoke

The client.request.invoke() method can be used in the app.js file to call a method that is defined in the server.js file.
The method takes two arguments:

  • A string indicating the name of the server.js function to call.
  • A JSON object containing arguments to be sent to the function. An additional iparams object, containing installation parameters, is automatically added to the options JSON to enable the function to access them.

app.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
var options = { "url": "https://api.github.com/users/sample" }; client.request.invoke("serverMethod", options).then( 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); }, 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 ↓
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.

Note: If the renderData() method is not used, a timeout error occurs.

The renderData() method can be used to handle both success and failure cases as follows.

  • On successful execution of a server method, a JSON object is returned 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" } }

  • Errors can be communicated by returning a JSON object that contains an error status and message. This object should be passed as the first argument.
    1. The status should be returned using the status key. In case this key is not present, the HTTP error code 500 is returned.
    2. The message should be returned using the message key.
    3. An additional key/value pair containing the request ID is 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." }
Testing

Note: For testing, we recommend that you use the latest version of Chrome browser.

You can render and test your app from your machine.

  1. Open your console, navigate to your project folder, and execute the following command. $ fdk run
  2. Log in to your Freshsales account (if you do not have a Freshsales account, sign up here).
  3. Go to the Lead Details page and in the address bar, append the URL with ?dev=true. For example, the URL should look like this: https://subdomain.freshsales.io/lead/1234?dev=true.
  4. When testing the app on your machine, you may see a shield icon in the browser address bar. Clicking the icon will display a warning message as the support portal runs on HTTPS while the server that is used for testing runs on HTTP.
  5. Click Load unsafe scripts to continue testing.