The FDK enables you to define and use parameters whose values app users can set when they install an app. These parameters are termed installation parameters or iparams. To define and use iparams:

1. Configure the iparams. During app installation, the configured iparams are displayed on an installation page. App users can enter appropriate values for the iparams and click INSTALL. The entered values are validated and saved.
2. In the app logic, use the client.iparams.get(), client.iparams.get(iparam_key), or the Request method (for secure iparams), to retrieve the iparam values.
   Note: To prevent exposure of sensitive iparam information, secure iparams can only be retrieved by the Request method.

Configure

1. From your app’s root directory, navigate to the iparam.json file.
2. Configure iparams by using the following sample format.

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
35
36
37
38
39
40
41
42
{
  "contact": {
    "display_name": "Contact Details",
    "description": "Please enter the contact details",
    "type": "text",
    "required": true
  },
  "age": {
    "display_name": "Age",
    "description": "Please enter your age in years",
    "type": "number"
  },
  "contactType": {
    "display_name": "Contact Type",
    "description": "Please select the contact type",
    "type": "dropdown",
    "options": [
      "Phone",
      "Email"
    ],
    "default_value": "Email"
  },
  "domainName": {
    "display_name": "Domain Name",
    "description": "Please enter your domain name",
    "type": "domain",
    "type_attributes": {
      "product": "freshworks_crm"
    },
    "required": true
  },
  "apiKey": {
    "display_name": "API Key",
    "description": "Please enter your api_key",
    "type": "api_key",
    "secure": true,
    "required": true,
    "type_attributes": {
      "product": "freshworks_crm"
    }
  }
}

Configure each iparam as a JSON object with the following attributes.

1
2
3
4
5
6
7
8
9
{
    "contact": {
      "display_name": "Contact Details",
      "description": "Please enter the contact details",
      "type": "text",
      "required": true,
      "visible": true
    }
  }

1
2
3
4
5
6
7
8
{
  "apiKey": {
    "display_name": "Api Key",
    "type": "text",
    "required": true,
    "secure": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
{
 "Age": {
   "display_name": "Age",
   "description": "Please enter your age in years",
   "type": "text",
   "regex": {
     "age-limit": "[1-9][0-9]",
     "age-limit-error": "The age must be between 10-99"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
              "apikey": {
                "display_name": "API key",
                "description": "Please enter your account’s API key",
                "type": "text",
                "data-bind": "product.api_key",
                "required": true
              },
              "domain": {
                "display_name": "Product Domain",
                "description": "Please enter your account’s Domain",
                "type": "text",
                "data-bind": "product.domain",
                "required": true
              }
              "url": {
                "display_name": "Product URL",
                "description": "Please enter your product URL",
                "type": "text",
                "data-bind": "product.url",
                "required": true
              }
          }

Types

In the iparam.json file, the type parameter value should be one of the following.

text - A single-line text field is displayed on the installation form.

1
2
3
4
5
6
7
8
{
  "ContactDetails": {
    "display_name": "Contact details",
    "description": "Please enter the contact details",
    "type": "text",
    "required": true
  }
}

paragraph - A multi-line text field is displayed.

1
2
3
4
5
6
7
8
{
  "ContactAddress": {
    "display_name": "Contact address",
    "description": "Please enter the contact address",
    "type": "paragraph",
    "required": true
  }
}

dropdown - A drop-down list from which a single option can be selected is displayed. The values specified in the options attribute of the iparams.json file are used to populate the drop-down list.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "ContactType": {
    "display_name": "Contact Type",
    "description": "Please select the contact type",
    "type": "dropdown",
    "options": [
      "Phone",
      "Email"
    ],
    "default_value": "Email"
  }
}

email - A single-line text field to enter a valid email address is displayed.

1
2
3
4
5
6
7
8
{
  "EmailAddress": {
    "display_name": "Email Address",
    "description": "Please enter your email address",
    "type": "email",
    "required": true
  }
}

number - A numeric field that accepts integers upto 10 digits is displayed.

1
2
3
4
5
6
7
8
{
  "Age": {
    "display_name": "Age",
    "description": "Please enter your age in years",
    "type": "number",
    "required": true
  }
}

phone_number - A single-line text field to enter a valid phone number is displayed.

1
2
3
4
5
6
7
8
{
  "PhoneNumber": {
    "display_name": "Phone Number",
    "description": "Please enter your phone number with the country code",
    "type": "phone_number",
    "required": true
  }
}

date - A field to enter a valid date (or pick a date by using a date picker) is displayed.

1
2
3
4
5
6
7
8
{
  "Birthday": {
    "display_name": "Birthday",
    "description": "Please enter your birthday",
    "type": "date",
    "required": true
  }
}

url - A single-line text field to enter a valid URL is displayed.

1
2
3
4
5
6
7
8
{
  "Freshworks_crmDomain": {
    "display_name": "Freshsales Domain",
    "description": "Please enter your Freshsales domain web address",
    "type": "url",
    "required": true
  }
}

radio - Radio buttons along with values specified in the options attribute of the iparams.json file are displayed.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "ContactType": {
    "display_name": "Contact Type",
    "description": "Please select the contact type",
    "type": "radio",
    "options": [
      "Phone",
      "Email"
    ],
    "default_value": "Email"
  }
}

checkbox - A checkbox is displayed next to the iparam.

1
2
3
4
5
6
7
8
{
  "ArchiveTicket": {
    "display_name": "Archive ticket",
    "description": "Check this option if the tickets are to be archived",
    "type": "checkbox",
    "default_value": true
  }
}

multiselect - A list, from which users can select one or more options, is displayed. The values specified in the options attribute of the iparams.json file are used to populate the list.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "ContactMethods": {
    "display_name": "Contact Methods",
    "description": "Please select the preferred contact methods",
    "type": "multiselect",
    "options": [
      "Phone",
      "Mobile",
      "Twitter ID",
      "Email"
    ],
    "default_value": ["Mobile", "Email"]
  }
}

domain - An input box to enter the sub-domain part of a domain URL is displayed. By default, the protocol and domain name part of the URL are displayed in the input box and are not editable. The domain name is generated based on the type_attributes.product value that is specified as part of the JSON object used to define the iparam.

1
2
3
4
5
6
7
8
9
10
11
{
  "domainName": {
    "display_name": "Domain_FCRM",
    "description": "Enter the domain of your Freshsales Suite account",
    "type": "domain",
    "type_attributes": {
      "product": "freshworks_crm"
     },
    "required": true
  }
}

If the type_attributes.product value is freshworks_crm, in the input box that is displayed on the Installation page, the domain name part is populated as myfreshworks.com.
If the value is freshworks_crm and if the app is installed on a Freshsales Suite account that has been migrated from Freshsales Classic, the domain name part is populated as freshworks.com.

If the type_attributes.product value is current, the domain name is populated based on the product on which the app is installed. If the app is installed on an Freshsales Suite account, the domain name part is populated as myfreshworks.com or freshworks.com (if the account is migrated from Freshsales Classic).

api_key - A single-line text box to enter the product’s API key is displayed.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "apiKey": {
    "display_name": "api_key",
    "description": "Enter your api_key",
    "type": "api_key",
     "secure": true,
     "required": true
     "type_attributes": {
       "product": "freshworks_crm"
      }
    }
  }

Note: The iparams of the domain and api_key types are validated when the app is installed.

Make your installation page dynamic

You can build a product specific installation page by using the onFormLoad() and onFormUnload() functions. The onFormLoad() is a callback function that is triggered when an Installation page is loaded, during app installation. The onFormUnLoad() is a callback function that is triggered when the Settings page, where the app user enters values for the installation parameters, is closed. On app initialization, the client.context.productContext is set based on the product account on which the app is being installed. The callback functions use productContext to render an Installation page with iparams whose attributes are set based on productContext. To do this:

1. From the app’s root directory, navigate to the config directory and create the assets/iparams.json file.
2. Define the onFormLoad()() and onFormUnLoad()() callback functions by using the following sample format. 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
   function onFormLoad() {
             app.initialized().then(
               function(client)
               {
                 let product = client.context.productContext.name;
                 if(product == "freshsales")
                 {
                  //iparams definition for Freshsales Classic
                }else if(product == "freshworks_crm")
                {
                  //iparams definition for Freshsales Suite
                }else{
                 console.log("ERROR:Missing Expected product from client");
                }
               },
               function(error)
               {
                 //If unsuccessful
                 console.log("ERROR:Problem in fetching product from client");
               }
             );
           }
             function onFormUnload() {
               //logic to perform when the installation page is closed
             }

   EXPAND ↓
3. To set or modify the attribute value of iparams, based on productContext, use utils.set(); in the callback function definition. For information on how to use utils.set();, see iparam utility methods.

   Sample iparams.js to render product specific installation page

   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
   35
   36
   function onFormLoad() {
             app.initialized().then(
             function(client)
             {
               let product = client.context.productContext.name;
               if(product == "freshsales")
               {
                 //Change display names based on product
             utils.set("Domain", {label: "Freshsales Domain"});
             utils.set("ApiKey", {label: "Freshsales API Key"});
                 //Change hint based on product
                   utils.set("Domain", {hint: "Enter the sub-domain of your Freshsales account"});
                   utils.set("ApiKey", {hint: "Enter API key of your Freshsales account"});
           //Hide FCRM specific fields
             utils.set("FieldToDisplayInFCRM", {visible: false});
           }else if(product == "freshworks_crm")
                 {
           //Change display names based on product
             utils.set("Domain", {label: "FCRM Domain"});
             utils.set("ApiKey", {label: "FCRM API Key"});
                 //Change hint based on product
                   utils.set("Domain", {hint: "Enter the sub-domain of your FCRM account"});
                   utils.set("ApiKey", {hint: "Enter API key of your FCRM account"});
           //Hide Freshsales specific fields
             utils.set("FieldToDisplayInFreshsales", {visible: false});
           }else{
           console.log("ERROR:Missing expected product from client");
           }
           },
           function(error)
           {
             //If unsuccessful
               console.log("ERROR:Problem in fetching product from client");
            }
             );
           }

   EXPAND ↓

When you configure iparams, you can use the events attribute to build a dynamic installation page to collect values for the installation parameters.

1. From the app’s root directory, navigate to the config/iparams.json file.
2. Include the events attribute as part of the iparam configuration. Specify an HTML event and a corresponding callback function, as a JSON object of "<event name>": "<callback function name>" pair by using the following sample format. Copied Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   {
   "firstname": {
     "display_name": "First Name",
     "description": "Please enter your business name",
     "type": "text",
     "required": true,
     "events": [
       {"change": "firstnameChange"}
     ]
   },
   "multiselect": {
     "display_name": "Other Details",
     "description": "Please select values",
     "type": "multiselect",
     "required": true,
     "options": [
       "opt1",
       "opt2",
       "opt3"
     ]
   }
   }

   EXPAND ↓
3. From the app’s root directory, navigate to the config directory and create the assets/iparams.js file.
4. Define the callback function by using the following sample format.
   Note: Ensure that the callback function’s name is the <callback function name> specified in the iparams.json file.
   Copied Copy

   1
   2
   3
   4
   5
   function firstnameChange(arg) {
     //validation logic and subsequent action performed
     //arg is the iparam value passed to the callback function
     console.log(arg);
   }

5. To set or modify the attribute value of an iparam and add validations to an iparam, based on the input value of another iparam, use utils.set(); in the callback function definition.
   For more information, see iparam utility methods.
6. To retrieve the value of an iparam, based on the input value of another iparam, use utils.get(); in the callback function.
   For more information, see iparam utility methods.
7. To validate a value entered for an iparam or use the value entered to perform some action (such as an API call), validate the value returned, and display a success or failure message, use return; in the callback function.
   For more information, see return;.

When an app user enters or modifies an iparam value, the change event is triggered and the iparam value is passed to the callback function. The value is validated and subsequent actions are performed. The validation and actions are based on the logic defined in the callback function.

iparams utility methods

The FDK consists of in-built utility methods that enable you to set or modify the attribute value of an iparam, add validations to an iparam, and retrieve the value of an iparam during run-time. You can use the following methods in your callback function.

utils.set();

Enables you to set or modify the iparam attributes that are displayed in the installation page or impart further validations to the iparams.

1
utils.set(‘<iparam_key>’, {<attribute>: <value>});

<iparam_key> identifies the iparam that is modified or validated when the change event occurs.
<attribute> specifies the iparam’s installation page attribute that is modified or the validation set for the iparam. <value> specifies the value that is set for <attribute> and must adhere to the data type of <attribute>.

For an iparam identified by <iparam_key>, <attribute> can be any of the following values.

value

Sample code to set the value of the lastname iparam to the value the app user specifies for the firstname iparam.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
     "display_name": "Last Name",
     "description": "Please enter your last name",
     "type": "text",
     "required": false
  }
}

1
2
3
function firstnameChange(arg) {
  utils.set(‘lastname’, {value: arg});
}

Sample code to populate the multiselect iparam field with a list of options, if the app user specifies a value for the firstname iparam.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "firstname": {
    "display_name": "First Name",
     "description": "Please enter your business name",
     "type": "text",
     "required": true,
     "events": [
      {"change": "firstnameChange"}
     ]
  },
  "multiselect": {
     "display_name": "Other Details",
     "description": "Please select values",
     "type": "multiselect",
     "required": true,
     "options": [
  	   "opt1",
  	   "opt2",
  	   "opt3"
     ]
  }
}

iparams.js

1
2
3
function firstnameChange(arg) {
  utils.set(‘multiselect’, {value: [opt1,opt2]});
}

visible

Sample code to hide the lastname iparam from the installation page, if the app user specifies a value for the firstname iparam.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
}

iparams.js

1
2
3
function firstnameChange(arg) {
  utils.set(‘lastname’, {visible: false});
}

Sample code to display the lastname iparam in the installation page, if the app user enters a valid value for the firstname iparam and to hide the lastname iparam from the installation page, if the app user deletes the entered value.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
}

iparams.js

1
2
3
function firstnameChange(arg) {
  utils.set(‘lastname’, {visible: arg !== ‘’});
}

values

Sample code to modify the list of options available for the multiselect iparam and display_name to Hobbies, if the app user enters a value for the firstname iparam.

iparams.json

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
{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
  "multiselect": {
    "display_name": "Other Details",
    "description": "Please select values",
    "type": "multiselect",
    "required": true,
    "options": [
	    "opt1",
	    "opt2",
	    "opt3"
    ]
  }
}

iparams.js

1
2
3
function firstnameChange(arg) {
  utils.set(‘multiselect’, {values: [Travelling, Swimming, Reading books], label: ‘Hobbies’});
}

min and max

Sample code to set a validation criteria and to modify display_name of the age iparam, if the app user enters a value for the firstname iparam.
When the app user enters a value for the age iparam, if the value fails to meet the validation criteria, an error message is displayed.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "age": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "number",
    "required": false
  }
}

iparams.js

1
2
3
function firstnameChange(arg) {
  utils.set(‘age’, {label: ‘Age in years’, min: 18, max: 65});
}

utils.get();

Enables you to identify an iparam and retrieve its value during run-time.

Format

1
utils.get(‘<iparam_key>’);

<iparam_key> identifies the iparam whose value is retrieved when the change event occurs.

return;

Returning an error message, clears the value entered for the iparam and thereby invalidates the field. Returning an empty string or not returning a value, passes the validation as a success.

Format

1
return <validation criteria> ? ‘<Success Message>’: ‘<Error Message>’;

Sample code to make an API call based on the value entered for the APIKey iparam, validate if an empty value is returned by the API call, and if so, display an error message.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "APIKey": {
    "display_name": "API Key",
    "description": "Please enter your api key",
    "type": "api_key",
    "secure": true,
    "required": true,
    "type_attributes": {
      "product": "freshworks_crm"
    },
    "events": [
      {"change": "APIKeyChange"}
    ]
  }
}

iparams.js

1
2
3
4
5
function APIKeyChange(arg) {
//API call by using arg which is the API Key entered by the app user
//value is the response returned by the API call
  return value==‘’ ? ‘Invalid API Key’: ‘’;
}

Sample code to invoke a third-party API based on the value entered for the acc_id iparam and validate the iparam field asynchronously by using the callback functionality.

iparams.json

1
2
3
4
5
6
7
8
9
10
11
{
  "acc_id": {
    "display_name": "Account ID",
    "description": "Please enter your Acc. ID",
    "type": "text",
    "required": true,
    "events": [{
      "change": "checkAccountID"
    }]
  }
}

iparams.js

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
35
/* global app, client, utils */
app.initialized().then(
  function(_client) {
    //If successful, register the app activated and deactivated event callback.
    window.client = _client;
  },
  function(error) {
    //If unsuccessful
    console.log(error);
  }
);

/* Using the iparam callback function, we are validating the iparam value after a third-party API call. */
/* Payload and other options can be specified using ‘options’. */
function checkAccountID(newValue) {
  var url = "https://example.com/verify";
  var options = {
    body: JSON.stringify({
      param: newValue
    })
  };
  var p = new Promise(function(resolve, reject) {
    client.request.post(url, options).then(
      function(data) {
        // Upon success
        resolve();
      },
      function(error) {
        // Upon failure - send an appropriate validation error message
        reject("The account does not exist.");
      }
    );
  });
  return p;
}

Retrieve

To retrieve the configured iparams and to use them in the app components, use the following methods:

• client.iparams.get()
• client.iparams.get(iparam_key)

Note: Secure iparams can be retrieved through the Request Method as part of HTTPS request headers.

client.iparams.get() - This method returns all the configured installation parameters except secure iparams.

1
2
3
4
5
6
7
8
9
10
client.iparams.get().then (
    function(data) {
      // success output
      // "data" is returned with the list of all the iparams
    },
    function(error) {
      console.log(error);
      // failure operation
    }
);

Sample Response

1
2
3
4
5
6
{
  "contact": "rachel@freshworks.com",
  "contact-type": "Email",
  "request_domain": "sample.freshworks.com",
  "subdomian": "sample"
}

client.iparams.get(iparam_key) - This method identifies an iparam by the iparam key specified and returns the value corresponding to the iparam. If you try to retrieve a secure iparam, an error message is displayed.

1
2
3
4
5
6
7
8
9
10
client.iparams.get("contact").then (
    function(data) {
      // success output
      // "data" is returned with the value of the "contact" attribute.
    },
    function(error) {
      console.log(error);
      // failure operation
    }
);

Sample Success Response

1
2
3
{
  "contact": "rachel@freshworks.com"
}

Sample Failure Response

1
2
3
{
  "message": "Could not find an installation parameter that matches this key."
}

Test

To test the configured installation parameters:

1. From the command prompt, navigate to the app project folder, and run the following command: $ fdk run If the app contains an Installation page, the following message is displayed: To test the installation page, visit - http://localhost:10001/custom_configs
2. Navigate to the specified location. The Installation page is displayed.
Note: For an app, if a domain type iparam is configured, when testing the installation page, the domain part of the URL is updated as myfreshworks.com
3. Enter appropriate values in the fields and click INSTALL.