REST – Data Objects
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:
Name | Type | Writable | Description |
---|---|---|---|
Id | string | required-create | The unique Id of this data object |
Name | string | required | The display name (“alias”) of this data object |
Schema | string | yes | The schema of this data object |
SchemaAccessType | string | yes | How Exago should retrieve the schema for the data object. There are three possibilities:
|
CategoryName | string | yes | The Category/Folder group this object will appear in |
DataName | string | required | The name of this data object in its data source
|
DataSourceId | integer | required | The Id of the data source of this data object (see Data Sources) |
DataType | enum | yes (“Table”) | Data Object Type |
SqlStatement | string | yes | The custom SQL of this data object if it’s DataType is SqlStmt |
canreexecuteindb | Boolean | yes | See Interactive Filtering in Database in the Data Object Properties section of the Data Objects article for more information |
Parameters | array of strings | yes | Any parameters for stored procedure, .NET Assembly or Web Service API calls |
KeyColumns | array of strings | yes | The unique key fields of this data object |
TenantColumns | array of Tenant Column | yes | The tenant fields of this data object |
FilterDropdownObject | Filter Dropdown | yes | The 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:
Name | Type | Writable | Description |
---|---|---|---|
Column | string | required | The tenant data field |
Parameter | string | required | The 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:
Name | Type | Writable | Description |
---|---|---|---|
FilterDbName | string | required | The name of this data object in its data source |
FilterObjectType | enum | yes | Data Object Type |
FilterSchema | string | yes | The schema for this data object |
FilterSqlStmt | string | yes | The custom SQL for this data object if it is of type SqlStmt |
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.
Important
The IsFilterable property name changed to Filterable in v2019.1.13.
Name | Type | Writable | Description |
---|---|---|---|
Id | string | no | The unique name for this data field |
Name | string | yes | The display name for this data field |
Type | enum | yes | Data Field Type |
IsFilterable (pre-2019.1.13) Filterable (v2019.1.13+) |
bool (pre-v2017.2) const (v2017.2+) |
yes | Whether this field is filterable Filterable Type |
IsVisible | boolean | yes | Whether this field is visible to end users. Set to false to hide it or true to show it. |
Value | string | yes |
The content of the data field. Enclose other Exago data fields in curly braces { }. There are three possibilities:
|
Description | string | yes | A text description of the data field what will be shown to the end user |
ColumnSource | string | yes |
Describes the content of the Value property. Either:
|
SortAndGroupBy | string | yes | Either 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 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
Name | Type | Description |
---|---|---|
Id | string | The unique Id of this data object |
Name | string | The 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" }, ... ]
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
Note
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
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 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
Name | Type | Description |
---|---|---|
Id | string | The unique Id of this data field |
Name | string | The 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" }, ... ]
List Data Field Properties
List the properties of the data field specified by its Id, of the Data Object specified by its Id.
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}
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}
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.
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