Configure developer app settings

When developing an app, configuring credentials such as tokens and API keys is often necessary. The app settings functionality allows you to provide runtime data for these credentials without hard-coding them into the app's code.

These credentials are defined as environment variables within the app code, and their values are set on the app details page when submitting the app to the Freshworks Developer portal. If any updates to the credential values are required after submitting the app to the Freshworks Marketplace, you can make these changes directly on the app details page. The updated credentials values are then applied to all existing versions of the app that use the app settings functionality.

This functionality eliminates the need to republish a new version of the app whenever you need to update the values of these credentials.

Important:If you have already published an app and want to use the app settings functionality, follow this document to update your app code and release a new app version on the Freshworks marketplace. Once updated, you can change the existing credential values without releasing another version, unless you need to add a new set of credentials in the app code.

To implement app settings,

  1. Create app_settings.json file inside the config folder of the app’s root directory and define the credentials.
  2. Add the onSettingsUpdate method in the server.js file.

Create app_settings.json file

The app requires a configuration file named app_settings.json to implement the app settings functionality.

In the app_settings.json file, construct a JSON structure of key-value pairs where only the keys are defined, and the values are empty objects. The keys represent the name of the credentials that the app will use.

To set up the app_settings.json file,

  1. From the app’s root directory, navigate to the config folder and create the app_settings.json file.

  2. In the app_settings.json file, define the keys to be used by the app, leaving the values empty. The corresponding values are provided by the app developer in the following scenarios:

    • Local development: When running the app using fdk run, open the app settings page and enter values for the keys, as explained in the Test the app section.
    • Production: During app submission to the Freshworks Marketplace, navigate to the App Settings tab and enter values for the keys.

    Note:The provided key-value pairs of the app settings are returned as attributes in the app_settings JSON object of every serverless events payload.

Important:
  • There is no limit on the number of keys in the app_settings.json file. However, the file size should not exceed 50 KB.
  • Using nested JSON objects is not supported in the app_settings.json file.
  • For an already published app that uses this app settings functionality, adding new keys is supported. However, if you remove existing keys from the app_settings.json file and then pack the app for submission, you will encounter an error when submitting the latest app version to the Freshworks Developer portal.

Add the onSettingsUpdate method

The onSettingsUpdate method is used for validating the values passed to the keys defined in the app_settings.json file.

In the server.js file, define the onSettingsUpdate method and include,

  • the app logic that runs based on the payload passed.
  • the renderData() method to return success and failure responses.
Important:
  • If the server.js file does not contain the onSettingsUpdate method, an error is displayed when packaging the app using the fdk pack command.
  • Accessing app settings directly through the Request Method in the onSettingsUpdate method is not supported. However, you can access the app settings from the method's argument and pass them as context to the Request Method.
  • Using app settings through the Request Method with a template is supported in front-end apps and all serverless functions, except in the onSettingsUpdate method.

Test the app

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

  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. 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 and currentHost.endpoint_urls are determined.

  4. Click Continue.

  5. If the app uses app settings, the following message is displayed: To test the app settings page, visit - http://localhost:10001/app_settings

  6. Navigate to the specified location. The App Settings page is displayed.

  7. Enter appropriate values in the fields and click Save.

    Note:The provided key-value pairs of the app settings are returned as attributes in the app_settings JSON object of every serverless events payload.