Secure Interaction with External APIs in an App (Portal Page)

This article describes the approach to integrating an external API that requires authentication with an App (Portal Page) in Metric Insights.

The following steps are required to achieve a secure integration with any external web API:

  1. Define a Custom Script that makes the necessary external API calls and returns results that will be presented to the user via an App (Portal Page):
    1. The Custom Script holds credentials in variables with any secrets encrypted.
    2. Any other variables used that will be set in the App (Portal Page) should be defined and referenced in the script.  For example, if the user initiating the request from the page should be passed through to the API call, it must be defined as a variable.
    3. The custom script makes the API call (via JavaScript), passing in any necessary variables.
    4. The script returns any results from the API call that should be presented to the user in JSON format.
  2. Setup the Custom Script as an Entity in the App/Portal Page Editor.
  3. Define variables within the Portal Page for any information that should be passed to the external API call (e.g. username of the user and any relevant information provided by the user).
  4. Call the custom script from the Portal Page code, passing values for all required variables.

The following is a sample implementation that connects to a CSV in Azure Data Lake Store (ADLS).

Table of contents:

  1. Copy Azure Storage Credentials
    1. Copy Storage Account Name
    2. Copy Access Key
    3. Copy Path to File
  2. Configure Custom Script
    1. Create New Custom Script
    2. Add Parameters
      1. Add apiKey Parameter
      2. Add accountName Parameter
    3. Add Parameter Set
    4. Enter Custom Script Code
  3. Configure Portal Page Template
    1. Create New Portal Page Template
    2. Define Variables
      1. Define Path to File Variable
      2. Define ADLS Entity Name Variable
    3. Enter Portal Page Template Code
  4. Configure Portal Page
    1. Create New Portal Page
    2. Create New Entity
    3. Provide Values for Variables
    4. View Portal Page
    5. Row-Level Security Example

1. Copy Azure Storage Credentials

1.1. Copy Storage Account Name

Access https://portal.azure.com

  1. Enter 'Storage account' in the search box, then access Storage accounts
  2. Copy the Storage account name, then click on it. The Overview tab will open

1.2. Copy Access Key

  1. From the Overview tab, go to Access keys
  2. [Show], then copy a Key value

1.3. Copy Path to File

  1. Access Containers
  2. Open a container
  3. Access the file inside the container
  4. Copy the URL, then remove the server hostname part of the URL. The result should like this: <container name>/<folder name>/<file name>. Copy and save this value.
    • Example: mi-test-ops/ops-2895/Wine_Sales_Data.csv

2. Configure Custom Script

2.1. Create New Custom Script

Access Admin > System > Custom Scripts

  1. [+ New Custom Script]
  2. Name: Enter a name for the Custom Script
  3. External Application Name: Choose an External Application to automatically generate an API token for the Custom Script.
  4. Authentication User: Choose a User on whose behalf the Custom Script will operate.

NOTE: See Configure Custom Scripts for more details.

2.2. Add Parameters

2.2.1. Add apiKey Parameter

  1. [+ Add Parameter]
  2. Name: apiKey
  3. Type: Password
  4. Activate the Required checkbox
  5. [Save]

2.2.2. Add accountName Parameter

  1. [+Add Parameter]
  2. Name: accountName
  3. Type: String
  4. Activate Required the checkbox
  5. [Save]

2.3. Add Parameter Set

  1. [+Add Parameter Set]
  2. Parameter Set Name: Enter a name for the Parameter Set
  3. apiKey: Enter the Access key value from Azure Storage account
  4. accountName: Enter Azure Storage Account Name
  5. Is Default: Activate the checkbox
  6. [Save]
  7. [Save and Enable] the Custom Script

2.4. Enter Custom Script Code

Access the Editor tab

  1. Enter the Custom Script code
  2. [Save and Enable]

NOTE: A Custom Script parameter value can be accessed via customScript.parameters.<parameter_name>.

3. Configure Portal Page Template

3.1. Create New Portal Page Template

Access Content > Portal Pages> Templates

  1. [+ New Template]
  2. Name: Enter a descriptive Portal Page Template Name
  3. Internal name: Enter a name which is used to build URL
    • Letters, numbers, dashes, and underscores are the only supported characters for Portal Page Template URLs
  4. [Save]

3.2. Define Variables

Access the Variables tab

3.2.1. Define Path to File Variable

  1. [+ Variable]
  2. Name: Path To File in ADLS
  3. Type: Text
  4. [Save Variable]

3.2.2. Define ADLS Entity Name Variable

  1. [+ Variable]
  2. Name: Path To File in ADLS
  3. Type: Text
  4. [Save Variable]

3.3. Upload Assets

Access the Assets tab

  1. [Upload Assets], select a .zip archive with the Portal Page template assets
  2. The assets are displayed once uploaded

3.4. Enter Portal Page Template Code

Access the Code tab

  1. Enter the code for the Portal Page Template
    • This code is using the Portal Page Template Variables created on the previous steps.
  2. [Save]
  3. Navigate to the Pages tab to create a new Portal Page

4. Configure Portal Page

4.1. Create New Portal Page

  1. [+ New Page]
  2. Name: Enter a descriptive name for the Portal Page
  3. Internal name: Provide a name to be used in the page URL
    • NOTE: Letters, numbers, dashes and underscores are the only supported characters for the Portal Page URL name
  4. [Save]

4.2. Create New Entity

  1. [+ Add Entity]
  2. Name: Enter a descriptive name for the Portal Page Entity
  3. Entity Type: Custom Script
  4. Custom Script: Choose the previously created Custom Script
  5. [Save]

4.3. Provide Values for Variables

Access the Content tab

  1. Path To File in ADLS: Enter the path to a file located in the Azure container
  2. ADLS Entity Name: Enter the name of the Portal Page Entity created on the previous step
  3. [Save]
  4. [View]

4.4. View Portal Page

The Portal Page displays data fetched by the Custom Script from the Azure Storage.

5. Row-Level Security Example

Another example of interaction with external APIs is applying row-level security to the fetched CSV file. This ensures that users can only see data relevant to their own accounts.

  1. The following code is added to the Portal Page to retrieve the username of the user viewing the Portal Page:
$.ajax({"url":'/index/index/user-info/ajax/Y'})
  .done(function(response){  
    console.log(response.username);
 })
  1. The username value is passed from the Portal Page to the Custom Script.
  2. The Custom Script applies row-level security to the fetched CSV data based on the username received from the Portal Page. As a result, the user viewing the Portal Page sees only the rows where the "user" column matches the username passed from the Portal Page.