Entity filter syntax

Overview

The document outlines how entity queries are made and the format of the Entity filter syntax in the Gateway Hub REST API.

Filter Syntax

Entities represent something being monitored, and they possess attributes. Attributes are a collection of key / value pairs.

Attribute keys are:

• Namespaced to avoid conflicts between:
  • ITRS defined attributes — itrs.* namespace.
  • User defined attributes — user.* namespace.
  • Integration defined attributes — namespace per integration, for example servicenow.*.
• Case sensitive.

Entity information can be accessed using the /entities endpoint. To use this endpoint make a request to the hub using a URL of the form https://hubhost:8081/v0/entities replacing the hostname as appropriate.

The GET /entities and GET /entities/summary endpoints can apply a filter on entity attributes based on the following syntax:

• Values can be compared against a single value (using lexicographic comparison):

  Operator	Definition	Example
  =	Equal	itrs.os-type = Linux
  !=	Not equal	itrs.os-type != Linux
  >	Greater than	user.yearCreated > 2018
  >=	Greater than or equal to	user.yearCreated >= 2018
  <	Less than	user.yearCreated < 2018
  <=	Less than or equal to	user.yearCreated <= 2018

• Values can be compared against a set of values:

  Operator	Definition	Example
  IN	In	user.department IN (eq, fx)
  NOT IN	Not In	user.department NOT IN (eq, fx)

• Attributes can be tested for existence (attributes containing empty strings are treated as if the attribute does not exist):

  Operator	Definition	Example
  EXISTS	Exists	user.department EXISTS
  NOT EXISTS	Does not exist	user.department NOT EXISTS

• Filters can be combined with boolean logic:

  Operator	Definition	Example
  AND	X and Y	itrs.os-type = Linux AND user.department = fx
  OR	X or Y	user.department = eq OR user.department = fx

  • Parentheses are also supported. For example, (user.department = eq OR user.department = fx) AND itrs.os-type = Linux.

When using the filter syntax, the following rules apply to attribute names and values:

• Quotes (") or backslashes (\) must be escaped. For example, "user.department \"name\"" = "Equity \"Derivatives\"" and "user.department\\name" = "Equity\\Derivatives".
• Characters other than 0-9, a-z, A-Z, or . must be surrounded by quotes. For example:
  • Names with spaces — "user.data centre" = "Telehouse Docklands".
  • Names with non-English characters — "user.数据中心" = "上海".

Entity Attributes

You can fetch information on the attributes of entities using the REST API.

You can get a list of known attributes using the /entities/attributes endpoint. To do this, make a GET request to Gateway Hub using a url of the form https://hubhost:8081/v0/entities/attributes replacing the hostname as appropriate.

You can get a list of possible values for a specific attribute using the /entities/attributes/<target_attribute> endpoint. To do this, make a request to Gateway Hub using a url of the form https://hubhost:8081/v0/entities/attributes/<target_attribute> replacing the hostname as appropriate.