Installation Parameters

The installation parameters or iparams are the values that you want your users to configure when installing apps. You can define these parameters in the iparams.json file accessible via the config directory in your app project.


Sample iparams.json

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "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" } }
EXPAND ↓

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

Sample test data

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

The following types of parameters are supported:

TYPE DESCRIPTION
text Single line text
dropdown Drop down list from which users can select a single option
email Single line text field where users will have to enter a valid email address
number Users can enter a number (integers upto 10 digits)
phone_number Single line text field where users will have to enter a valid phone number
date Users can either enter a date or select it from a date picker
URL Single line text field where users will have to enter a valid URL
radio Radio buttons from which users can select a single value
checkbox Checkbox from which users can select or unselect an option
multiselect Users can select one or more values from a multi select field


Text - Single line text

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 } }

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 will have to enter a valid email address

Copied Copy
1
2
3
4
5
6
7
8
{ "Age": { "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 will have to enter a valid phone number

Copied Copy
1
2
3
4
5
6
7
8
{ "Age": { "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
{ "Age": { "display_name": "Birthday", "description": "Please enter your birthday", "type": "date", "required": true } }

URL - Single line text field where users will have to enter a valid URL

Copied Copy
1
2
3
4
5
6
7
8
{ "Age": { "display_name": "Freshservice Domain", "description": "Please enter your Freshservice domain web address", "type": "rul", "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 or unselect an option

Copied Copy
1
2
3
4
5
6
7
8
{ "contact-type": { "display_name": "Also archive the 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-type": { "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, you need to include the following metadata for each installation parameter:

  • display_name: Users will see this as the parameter name in the installation form:
  • description: Users will see this as helper text that appears below the parameter. You should guide users by including relevant information and examples:
  • type: Type of the parameter. If the type is dropdown, radio, or checkbox then you will need to define these additional fields:
    • options: List of available options.
    • default_value: Make one as default from the list of options.


Retrieve

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

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

Note:
The serverless component of the app can access the iparams directly from the event payload.


client.iparams.get() - This API returns all the configured installation parameters.

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@freshservice.com", "contact-type": "Email", "request_domain": "sample.freshservice.com", "subdomian": "sample" }

client.iparams.get(iparam_key) - This API returns the value of the iparam key that is passed as the parameter.

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@freshservice.com" }

Sample failure response

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

Log in with your Freshservice account

Enter your helpdesk URL to proceed to login

Proceed

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