How to Configure Installation Parameters for a Freshworks app

Modified on Fri, 04 Nov 2022 at 04:09 PM

You will often find your apps requiring the ability to allow your users to define configuration parameters at installation time so that the app can behave differently based on the parameters provided. For example, users can provide their API Key to the app so it could perform desired actions using the API Key. The Freshworks platform offers an effective and secure way to collect and pass such installation parameters to your app.


From the Uiflow Studio, you can use Publish Settings to configure installation parameters that can later be retrieved within the app. 

Configure the parameters:

In the Uiflow studio, click on the gear icon ⚙️ on the top right. This will lead you to the app’s Publish Settings.


Go to the “Install Parameters” section to add your configuration as a JSON object. 


A JSON object is a set of key and value pairs that are separated by a colon (‘:’). Note that the values in turn can be another JSON object themselves. We will use JSON to define the parameters used by our app. 


The most common set of parameters you may want to use for your app will include a sub-domain (the portion of your account URL before “.freshdesk.com” or “.freshservice.com”) and an API Key (a unique secret belonging to a user in Freshdesk or Freshservice). You can add this configuration using the following JSON object:


{

   "freshdesk_subdomain": {

      "display_name""Freshdesk subdomain",

      "description""Please enter your Freshdesk subdomain.",

      "type""domain",

      "type_attributes": {

         "product""freshdesk"

      },

      "required"true

   },

   "freshdesk_api_key": {

      "display_name""Freshdesk API key",

      "description""Please enter your Freshdesk API key",

      "type""api_key",

      "secure"true,

      "required"true,

      "type_attributes": {

         "product""freshdesk"

      }

   }


The above JSON will render as follows in the app’s installation/setup page:

Retrieve parameters within the app:

The Uiflow Studio offers the Get Installation Parameters element that fetches the installation parameters provided by the user during installation. You will typically want to work with one parameter at a time, in which case the Get Value at Path element will help retrieve the desired value from the JSON object.


Here’s an example of how you can get the Freshdesk Subdomain parameter we defined above from the Install Parameters in publish settings.

  1. In the Elements panel, search for ‘Get Installation Parameters’ and drag it to the Flow panel.
  2. Search again for Get Value at Path, and add it to the Flow panel.
  3. Select the Get Value at Path element and go to the Actions tab in the Inspector Panel on the right.
  4. Set the Path field to ‘freshdesk_subdomain’, which is the name we gave to this parameter earlier.
  5. Wire up the iParams output node of the Get Installation Parameters element to the input object of the Get Value at Path element.
  6. Now the output of the Get Value at Path element will be the Freshdesk subdomain which was provided by the user when installing the app.

Optionally, you can view the parameter value using a Text element or log it using the Console element. An example flow covering all the steps is demonstrated in the video below.

 

Now that we’ve learned how you can use the “Get Installation Parameters” element to retrieve installation parameters within the app, let’s try to use the retrieved information to make a sample API request.


Retrieving installation parameters to make an API request

The keen eye will note that the “freshdesk_api_key” parameter we defined earlier has a property called “secure” set to “true”. This implies that the API Key is deemed to be a sensitive value and cannot be retrieved within the app as above. We must use a secure template to work with the API Key parameter value.


Here’s how you can make a request using the Freshworks Request Method from the Uiflow studio:

  1. As a first step, you must whitelist the URL you want to make a request to. This ensures the app can only make requests to certain URLs approved by you as a developer.
    1. Open Publish settings from the Top right ⚙️ icon
    2. Go to the ‘Whitelisted Domains’ Section
    3. Add the following string if you are building an app for Freshdesk:
    4. [
      https://your-own-domain.freshdesk.com”
      ]
      Or the following if you are building an app for Freshservice:
      [
      https://your-own-domain.freshservice.com”
      ]
      Remember to replace your-own-domain with the domain of your Freshdesk or Freshservice account and click Save.
  2. In the Elements panel, search for Request and drag the Request element found under the Freshworks section to the Flow panel.
  3. Configure the request fields under the Actions tab of the element in the Inspector panel as follows.
    1. Method: Possible values are GET, POST, PUT, UPDATE and DELETE. Let’s set this to GET for now.
    2. Url: Provide the URL for the API endpoint you wish to make a request to. Let’s set this to https://your-own-domain.freshdesk.com/api/v2/tickets or https://your-own-domain.freshservice.com/api/v2/tickets , taking care to replace your-own-domain with the domain associated with your Freshworks Host (Freshdesk or Freshservice).
    3. contentType: Provide the format in which the request’s contents are sent. Let’s set this to application/json for now.
    4. Body: Pass the input data for this request. We will keep this empty for our request.
    5. Headers: This is where we’ll use a template to refer to the API Key and use it as Authorization for this request.


An example flow showing how a Request can be made on the click of a button and the response logged onSuccess, as well as the error captured onError is shown below for reference.


You can use the Console element to log the response of the Request and take a closer look at it.


In addition, have a look at our video on this topic:




 




Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article