This documentation is for Insight for Server/Data Center only.

The Insight Query Language is something that you can use in different places in Insight. The IQL will also be improved more and more and used in more places within Insight. Below, we will explain how to use it and give you some examples.

Syntax

<attribute> <operator> <value/function>
<attribute>.<attribute> <operator> <value/function>

Expression containing space has quote surrounded like "Mathias Edblom"

The attribute in the IQL is case sensitive!

Attributes

Placeholders

AttributeDescription
objectTypeYou can limit the search result to a specific object type, e.g. objecttype = Servers
objectTypeIdYou can limit the search result on object typ ids like objectTypeId in (1, 2) 
anyAttributeYou can search on any attribute like: "anyAttribute = 123.123.123.123"
objectLimit the search to the object, e.g. "object having inboundReferences()"


Operators

NameOperatorDescription
EQUAL=The value is equal (not case sensitive) to input
LESS_THEN<The value is less then input
MORE_THEN>The value is more then input
LESS_THEN_AND_EQUAL<=The value is less or equal then value
MORE_THEN_AND_EQUAL>=The value is more or equal then value
LIKElikeThe input is a subset of value
NOT_LIKEnot likeThe input does not contain the value
INinThe input is a set of values
NOT_EQUAL!=The value is not equal to input
NOT_INnot inThe input is not a set of values
STARTS_WITHstartswithThe input starts with input
ENDS_WITHendswithThe input ends with input
ISisThe input is something or not.

It followed by "empty" or "not empty". It represents if a value is existing or not.

OUTBOUND_REFERENCE.The attributes reference attribute is queried
STRICT_EQUAL==The value is strict (case sensitive) equal to input
HAVINGhavingThe input is having a property like inbound references
NOT HAVINGnot havingThe input is not having a property like outbound references

Combination

You may use AND/OR to combine IQL expressions.

Functions 

Functions are used as the value in the above IQL syntax. They supply dynamic values. 

Date:

  • now()
  • startOfDay()
  • endOfDay()
  • startOfWeek()
  • endOfWeek()
  • startOfMonth()
  • endOfMonth()
  • startOfYear()
  • endOfYear()

We use m for minutes, h for hours, d for days and w for weeks to represent relative time, e.g. Created > "-2h 15m" returns all objects created in the last 2 hours and 15 minutes.

You may do queries as iqlFunction([offset]), e.g startOfDay(-3w)You may also check for an upcoming date, e.g. now(100d), which could be used for example to see if a license expires within certain amount of time.

IP Address:

  • CIDR(IP RANGE) - Filter on IP ranges 

Example
"IP Address" IN CIDR("192.0.0.0/8")
"IP Address" IN CIDR("192.168.0.0/16")

User:

  • currentUser() - Filter on user attributes connected to the current (logged in) user. Attribute needs to be of type User.
  • currentReporter() - Filter on user attributes connected to current reporter in custom fields. Attribute needs to be of type User.
  • user(user1, user2, ..) - Filter on user attributes having the specified users

Group:

  • group(group1, group2,...) - Filter on any object connected to a user within a specific group.
  • user(user1, user2, ...) - Filter on any object connected to a user within a specific group.

Example
User in group("jira-users", "jira-administrators")
User having user("admin")
Group having user("currentReporter()")

Project:

  • currentProject() - Filter on any object connected to the current project in a custom field. Works only in the context of a ticket.

Project = currentProject()


References:

The reference functions can take two arguments: an IQL and/or Reference Types Names.

The IQL argument can be an arbitrary IQL including an IQL with reference function. 

The Reference Type argument is optional.

NameAliasDescription

inboundReferences(IQL)

inR(IQL)Filter objects having inbound references where the objects referencing to the object matches the IQL, e.g. object having inboundReferences() filters all objects having inbound references since the empty IQL will match all objects. If the query is changed to object having inboundReferences(Name="My Name") all objects that are referenced by an object with the name "My Name" are filtered.
outboundReferences(IQL)outR(IQL)Filter objects having outbound references where the referenced objects match the IQL, e.g. object having outboundReferences() filters all objects having outbound references since the empty IQL will match all objects.
inboundReferences(IQL, referenceTypes)
inR(IQL, refTypes)

Filter object having inbound references where the objects referencing to the object matches the IQL. E.g. object having inboundReferences() will filter all objects having inbound references since the empty IQL will match all objects. If the query is changed to object having inboundReferences(Name="My Name") all objects that is referenced by an object with the name My Name will be filtered.

The Reference Type argument can be simple or advanced:

simple can take only one Reference Type name as parameter and looks like "Installed", e.g. object having inR("", "Installed")

advanced has the following structure: argumentName + operator + ("value 1", "value 2", "value 3"), where

      • argumentName: refType or referenceType
      • operator: IN or NOT IN
outboundReferences(IQL, referenceTypes)
outR(IQL, refTypes)

Filter object having outbound references where the referenced objects match the IQL. E.g. object having outboundReferences() will filter all objects having outbound references since the empty IQL will match all objects.

The Reference Type argument can be simple or advanced:

simple can take only one Reference Type name as parameter and looks like "Installed"

e.g. object having outR("", "Installed")

advanced has the following structure: argumentName + operator + ("value 1", "value 2", "value 3"), where

      • argumentName: refType or referenceType
      • operator: IN or NOT IN
    e.g. object having inR(label = application, refType IN ("depends", "installed", "using"))

Placeholders, references, and IQL can be combined in powerful ways. For example, you could add multiple object references to a custom field attached to an object, and then search those references for a specific key:

Example
object HAVING inboundReferences(Key IN (${MyCustomField${0}}))

Or a specific label, by using dot notation:

Example
object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))

Connected Tickets:

The connectedTickets() function is used to filter objects having tickets connected to them. Specific Jira issues may be selected by providing a proper Jira Query Language (JQL) query. If no JQL query is provided, all objects having Jira issues connected are returned.

NameDescription
connectedTickets()
All objects having tickets connected to them are returned.
connectedTickets(JQL)
Object having tickets connected to them that match given JQL query are returned.

Please observe that this powerful function may produce results that are not obvious at the first sight especially when complex queries, that uses for example negation, are constructed. To help interprete them one should think about the query as a two step action: 1. JQL execution 2. IQL execution operating on the JQL result.

To avoid confusion please remember that Insight Object Detail View presents Unresolved connected tickets by default.

Examples
object HAVING connectedTickets(labels is not empty)
object NOT HAVING connectedTickets(labels is empty)
object HAVING connectedTickets()

"connectedJiraIssues" is deprecated


Object Types:

  • objectTypeAndChildren(Name) - Filter objects based on the object type specified by the Name and its children.
  • objectTypeAndChildren(ID) - Filter objects based on the object type specified by the ID and its children.
Example
objectType in objectTypeAndChildren("Object Type Name")


More Examples:

Owner = "Mathias Edblom"
Status IN ("Running", "Open") AND Group = "jira-developers"
"License Date" > "-30d"
objectType = "Computer System" AND Status = Running
objectTypeId in (1, 2, 3)
Name like "Micro"
"Operating System" = "Linux"
"System Date" < "1/Nov/18"
Created = "1/Nov/18"
Manager IS NOT EMPTY
"License Date" IS EMPTY
"System Owner" IN ("Mathias Edblom", "Tommy Nordahl")
"User Group" != jira-developers
anyAttribute = 123.123.123.123
"System Owner"."JIRA User" = currentReporter()
"System Owner".anyAttribute = 23
Host.Virtual = true
object HAVING inboundReferences("IP address" is empty)
object NOT HAVING outboundReferences()
object HAVING inboundReferences(object HAVING outboundReferences(Name = "Linux"))
object HAVING inR("", "Installed")
object HAVING outR("", refType IN ("Installed","Uses"))
object HAVING inboundReferences(Name = "Linux", referenceType NOT IN ("Installed", "Uses"))
"System Owner" IN group("jira-users", "jira-administrators")
object not having connectedTickets(labels is not empty)
object having outR(Name Like "Microsoft" and objectType = "Operating System") and object not having inR("HotFix ID" = "KB2919355" and objectType = "Patch")

Objects containing quotes

When searching for objects containing quotes, they need to be escaped.

Let's say you have an Object name 15" Screen, to search for it escape " with \, like \"

Name= "15\" Screen"

Dot notation

Dot notation is used to traverse down a reference chain. 

To demonstrate. Given a structure with 2 object types 

Attribute

ObjectType: Employee Details
NameDefault string attribute
Using SoftwareReference to object type Software

Attribute

ObjectType: Software
NameDefault string attribute
Status

Status attribute

To query object of type Employee Details using a software with status attribute missing one would query

"Using Software".Status is empty


The following screenshots show the same example.



IQL - Order By

It is possible to add the order by suffix described by the following syntax
Syntax

order by [AttributeName|label] [asc|desc]


If the attribute specified in the order by clause is of the object reference type you can use dot notation to order by attributes on the referenced object. This can be done in unlimited depth. Note that the every dot in the order by clause will decrease the performance of that particular IQL. 

Values that are missing will be considered to be last (using asc) or first (using desc).

The attribute name specified in the IQL must exist in Insight if not the IQL will be considered invalid. The attribute name is case sensitive.

If the filtered objects does not contain the attribute specified in the order by clause the order of the objects returned will be arbitrary. 

The placeholder label can be used instead of the attribute name to order the objects by their configured label. 
Example

order by label
order by Key desc
order by "My custom Attribute"
order by "My object reference"."Attribute on referenced object" asc




Read about where to use IQL

  Page: Insight Automation
  Page: Insight Custom Field
  Page: Insight Referenced Custom Field
  Page: Insight Searching & Filtering