Portal Page Entities API

This article describes Portal Page Entities API functionality. Related API endpoints are not presented in the API Toolkit and can be accessed via direct API calls listed in this article.

Table of contents:

  1. Get All Entities
  2. Configure Internal Entities
    1. Get Internal Entity Info
      1. Get All Entity Data
      2. Get Entity Data Entry By ID
      3. Filtering Internal Entity Info
    2. Add Internal Entity Info
      1. Bulk Add Internal Entity Info
      2. Add Single Data Entry to Internal Entity
    3. Update Internal Entity Info
    4. Delete Internal Entity Info
  3. Configure Dataset Entities
    1. Get Dataset Entity Info
  4. Configure Custom Script Entities
    1. Trigger Custom Script Execution
    2. Pass Data to the Custom Script

1. Get All Entities

Execute the following request to retrieve information about all Portal Page Entities:

$.ajax({"url":"/data/page/<Portal Page Internal Name>/entity"})

Replace <Portal Page Internal Name> with the Portal Page's name used in URL.

Example Response 

[
   {
     "name": "countries_info",
     "entity_type": "internal",
     "dataset_id": null,
     "dataset_filter_id": null,
     "data_fetch_method": "sql",
     "source_database_connection_id": null,
     "plugin_connection_profile_id": null,
     "custom_script_id": null,
     "custom_script_parameter_set_id": null
   },
   {
     "name": "csv-countries",
     "entity_type": "dataset",
     "dataset_id": "568",
     "dataset_filter_id": "0",
     "data_fetch_method": "sql",
     "source_database_connection_id": null,
     "plugin_connection_profile_id": null,
     "custom_script_id": null,
     "custom_script_parameter_set_id": null
   },
   {
     "name": "customscript_entity",
     "entity_type": "custom_script",
     "dataset_id": null,
     "dataset_filter_id": null,
     "data_fetch_method": "sql",
     "source_database_connection_id": null,
     "plugin_connection_profile_id": null,
     "custom_script_id": "15",
     "custom_script_parameter_set_id": null
   },
   {
     "name": "datasource-entity",
     "entity_type": "data_source",
     "dataset_id": "371",
     "dataset_filter_id": "0",
     "data_fetch_method": "sql",
     "source_database_connection_id": "150",
     "plugin_connection_profile_id": "187",
     "custom_script_id": null,
     "custom_script_parameter_set_id": null
   }
]

Fields Description

Field Name Value Type Description
name string The name of the Entity.
dataset_id string The ID of the Dataset from which the Entity is populated.
dataset_filter_id string The ID of the Dataset View from which the Entity was populated.
data_fetch_method string The method of Entity data retrieval.
source_database_connection_id string The ID of the SQL Data Source from which the Entity was populated.
plugin_connection_profile_id string The ID of the Plugin Connection Profile from which the Entity was populated.
custom_script_id string The ID of the Custom Script from which the Entity is populated.
custom_script_parameter_set_id string The ID of the Custom Script's Parameter Set.

2. Configure Internal Entities

Note: It is only possible to retrieve information of Internal Entity with Access Type: Public and Access Type: Private. The data of Internal Entities with Access Type: Public is available for all Users and the data of Internal Entities with Access Type: Private is only available for the User who created it.

See Understanding Portal Page Entities for details.

2.1. Get Internal Entity Info

Internal Entity data is stored as an array of objects, where each object represents a separate data entry. There are two API calls which allow to retrieve:

To find out the IDs of single data entries you need to get all Entity data first.

2.1.1. Get All Entity Data

Execute the following request to retrieve all data specific to a Portal Page Entity:

$.ajax({"url":"/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>"})
Example Response

The id key corresponds to the ID of a single data entry. Its value is unique and can be utilized to retrieve, update, or delete information about data entry.

{            
   "data":[              
       {                  
         "id":"User5",
         "value":{                     
            "name":"User5",
            "Country":"Italy",                     
            "Customer ID":"3",                     
            "Items Purchased":"12"
          }         
        }, 
        {                  
         "id":"User6",
         "value":{                     
            "name":"User6",
            "Country":"France",                     
            "Customer ID":"4",                     
            "Items Purchased":"20"
          }         
        },
        {                  
         "id":"User7",
         "value":{                     
            "name":"User7",
            "Country":"Germany",                     
            "Customer ID":"8",                     
            "Items Purchased":"5"
          }         
        },          
   ],            
   "count":"3"         
}

2.1.2. Get Entity Data Entry By ID

Note: The part of URL containing parameters must be URL-encoded.

To get a specific Entity data entry, use the following request:

$.ajax({url: "/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>?id=<Entity Data Entry ID>"})

2.1.3. Filtering Internal Entity Info

Note: The part of URL containing parameters must be URL-encoded.

Entities API can be utilized to apply filtering and pagination of Entity data with the following request:

 $.ajax({"url":"/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>?limit=2&offset=1&filters[<Entity Field Name>]=<Entity Field Value>"})

Filtering is configured by utilizing three separate parameters:

  • limit - the number of returned rows,
  • offset - the number of rows to be skipped before returning any rows,
  • filters - a key-value pair of an <Entity Field Name> and a corresponding <Entity Field Value> by which the returned data is filtered.

For example, you have a Portal Page with URL name sales-general containing an Internal Entity products. You want to retrieve 5 products with size "L" skipping the first 10 products. The request is as follows: 

$.ajax({"url":"/data/page/sales-general/products?limit=5&offset=10&filters[size]=L"})

2.2. Add Internal Entity Info

There are two API calls which allow to:

2.2.1. Add Multiple Data Entries to Internal Entity

Note: Make sure that your JSON data is properly aligned and objects contain field name written with lowercase letters.

  1. Convert data that needs to be added to Entity to JSON
  2. Assign const json the value of an array containig JSON with Entity data: 
const json = [
{
   "name": "User5",
   "Country": "Italy",
   "Customer ID": "3",
   "Items Purchased": "12",
 },
 {
    "name": "User6",
   "Country": "France",
   "Customer ID": "4",
   "Items Purchased": "1",
 },
 {
   "name": "User7",
   "Country": "Germany",
   "Customer ID": "2",
   "Items Purchased": "20",
 }
]
  1. Assign const entityName the value of the Entity Name:
const entityName = 'Countries';
  1. Run the following code in your browser console:
const internalPageName = window.location.href.replace(/^.*\/pt?\/([^\/]+).*$/, '$1');
  1. Run the following code in your browser console:
async function main(json) {
  for (const record of json) {
    await fetch(`/data/page/${internalPageName}/${entityName}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
      dataType: 'json',
      body: JSON.stringify({ id: record.name, value: record }),
    });
  }
  
  console.log('Done');
}
  1. Run the following code in your browser console:
main(json);
  1. Refresh the page
  2. Run the following code in your browser console replacing <Portal Page Internal Name> and <Portal Page Entity Name> with Portal Page's name used in URL and Portal Page Entity Name correspondingly:
fetch("/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>", {headers:{"Content-Type":"application/json", Accept:"application/json"}}).then(v=>v.json())

2.2.2. Add Single Data Entry to Internal Entity

To add a single data entry to the Portal Page Entity, use the following request:

 fetch("/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>",
    {
       "headers":
          {
              "Accept": "application/json",
              "Content-Type": "application/json"
          },
       "body": "<Entity Data>",
       "method": "POST" 
    }
);
  • Replace the following:
    • <Portal Page Internal Name> with the Portal Page's name used in URL,
    • <Portal Page Entity Name> with the Portal Page Entity Name,
    • <Entity Data> with the Entity data entry which must include ID of the data entry. This ID can have any value but must be unique.
      • Note that double quote characters must be prefixed by backslash character in the request body, see example request below for reference.
      • See Example Response for details on Entity data structure.

Example request: 

fetch("/data/page/robert-pp-new/entity-2",
 {
    "headers":
       {
        "Accept": "application/json",
        "Content-Type": "application/json"
       },
    "body": "{\"id\":\"User19\",\"value\":{\"Country\":\"Canada\",\"Customer ID\":\"12\",\"Items Purchased\":\"3\"}}",
    "method": "POST"
 }
);

2.3. Update Internal Entity Info

Note: The part of URL containing parameters must be URL-encoded.

To update Entity data entry, use the following request:

fetch("/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>?id=<Entity Data Entry ID>",
    {
       "headers": 
          {
           "Accept": "application/json",
           "Content-Type": "application/json"
          },
       "body": "<Entity Data>",
       "method": "PUT"
    }
);
  • Replace the following:
    • <Portal Page Internal Name> with the Portal Page's name used in URL,
    • <Portal Page Entity Name> with the Portal Page Entity Name,
    • <Entity Data Entry ID> with the ID of a data entry that needs to be updated.
    • <Entity Data> with the Entity data entry which must include ID of the data entry. This ID can have any value but must be unique.
      • Note that double quote characters must be prefixed by backslash character in the request body, see example request below for reference.
      • See Example Response for details on Entity data structure.

Example request:

fetch("/data/page/robert-pp-new/country-2?id=User5",
    {
       "headers":
          {
           "Accept": "application/json",
           "Content-Type": "application/json",
          },
       "body": "{\"id\":\"User5\",\"Country\":\"Canada\",\"Customer ID\":\"12\",\"Items Purchased\":\"3\"}",
       "method": "PUT"
    }
);

2.4. Delete Internal Entity Info

Note: The part of URL containing parameters must be URL-encoded.

To add a single data entry to the Portal Page Entity, use the following request:

$.ajax({url: "/data/page/<Portal Page Internal Name>/<Portal Page Entity?id=<Entity Data Entry ID>",type : 'DELETE'});

3. Configure Dataset Entities

3.1. Get Dataset Entity Info

Execute the following request to retrieve data specific to a Portal Page Entity:

$.ajax({"url":"/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>"})

Replace the following:

Filtering Dataset Entity Info

Note: The part of URL containing parameters must be URL-encoded.

Optionally, you can filter out the Entity data with the following request:

 $.ajax({"url":"/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>?limit=2&offset=1"})

Filtering is configured by utilizing three separate parameters:

  • limit - the number of returned rows,
  • offset - the number of rows to be skipped before returning any rows.

For example, you have a Portal Page with URL name sales-general containing a Dataset Entity products. You want to retrieve 5 products skipping the first 10 products. The request is as follows: 

$.ajax({"url":"/data/page/sales-general/products?limit=5&offset=10"})

4. Configure Custom Script Entities

4.1. Trigger Custom Script Execution

To trigger Custom Script execution, execute the following request:

$.ajax({"url":"/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>"})

Replace the following:

4.2. Pass Data to Custom Script

  1. Declare an object containing data that needs to be passed to the Custom Script
const messages  = {...};
  1. Execute the following request:
$.ajax({
        url: '/data/page/<Portal Page Internal Name>/<Portal Page Entity Name>',
        type: 'POST',
        data: {
          req: JSON.stringify({
            messages,
          })
        }
})

Replace the following: