Build SMI apps

Server Method Invocation (SMI) facilitates the front-end component of an app to invoke a server method that runs as a serverless component.

To build an SMI app,

1. Create a serverless app.
2. Configure the app manifest.
3. Register the SMI functions: In the manifest.json > product.<product-name>.functions object, specify all the server methods that are called from the front-end component of the app, to allowlist the methods.
4. Navigate to server.js and enter your app logic.
   1. Navigate to the root folder and create an app folder to host the app’s front-end files. For information on the app folder structure, see Create a front-end app.
   2. In the app folder, create an app.js file and enter the app logic for the front-end component. Use our front-end methods - app lifecycle methods, data methods, events methods, and interface methods - to formulate your app logic.
   3. Invoke the serverless component: In app.js, specify the method to invoke the serverless component and pass an appropriate payload to the serverless component. By default, the serverless environment adds the installation parameters set during app installation to the payload.
   4. Navigate to server.js and and enter your app logic. Use our serverless events - app set-up events, product events, external events, and scheduled events - to formulate your app logic.
   5. Define the server methods: In server.js, define the server method (SMI function) that is allow-listed in the app manifest and called from the front-end component. In this server method, include the app logic that runs based on the payload passed and the renderData() method to return success and failure responses to the front-end component.
5. Use our developer tooklit to help solve specific requirements of your app.

6. Use Crayons (the Freshworks component library) to construct your app’s UI.

7. Configure app settings.

After creating a serverless app’s files, to configure the app manifest for an SMI app , from the app’s root directory, navigate to manifest.json.

From the app’s root directory,

1. Navigate to the app.js file.
2. Define the JSON payload that is to be passed to the method in the server.js file. In the sample app.js code displayed in the right pane, options is the JSON payload that is passed.
3. Include the client.request.invoke(“serverMethodName”, JSON_payload) method to invoke the serverless component. By default, the serverless environment adds an iparams object to the payload.
4. Include functions to handle the response obtained from the serverless component.

After the app logic in the server method runs, the server method sends an appropriate response to the front-end component. To enable this:

1. Navigate to the server.js file. In the exports code block, define the server method that is called from the front-end component. Place the app logic inside the server method.

   Notes:
   • The SMI function name is case-sensitive.
   • The SMI function name:
     • Can be alphanumeric ([a-z], [A-Z], [0-9]) and can contain the special character underscore ( _ ).
     • Should not start with a number.
     • Should not contain any spaces between the characters.
     • Can be 2 to 40 characters long.

2. Use the renderData(error, data) method to return a response to the front-end component.

   Notes:

   • error and data are passed as JSON objects to the caller method. Ensure that the first argument of renderData(error, data) is always the error object. For success responses, ensure to pass null as the first argument.

   • error is an object with status and message attributes. data is an object with valid <key>: <value> pairs.

   • The serverless environment adds a requestID attribute, to the error or data object.

3. To send a success response, use the renderData() method as follows:

   Code

   Sample response

   exports = {
    serverMethod:  function(options) {
      // app logic resides here
      renderData(null,  { "key": "value" });
    }
   }

4. To send a failure response, use the renderData() method as follows:

   Code

   Sample response

   exports = {
    serverMethod:  function(options) {
      var error = { status: 403, message: "Error while processing the request" };
      renderData(error);
    }
   }

   In the response if error.status is not present, the default status code of 500 is used as the error status. If the error object in renderData(error) is of incorrect JSON format, error.status value is 400 and error.message value is The error should be a JSON Object with a message or a status parameter.

   The front-end component can render this error as follows:

    {
      "requestID": "2edc13f8-3b81-4ade-b857-8d8e316fa87c",
      "status": 400,
      "message": "The error should be a JSON Object with a message or a status parameter."
    }

   Note:If the server method does not return a response, the app execution timeout error occurs.

1. From the command line, navigate to the directory that contains the app related files and run the fdk run command.

2. Log in to your Freshservice account.

3. To the Freshservice account URL, append ?dev=true.

   Example URL: https://subdomain.freshservice.com/helpdesk/tickets/1?dev=true

4. To allow the Chrome browser to connect to the test server that runs on HTTP,

   1. Navigate to Settings > Advanced > Privacy and security > Site settings > Insecure content.

   2. In the Allow section, click Add and enter the account URL.

      Example URL: https://subdomain.freshservice.com

5. From the homepage of your account, navigate to the appropriate location where your app is to be deployed, verify that the app is rendered and test your app’s function.