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:

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:

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:

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.

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.

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.

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.