A downloadable version of this article is attached.

Entity Search

The Entity Search functionality allows a user to search for subsets of data.

The API endpoint URI includes parameters which can be manipulated via logical and comparison operators to specify exactly the data set required.

Logical Operators

The available logical operators are:

• AND
• OR

Comparison Operators

The available comparison operators are:

• =
• <> 
• < 
• > 
• <=
• >=
• IN(x,y,z…)
• NOTIN(x,y,z…)
• BEGINS(xyz)
• NOTBEGINS(xyz)
• CONTAINS(xyz)
• NOTCONTAINS(xyz)

Creating a Search Filter

The logical and comparison operators can be combined using the ‘criteria’ URL parameter to create filter queries against a particular Entity type. For example, if a user wished to search for all Level 1 Projects which contain the word ‘TEST’ in the description, they would use the URI:

Figure 1 - Search criteria URI format

It is also possible to search using Custom Fields as a criterion. Firstly, the user would need to find out the Custom Field Key which they wish to search on. This is done by opening the custom field edit view and viewing the key value which is displayed in the bottom left hand corner.

Restricting Returned Fields

The API Search functionality makes it possible to return only a subset of the total number of fields for each return result by utilising the ‘fields’ URL parameter and a comma separated list of field names, as depicted in figure mtamta, which illustrates a Project entity search where only the code and description fields of the Projects found are returned.

A special case within the Search functionality is the specification of Custom Fields. Specifying which Custom Fields are required is done within the ‘fields’ URL parameter. To specify a Custom Field we must take the Custom Field Key and prepend ‘cf_’. For example, to return the code, description and value of Project Custom Field with Key 136 for all Projects the URL would be:

It is also possible to search using Custom Field values. The key is constructed in the same way as when specifying a return field, i.e. the Custom Field key prefixed by the characters ‘cf_’. So in order to repeat the previous query but this time restrict the results to all Level 1 Projects with Custom Field 136 set to “Live” we would construct the following endpoint:

<base_address>/search/project?fields=code,description,cf_136&criteria=level=1 AND cf_136=Live

Note that it is not necessary to return a Custom Field in the result set in order to specify it as a search parameter so the following endpoint is also valid:

<base_address>/search/project?fields=code,description&criteria=level=1 AND cf_136=Live

User Functions

KIP User Functions have been incorporated into the Web API search functionality. This allows the caller to specify a User Function in the URL. For example to return all Projects where the Project Start Date is within the past two months the endpoint would be:

<base_address>/search/project? criteria=startdate>=#BOM-2# AND startdate<=#TODAY#

Note that calling applications will URL encode all calls to the Web API. If testing using a third party Web API test application ensure that this is also the case. If the test application does not support this functionality then make sure to encode the URL manually. In this case the above URL would become:

<base_address>/search/project? criteria=startdate>=%23BOM-2%23 AND startdate<=%23TODAY%23