Scroll

REST - Data Objects

Data Objects (a.k.a. "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 Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.

Data Object JSON

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

Name Type Writeable 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
CategoryName string yes The Category group of this data object
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 is of type SqlStmt
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":  "",
  "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 Writeable 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 Writeable 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":      ""
  }

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.

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

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":            "Employees_0",
  "Name":          "Employees",
  "Schema":        "dbo",
  "CategoryName":  "",
  "DataName":      "Employees",
  "DataSourceId":  "0",
  "DataType":      "Table",
  ...
}

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": "", "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.

Name Type Writeable 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 boolean yes Whether this field is filterable
IsVisible boolean yes Whether this field is visible

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.

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

Show Data Field

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 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

Hidden Article Information

Article Author
Exago Development
created 2017-02-21 17:23:20 UTC
updated 2017-04-05 21:01:12 UTC

Labels
REST, API, Web Service, Entities,
Have more questions? Submit a request