Implement server method invocation

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 > modules.common.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, 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 our app UI guidelines or 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. The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

3. In the system settings page,

   1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.

   2. The Organization Domain field is displayed, with a prompt to enter the organization domain value for the account.

      In the Organization Domain field, enter the domain value from the organization URL for the account. For example, if your organization URL is https://sample.freshdesk.com, the value in Organization Domain should be sample.freshdesk.com.

      Note:The org_domain attribute attribute will only be retirevied as a part of currentHost object in app installation page and app settings page.

   3. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.

      In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost.

      Based on the currentHost, the currentHost.subscribed_modules, currentHost.org_domain and currentHost.endpoint_urls are determined. In the response payload of the currentHost data method and in the serverless events’ payloads, the determined values are used.

   4. If your app manifest includes the service_ticket or service_user modules and you select either of them, the Select Freshservice Product Type section will appear. In this section, choose the appropriate product type: ITSM or MSP.

      If your app manifest includes modules supported by Freshdesk or Freshdesk Omni, and you select either one, the Select Product Type section will appear. In this section, choose the appropriate product type: DEFAULT or UNIFIED_OMNI.

      Note:

      The Select Product Type section is displayed only if the app manifest includes at least one of the following modules and you have selected it:

      • service_ticket module
      • service_user module
      • Modules supported by Freshdesk and Freshdesk Omni

   5. If you have defined the app scope as both service_workspace and account or service_workspace alone in your app manifest, then the workspace_id field appears. Enter the workspace ID of the client (workspace) for which you want to install the app.

      To find the workspace_id:Navigate to the particular workspace in the workspace section and locate the URL. For example, if the URL is https://sample.freshservice.com/a/admin/workspaces/2/edit,then the workspace_id is 2.

      Notes:
      • The currentHost payload returns the workspace ID.
      • If the installation scope in the app manifest is set to both account and service_workspace, the workspace_id field is optional on the system settings page.
      • If the installation scope in the app manifest is set to service_workspace only, the workspace_id field is mandatory on the system settings page.
      • If the installation scope in the app manifest is set to account only, the workspace_id field is not shown on the system settings page.

   6. Click Continue.

4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

   Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

5. Navigate to http://localhost:10001/web/test to test the serverless events that the app uses. All modules that you select in the system settings page, for which serverless events are registered in the app manifest, are listed in the Select module drop-down.

   Note:The payloads of all serverless events that are registered in the app manifest are populated in the server/test_data folder. During the actual runtime, the payloads that are passed to the serverless event contain the currentHost attribute. In the local simulation, the payloads in server/test_data do not contain this attribute. During testing, the modules, account URLs, and organization domain value entered in the system settings page are passed as the currentHost data.

6. From the Select module drop-down, select the module whose events you want to test. The Select an event drop-down is displayed and it lists all the events configured (in the app manifest) for the selected module.

   Note:To test app setup events, select onAppInstall, afterAppUpdate, or onAppUninstall. To test external events, select onExternalEvent. To test scheduled events, select onScheduledEvent.

7. From the Select an event drop-down, select the event you want to test. The payload for the event is populated on the page.

   Event simulation page

8. Click Simulate. If the event is simulated successfully, the Simulate button’s display name changes to Success. The event payload is added to the <app's root directory>/server/test_data folder.

9. To test more events, select another appropriate module and event and click Simulate. If the event simulation fails because of invalid payload data, the Simulate button’s display name changes to Failed. Modify the payload appropriately and click Simulate.

10. Log in to the Freshworks product account where you want to test the app deployment.

11. To the default account URL displayed in the address bar, append ?dev=true.

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

12. Navigate to the appropriate location where the app is intended to be deployed, verify that the app is rendered, and test the app’s function.