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 Access to Internal Managed Entities
    1. Get List of Entity Accesses
    2. Add Access to Entity
    3. Delete Access to Entity
  4. Configure Dataset Entities
    1. Get Dataset Entity Info
  5. 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 Access to Internal Managed Entities

3.1. Get List of Entity Accesses

NOTE: Admins can get the full list of granted accesses, whereas Power Users and Regular Users can only get the list of accesses directly assigned to them or created by them.

Retrieve a list of accesses to Portal Page Entity:

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

Retrieve a specific access data entry by ID:

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

Replace the following:

Example Response 

{
    "resultCode": 0,
    "users": [
        {
            "id": "1",
            "user_id": 229,
            "username": "jamespower",
            "display_name": "James Powers"
        }
    ],
    "groups": [
        {
            "id": "2",
            "group_id": 63,
            "name": "Robert Group",
            "description": "",
            "ldap_organizational_unit": "",
            "external_group_id": ""
        }
    ]
}

Fields Description

 
Parameter Name Value Type Description
resultCode integer Execution result code
users array An array of users with access to the App Entity
groups array An array of groups with access to the App Entity
Below are the User object parameters from the users array:
id string The ID of the User access entry
user_id integer The ID of the User
username string Login name of the user
display_name string Full name of the user shown in the UI
Below are the Group object parameters from the group array:
id string The ID of the Group access entry
group_id integer The ID of the Group
name string The name of the Group
description string The description of the Group
ldap_organizational_unit string The Group's LDAP org. unit
external_group_id string Group Alias

Result Codes

Code
 Description
0, 200 Status: OK
403 User has no access
404 Entity not found, No Custom Script
412
 Session expired

3.2. Add Access to Entity

NOTES:

  • Admins can assign Entity access to other Users.
  • Only Power Users and Regular Users that have Entity edit access can assign Entity access to other Users.

Assign Entity access to User:

$.ajax({
  url: "/data/page/<Portal Page Internal Name>/access/<Portal Page Entity Name>?id=<Access Data Entry ID>",
  method: "POST",
  contentType: "application/json",
  data: JSON.stringify({ user_id: <User ID>, edit: "<Y/N>" })
});

Assign Entity access to Group:

$.ajax({
  url: "/data/page/<Portal Page Internal Name>/access/<Portal Page Entity Name>?id=<Access Data Entry ID>",
  method: "POST",
  contentType: "application/json",
  data: JSON.stringify({ group_id: <Group ID>, edit: "<Y/N>" })
});

Replace the following:

3.3. Delete Access to Entity

NOTES:

  • Admins can revoke Entity access from other Users.
  • Only Power Users and Regular Users that have Entity edit access can revoke Entity access from other Users.

Revoke Entity access from User:

$.ajax({
  url: "/data/page/<Portal Page Internal Name>/access/<Portal Page Entity Name>?id=<Access Data Entry ID>&user_id=<User ID>",
  method: "DELETE"
});

Revoke Entity access from Group:

$.ajax({
  url: "/data/page/<Portal Page Internal Name>/access/<Portal Page Entity Name>?id=<Access Data Entry ID>&group_id=<Group ID>",
  method: "DELETE"
});

Replace the following:

4. Configure Dataset Entities

4.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"})

5. Configure Custom Script Entities

5.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:

5.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: