Installation Parameters

The config/iparams.json file contains all the installation parameters (iparams) that app users configure when the app is installed. This section specifies how to:

  • Configure an iparam in the iparams.json file.
  • Use a configured iparam in the app.
  • Protect sensitive iparams from being exposed in the apps's front-end components.

Configure

During app installation, app users can configure the iparams which are displayed on an installation form.

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 ↓

For testing, navigate to http://localhost:10001/custom_configs and enter appropriate test values for the configured installation parameters.

Parameters

To configure the information parameters in the iparams.json file, specify each iparam as a JSON object with the following attributes.

Parameter Name Date Type Description
display_name
MANDATORY
string Specifies the parameter name on the installation form.
description
string Specifies the helper text that is displayed below the parameter. The description can include examples.
type
MANDATORY
string Specifies the type of input field displayed for the iparam.
Possible values: text, paragraph, dropdown, email, number, phone_number, date, url, radio, checkbox, multiselect
If the parameter value is specified as dropdown, radio, or multiselect, configure the options and default_value parameters.
For example usage of all possible values, see Types.
options
array of string Specifies the values to be displayed on the installation form, if the iparams' input field type is radio, multiselect, or dropdown.
default_value
string Specifies the value (from the list of values specfied in the options array) that has to be selected when the iparam is displayed on the installation form.
required (optional) boolean Set to true for required parameters. An asterisk is displayed near the required parameters in the UI.
secure (optional) boolean Specifies if the iparam is used to collect sensitive data, which has to be protected from exposure through the app’s front-end components.

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 Specifies the various regex expressions that are used to validate the parameter value entered on the installation form. The regex validation is performed in addition to the default field-type vaidation. 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, you need to manually update the API key in the Installation page.

Types

The following types of parameters are supported in the iparam.json file.

text - A single-line text field is displayed.

Copied Copy
1
2
3
4
5
6
7
8
{ "Employee-Name": { "display_name": "Employee Name", "description": "Please enter the employee name", "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 users can select a single option is 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": "dropdown", "options": [ "Full time", "Contract" ], "default_value": "Full time" } }
EXPAND ↓

email - A single-line text field where users can 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 where users can 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. Users can select a single value.

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 installation parameter.

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

You can retrieve the configured iparams and use them in the app components with the following methods:

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

Note:
1. Secure iparams can be used only with the Request method to make HTTP requests.
2. The serverless component of the app can access iparams directly from the event payload.

client.iparams.get() Method

This method returns all 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) Method

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 Success 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." }