Finding global configurations by using queries

Build queries to find global configurations that meet the attribute conditions you specify. With queries, you can work more efficiently by selecting multiple configurations at a time to complete tasks such as editing attributes or tagging configurations.

Before you begin

  • You must be logged in to a Global Configuration Management project area.
  • To share your queries with other project area members, you must have the Configuration Lead role or higher, or the Create shared queries privilege.
  • To modify and delete the queries that are written by other project area members, you must be assigned that privilege.

About this task

You can build conditions for both built-in attributes and custom attributes. Attributes might be used differently by teams, even within the same project area: different teams might use different sets of attributes. So even after an administrator defines a custom attribute for configurations, it might not be added to all configurations yet. For example, if your Configuration Lead defines a custom attribute, named Approver, to indicate that a configuration is reviewed and approved. This attribute is likely added to, and set, only on configurations that are reviewed and approved.

Global Configuration Management queries are not published to Report Builder. To create queries across artifacts, project areas, or servers, build queries in Report Builder.

Procedure

  1. On the banner, click Queries and click the query type to create.
    • Personal Query, which only you can edit and run.
    • Shared Query, which all project area members can run (you must have permission to create shared queries).
    Tip: You can also click Browse and create queries on the Welcome page.
  2. In the Name text box field, enter a name for your query.
    Use a descriptive name so that team members can find your query easily.
  3. On the Conditions tab, build your query.
    When you build your query:
    • Choose where to run your query using the Project Areas field. By default, the query runs against the current project area, but you can modify it to run across multiple project areas.
    • Click Add Condition and then build the condition by using the menus. To add a group of conditions, click Add Group.
    • For each group of conditions, choose whether all or only some conditions must be met. If you want the query results to not match the specified conditions, choose whether not all or none of the conditions match.
    • Move conditions by dragging them.
    • You can specify a condition for any attribute in a global configuration or component, except for attributes that use the String (Large) data type.
      Note:
      • You can't query custom attributes that are large strings. If you need to query that information, replace those attributes with new ones whose data type is a small or medium string, or an enumerated data type.
      • If you want to create a condition but no existing attribute reflects what you need, ask your Configuration Lead to consider adding a custom attribute to the configuration or component artifact type.
    • You can also specify conditions based on attributes of these related items: components, parent configurations, child configurations, and configurations that are derived from the configurations that meet the conditions you specify.
    • Determine whether archived configurations are included in the results by adding the Archived query condition. If your query doesn't include an archived condition, the results show only active configurations by default.
  4. Optional: On the Details tab, provide a description of the query so that it can be easily identified in a list. Query descriptions are not searched.
  5. On the Columns tab, in the Result Columns section, choose which attributes to show. The order in which the columns are shown on the Columns tab, matches the order that they are shown in the results. To sort the query results, select the attribute to sort on, and then specify the sort order. You cannot sort on String (Large) types.
  6. Click Save. By default, the query is saved on the My Queries tab, where only you can see it.
  7. Click Run.

Example

Example 1: You want a list of streams that contain manual in their Title. Add these conditions:
  • Choose Configuration Type, is any of, and select Stream. Then, click Add Condition.
  • Choose Title, contains, and write manual. Then, click Run.
Example 2: Return the list of streams and baselines that are derived from any configuration with the amr tag. Add these conditions:
  • Choose Configuration Type, is any of, and select Stream and Baseline. Then, click Add Condition.
  • Choose Created From Configuration> Tags, is any of, and write amr. Then, click Run.
Example 3: Return the list of archived configurations that are assigned to the team areas that you belong to.
  • Choose Team Area, and I'm a member of. Then, click Add Condition.
  • Choose Archived, and true. Then, click Run.

What to do next

To complete tasks (such as tagging or editing attributes) for multiple configurations at a time, select the configurations from the list of results. To select all configurations, click the main checkbox of the Name result column. Then, click the Actions menu Image of actions menu, and select the task for completion.

View a specific configuration tree by clicking its name, and then click Edit in the configuration editor to make any changes.

View the list of other queries by clicking the Queries breadcrumb, or on the banner select Queries > Browse > My Queries or Shared Queries. To add a query to your Favorites list, click the star icon that is placed with the query name.

Creating queries across project areas

Create queries that run across multiple project areas in the same repository.

About this task

A new query runs against the current project area by default. However, you can choose a set of project areas for querying. When multiple project areas are selected, the query results show all matching configurations from these chosen project areas. The attributes that are available to use for the conditions and result columns are a combination of attributes from the selected project areas.

The query editor collapses equivalent attributes (having the same URI and data type) from different project areas, and flags the following conflicts in the attribute names:

  • Equivalent attributes with different names.
  • Non-equivalent attributes with the same name.

To resolve these conflicts, assign the same URI to equivalent attributes, and use different names for non-equivalent attributes.

Procedure

  1. On the banner, click the Queries menu.
    You can create a new query or browse to an existing one, and edit it.
  2. Click the value of the Project Areas field.
    A window opens with the list of all project areas that you have a read access to.
  3. From the list, add a set of project areas of your choice, and click OK.

Sharing queries in the project area

Create queries that anyone with at least read access to the project area can run.

Before you begin

You must have the Create shared queries privilege.

About this task

After you share a query, you can't make it private again. Instead, you can save a copy of it to the My Queries tab and then delete the original query from the Shared Queries tab.

Procedure

  • Create shared queries from these locations:
    • On the banner, click Queries, and in the Create Query section, click Shared Query.
    • On the Queries page, click Create Query > Shared Query.
  • Share existing personal queries from the My Queries tab, click a query name, and then on the results page, click Share.

Finding global configurations that have external contributions or local configurations

Add conditions to your query to discover global configurations that have external contributions or local configurations.

About this task

You can add query conditions to find global configurations that have external contributions or local configurations. You can also learn about how to enable Global Configuration Management servers to contribute configurations to other Global Configuration Management servers.

Suppose you are a Configuration Lead who is managing the reuse of components across multiple Global Configuration Management servers and want to review the existing usage of external contributions in a particular Global Configuration Management instance. Using these query conditions, you can find global streams that have external contributions in their hierarchy. You can also look for global baselines that don't have a local configuration as a direct child.

Note:
  • An external contribution is a global configuration from another Global Configuration Management server.
  • A local configuration is a configuration from an IBM Engineering Lifecycle Management application.

Procedure

  1. On the banner, click the Queries menu.
    You can create a new query or browse to an existing one, and edit it.
  2. On the Conditions tab, click Add Condition.
  3. Choose External Contributions or Local Configurations; then, are or are not.
    Note: The External Contributions option is only available if you enable collaborating Global Configuration Management servers. For more information, see Enabling Global Configuration Management servers to contribute configurations to other Global Configuration Management servers.
  4. Choose in the hierarchy or direct children.
    You can also add more conditions to this query.
  5. Save your changes, and click Run.

Adding a subquery as a condition

Create queries that can include another query inside it as a condition.

About this task

You can nest one query inside another query by using a Subquery condition.

The value of this condition is another query in the same project area. Whenever the main query runs, the most recent conditions of the subquery are placed inline with the conditions of the main query.

When you select the matches operator, the subquery matches the results that are specified by its conditions. When you select the does not match operator, the subquery results are negated, matching everything that does not meet conditions of the subquery. You can add a subquery condition to a group of conditions, and it works just like any other condition.

Note: The subquery results are scoped to its own Project Areas setting, regardless of the main query's Project Areas setting.

Procedure

  1. On the banner, click the Queries menu.
    You can create a new query or browse to an existing one, and edit it.
  2. On the Conditions tab, click Add Condition.
  3. Choose Subquery, then matches or does not match, and select a query from the list of available queries.
  4. Save your changes, and click Run.

Checking existence and non-existence of certain attributes in queries

Customize your query for checking the presence or absence of certain attributes in the global configurations.

About this task

By using some special operators, you can create queries that check the existence and non-existence of certain attributes in a global configuration or component.

Procedure

  1. On the banner, click the Queries menu.
    You can create a new query or browse to an existing one, and edit it.
  2. On the Conditions tab, click Add Condition.
  3. To check the presence or absence of any custom attribute, use exists or does not exist in your query.
  4. For the Tags attribute, to find global configurations that don't use a particular set of tags, use is not any of. Example: If you want to find global configurations that don't use mtm or amr as tags, select is not any of and specify these values for your Tags attribute condition.

    To check the presence or absence of Tags in the configurations, use any or none in your query.

  5. Save your changes, and click Run.

Running queries

Query results show global configurations from the selected project areas.

Procedure

You can complete one of these steps:
  • On the Welcome page, click Browse and create queries, and explore the queries on the tabs.
  • On the banner, click Queries > Browse > My Queries or Shared Queries, and select a query.
    Note: You can also search and run queries to add configurations in the configuration editor.

    In the Add Configurations dialog box, select the Global Configuration Management application and a project area. Click the menu with the search field, and choose a query type (My Queries, Shared Queries, or Favorite Queries) to list all queries. Then, select a query of your choice.

What to do next

Edit attributes and tag configurations: Select the checkbox placed with a configuration name, and click Actions > task.

Add or remove attribute columns: To make a temporary change to the results shown, click the Add or remove columns icon (Table columns) on the query results table, or right-click the column headings. You can also apply these temporary changes to the results of the query that you don’t own. You lose your choices when you leave the results page. To save your column choices, edit the query or ask the query owner to edit it. Select the Project Area result column from the list to identify the source of the matching configurations.

Add to Favorites: To add a query to your Favorites list, click the star icon that is placed with the query name.