REST — Data Objects

Data Objects (referred to as Entities internally and in the API) 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.

Data Object JSON

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

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":      ""
}

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.

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

List All Data Objects

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

GET /rest/Entities

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"
  },
  ...
]

List Properties of a Single Data Object

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

GET /rest/Entities/{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
}

Add a New 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 a Data Object

Only supply the properties to be edited.

PATCH /rest/Entities/{Id}

Using curl

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

Example response

Status: 204 No Content

Delete a Data Object

DELETE /rest/Entities/{Id}

Using curl

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

Example response

Status: 204 No Content

List the Data Fields of a Data Object

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.

GET /rest/Entities/{Id}/Fields

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"
  },
  ...
]

List Data Field Properties

List the properties of the data field specified by its Id, of the Data Object specified by its Id.

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}

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
}

Add Data Field/Column Metadata

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

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

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.

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.

Edit Data Field/Column Metadata

Only supply the properties to be edited.

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

Using curl

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

Example response

Status: 204 No Content