Migration Overview

As part of our initiatives to better our app development environment and enable developers to build secure apps, the app development platform and the FDK are constantly upgraded. Though most of the upgrades are seamless and inherently handled by the FDK, at times upgrades entail migrating an app manually. In such cases, the FDK throws warning or error messages with appropriate links to resources that help in migration.

Important: When you run Freshworks CLI commands, an upgrade check is performed only if it hasn’t been performed in the last 24 hours. If a check has run in the last 24 hours, migration or upgrade warnings are not displayed.

The Migration Map

FDK and compatible Node.js versions

FDK version Node.js version Support for Node.js - Status
8.0.0 or later Node 14.x Live.
7.0.0 - 7.5.1 Node 12.x Deprecated as on September 30, 2022.
Please ensure to migrate your local FDK to the latest version.
Prior to 7.0.0 Node 10.x Deprecated.

Local FDK version Create, validate, or test an app…
Built with 6.13.0 - 7.5.1 Built prior to 6.13.0
8.0.0

There is a major version mismatch between the Node.js version used to build the app and the current version on which the app is run.

The FDK displays a warning message (provided an upgrade check is not run in the last 24 hours). The message mentions the Node.js version on which the app is developed, the version on which the app is run currently, and prompts for continuation.

  1. Type Yes. The FDK,

    1. Deletes the existing coverage folder if the app has a serverless component. The folder contains the coverage summary captured as a result of the previous fdk run.
      Note: The coverage folder is retained for front-end apps.

    2. Deletes the existing node_modules folder. The folder contains the npm dependencies (specified in manifest.json) that were installed during the previous fdk run.

    3. Includes or updates the engines attribute in manifest.json. The updated engines.node and engines.fdk values reflect the Node.js and FDK versions on which the app is validated.

    4. Displays an error message stating that the earlier platform version is deprecated, if the app was built on an earlier platform version. The latest platform version is 2.2. Migrate your app to the latest platform version.

      Note: Some apps built with 6.13.0 - 7.0.1 may be on earlier platform versions. For all these apps, the FDK displays the error message stating that the earlier platform version is deprecated.

  2. Run the fdk run command to test the app. This generates the coverage folder.

There is a major version mismatch between the Node.js version used to build the app and the current version on which the app is run.

The FDK displays a warning message (provided an upgrade check is not run in the last 24 hours). The message states the Node.js version on which the app is developed, the version on which the app is run currently, and prompts for continuation.

  1. Type Yes. The FDK,

    1. Deletes the existing coverage folder if the app has a serverless component. The folder contains the results of the previous fdk run that was used to set up the local server and test the app.
      Note: The coverage folder is retained for front-end apps.

    2. Deletes the existing node_modules folder. The folder contains the npm dependencies (specified in manifest.json) that were installed during the previous fdk run.

    3. Includes or updates the engines attribute in manifest.json. The updated engines.node and engines.fdk values reflect the Node.js and FDK versions on which the app is validated.

    4. Displays an error message stating that the earlier platform version (on which the app was built) is deprecated. The latest platform version is 2.2.

  2. Migrate your app to the latest platform version

  3. Run the fdk run command to test the app. This generates the coverage folder and coverage summary.
Any earlier FDK version - 7.5.1

The FDK displays a warning message stating that your FDK version is deprecated (provided an upgrade check is not run in the last 24 hours). The message directs you to resources that contain information on the deprecation.

The FDK displays another warning message. The message mentions the Node.js version on which the app is developed, the version on which the app is run currently, and prompts for continuation.

  1. Type Yes. The FDK,

    1. Deletes the existing coverage folder if the app has a serverless component. The folder contains the coverage summary generated as a result of the previous fdk run.
      Note: The coverage folder is retained for front-end apps.

    2. Deletes the existing node_modules folder. The folder contains the npm dependencies (specified in manifest.json) that were installed during the previous fdk run.

    3. Includes or updates the engines attribute in manifest.json. The updated engines.node and engines.fdk values reflect the Node.js and FDK versions on which the app is validated.

    4. Displays an error message stating that the earlier platform version is deprecated, if the app was built on an earlier platform version, the FDK. The latest platform version is 2.2. Migrate your app to the latest platform version.

      Note: All apps built prior to 6.13.0 are on earlier platform versions. Some apps built with 6.13.1 - 7.0.1 may be on earlier platform versions. For all these apps, the FDK displays the error message stating that the earlier platform version is deprecated.

  2. Migrate to the latest FDK version

  3. Run the fdk run command to test the app. This generates the coverage folder.
Migrate to the latest platform version

manifest.json changes

  1. platform-version: From the app’s root directory, navigate to manifest.json. Modify the platform-version value to 2.2.

  2. For a serverless SMI app, in manifest.json under product.<productName>, allow list all SMI functions/methods defined in the serverless component of the SMI app. To do this, in manifest.json, add an attribute - functions of the following format and list all SMI functions (server methods) defined in the exports code block of the app’s server.js file:

    Copied Copy 
    1
    2
    3
    4
    5
    6
    7
    8
    		"functions": {
  "<serverMethodName1>": {
    "timeout": 10
  },
  "<serverMethodName2>": {
    "timeout": 15
  }
}
    EXPAND ↓

    timeout (integer): Time in seconds beyond which the app execution times out, if the SMI function does not return a valid response to the front-end component. You can specify an appropriate timeout value based on the SMI function.
    Valid values : 5, 10, 15, and 20

    Notes:
    • If the SMI function does not return a response within the stipulated time, the app execution times out and an error message is displayed.
    • If an invalid timeout value is specified, the fdk run or fdk validate commands display the error message Timeout should be one of the allowed values.

  3. For a serverless app, in manifest.json, under product.<productName> register all the serverless events defined in server.js and the corresponding callback methods. To do this, in manifest.json, add an attribute - events of the following format and list all serverless methods defined in the exports code block of the app’s server.js file:

    Copied Copy 
    1
    2
    3
    4
    5
    6
    7
    8
    		"events": {
  "<eventName1>": {
    "handler": "<callbackFunctionName1>"
  },
  "<eventName2>": {
    "handler": "<callbackFunctionName2>"
  }
}
    EXPAND ↓

  4. In manifest.json, ensure that the whitelisted-domains attribute is present. If the app uses the Request method to make secure HTTP calls to third-party domains, in manifest.json, ensure to whitelist the third-party domains. For more information, see the whitelisted-domains attribute definition in App Manifest.

Sample manifest.json after all platform 2.2 changes are incorporated

For serverless apps

Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
      "platform-version": "2.2",
      "product": {
        "freshteam": {
          "events": {
            "onApplicantCreate": {
              "handler": "onApplicantCreateCallback"
            },
            "onExternalEvent": {
              "handler": "onExternalEventHandler"
            }
          }
        }
      },
      "whitelisted-domains": [
        "https://www.google.com"
    ]
    }
EXPAND ↓

For serverless SMI apps

Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "platform-version": "2.2",
  "product": {
    "freshteam": {
      "location": {
        "candidate_sidebar": {
          "url": "index.html",
          "icon": "styles/images/icon.svg"
        }
      },
      "events": {
        "onApplicantCreate": {
          "handler": "onApplicantCreateCallback"
        },
        "onExternalEvent": {
          "handler": "onExternalEventHandler"
        }
      },
      "functions": {
        "serverMethod": {
          "timeout": 10
        }
      }
    }
  },
  "whitelisted-domains": [
    "https://www.google.com"
  ]
}
EXPAND ↓

App code changes

  1. The latest FDK version supports app creation, testing, validation, and packing in a local developer environment that is based on Node.js 14. In your app code, ensure that the app code doesn’t contain any Node.js features that are deprecated.

  2. The latest FDK version contains support for the use of ES2020 features when building apps. This enables using constructs such as optional chaining operators in your app code.

  3. Ensure that template substitutions of the form <%= iparam.key %> are used only in the Request method.

Migrate to the latest FDK version

  1. Install Node.

  2. Install the Freshworks CLI. This upgrades your local FDK version to the latest FDK version.

Important: The latest FDK version supports app creation, testing, validation, and packing in a local developer environment that is based on Node.js 14. Ensure that the app code doesn’t contain any Node.js features that are deprecated.

Note: The latest FDK version contains support for the use of ES2020 features when building front-end apps. This enables using ES2020 features such as optional chaining operators in your app code.