Querying on a condition

You can specify that a RESTful get returns elements that match a certain property condition. For example, you can request "for JobA, get me all the job runs, and show me just the HAD_ERRORS property for each job run." In addition to specifying the condition, you can order the results.

• Getting started — a simple example
• Choosing properties to use with the SELECT and WHERE keywords
• Using NOT, AND, and OR
• Ordering results
• Querying with /type and /group prefixes
• Query operators
• Query parameters

Getting started — a simple example

The following example introduces the basic parts of the query language. Here is the syntax for the request "for JobA, get me all the job runs, and show me just the HAD_ERRORS property for each job run."

With UTF-8 encoding (this encoding is required)

Without UTF-8 encoding

This and subsequent non-UTF-8 versions are included just to make them easier to read.

The key things to note about this syntax are:

• UTF-8 encoding. You must encode queries in UTF-8 (replacing spaces with %20, and so on).
• The query prefix. /query is the general purpose prefix for requesting a query.
   You can also append a query string to /type and /group requests, as described in Querying with /type and /group prefixes.
• Authentication. When using the query prefix, state authentication information (username, password, role) first.
• BQUERY keyword. The BQERY keyword introduces the query string.

• SELECT keyword. The SELECT keyword indicates which property or properties you are interested in. In this example, you want any job run where the HAD_ERRORS property is set to true. For information about the property syntaxes you can use with the SELECT keyword, see Choosing properties to use with the SELECT and WHERE keywords.

  Note

  If a property begins with a number or a special character (such as ! or |), enclose it in double quotes. For example: SELECT "0s1"

• FROM keyword. The FROM keyword indicates the type of object, such as SystemObject/Job, SystemObject/Server, and SystemObject/Component. You can list all available objects by using the following URI: /type/PropertySetClasses/SystemObject/
• WHERE keyword. The WHERE keyword introduces the condition that the FROM object must meet. The general form of the condition is: <property> <operator> <value>
   For example: NAME equals foo
  • For information about the various property syntaxes you can use, see Choosing properties to use with the SELECT and WHERE keywords.
  • For a list of legal operators, see Query operators.
  • For information about using NOT, AND, and OR, see Using NOT, AND, and OR.

Choosing properties to use with the SELECT and WHERE keywords

You can specify the following property designations with SELECT and WHERE keywords:

• One or more simple (such as HAD_ERRORS ) or complex (such as TARGET.OS ) properties.
• The asterisk wildcard *.
• Aliases.
• NOT, AND, and OR (use with WHERE keyword only).

One easy way to find property names is to launch the TrueSight Server Automation console (GUI) and display the property dictionary (Configuration, Property Dictionary View). Navigate to the object you want and view the names of its properties.

Complex properties

Some properties are "complex," in that the property itself is an object, and that object has its own properties. For example, a complex property of a component is the template on which the component is based. The referenced template is itself an object with its own properties.
A technique for building complex property names for use in RESTful gets is to take a look at the condition drop-down boxes in the smart group windows. For example, suppose you right click a component group, then select New, Component Smart Group.

The resulting dialog box shows the properties you can use to create the smart group's condition.

Some properties, like ROLE_CREATED, are simple string properties. Other properties, like TEMPLATE are objects -- in this case TEMPLATE is a component template object. If you click the icon to display the properties of TEMPLATE, the component template properties appear:

Suppose you want to create a complex property that represents the name of the template upon which a given component is based. The syntax for this complex property automatically appears in the dialog box--in this case TEMPLATE.NAME.
You can then use this syntax in a query such as:

This gets all the components that are based on a template named T1.

Multiple properties

You can specify more than one property with the SELECT keyword. Separate properties with commas.
For example, suppose you want to get all runs that had errors for a certain job named myJob, and then get the job logs for those job runs. You can use syntax like this:

Note that the asterisk in JOB_LOG_ITEMS* is just part of the property name--it is not a wildcard.
Here is another example, this time getting the names and descriptions of the components that target Windows systems:

For a list of all available operators, see Query operators.

Using aliases

You can use aliases to reference properties on multiple classes. You can use aliases either in the SELECT clause or in the WHERE clause.
For example, you can select a server's IP address and a depot object's install path by declaring a server alias (in this case s) and a depot object alias (in this case d):

Using NOT, AND, and OR

You can use NOT, AND and OR with the WHERE keyword. You can optionally use parentheses for readability. The AND or OR combine conditions. Using <PropertyCondition> as shorthand for a name/operator/value statement (for example "OS equals Windows"), all of the following are legal:

WHERE NOT <PropertyCondition>

WHERE <PropertyCondition> OR <PropertyCondition>

WHERE <PropertyCondition> OR <PropertyCondition> OR <PropertyCondition> OR <PropertyCondition>

WHERE <PropertyCondition> AND <PropertyCondition>

You can also use parentheses:

WHERE (<PropertyCondition> OR <PropertyCondition> OR <PropertyCondition> OR <PropertyCondition> )

WHERE (<PropertyCondition> AND <PropertyCondition> AND <PropertyCondition> AND <PropertyCondition> )

WHERE ((<PropertyCondition>) AND (<PropertyCondition> ) AND (<PropertyCondition> ) AND (<PropertyCondition> ))
The query language uses operator precedence, so that frequently you only need parentheses for the sake of readability.
The following statements change the shorthand to <Condition> to indicate any <PropertyCondition> or NOT <Condition> or AND <Condition> or OR <Condition>:

• The NOT applies to the closest <Condition> or to an AND/OR in parenthesis.
• The OR s are evaluated next.
• The AND s glue together the OR s.

Therefore, the following two strings are equivalent:

WHERE <Condition> OR <Condition> AND <Condition> AND NOT <Condition>

WHERE (<Condition> OR <Condition) AND ( <Condition> AND (NOT <Condition))

Ordering results

You can use the ORDER BY keyword to order your results. Here are some examples:
Get the names and descriptions of all servers whose names contain xyz, then order the servers by AGENT_BUILD_VERSION (a server property):

You can order by multiple properties, separated by commas. This example orders servers first by OS, then within each OS, orders them by AGENT_BUILD_VERSION.

Querying with /type and /group prefixes

Sometimes you might find it convenient to "browse" to a resource using /type and /group requests, and then perform a query. Here are some examples:
List the contents of the myServers group, showing only the DATE_MODIFIED property for each listing:

Note that in this case, you are using only the SELECT keyword--the other keywords are not required here.
Continuing with this example, the contents of the myServers group can include individual servers as well as other server groups. Suppose you want to list only the individual servers. You can do it like this:

Note that this example uses the * wildcard syntax SELECT * to say "give me all the group members that match the condition specified in the FROM keyword." The condition specified in the FROM keyword is that the group members have to be SystemObject/Server objects — individual servers.

Query operators

Query parameters