<< Click to Display Table of Contents >> Navigation:  Using Cimera > Searching and Querying > Structured Queries > Query Symbolics

Symbolics allow a query to prompt the user for information which is then incorporated into the query. Using symbolics generalised queries may be written once and used many times.

 

For example, the following CQL query may be used to find Problems that have been resolved by Product Builds hosted on a particular Server.

 

FIND Problem WHERE [Resolved by](

   FIND [Product Build] VERSION WHERE [Is hosted by](

        FIND Server WHERE ciname = 'ABC123' ))

 

This is useful but would have to be edited before reusing it for a different server. The use of symbolics allows enhancing the query to make it work against any user-defined server:

 

FIND Problem WHERE [Resolved by](

   FIND [Product Build] VERSION WHERE [Is hosted by](

        FIND Server WHERE ciname = '$$server-name$$' ))

 

Symbolics may be of the following types:

 

In addition symbolics may be used to ask the user to select from a list of appropriate Cimera Items, for example to prompt the user to select a Server. In this case the symbolic returns the object id of the selected item and so we amend our previous query:

 

FIND Problem WHERE [Resolved by](

   FIND [Product Build] VERSION WHERE [Is hosted by](

        FIND Server WHERE ciobjid = $$server-id$$ ))

 

(no quotes are required as the symbolic wraps the object id with quotes for you, e.g. 'CI:123')

 

Is is also possible to allow the user to select multiple items in which case it returns a comma separated list of object ids: 'CI:123','CI:345','CI:789'

 

To use a list, the query is amended:

 

FIND Problem WHERE [Resolved by](

   FIND [Product Build] VERSION WHERE [Is hosted by](

        FIND Server WHERE ciobjid IN ($$server-list$$) ))

 

Symbolics can also be used to extend the right-click context menus of Items. With the sample query above - when, having selected one or more servers, the user right-clicks the standard context menu will be extended to include the query.

 

CQL and Reporting DB queries support the use of Symbolics but Query Builder queries do not.

 

To manage the symbolics for a query use Menu File > Manage Symbolics...

 

 

This will then display the Manage Symbolics window, which is shown populated with the symbolics in the examples above:

 

 

Note that symbolics are not defined with any $$ symbols in the name - these are only used in the CQL / SQL to tell Cimera that a symbolic is being referred to.

 

Right-clicking in the list presents a menu with options to create a new symbolic, or edit or delete existing symbolics.

 

The definition for the string symbolic server-name is shown below:

 

 

User prompt is the text that is to be shown to the user when requesting the value. If it is omitted then generic request text is used.

 

The definition for the Item Type symbolic server-id is shown below:

 

 

Type is set to Select Item and the Item Type is Server. Notice that the Appear in context menu for Item Type option is ticked - this is what tells Cimera to extend the right-click menu for Server items when the user has selected a single server.

 

The definition for the Item Type symbolic server-list is shown below:

 

 

 

In this instance Type is set to Select Multiple Items - which tells Cimera to obtain a list of one or more items from the user. Also notice that there is additional 'Where' criteria specified. When Cimera presents a list of Servers to the user to select from it is effectively running the CQL Find Server Where status = 'In Service'. Again this symbolic is ticked and Cimera will extend the right-click menu when the user has selected one or more Server items.

 

Note that whilst the additional where criteria is used when Cimera is presenting lists of items, it is not evaluated when right-clicking items. So if the user were to right click a Server that has status 'Out of Service' the user would still see the query in the right-click menu.

 

When the query below is run it prompts the user for the Server:

 

 

Note that on the Run menu there is a second option

 

 

When rerunning an opened query Cimera will not re-prompt for any symbolics (it would get boring having to keep answering the same question if simply wanting to rerun as is or having changed some of the query's criteria). To force Cimera to re-prompt for the symbolic values use the Run (reset symbolics) option.

 

When the user right-clicks a single Server the query appears in the list

 

 

Multiple symbolics can be defined within the same query and Cimera will prompt the user for each:

 

 

To see what symbolic values have been captured it is possible to view the query with the symbolics in place:

 

 

 

 

As well as displaying what values have been captured from the user it also shows how the substitution has been made into the query. This may help debugging queries that don't work as the user expects!