Installation Parameters

The config/iparams.json file contains all the installation parameters (iparams) whose values can be set by an app user when the app is installed. This section specifies how to configure an installation parameter in the iparams.json file, use a configured iparam in the app, and protect sensitive installation parameter values from being exposed in the apps's front-end components.

Configure

During app installation, the iparams configured in the iparams.json file are displayed on an installation form, which app users can use to set values for the parameters.

Sample iparams.json

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
37
{ "contact": { "display_name": "Phone / Email", "description": "Please enter the contact details", "type": "text", "required": true }, "contact-type": { "display_name": "Contact Type", "description": "Please select the contact type", "type": "dropdown", "options": [ "Phone", "Email" ], "default_value": "Email" }, "domain-name": { "display_name": "Domain Name", "description": "Please enter your domain name", "type": "domain", "type_attributes": { "product": "freshsales" }, "required": true }, "api-key": { "display_name": "API Key", "description": "Please enter your api_key", "type": "api_key", "secure": true, "required": true, "type_attributes": { "product": "freshsales" } } }
EXPAND ↓

Attributes

In the iparams.json file, specify each iparam as a JSON object with the following attributes.

ATTRIBUTE NAME DATE TYPE DESCRIPTION
display_name
MANDATORY
string Identifier of a parameter on the installation form.
description string Helper text that is displayed along with the parameter, on the installation form. The description can include examples.
type
MANDATORY
string Type of input field displayed, for the iparam, on the installation form.
Possible values: text, paragraph, dropdown, email, number, phone_number, date, url, radio, checkbox, multiselect, domain, api_key
For information on the available types of input fields, see Types.
options array of string List of values displayed on the installation form, if the iparam’s input field type is radio, multiselect, or dropdown.
default_value string Preselected value (from options) displayed on the installation form, if the iparam’s input field type is radio, multiselect, or dropdown.
required boolean Specifies whether the iparam is displayed as a mandatory parameter. An asterix is displayed near the parameter on the installation form.
Possible values: true, false
secure boolean Specifies whether the iparam is used to collect sensitive data, which has to be protected from exposure through the app’s front-end components.
Possible values: true, false
Example Copied Copy
1
2
3
4
5
6
7
8
{ "apiKey": { "display_name": "Api Key", "type": "text", "required": true, "secure": true } }
For comprehensive information on secure iparams, read the securing sensitive installation parameters blog post.
regex object Expression(s) used to validate a parameter value entered in the installation form. The regex validation is performed in addition to the default field-type validation. If the validation fails, an error message is displayed. The regex expression and associated error message formats are as follows:
"<regex_name>":"<valid_regex_expression>"
"<regex_name>":"<error_message>"
Example regex expression to verify that the age entered is between 10 and 99 Copied Copy
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" } } }
EXPAND ↓
data-bind string Used to autopopulate text fields. Sometimes, you might require certain product settings while installing an app. At present, you can retrieve the product's API key and Domain by using data-bind as shown in the following sample code. Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "api_key": { "display_name": "Freshsales API key", "description": "Please enter your Freshsales API key", "type": "text", "data-bind": "product.api_key", "required": true }, "domain": { "display_name": "Freshsales Domain", "description": "Please enter your Freshsales Domain", "type": "text", "data-bind": "product.domain", "required": true } }
EXPAND ↓
type_attributes object Freshworks’ product to which the app belongs. This attribute is required if the iparam’s input field type is domain or api_key.

Note: After app installation, if the API key is reset, ensure to manually update the API key on the Installation page.

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.

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

Paragraph - A multi-line text field is displayed.

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

Drop-Down - 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.

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

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

Copied Copy
1
2
3
4
5
6
7
8
{ "Email-Address": { "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.

Copied Copy
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.

Copied Copy
1
2
3
4
5
6
7
8
{ "Phone-Number": { "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.

Copied Copy
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.

Copied Copy
1
2
3
4
5
6
7
8
{ "Freshsales Domain": { "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.

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

Checkbox - A checkbox is displayed next to the iparam.

Copied Copy
1
2
3
4
5
6
7
8
{ "Delete-Lead": { "display_name": "Delete Lead", "description": "Check this option if the leads are to be deleted", "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.

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

domain - An input box to enter the account name 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 domain_name JSON object.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "domain_name": { "display_name": "domain_name", "description": "Please enter your domain name", "type": "domain", "type_attributes": { "product": "freshsales" }, "required": true } }
EXPAND ↓

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

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
{ "api_key": { "display_name": "api_key", "description": "Please enter your api_key", "type": "api_key", "secure": true, "required": true, "type_attributes": { "product": "freshsales" } } }
EXPAND ↓

Note: The domain name and API key are validated when the app is installed.

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:
1. Secure iparams can be used only with the Request API to make HTTP requests.
2. For serverless apps, iparams are available in the payload received with each event.


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

Copied Copy
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

Copied Copy
1
2
3
4
5
6
{ "contact": "andrea@freshsales.io", "contact-type": "Email", "request_domain": "sample.freshsales.io", "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.

Copied Copy
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 Successful Response

1
2
3
{ "contact": "andrea@freshsales.io" }

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.
  3. Enter appropriate values in the fields and click INSTALL.