Exago Logo
Search
Generic filters
Exact matches only

REST – Data Objects

Data Objects (also known as “Entities”) are the manner by which Exago views and accesses the tables, views, procedures, etc… from the Data Sources. Data objects represent the structure of the data, but the actual data is only accessed at report run-time.

Note

All requests require a Session ID URL parameter and basic request headers. In the following document, headers are omitted in the interest of brevity.

Data Object JSON

Data Objects are represented as JSON objects with the following properties:

NameTypeWritableDescription
Idstringrequired-createThe unique Id of this data object
NamestringrequiredThe display name (“alias”) of this data object
SchemastringyesThe schema of this data object
SchemaAccessTypestringyesHow Exago should retrieve the schema for the data object. There are three possibilities:

 

  • Default — Follow the global Schema Access Type setting in Other Settings.
  • Datasource — Queries the data source for the schema.
  • Metadata — Reads the schema from the stored metadata.
CategoryNamestringyesThe Category/Folder group this object will appear in
DataNamestringrequiredThe name of this data object in its data source

 

Important

The name of data objects may not contain the following characters:

{ } [ ] , . %

To create a data object for a database table (or other backing model) with one of these characters in its name, create a Custom SQL Object with a simple SELECT clause. For example for a table named sales.figures.2020:

SELECT * FROM [sales.figures.2020]

Note that the identifier delimiters (the [ ]) around the table name will vary with the database type.

DataSourceIdintegerrequiredThe Id of the data source of this data object (see Data Sources)
DataTypeenumyes (“Table”)Data Object Type
SqlStatementstringyesThe custom SQL of this data object if it’s DataType is SqlStmt
canreexecuteindbBooleanyesSee Interactive Filtering in Database in the Data Object Properties section of the Data Objects article for more information
Parametersarray of stringsyesAny parameters for stored procedure, .NET Assembly or Web Service API calls
KeyColumnsarray of stringsyesThe unique key fields of this data object
TenantColumnsarray of Tenant ColumnyesThe tenant fields of this data object
FilterDropdownObjectFilter DropdownyesThe filter dropdown object of this data object

Example

{
  "Id":            "Employees_0",
  "Name":          "Employees",
  "Schema":        "dbo",
  "CategoryName":  "",
  "DataName":      "Employees",
  "DataSourceId":  "0",
  "DataType":      "Table",
  "SqlStatement":  "",
  "canreexecuteindb": true,
  "Parameters":    [],
  "KeyColumns":    ["EmployeeID"],
  "TenantColumns": [
    {
      "Column":    "EmployeeID",
      "Parameter": "UserId"
    }
  ],
  "FilterDropdownObject": {
    "FilterDbName":       "Employee_List",
    "FilterDataSourceId": -1,
    "FilterObjectType":   "view",
    "FilterSchema":       "",
    "FilterSqlStmt":      ""
  }
}

Tenant Column JSON

Tenant Columns are represented as JSON objects with the following properties:

NameTypeWritableDescription
ColumnstringrequiredThe tenant data field
ParameterstringrequiredThe tenant parameter

Example

"TenantColumns": [
    {
      "Column":    "EmployeeID",
      "Parameter": "UserId"
    }
  ]

Filter Dropdown JSON

A Data Object’s Filter Dropdown is represented as a JSON object with the following properties:

NameTypeWritableDescription
FilterDbNamestringrequiredThe name of this data object in its data source
FilterObjectTypeenumyesData Object Type
FilterSchemastringyesThe schema for this data object
FilterSqlStmtstringyesThe custom SQL for this data object if it is of type SqlStmt

Example

  "FilterDropdownObject": {
    "FilterDbName":       "Employee_List",
    "FilterObjectType":   "view",
    "FilterSchema":       "",
    "FilterSqlStmt":      ""
  }

List Data Objects

GET /rest/Entities

List all the data objects in the current configuration. Output is an array of objects, each representing an individual data object.

NameTypeDescription
IdstringThe unique Id of this data object
NamestringThe display name (“alias”) of this data object

Using curl

curl http://{webservice}/rest/Entities?sid={sid} -X GET

Example response

Status: 200 OK

[
  {
    "Id":   "Customers_0",
    "Name": "Customers"
  },
  {
    "Id":   "Employees_0",
    "Name": "Employees"
  },
  ...
]

Show Data Object

GET /rest/Entities/{Id}

Show the properties of the data object specified by its Id.

Using curl

curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X GET

Example response

Status: 200 OK

{
"Id":"system_departments_0",
"Name":"Departments",
"Schema":"",
"CategoryName":"Roster",
"DataName":"system_departments",
"DataSourceId":"4",
"DataType":"Table",
"SqlStatement":"",
"Parameters":[],
"KeyColumns":["id"],
"TenantColumns":[],
"FilterDropdownObject":null
}

Create Data Object

POST /rest/Entities

Requires a DataName or a custom SqlStatement. One or more KeyColumns are required for most data types.

Using curl

curl http://{webservice}/rest/Entities?sid={sid} -X POST ^
	-d @newDataObject.txt

newDataObject.txt

"{'Id':'Employees_1','Name':'Employees','Schema':'dbo','DataName':'Employees','DataSourceId':0,'KeyColumns':['EmployeeID']}"

Example response

Status: 201 Created
Location: /{webservice}/rest/Entities/Employees_1

{
  "Id":            "Employees_1",
  "Name":          "Employees",
  "Schema":        "dbo",
  "CategoryName":  "",
  "DataName":      "Employees",
  "DataSourceId":  "0",
  "DataType":      "Table",
  "SqlStatement":  "",
  "Parameters":    [],
  "KeyColumns":    ["EmployeeID"],
  "TenantColumns": [],
  "FilterDropdownObject": null
}

Edit Data Object

PATCH /rest/Entities/{Id}

Only supply the properties to be edited.

Using curl

curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X PATCH ^
	-d "{'Name':'Staff List'}"

Example response

Status: 204 No Content

Delete Data Object

DELETE /rest/Entities/{Id}

Using curl

curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X DELETE

Example response

Status: 204 No Content

Data Field JSON

Data fields for each object are represented as JSON objects with the following properties. The actual data in the fields is not accessible via REST. Data fields cannot be created or deleted. However, some metadata for existing fields can be edited.

Important

The IsFilterable property name changed to Filterable in v2019.1.13.

NameTypeWritableDescription
IdstringnoThe unique name for this data field
NamestringyesThe display name for this data field
TypeenumyesData Field Type
IsFilterable (pre-2019.1.13)
Filterable (v2019.1.13+)
bool
(pre-v2017.2)
yesWhether this field is filterable
const
(v2017.2+)
Filterable Type
IsVisiblebooleanyesWhether this field is visible to end users. Set to false to hide it or true to show it.
ValuestringyesThe content of the data field. Enclose other Exago data fields in curly braces { }. There are three possibilities:

 

  • An Exago formula — A custom function used to define the field value. Can use other fields from the same data object. (e.g. “Concatenate({Orders.ShipCountry},'+ ',{Orders.ShipCity})”)
  • A SQL formula — SQL statement used to define the the field value. (e.g. “Concat(ShipCountry, ' + ', ShipCity)”)
  • A static value — Static content (e.g. “12345“)
DescriptionstringyesA text description of the data field what will be shown to the end user
ColumnSourcestringyesDescribes the content of the Value property. Either:

 

  • Data — use for either a static value, or when Value contains a single column name
  • ExagoFormula — use when the Value is an Exago formula
  • SqlFormula — use when the Value is a SQL formula
SortAndGroupBystringyesEither an Exago formula or another data field name that will be used to sort/group the values in this column. Enclose column names in curly braces { }. If null, sorting/grouping on a field is not enabled.

List Data Fields of a Data Object

GET /rest/Entities/{Id}/Fields

List all the data fields in the data object specified by its Id. Output is an array of objects, each representing an individual data field.

NameTypeDescription
IdstringThe unique Id of this data field
NamestringThe display name of this data field

Using curl

curl http://{webservice}/rest/Entities/{Id}/Fields?sid={sid} -X GET

Example response

Status: 200 OK

[
  {
    "Id":   "Address",
    "Name": "Address"
  },
  {
    "Id":   "BirthDate",
    "Name": "Date of Birth"
  },
  {
    "Id":   "EmployeeID",
    "Name": "ID Number"
  },
  {
    "Id":   "FirstName",
    "Name": "First Name"
  },
  {
    "Id":   "LastName",
    "Name": "Last Name"
  },
  ...
]

Show Data Field

Important

Performing a GET for the data fields will result in fixing the current column metadata list as the only defined columns. The column metadata can be further altered, but will not be reflected in the Entity Columns collection until the session is launched in a browser.

GET /rest/Entities/{Id}/Fields/{Field Id}

Show the properties of the data field specified by its Id, of the data object specified by its Id.

Using curl

curl http://{webservice}/rest/Entities/{Id}/Fields/{Field Id}?sid={sid} -X GET

Example response

Status: 200 OK

{
  "Id":           "LastName",
  "Name":         "Last Name",
  "Type":         "String",
  "IsFilterable": true,
  "IsVisible":    true
}

Edit Metadata for Data Field

PATCH /rest/Entities/{Id}/Fields/{Field Id}

Only supply the properties to be edited.

Using curl

curl http://{webservice}/rest/Entities/{Id}/Fields/{Field Id}?sid={sid} -X PATCH ^
	-d "{'Name':'Surname'}"

Example response

Status: 204 No Content

Add New Metadata to Data Field

Add new metadata that doesn’t already exist to a data field.

POST /rest/Entities/{Id}/Fields/{Field Id}

Caution

Setting the Type property to a data type that does not match the actual type in the data source will cause errors when reports are run or designed.

Important

Adding additional column metadata will result in fixing the current column metadata list as the only defined columns. The column metadata can be further altered, but will not be reflected in the Entity Columns collection until the session is launched in a browser.

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents