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 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 |
{
"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 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 |
"TenantColumns": [
{
"Column": "EmployeeID",
"Parameter": "UserId"
}
]
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 |
"FilterDropdownObject": {
"FilterDbName": "Employee_List",
"FilterObjectType": "view",
"FilterSchema": "",
"FilterSqlStmt": ""
}
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 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 |
curl http://{webservice}/rest/Entities?sid={sid} -X GET
Status: 200 OK [ { "Id": "Customers_0", "Name": "Customers" }, { "Id": "Employees_0", "Name": "Employees" }, ... ]
Show the properties of the data object specified by its Id.
GET /rest/Entities/{Id}
curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X GET
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 }
POST /rest/Entities
Note
Requires a DataName or a custom SqlStatement. One or more KeyColumns are required for most data types.
curl http://{webservice}/rest/Entities?sid={sid} -X POST ^ -d @newDataObject.txt
{
"Id":"Employees_1",
"Name":"Employees",
"Schema":"dbo",
"DataName":"Employees",
"DataSourceId":0,
"KeyColumns":[
"EmployeeID"
]
}
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 }
PATCH /rest/Entities/{Id}
Only supply the properties to be edited.
curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X PATCH ^ -d "{'Name':'Staff List'}"
Status: 204 No Content
DELETE /rest/Entities/{Id}
curl http://{webservice}/rest/Entities/{Id}?sid={sid} -X DELETE
Status: 204 No Content
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 |
curl http://{webservice}/rest/Entities/{Id}/Fields?sid={sid} -X GET
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 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}
curl http://{webservice}/rest/Entities/{Id}/Fields/{Field Id}?sid={sid} -X GET
Status: 200 OK { "Id": "LastName", "Name": "Last Name", "Type": "String", "IsFilterable": true, "IsVisible": true }
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.
Only supply the properties to be edited.
PATCH /rest/Entities/{Id}/Fields/{Field Id}
curl http://{webservice}/rest/Entities/{Id}/Fields/{Field Id}?sid={sid} -X PATCH ^ -d "{'Name':'Surname'}"
Status: 204 No Content