OTISS provides a RESTful API to allow customers to read and update the asset and inspection data. This API is typically used to extract asset information from OTISS to store in another Asset Management or Data Processing system. OTISS can also accept updates.
This is a new feature within OTISS and is constantly developing to suit our users’ requirements. Please contact us if you have suggestions for features or options that you would like to see.
You need to pay an extra DATA API subscription to enable this feature on each estate. When this option is enabled, the Estate Settings-> Data API webpage appears to allow you to create the Security Credentials required.
API Protocol
All access must use HTTPS GET or HTTPS POST requests.
For example: HTTPS GET “https://www.otiss.co.uk/treesurvey/api/furniture/table.json?token=R7IkHoyH78mWK5XQMAcH&rows=50&page=1”
or HTTPS POST “https://www.otiss.co.uk/treesurvey/api/furniture/table.json” with POST data of “token=R7IkHoyH78mWK5XQMAcH&rows=50&page=1”
All data is returned formatted as JSON.
Security Credentials
All access to the RESTful API is controlled via an alpha-numeric token that must be included with every request, e.g. &token=R7IkHoyH78mWK5XQMAcH. These tokens must be stored securely and not shared with un-authorised users.
The token determines what data can be accessed and in whose name.
| Aspect | Security |
| Estate | Only data from a specified OTISS estate can be accessed via each token. |
| Account | + All API calls are performed in the name of a specified user that must have access to the estate. + All API calls are subject to the Access Level assigned for this user on the Estate-> Access webpage. + Updating items as part of a survey is subject to the OTISS access rules for Surveys – read more. In brief, the Survey must be in the Active|Work stage, and the user must be assigned to the Survey. |
| Roles | A token is further restricted to a small set of specified roles – e.g. Read-Furniture-Items and/or Update-Furniture-Items. |
Use the Estate Settings-> Data API webpage to create, delete and modify tokens.
- Create new tokens and assign a user and roles.
- Enable/Disable existing tokens.
- Edit existing tokens to change the user or the roles.
- Delete tokens.
If a token is compromised or suspected of been compromised, then the token can be revoked at any time and a replacement token can be generated.
Tree and Furniture Inspections
Within OTISS, each asset (i.e. a tree or item of furniture) is assigned a unique asset-UUID. A asset is stored/viewed as a set of inspections which all share the same asset-UUID. Each inspection has a separate inspection-UUID and an inspected date – to maintain a history of the asset’s condition and work done.
To access the OTISS asset/inspection tables, use HTTPS GET or POST with one of the following URLs.
| Furniture | https://www.otiss.co.uk/treesurvey/api/furniture/table.json |
| BS 5837 | https://www.otiss.co.uk/treesurvey/api/bs5837/table.json |
| Tree Safety | https://www.otiss.co.uk/treesurvey/api/treesafety/table.json |
Use the following request parameters.
| Request Parameter | Status | Data Type | Comments |
| token | required | Alpha-numeric String | security credential |
| rows | required | Integer | requested number of rows of data. E.g. 50 rows. |
| page | required | Integer | page number. E.g. 1 = return the first 50 rows, 2= return rows 51..100. |
| siteId | optional | String UUID | If UUID provided, then only items from that site are provided. Otherwise items from all sites are provided. |
| surveyId | optional | String UUID | If UUID provided, then only inspections/items from that specific survey are provided. If set to “ALL_SURVEYS_ID”, then inspections for for all the surveys for the selected site (or all sites) – each asset will have multiple rows with the same assetId and different inspectionIds. Otherwise, only the most recent inspection is provided for each item. |
| filters | optional | URL encoded JSON | specify a simple/complex filter based on the data fields – see below for more information. NB the JSON must be URL encoded. |
The returned JSON data is formatted as {“page”:1,”total”:13,”records”:602,”rows”:[{…},{…},…]}”
| Field Name | Data Type | Comments |
| page | Integer | the requested page number |
| total | Integer | total number of pages of data for the specified #rows |
| records | Integer | total number of rows across all pages |
| rows | Array of Objects | the data rows on this page – i.e. #rows or less. A values of [ ] means that these is no data rows on this page. |
| message | String | error message or null |
The data items for each row is similar to those available when viewing the Furniture Spreadsheet page – see Furniture page for more information, or contact OTISS support.
Update Tree and Furniture Inspections
The inspections can be updated using a HTTPS POST operation with one of the following URLs. NB: At present, new assets cannot be created via the API.
| Furniture | https://www.otiss.co.uk/treesurvey/api/furniture/update.json |
| BS 5837 | https://www.otiss.co.uk/treesurvey/api/bs5837/update.json |
| Tree Safety | https://www.otiss.co.uk/treesurvey/api/treesafety/update.json |
Use the following request parameters.
| Request Parameter | Status | Data Type | Comments |
| token | required | Alpha-numeric String | security credential |
| inspectionId | required | UUID as String | The UUID of the inspection to be updated. |
| dataField (mostly the same fieldIds as provided above for each field in the inspection row) | optional | varies, can be blank/null | The new value for this field. |
The returned JSON data is formatted as {“success”:true|false,”items”:[{…},{…},…]}”
| Field Name | Data Type | Comments |
| success | Boolean | The request succeeded or failed. If false, then no data was update. |
| items | Array of Objects { id: “field”, message: “error” } | Explanation messages are provided for each field when the operation fails. |
Table Filtering
The API filtering is based on that used by the free jqGrid library – see https://github.com/free-jqgrid/jqGrid/wiki/Custom-filtering-searching-Operation
The internal structure of filters property of postData is like on the example below
{
"groupOp": "AND", // or "OR"
"rules": [
{"field": "name", "op": "eq", "data": "test1"},
{"field": "ship_via", "op": "ne", "data": "FE"}
]
} would only return data rows where (name='test1' AND ship_via<>'FE').
{ "groupOp": "AND", "rules": [ {"field":"modifiedDate","op":"ge","data":"17-Nov-21"} ] } would only return data rows where the “modifiedDate is on or after 17-Nov-21”.
The list of possible values of op property used in rules of filters is the following
"eq"– “equal”. Used with all typed of data for local and remote searching."ne"– “not equal”. Used with all typed of data for local and remote searching."lt"– “less”. Used mostly with numeric or date types of data for local and remote searching."le"– “less or equal”. Used mostly with numeric or date types of data for local and remote searching."gt"– “greater”. Used mostly with numeric or date types of data for local and remote searching."ge"– “greater or equal”. Used mostly with numeric or date types of data for local and remote searching."bw"– “begins with”. Used with string types of data for local and remote searching."bn"– “does not begin with”. Used with string types of data for local and remote searching."in"– “is in”. Used for remote searching only. The local implementation just use “eq” operation instead."ni"– “is not in”. Used for remote searching only. The local implementation just use “ne” operation instead."ew"– “ends with”. Used with string types of data for local and remote searching."en"– “does not end with”. Used with string types of data for local and remote searching."cn"– “contains”. Used with string types of data for local and remote searching."nc"– “does not contain”. Used with string types of data for local and remote searching."nu"– “is null”. Used with all types of data for local and remote searching. It’s important that the data be correctly loaded in the grid andnullvalues are not replaced to empty string for example."nn"– “is not null”. Used with all types of data for local and remote searching. It’s important that the data be correctly loaded in the grid andnullvalues are not replaced to empty string for example.