Build an installation page

Installation params or iparams are parameters whose values app users can set when they install an app. These parameters are presented to the app users through the Settings page. To define iparams, render the Settings page, and use iparams:

  1. Configure the iparams. During app installation, the configured iparams are displayed on an installation page. App users can enter appropriate values for the iparams and click INSTALL. The entered values are validated and saved.
  2. In the app logic, use the client.iparams.get(), client.iparams.get(iparam_key), or the Request method (for secure iparams), to retrieve the iparam values. Note:To prevent exposure of sensitive iparam information, secure iparams can only be retrieved through the Request method, as part of HTTPS request headers.

For serverless apps, the configured iparams are passed as part of event payloads. The app logic can retrieve the iparams’ values from the payload.

For a demonstration of how to build an app settings page using iparams.json, see the sample global app - iparams.

Configure iparams

  1. From your app’s root directory, navigate to the iparam.json file.
  2. Configure iparams as a JSON object with the following attributes.
  • display_namestringRequired

    Identifier of a parameter on the Installation page.

  • descriptionstring

    Helper text that is displayed along with the parameter, on the Installation page. The description can include examples.

  • typestringRequired

    Type of input field displayed, for the iparam, on the installation page.


    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.

  • modulesarray of strings

    From the modules registered in the App Manifest, names of the modules for which the iparam is applicable. For an app built for multiple modules, only if the iparam is applicable to the module on which the app is deployed, the iparam is displayed on the Settings page of the app.


    For example, for an app built for module_a and module_b, if iparams.json > <iparam-name>.modules is module_a, the iparam is displayed in the App Settings page only if the app is being installed on a SKU with module_a.


    The modules attribute is optional. If not included in iparams.json, the configured iparams are displayed on the app Setting page, irrespective of the SKU on which the app is installed.

    Important: Ensure to use only the names of the modules registered in the App Manifest.

  • optionsarray of strings

    List of values displayed on the installation page, if the iparam’s input field type is radio, multiselect, or dropdown.

  • default_valuestring

    Preselected value(s) (from options) displayed on the installation page, if the iparam’s input field type is radio, multiselect, or dropdown.

  • requiredboolean

    Specifies whether the iparam is displayed as a mandatory parameter. An asterisk is displayed next to the parameter on the Installation page.


    Possible values: true, false

  • visibleboolean

    Specifies whether the iparam is displayed on the Installation page.


    Possible values: true, false

    Example
     {
       "contact": {
         "display_name": "Contact Details",
         "description": "Please enter the contact details",
         "type": "text",
         "required": true,
         "visible": true
       }
     }
  • secureboolean

    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
     {
      "apiKey": {
        "display_name": "Api Key",
        "type": "text",
        "required": true,
        "secure": true
      }
    }

    NoteSensitive iparams, such as key, auth, token, secret, are detected when running the fdk validate and fdk pack commands and a warning is displayed to mark them as secure.

    For comprehensive information on secure iparams, read the securing sensitive installation parameters blog post.

  • regexobject

    Expression(s) used to validate a parameter value entered in the installation page. 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

    {
       "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"
         }
       }
    }
    
  • eventsarray of objects

    HTML events and associated callbacks, specified as an array of JSON objects. Each JSON object is an "<event name>": "<callback function name>" pair.

    NoteCurrently, only change events are supported. Therefore, ensure that the <event name> is change.

    For information on how to define callback functions, see the make your installation page dynamic section.

Types

In the iparams.json file, the value of the type parameter should be one of the following.

text

A single-line text field is displayed on the installation form.

paragraph

A multi-line text field is displayed.

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.

email

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

number

A numeric field that accepts integers upto 10 digits is displayed.

phone_number

A single-line text field to enter a valid phone number is displayed.

date

A field to enter a valid date (or pick a date by using a date picker) is displayed.

url

A single-line text field to enter a valid URL is displayed.

radio

Radio buttons along with values specified in the options attribute of the iparams.json file are displayed.

checkbox

A checkbox is displayed next to the iparam.

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.

Make your installation page dynamic

A dynamic installation page or Settings page enables you to present a form in which the fields and/or values of the fields are populated dynamically, on the go, based on the app user’s input to certain fields.

When you configure iparams, you can use the events attribute to build a dynamic installation page to collect values for the installation parameters.

  1. From the app’s root directory, navigate to the config/iparams.json file.
  2. Include the events attribute as part of the iparam configuration. Specify an HTML event and a corresponding callback function, as a JSON object of "<event name>": "<callback function name>" pair by using the following sample format.
    {
     "firstname": {
      "display_name": "First Name",
      "description": "Please enter your business name",
      "type": "text",
      "required": true,
      "events": [
        {"change": "firstnameChange"}
      ]
     },
     "multiselect": {
      "display_name": "Other Details",
      "description": "Please select values",
      "type": "multiselect",
      "required": true,
      "options": [
        "opt1",
        "opt2",
        "opt3"
      ]
     }
    }
  3. From the app’s root directory, navigate to the config directory and create the assets/iparams.js file.
  4. Define the callback function by using the following sample format. Note:Ensure that the callback function’s name is the <callback function name> specified in the iparams.json file.
      function firstnameChange(arg) {
        //validation logic and subsequent action performed
        //arg is the iparam value passed to the callback function
        console.log(arg);
      }
  5. To set or modify the attribute value of an iparam and add validations to an iparam, based on the input value of another iparam, use utils.set(); in the callback function definition. For more information, see iparam utility methods.
  6. To retrieve the value of an iparam, based on the input value of another iparam, use utils.get(); in the callback function. For more information, see iparam utility methods.
  7. To validate a value entered for an iparam or use the value entered to perform some action (such as an API call), validate the value returned, and display a success or failure message, use return; in the callback function. For more information, see return;.

When an app user enters or modifies an iparam value, the change event is triggered and the iparam value is passed to the callback function. The value is validated and subsequent actions are performed. The validation and actions are based on the logic defined in the callback function.

iparams utility methods

The FDK consists of in-built utility methods that enable you to set or modify the attribute value of an iparam, add validations to an iparam, and retrieve the value of an iparam during run-time. You can use the following methods in your callback function:

utils.set();

Enables you to set or modify the iparam attributes that are displayed in the installation page or impart further validations to the iparams.

Format
utils.set(<iparam_key>, {<attribute>: <value>});

<iparam_key> identifies the iparam that is modified or validated when the change event occurs. <attribute> specifies the iparam’s installation page attribute that is modified or the validation set for the iparam. <value> specifies the value that is set for <attribute> and must adhere to the data type of <attribute>.

For an iparam identified by <iparam_key>, <attribute> can be any of the following values.

<ATTRIBUTE>Data typeDescription
valuestring array of strings (for iparams of the multiselect type)Enables you to set a value for the iparam. For a multiselect iparam, enables you to set certain values as selected options. On the installation page, the selected options are populated in the iparam’s input field.
labelstringEnables you to modify the display_name attribute value of the iparam.
visiblebooleanEnables you to hide the iparam from the installation page.
disabledbooleanEnables you to disable the iparam on the installation page.
requiredbooleanEnables you to modify the required attribute value of the iparam.
hintstringEnables you to modify the description attribute value of the iparam.
values
Valid only for iparams of the radio, multiselect, and dropdown types.
array of stringsEnables you to modify the options attribute value of the iparam.
min
Valid only for iparams of the number type.
numberEnables you to set a validation for the minimum value that can be entered for the iparam.
max
Valid only for iparams of the number type.
numberEnables you to set a validation for the maximum value that can be entered for the iparam.

Examples of using the value attribute

Example 1: Sample code to set the value of the lastname iparam to the value the app user specifies for the firstname iparam.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
     "display_name": "Last Name",
     "description": "Please enter your last name",
     "type": "text",
     "required": false
  }
}

Example 2: Sample code to populate the multiselect iparam field with a list of options, if the app user specifies a value for the firstname iparam.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "multiselect": {
    "display_name": "Other Details",
    "description": "Please select values",
    "type": "multiselect",
    "required": true,
    "options": [
  	  "opt1",
  	  "opt2",
  	  "opt3"
    ]
  }
}

Examples of using the visible attribute

Example 1: Sample code to hide the lastname iparam from the installation page, if the app user specifies a value for the firstname iparam.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
}

Example 2: Sample code to display the lastname iparam in the installation page, if the app user enters a valid value for the firstname iparam and to hide the lastname iparam from the installation page, if the app user deletes the entered value.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
}

Example of using the values attribute

Sample code to modify the list of options available for the multiselect iparam and display_name to Hobbies, if the app user enters a value for the firstname iparam.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "lastname": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "text",
    "required": false
  }
  "multiselect": {
    "display_name": "Other Details",
    "description": "Please select values",
    "type": "multiselect",
    "required": true,
    "options": [
	    "opt1",
	    "opt2",
	    "opt3"
    ]
  }
}

Example of using the min and max attributes

Sample code to set a validation criteria and to modify display_name of the age iparam, if the app user enters a value for the firstname iparam. When the app user enters a value for the age iparam, if the value fails to meet the validation criteria, an error message is displayed.

{
  "firstname": {
    "display_name": "First Name",
    "description": "Please enter your business name",
    "type": "text",
    "required": true,
    "events": [
      {"change": "firstnameChange"}
    ]
  },
  "age": {
    "display_name": "Last Name",
    "description": "Please enter your last name",
    "type": "number",
    "required": false
  }
}

utils.get();

Enables you to identify an iparam and retrieve its value during run-time.

Format
utils.get(<iparam_key>);

<iparam_key> identifies the iparam whose value is retrieved when the change event occurs.

return;

Returning an error message, clears the value entered for the iparam and thereby invalidates the field. Returning an empty string or not returning a value, passes the validation as a success.

Format
return <validation criteria> ?<Success Message>:<Error Message>;

Examples of using the return function

Example 1: Sample code to make an API call based on the value entered for the APIKey iparam, validate if an empty value is returned by the API call, and if so, display an error message.

{
  "APIKey": {
    "display_name": "API Key",
    "description": "Please enter your api key",
    "type": "text",
    "secure": true,
    "required": true,
    "events": [
      {"change": "APIKeyChange"}
    ]
  }
}

Example 2: Sample code to invoke a third-party API based on the value entered for the acc_id iparam and validate the iparam field asynchronously by using the callback functionality.

{
  "acc_id": {
    "display_name": "Account ID",
    "description": "Please enter your Acc. ID",
    "type": "text",
    "required": true,
    "events": [{
      "change": "checkAccountID"
    }]
  }
}

Retrieve iparams

To retrieve the configured iparams and to use them in the app components, use the following methods:

Notes:
  • Secure iparams can be retrieved through the Request Method as part of HTTPS request headers.
  • The serverless component of the app can access iparams directly from the event payload.

client.iparams.get()

This method returns all the configured installation parameters except secure iparams.

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

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.

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

Test iparams

To test the configured installation parameters:

  1. From the command line, navigate to the directory that contains the app related files and run the fdk run command.

    The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

  2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

  3. In the system settings page,

    1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.
    2. In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost. Based on the currentHost, the currentHost.subscribed_modules and currentHost.endpoint_urls are determined.
    3. Click Continue.
  4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

    Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

  5. To reselect modules or reenter account URLs, on the App Settings page, click Back.