Developer Portal – Extensibility

Docs: Additional Attributes

Mon, 01 Jan 0001 00:00:00 +0000

The ATS has a concept called layout lists which are predefined table definitions containing arbitrary columns of data attributes linked to the resource in question.

Most resource representations can be expanded by supplying a layout query parameter which should be the ID of an existing layout appropriate to the resource. The extra data will be present under the layout_data key in the returned representation. It will be an array of objects containing the value in the order defined in the layout. The order, column titles, and other meta-data for the requested layout need to be requested seperately via the layout listing endpoint. If value_raw is present this is the Oleeo internal ID for the value.

GET https://api.tal.net/api/v1/applications?layout=123


{
 "id": 47,
 ...
 "layout_data": [
 {
 "value": "Edinburgh",
 "value_raw": 1234
 },
 {
 "value":"1997"
 }
 ],
 ...
},

Docs: Data Paths

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Data Paths are strings that can be included in system config locations - like mail merge placeholders in emails, or column entries in layout listings which the ATS can evaluate at run-time to a value from the database specific to the current context (i.e the current application or another object, or relative to some other feature, like the current user).

You will likely come across data paths when querying layout listings and form configurations, amongst other areas. They are particularly useful in forms to control conditional visibility of form items based on the value entered in previous fields.

The syntax allows relationships to be followed through related objects. You can follow from an application to the user that made the application and eventually through to the target property on the (possibly distantly) related object.

The final value may be a direct property of an object (equivalent to what is stored in the database), or it could be the return of a method (function called on that object).

For example, in the context of an application, the path application.user.firstname will be evaluated to the firstname of the user who made the current application.

Example: Getting Form Data

To get to item values on a Formable class (Such as Application or Opportunity) you follow the formdata relationship e.g.

application.formdata
application.opportunity.formdata

The formdata relationship requires three indexes to uniquely identify an individual data element.

Item ID
Section instance
Form instance (If fewer are given then the first instance is assumed.)

For example:

application.formdata.21:2:1

This will return the value stored in the second section instance of item ID 21, for the application in question.

Docs: Searching & Filtering

Mon, 01 Jan 0001 00:00:00 +0000

Predefined searches

Complicated searches with grouped search terms and a rich set of operators can be configured in the main ATS application and used in calls to GET collections by their ID. These are supplied via the saved_search or config_search query parameters (saved_search refers to searches set up by normal users, config_search refers to searches configured generally and available to all users).

GET /api/v1/applications?saved_search=123

GET /api/v1/applications?config_search=123

Predefined selections

The ATS application has a concept called ‘selections’ which are explicit subsets of the resource in question that can be named and manipulated. The selection query parameter can be used in calls to GET collections to only return members of that selection.

GET /api/v1/applications?selection=123

Ad-hoc searching

The search query parameter can be used to search for a specific subset of a collection, this is a URI escaped string representing a search condition in the form of:

search=<key><operator><value>

The key is either a JSON pointer or one of our datapaths. A JSON pointer can be used to address attribute(s) of the resource representation to search on, whereas a ‘datapath’ can be used to refer to any arbitrary value than can be linked to from the resource in question. Although much more flexible than the JSON pointer the disadvantages of datapaths are that they are not as discoverable and may have to include arbitrary IDs.

Multiple instances of the search parameter, including a mixture of JSON pointer and datapath styles can be supplied, these are ANDed together.

In JSON pointer syntax elements of lists can only be addressed with * (any) or our custom syntax <label> available labels are detailed in the response schema.

The value is either a plain string or a comma seperated list of strings enclosed in curly braces. Lists can only be used with the = and != operators and provides IN, NOT IN style semantics.

The operator can be:

=, != Exact match, non-match
=~, !~ Case insenstive sub string match
<, >, >=, <= Order comparisons

Examples

Getting applications:

GET /api/v1/applications?search=...

/user/id=123 - Applications with user ID 123
application.user=123 - Same as above but with a datapath
/user/id={123,456} - Applications with user ID 123 or 124
/user/firstname=~bob - The application user’s firstname contains ‘bob’
/process_state/state=~interview - The current process state of the application’s title contains ‘interview’

Getting candidates:

GET /api/v1/candidates?search=...

/Address/*/AddressLine=~High Street - Candidates with any address that contains ‘High Street’
/Email/[personal]/Address=~gmail.com - Candidates with an email address labelled ‘personal’ that contains ‘gmail.com’

Filtering

The filter query parameter can be supplied to filter the collection by a string. Attributes marked ‘filterable’ in the resource description are considered, these are usually all the text and date attributes.

For example: GET /api/v1/users?filter=Oxford will return all candidates with the string ‘Oxford’ in any of the filterable attributes - addresess, education etc.