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. .
  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. Implement 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 .
    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 - - 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 replace the default code with your app logic. Use our serverless 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 to help solve specific requirements of your app.
  6. Use our App UI guidelines or Crayons (the Freshworks app's front-end component library) to construct your app’s UI.
  7. Configure app settings.
Notes:
  1. The rate limit for the serverless component is 50 triggers per minute.
  2. The payload passed to the severless component should not exceed 100 KB.

For a demonstration of how SMI works, see the SMI Freshdesk sample app.

Configure manifest and register SMI functions

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.

App manifest attributes - description and how to configure them

  • platform-versionstring

    Platform version you use to build the app. This value is auto-generated when you create the default app files by using the fdk create command.

    When you build a new app, ensure that you are on the latest version of the platform . If you update your existing app that was built with an earlier platform version, ensure to move to the latest version of the platform. For migration steps, see .

  • productobjectRequired

    Associates a Freshworks product with the information that is necessary to render the app on the specified product.

  • enginesobject

    Node.js and FDK versions that are used to build the app. When you create the front-end app files by using the fdk create command, this attribute value is auto-populated.

    Creating an app: If you use FDK 7.0.0 or later versions to create an app, the engines attribute is available by default as part of the manifest.json file.

    Migrating an app: If you have an existing app that is built using FDK 6.x.x or an earlier version, ensure to,

    1. Install the latest FDK version.
    2. Run fdk validate to migrate the app to the latest FDK version. As part of this process, the FDK updates the engines attribute.
    3. Retest the app.
  • whitelisted-domainsarray of stringRequired

    Valid only for apps built with platform version 2.2

    To make secure HTTP calls to third-party domains, apps must use the . For the method to work, in manifest.json, the third-party domains must be listed as the whitelisted-domains. For more information, see the section on how to .

    Notes:
    • If the requisite domains are not whitelisted, the fdk run command displays an error message This domain has not been whitelisted.
    • To use iparams to construct the whitelisted-domains values, use the following format:
      "whitelisted-domains": ["<%= iparam.url %>"]
    • Ensure that the whitelisted-domains array values:
      • Do not contain an IP address or multiple subdomains.
      • Do not contain the path to the resource.
      • Use HTTPS, if iparams are not used to construct the whitelisted-domains values.
      • Are not URLs to a localhost.


    This attribute is not a default attribute. If you are using an FDK version prior to 9.0.0 (platform version 2.2) and if you expect your app to make third-party HTTP calls, in manifest.json include this whitelisted-domains attribute and whitelist all the third-party domains with which the app can interact.

Invoke the serverless component

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.

Send response to the front-end 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:

    exports = {
     serverMethod:  function(options) {
       // app logic resides here
       renderData(null,  { "key": "value" });
     }
    }
  4. To send a failure response, use the renderData() method as follows:

    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.

Test the SMI app

  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 account.

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

    Example URL: https://subdomain.freshdesk.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.freshdesk.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.

Notes:
  • The extent of app testing is captured through the code coverage summary. For apps to be successfully published in the Freshworks Marketplace, each component in the coverage summary should be at least 80%. For more information, see .
  • When testing your app, if you run into any issue, for a quick resolution from the support team, attach detailed logs of the output in your support ticket.