Datatable
The datatable service is used to manage datatables and the rows they contain.
The Datatables feature allows the user to define their own set of fields in a similar way to profile fields, however they are not tied in a one-to-one connection to a recipient. Because of this, the user must also define their own unique key combination. Although this is enforced, the system uses its own identifier for each row, which is referred throughout this document as the 'row_id'.
fetchAll
array datatable.fetchAll( )Requests a list of Datatables. This method has no parameters to specify as it will request all Datatables regardless of the position within the folder hierarchy.
Return Values
Returns an array of associative arrays. For the possible returned elements see #find
find
array datatable.find( int datatableId )Requests the datatable details of the single datatable id requested.
Parameters
datatableId
ID of the datatable you're requesting.
Return Values
Returns an associative array. The possible returned elements are as follows:
Name | Type | Description |
|---|---|---|
datatable_id | int | Datatable Id |
folder_id | int | Folder Id |
name | string | Name of the datatable |
total_rows | int | Total number of rows in the datatable |
status | string | The datatable's current status |
progress | int | The datatable's current import progress |
created_ts | timestamp | Date and time when the datatable was created |
update_ts | timestamp | Date and time the datatable was last updated |
truncateTable
bool datatable.truncateTable( int datatableId )Removes all rows from the specified datatable.
Parameters
datatableId
ID of the datatable you want to empty.
Return Values
Returns true on success, false on failure.
fetchRows
array datatable.fetchRows( int datatableId, int limit, int start, string sort, string dir, array filter )Fetch rows from a particular datatable.
Parameters
datatableId
ID of the datatable from which you want to retrieve rows.
A maximum of 5000 rows will be returned. Therefore to retrieve the complete datatable, the function should be iterated in a loop, with each loop's start being increased by your value for limit, until the start value is greater than the list_total returned.
limit
The number of rows to be returned. If greater than 5000, a value of 5000 will be used.
start
The starting record from which to retrieve limit rows.
sort
Field on which to sort the data. Not yet implemented.
dir
The sort direction. Either 'ASC' or 'DESC'. Not yet implemented.
filter
Associative array of column filters.
Return Values
Returns an associative array:
Key | Type | Comment |
|---|---|---|
list_total | int | total number of rows in the datatable |
count | int | total number of records in records |
offset | int | reflects the start parameter |
limit | int | reflects the limit parameter |
sort | string | reflects the sort parameter |
dir | string | reflects the dir parameter |
records | array | indexed array of rows, as an associative array. See #findRow |
findRow
array datatable.findRow( int datatableId, int rowId )Fetch a single row.
Parameters
datatableId
ID of the datatable.
rowId
ID of the row you want to retrieve.
Return Values
Returns an associative array:
Key | Type | Comment |
|---|---|---|
row_id | int | row's unique identfier |
update_ts | timestamp | datetime of the last update |
<field_x>,... | string | A key and value are returned for each datatable field. The key is the system field name. |
addRow
int datatable.insertRow( int datatableId, array data )Adds a row to a datatable.
This should only be used on an individual basis.
To insert multiple rows, see the Datatable_Import service.
Parameters
datatableId
ID of the datatable.
data
Associative array of row data. The system field name is used as the key.
Return Values
Returns the new row ID.
updateRow
bool datatable.updateRow( int datatableId, int rowId, array data )Update a datatable row.
Parameters
datatableId
ID of the datatable.
rowId
ID of the row you want to update.
data
See #addRow.
Return Values
Returns a boolean true on success.
deleteRow
bool datatable.deleteRow( int datatableId, int rowId )Removes a particular row from the specified datatable.
Parameters
datatableId
ID of the datatable from which you want to delete the row.
rowId
ID of the row you want to be removed.
Return Values
Returns a boolean true on success.
Service
datatable
Methods