App development process

The FDK is built as a Node.js application and it requires installation of the following components in your system.

• Node Version Manager/NVM (Optional)
• Node.js v18.13.0 or later

Note:If Node.js v18.13.0 or later is installed already on the system, skip this section and proceed with the FDK installation via NPM step.

There are following two methods to install the prerequisites.

Based on the installation information provided in the prerequisites section, refer to the steps in the following tabs to install FDK.

1. From the command-line, navigate to the empty directory in which you want to create an app.

2. Run the following command, to create and set the requisite environment configuration for developing a global app.

   fdk config set --scope local global_apps.enabled true

   The configs.json file (with the global_apps attribute) is created in the app directory.

3. Run the fdk create command. A prompt to choose a template is displayed.

4. Select serverless-starter-template. A new app with the following directories/files is created based on the template.

   Directories and files that the create command generates for serverless-starter-template

   The following directories and files are created as a result of the fdk create command.

   Directory/File	Description
   Important:When building an app, do not modify the default folder/file names.
   config/	Contains the installation parameters, request template, and OAuth configuration files.
   config/iparams.json	Contains all the installation parameters whose values are set when the app is installed. For more information, see App settings.
   log/	Contains the files in which the app debugging information is captured.
   log/fdk.log	Contains all debugging information, warnings, and errors generated when an app is created, run, packed or validated.
   manifest.json	Contains details such as the platform version the app uses, modules to which the app belongs, common and module-specific event listeners for the app, the Node.js version, request templates that the app code uses, and FDK version used to build, test, validate, and pack the app, and npm packages that the app uses (dependencies).
   server/ (All js files are ES6 compatible)	Contains files and folders related to a serverless app or the serverless component of an app.
   server/ lib	Contains external libraries with methods that can be used in server.js.
   server/ lib/ handle-response.js	Contains the method that can be used in server.js to handle the API responses.
   server/ server.js	Placeholder file for your app logic (app code).
   server/ test_data	Includes files that contain sample payloads for the events that are simulated to test a serverless app. By default, it contains sample payload data for serverless events of the common and support_ticket modules.
   README.md	Contains additional instructions, information, and specifications.

Important:After you build a global app that works across modules and publish it to our marketplace, in the subsequent versions of the app, you cannot remove modules (that is, downgrade the number of modules).

After creating the default serverless app files, to build the app,

1. Configure the app manifest.

2. Implement your app logic.

   1. Navigate to server.js and code your app logic.

   2. Use our serverless events to formulate your app logic.

      • For your app to react to app installation, updation, or uninstallation, use the appropriate app set-up events.
      • For your app to react to events (such as contact creation, deletion, and so on) that occur in the product, retrieve the event-related information, and use the information to process the app logic, use the appropriate product events.

      • For your app to react to the events that occur in an external product or service, use external events.

      • For your app to react to precreated schedules, use scheduled events.

   3. Use our developer toolkit to help solve specific requirements of your app.

      • To use npm packages, use our provision to include external libraries into your app files.

      • To place secure http calls from your app to a third-party domain, use the request method.

      • To enable communication between the various instances of your app, use the instance method.

      • To enable your app to access third-party resources that require an OAuth authentication, use the provision to place OAuth requests.

      • To persist and use data throughout your app’s lifecycle, use our data storage tools.

3. Configure app settings.

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. During app testing, in the serverless events’ payloads, the selected modules are passed as currentHost.subscibed_modules.
   2. In the corresponding Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, in the serverless events’ payloads, the entered URLs are passed as currentHost.endpoint_urls.
   3. 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 and account URLs 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. To test a product event, select the corresponding product event’s name.

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.

To validate the app code for errors and pack the app for submission:

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

   fdk validate

   Or

   From the command line, run the following command.

   fdk validate --app-dir <DIR>

   If there are errors in the code, corresponding violations are displayed. Ensure to fix all violations before packing the app. Reference: App validation.

2. To fix all lint errors for which auto-fix support is available, run the following command.

   fdk validate --app-dir -fix <DIR>

3. To pack the app for submission, run one of the following commands.

   fdk pack

   fdk pack --app-dir <DIR>

   A dist/<app_directory>.zip file is generated.

To publish the app to the Freshworks Marketplace, navigate to the developer portal and upload the validated and packed app file. You can use the Login button in the header of this webpage to navigate to the developer portal.

For detailed app submission steps, see App submission process.