Installation Parameters

Installation parameters or iparams are values that users configure when installing apps. You can define these parameters in the iparams.json file available in the config directory.

In addition, you can protect sensitive data, such as API keys and passwords, by marking it as secure so that app users cannot access the data in the front end via the browser console.

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
{ "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", "regex": {       "age-limit": "[1-9][0-9]",       "age-limit-error": "The age must be between 10-99" } }, "contact-type": { "display_name": "Contact Type", "description": "Please select the contact type", "type": "dropdown", "options": [ "Phone", "Email" ], "default_value": "Email" } }
EXPAND ↓

For testing, you have to set values for the iparam keys in the iparam_test_data.json file.

Sample test data

Copied Copy
1
2
3
4
{ "contact": "rachel@freshdesk.com", "contact-type": "Email" }
Types

The following types of parameters are supported.

Text - Single-line text.

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

Drop-Down - Drop-down list from which users can select a single option.

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 - Single-line text field where users can enter a valid email address.

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 - Users can enter a number (integers upto 10 digits).

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 - Single-line text field where users can enter a valid phone number.

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 - Users can either enter a date or select it from a date picker.

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

URL - Single-line text field where users enter a valid URL.

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

Radio - Radio buttons from which users can select a single value.

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 - Checkbox from which users can select more than a single value.

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

Multiselect - Users can select one or more values from a multi-select field.

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 ↓
Configure

To configure an installation parameter, you need to include the following metadata.

  • display_name: Appears as the parameter name in the installation form.
  • type: Parameter type; if the type is dropdown, radio, or multiselect, you need to define the following additional fields.
    • options: List of available options.
    • default_value: Pre-select one of the available options.
  • required (optional): Set this to true for required parameters. An asterisk is displayed near the required parameters in the user interface.
  • description (optional): Appears as helper text below the parameter. You can add relevant information and examples.
  • secure (optional): To define an installation parameter as "secure", add secure: true to the iparam key. In the following snippet, the API key is a secure iparam and Domain is not. Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    { "apiKey": { "display_name": "Api Key", "type": "text", "required": true, "secure": true }, "domain": { "display_name": "Domain", "type": "text", "required": true } }
    EXPAND ↓
    Read more about securing sensitive installation parameters from this blog post.

  • regex (optional): Enables you to specify one or more regexes that can be used to validate a user's input. This is in addition to the default validation that each type provides. If validation fails, the specified error message is shown to the user. Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    { "contact": { "display_name": "Name", "description": "Please enter your first name", "type": "text", "regex": {       "regex1": "<regex>",       "regex1-error": "Error message",       "regex2": "<regex>",       "regex2-error": "Error message", .....     } }
    EXPAND ↓

    For example, if you have a number field for age, you can specify an additional regex to make sure that the value is between 10-99. Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    { "Age": { "display_name": "Age", "description": "Please enter your age in years", "type": "number", "regex": {       "age-limit": "[1-9][0-9]",       "age-limit-error": "The age must be between 10-99" } }

Retrieve

Once you have configured the iparams for your app, you can use them in your app’s UI components with the following APIs:

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

Note:
1. You can use secure iparams with Request API to make HTTP requests.
2. The serverless component of the app can access iparams directly from the event payload.


client.iparams.get() - This API 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": "rachel@freshdesk.com", "contact-type": "Email", "request_domain": "sample.freshdesk.com", "subdomian": "sample" }

client.iparams.get(iparam_key) - This API returns the value of the iparam key that is passed as the parameter. If you try to fetch a secure iparam, you will get the following error message: "Could not find an installation parameter that matches this key."

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": "rachel@freshdesk.com" }

Sample failure response

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

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.