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
{ "Employee-Details": { "display_name": "Employee Details", "description": "Please enter the employee details", "type": "text", "required": true }, "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" } }, "Employee-Type": { "display_name": "Employee Type", "description": "Please select the employee type", "type": "dropdown", "options": [ "Full time", "Contract" ], "default_value": "Full time" } }
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
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(s) (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 ↓

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
{ "Employee-Name": { "display_name": "Employee Name", "description": "Please enter the employee details", "type": "text", "required": true } }

paragraph - A multi-line text field is displayed.

Copied Copy
1
2
3
4
5
6
7
8
{ "Employee-Address": { "display_name": "Employee address", "description": "Please enter the employee 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.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
{ "Employee-Type": { "display_name": "Employee Type", "description": "Please select the employee type", "type": "dropdown", "options": [ "Full time", "Contract" ], "default_value": "Full time" } }
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
{ "Official-Email": { "display_name": "Official Email", "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
{ "Date-of-Birth": { "display_name": "Date of Birth", "description": "Please enter your date of birth", "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
{ "Team-Domain": { "display_name": "Team Domain", "description": "Please enter your team 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
{ "Employee-Type": { "display_name": "Employee Type", "description": "Please select the employee type", "type": "radio", "options": [ "Full time", "Contract" ], "default_value": "Full time" } }
EXPAND ↓

checkbox - A checkbox is displayed next to the iparam.

Copied Copy
1
2
3
4
5
6
7
8
{ "Archive-Details": { "display_name": "Archive Details", "description": "Check this option if the employee details 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.

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 ↓
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 Request Method 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
{ "employee": "rachel@freshteam.com", "employee_type": "Full time", "request_domain": "sample.freshteam.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.

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

Sample Successful Response

1
2
3
{ "employee": "rachel@freshteam.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.
  3. Enter appropriate values in the fields and click INSTALL to test the installation page.