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
9.0.0 or later Node 18.x Live.
8.0.0 or 8.6.7 Node 14.x Planned to be deprecated by July 31st, 2023.
Please ensure to migrate your local FDK to the latest version.
7.0.0 - 7.5.1 Node 12.x Deprecated as on September 30, 2022.
Prior to 7.0.0 Node 10.x Deprecated.

Local FDK version Create, validate, or test an app…
Built with 8.0.0 or later Built with 6.13.0 - 7.5.1 Prior to 6.13.0
9.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.3.

    5. Displays an error message stating that the parameter whitelisted-domains in manifest.json is deprecated.

  2. Migrate your app to the latest platform version.

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

    5. Displays an error message stating that the parameter whitelisted-domains in manifest.json is deprecated.

  2. Migrate your app to the latest platform version

  3. Run the fdk run command to test the app. This generates the coverage folder.
8.0.0 - 8.6.7

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

    5. Displays an error message stating that the parameter whitelisted-domains in manifest.json is deprecated.

  2. Migrate your app to the latest platform version.

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

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

    5. Displays an error message stating that the parameter whitelisted-domains in manifest.json is deprecated.

  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 latest platform version is 2.3. Migrate your app to the latest platform version.

    5. Displays an error message stating that the parameter whitelisted-domains in manifest.json is deprecated, if the app was built with 6.11.0 - 7.5.1.

  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

Construct request templates (config/requests.json)

If your app uses the request method to make secure HTTP calls to third-party domains, you should modify the app files such that they use the latest templated request method. To perform this,

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

  2. In requests.json, provide appropriate <requestTemplateName>s and create empty snapshots for all requests that the app uses. For information on how to create a snapshot, see Configure request templates.

  3. In your app.js or server.js files, look for the details similar to the ones mentioned in the following table and move them to appropriate sections of config/requests.json - that is, fill in the snapshot.

Details in app.js or server.js Corresponding config/requests.json attributes to fill in
Core request attributes

In app.js or server.js, look out for properties such as headers and URL. Move the values of these properties to the corresponding attributes in config/requests.json. The mapping is as follows:

  • Break down the URL into components such as protocol, host, and path. This maps to <requestTemplateName>.schema.protocol, <requestTemplateName>.schema.host, and <requestTemplateName>.schema.path.
  • Identify the HTTP method from client.request.get(), $request.get(), and other such methods. This maps to <requestTemplateName>.schema.method.
  • options.headers maps to <requestTemplateName>.schema.headers.
 
1
const URL = 'https://${subdomain}.freshcaller.com/api/v1/calls';
 • Set <requestTemplateName>.schema.protocol as https
• Set <requestTemplateName>.schema.host as <%= iparam.subdomain %>.freshcaller.com
• Set <requestTemplateName>.schema.path as /api/v1/calls.
 
1
client.request.get(URL, authOpts)
 Or 
1
$request.get(URL, authOpts)
 		Set <requestTemplateName>.schema.method as GET 
1
2
3
4
headers: {
  'Authorization': 'Basic <%= encode(iparam.api_key) %>',
  'Content-Type': 'application/json'
}
 Set <requestTemplateName>.schema.headers as follows:
1
2
3
4
"headers": {
  "Authorization": "Basic <%= encode(iparam.api_key) %>",
  "Content-Type": "application/json"
}
Options

In app.js or server.js, look out for options such as headers, maxattempts, retryDelay, and isOAuth. Move the values of these options to the corresponding attributes in config/requests.json. The mapping is as follows:

  • options.headers maps to <requestTemplateName>.schema.headers
  • options.isOAuth maps to <requestTemplateName>.options.isOAuth
  • options.maxAttempts maps to <requestTemplateName>.options.maxAttempts
  • options.retryDelay maps to <requestTemplateName>.options.maxAttempts

Request body: In the new request method, the request body is passed at runtime as part of the invokeTemplate() call and is not part of config/requests.json. So, look for options.body and use it appropriately in app.js or server.js. For more information, see App code changes.

Response caching: If app.js or server.js contains options.cache and options.ttl, for information on how to migrate them to the new request method, see App code changes.

 
1
2
3
4
5
6
7
let authOpts = {
  'headers': {
      'Authorization': 'Basic <%= encode(iparam.api_key) %>',
      'Content-Type': 'application/json'
    },
  'isOAuth': false
}
 		Set <requestTemplateName>.options as follows:
1
2
3
"options": {
  "isOAuth": false
}
 And
Set <requestTemplateName>.schema.headers as follows:
1
2
3
4
"headers": {
  "Authorization": "Basic <%= encode(iparam.api_key) %>",
  "Content-Type": "application/json"
}
 
1
2
3
4
5
6
7
let authOpts = {
  'headers': {
  'Authorization': 'Basic <%= encode(iparam.api_key) %>',
  'Content-Type': 'application/json'
  },
  'maxAttempts': 2
}
 		Set <requestTemplateName>.options as follows:
1
2
3
"options": {
  "maxAttempts": 2
}
 And
Set <requestTemplateName>.schema.headers as follows:
1
2
3
4
"headers": {
  "Authorization": "Basic <%= encode(iparam.api_key) %>",
  "Content-Type": "application/json"
}
 
1
2
3
4
5
6
7
let authOpts = {
  'headers': {
      'Authorization': 'Basic <%= encode(iparam.api_key) %>',
      'Content-Type': 'application/json'
  },
  'retryDelay': 100
}
 		Set <requestTemplateName>.options as follows:
1
2
3
"options": {
  "retryDelay": 100
}
 And
Set <requestTemplateName>.schema.headers as follows:
1
2
3
4
"headers": {
  "Authorization": "Basic <%= encode(iparam.api_key) %>",
  "Content-Type": "application/json"
}

manifest.json changes

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

  2. In manifest.json, remove the deprecated attribute - whitelisted-domains.

  3. If your app uses the request method to make secure HTTP calls to third-party domains, in manifest.json, list all request templates that the app intends to use. To do this, under product.<productName>, add a requests attribute of the following format.

    Copied Copy 
    1
    2
    3
    4
    5
    		"requests": {
"<requestTemplateName>":{},
"<requestTemplateName1>": {}
…
}
    Note: Ensure that the <requestTemplateName> is the same as that configured in config/requests.json.

  4. To migrate a serverless SMI app built on FDK versions prior to 6.13.0, 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.

  5. To migrate a serverless app built on FDK versions prior to 6.13.0, 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 ↓     For more information, see App Manifest.

Sample manifest.json after all platform 2.3 changes are incorporated

For front-end apps

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "platform-version": "2.3",
    "product": {
      "freshcaller": {
        "location": {
          "conversation_card": {
            "url": "template.html",
            "icon": "logo.svg"
          }
          "requests": {
            "createCall": {},
            "getCalls": {}
          }
        }  
      }
    },
    "engines": {
      "node": "18.12.1",
      "fdk": "9.0.0"
  }
}
EXPAND ↓

For serverless apps

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "platform-version": "2.3",
    "product": {
      "freshcaller": {
        "events": {
          "onCallCreate": {
            "handler": "onCallCreateHandler"
          }
        },
        "requests": {
          "createCall": {},
          "getCalls": {}
        }
      }
    },
    "engines": {
      "node": "18.12.1",
      "fdk": "9.0.0"
  }
}
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
30
31
32
33
34
{
    "platform-version": "2.3",
    "product": {
        "freshcaller": {
            "location": {
              "conversation_card": {
                    "url": "index.html",
                    "icon": "styles/images/icon.svg"
                }
            },
            "events": {
                "onCallCreate": {
                    "handler": "onCallCreateHandler"
                },
                "onExternalEvent": {
                    "handler": "onExternalEventHandler"
                }
            },
            "functions": {
                "serverMethod": {
                    "timeout": 10
                }
            },
            "requests": {
                "createCall": {},
                "getCalls": {}
            }
        }
    },
    "engines": {
        "node": "18.12.1",
        "fdk": "9.0.0"
    }
}
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 18. In your app code, ensure that the app code doesn’t contain any Node.js features that are deprecated.

  2. In the front-end HTML files (such as iparams.html), replace the existing client JS resource as follows:

    Replace:

    Copied Copy 
    1
    2
    		<script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js">
</script>

    with:

    Copied Copy 
    1
    		<script src="{{{appclient}}}"></script>

  3. If your app uses the request method to make secure HTTP calls to third-party domains, you should modify the app.js file such that it uses the latest templated request method. To do this, look for the details similar to the ones mentioned in the following table and move them to the appropriate specified format.

    4. Details in app.js or server.js Format to be moved to
    Runtime API for front-end apps 
    1
    		client.request.get(URL, authOpts)
     Sample 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    		async function getCalls(client) {
  let { subdomain } = await client.iparam.get('subdomain');
  const URL = 'https://${subdomain}.freshcaller.com/api/v1/calls';
  let authOpts = {
    headers: {
      'Authorization': 'Basic <%= encode(iparam.api_key) %>',
      'Content-Type': 'application/json'
    }
  }
  let response = await client.request.get(URL, authOpts)
  // logic with the response ....
}
    EXPAND ↓ 
    1
    		client.request.invokeTemplate(requestTemplateName, {})
     Sample 
    1
    2
    3
    4
    5
    		async function getCalls(client) {
    let response = await client.request.invokeTemplate(
      "getCalls", {})
    // logic with the response ....
}
    Response caching options for front-end apps 
    1
    2
    3
    4
    		let authOpts = {
    'cache': true,
    'ttl': 70000
}
     
    1
    2
    		client.request.invokeTemplate(requestTemplateName,{
  cache: true, ttl: 70000});
    Runtime API for serverless apps 
    1
    		$request.get(URL, authOpts)
     
    1
    		$request.invokeTemplate(requestTemplateName, {});
    Request body 
    1
    2
    3
    4
    5
    6
    7
    		client.request.post(URL, {
  headers: {
    Authorization: "Bearer <%= encode(iparam.ApiToken) %>"
  },
  body: JSON.stringify({
    "email": "yeahItsMail@freshworks.com"})
});
     
    1
    2
    3
    		client.request.invokeTemplate(requestTemplateName, {
  body: JSON.stringify({
    "email": "yeahItsMail@freshworks.com"})});

  4. In the front-end HTML files (such as iparams.html), replace the existing client JS resource as follows:

    Replace: 
    1
    		<script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script>

    with: 
    1
    		<script src="{{{appclient}}}"></script>
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 18. 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.