API Documentation Portal
API Documentation Portal
This API has been designed to provide a simple interface layer between Agility and external 3rd party systems and services. Making it easier to integrate Agility into the larger software ecosystem of your SMART business processes. It enables data to be read, actions to be triggered and records updated from and within the Agility system from external sources. These functions can be used as key elements in forming an autonomous workflow process. It has been built on a platform that facilitates rapid and ongoing continuous development of new and existing endpoints. The overview below provides some information on getting started.
This integration platform has many applications and uses extending the Agillity CMMS system into wider business processes.
It is designed primarily for use by programmers, system or integration developers and technical specialists.
Every agility system is identified by a unique TenantID. Every request made through the API requires the passing of
a unique TenantID in the request header. Currently, you can only obtain the TenantID for your Agility system by request from our
technical support team. This will soon become a self service option in this portal.
For clarity; 'Authentication' is proving correct identity. This is different from 'Authorisation' which is what actions you are allowed to perform. Agility API supports 2 authentication methods;
We recommend the use of API key for 3rd party integrations. Currently the get API key button on this page is disabled and you can only obtain an API key by request from our technical support team. This will soon become a self service option.
Once you have obtained your TenantID and API Key you are ready to go. Click the authorise button to enter your API key. Getting data from the API does require knowledge of the table and column names in Agility. There are endpoints that can help in returning schema information. We recommend reading the overview below that describes querying Agility for data using the API.
The API is categorised into business objects e.g. 'Work Orders'. Each business object contains one or more endpoints allowing
querying of that business object and functions available for that business object. As well a schema endpoint that helps identifying
the table and field names that the business object is aware of.
Each business object category has a query endpoint that will allow you to query any data that the business object is aware of. The method of querying data is consistent across business objects and is described in detail below
Querying the data requires knowledge of the Agility table and field names. The schema endpoint provided for each business object will return details of all the table and fields that the business object is aware of. Additionally the form field helper will help you to identify table and field names for items used in the Agility application.
To use a query endpoint a post request is made with the query defined as an object in the request body. The request body contains keys that will look familiar to anyone who uses SQL.
select Required
The select key is the only required key in the query object. It is a string array of table and column names. You can use any table names
and field names that the endpoint is aware of.
The format must be
filter Optional
The filter is optional and allows definition of multiple filter criteria. Each individual filter criteria is described by a filter element object. (Shown Below)
column
This needs to be a tablename and fieldname that the endpoint is aware of.
value
This is the value you want to compare the column to. Supported data types are string, number, boolean, array and null.
condition
This must be one of the following conditions described in the table below:
| Agility API Condition | Description | SQL Equivalent |
|---|---|---|
| eq | equal to | = |
| neq | not equal to | != |
| gt | greater than | < |
| lt | less than | > |
| lte | less than or equal to | <= |
| gte | greater than or equal to | >= |
| like | is like | like '%value%' |
| nlike | is not like | not like '%value%' |
| in | is one of | in ('value1','value2','value3') |
| nin | is not one of | not in ('value1','value2','value3') |
| begins | begins with | like 'value%' |
| ends | ends with | like '%value' |
The filter is passed as an array. Each item in the array can be either a filter element object.
In SQL the above would equate to;
syJobtype.Code = 'PPM' and woJob.site != 'abc'
Or an array of filter element objects. Passing an array of filter element objects as an item in the filter array is how an 'OR' is described.
In SQL the above would equate to;
syJobtype.Code = 'PPM' or syJobType.Description like '%break%'
Filter element objects and arrays of filter element objects can be combined in the same filter.
In SQL the above would equate to:
syPriority.Description = '24 hours' and (syJobtype.Code = 'PPM' or syJobType.Description like '%break%')
and woJob.site != 'abc'
Each item in the filter array is always treated as an 'AND' operator. i.e. Filter[0] + " and " + Filter[1] + " and " + Filter[2] ... etc
orderby Optional
This optional key enables one or more sort orders to be applied to the data. It is a string array of table and column names. Each column name can be suffixed with 'desc' to change the default ascending sort order. Sorting is applied in the same order as it is passed in the request. You can sort on any table and column names that the endpoint is aware of. This key is particulary useful, when combined with the 'maxrows' key described below, for obtaining Top N or Bottom N type data.
Example order by;
maxrows Optional
This optional key allows the passing of a maxium rows to return value as an integer. If no maxrows value is passed, default
behaviour is to return all rows meeting the filter criteria, or all rows if no filter is passed.
Please note that a maxium row limit of 100 rows is always applied when making requests from this documentation portal.
Even if a 'maxrows' value greater than 100 or no maxrows value is specified.
Example maxrows;
distinct Optional
This key allows optionally passing a boolean value to apply a 'distinct' selection to the query. If no distinct value is passed, default behaviour is to not apply a 'distinct' clause to the query.
Example distinct;
Results are returned as an object array with each object presenting one row of data. Each object will contain the fields requested in the 'select' key. A primary key for the buisness object will always be returned with each object, even if it is not requested.
All available endpoints are descibed in the swagger documentation.