Red Hat Customer Portal Logo
AUTOMATION CONTROLLER
v4.2.0
You can find more information in the Ansible Automation Platform documentation.
  • Automation Controller User Guide v4.2.0
  • 1. Overview
    • 1.1. Real-time Playbook Output and Exploration
    • 1.2. “Push Button” Automation
    • 1.3. Enhanced and Simplified Role-Based Access Control and Auditing
    • 1.4. Cloud & Autoscaling Flexibility
    • 1.5. The Ideal RESTful API
    • 1.6. Backup and Restore
    • 1.7. Ansible Galaxy Integration
    • 1.8. Inventory Support for OpenStack
    • 1.9. Remote Command Execution
    • 1.10. System Tracking
    • 1.11. Integrated Notifications
    • 1.12. Satellite Integration
    • 1.13. Run-time Job Customization
    • 1.14. Red Hat Insights Integration
    • 1.15. Enhanced User Interface
    • 1.16. Custom Virtual Environments
    • 1.17. Authentication Enhancements
    • 1.18. Cluster Management
    • 1.19. Container Platform Support
    • 1.20. Workflow Enhancements
    • 1.21. Job Distribution
    • 1.22. Support for deployment in a FIPS-enabled environment
    • 1.23. Limit the number of hosts per organization
    • 1.24. Inventory Plugins
    • 1.25. Secret Management System
    • 1.26. Automation Hub Integration
  • 2. Red Hat Ansible Automation Platform controller Licensing, Updates, and Support
    • 2.1. Support
    • 2.2. Trial / Evaluation
    • 2.3. Subscription Types
    • 2.4. Node Counting in Licenses
    • 2.5. Attaching Subscriptions
    • 2.6. Ansible Automation Platform Component Licenses
  • 3. Logging In
  • 4. Import a Subscription
    • 4.1. Obtaining a subscriptions manifest
    • 4.2. Adding a subscription manually
  • 5. The User Interface
    • 5.1. Activity Streams
    • 5.2. Views
    • 5.3. Resources and Access
    • 5.4. Administration Menu
    • 5.5. The Settings Menu
  • 6. Search
    • 6.1. Searching Tips
    • 6.2. Sort
  • 7. Organizations
    • 7.1. Creating a New Organization
    • 7.2. Work with Access
    • 7.3. Work with Notifications
  • 8. Users
    • 8.1. Create a User
    • 8.2. Delete a User
    • 8.3. Users - Organizations
    • 8.4. Users - Teams
    • 8.5. Users - Permissions
    • 8.6. Users - Tokens
  • 9. Teams
    • 9.1. Create a Team
  • 10. Credentials
    • 10.1. Understanding How Credentials Work
    • 10.2. Getting Started with Credentials
    • 10.3. Add a New Credential
    • 10.4. Credential Types
  • 11. Custom Credential Types
    • 11.1. Content sourcing from collections
    • 11.2. Backwards-Compatible API Considerations
    • 11.3. Getting Started with Credential Types
    • 11.4. Create a New Credential Type
  • 12. Secret Management System
    • 12.1. Configure and link secret lookups
  • 13. Applications
    • 13.1. Getting Started with Applications
    • 13.2. Create a new application
  • 14. Execution Environments
    • 14.1. Building an Execution Environment
    • 14.2. Use an execution environment in jobs
    • 14.3. Execution Environment mount options
  • 15. Execution Environment Setup Reference
    • 15.1. Execution environment definition
    • 15.2. ansible-builder build options
    • 15.3. Collection-level metadata¶
  • 16. Projects
    • 16.1. Add a new project
    • 16.2. Updating projects from source control
    • 16.3. Work with Permissions
    • 16.4. Work with Notifications
    • 16.5. Work with Job Templates
    • 16.6. Work with Schedules
    • 16.7. Ansible Galaxy Support
    • 16.8. Collections Support
  • 17. Inventories
    • 17.1. Smart Inventories
    • 17.2. Inventory Plugins
    • 17.3. Add a new inventory
    • 17.4. Running Ad Hoc Commands
  • 18. Supported Inventory Plugin Templates
    • 18.1. Amazon Web Services EC2
    • 18.2. Google Compute Engine
    • 18.3. Microsoft Azure Resource Manager
    • 18.4. VMware vCenter
    • 18.5. Red Hat Satellite 6
    • 18.6. OpenStack
    • 18.7. Red Hat Virtualization
    • 18.8. Red Hat Ansible Automation Platform
  • 19. Job Templates
    • 19.1. Create a Job Template
    • 19.2. Add Permissions
    • 19.3. Work with Notifications
    • 19.4. View Completed Jobs
    • 19.5. Scheduling
    • 19.6. Surveys
    • 19.7. Launch a Job Template
    • 19.8. Copy a Job Template
    • 19.9. Scan Job Templates
    • 19.10. Fact Caching
    • 19.11. Utilizing Cloud Credentials
    • 19.12. Provisioning Callbacks
    • 19.13. Extra Variables
  • 20. Job Slicing
    • 20.1. Job slice considerations
    • 20.2. Job slice execution behavior
    • 20.3. Search job slices
  • 21. Workflows
    • 21.1. Workflow scenarios and considerations
    • 21.2. Extra Variables
    • 21.3. Workflow States
    • 21.4. Role-Based Access Controls
  • 22. Workflow Job Templates
    • 22.1. Create a Workflow Template
    • 22.2. Work with Permissions
    • 22.3. Work with Notifications
    • 22.4. View Completed Jobs
    • 22.5. Work with Schedules
    • 22.6. Surveys
    • 22.7. Workflow Visualizer
    • 22.8. Launch a Workflow Template
    • 22.9. Copy a Workflow Template
    • 22.10. Extra Variables
  • 23. Instance Groups
    • 23.1. Create an instance group
  • 24. Jobs
    • 24.1. Inventory Sync Jobs
    • 24.2. SCM Inventory Jobs
    • 24.3. Playbook Run Jobs
    • 24.4. Automation controller Capacity Determination and Job Impact
    • 24.5. Job branch overriding
  • 25. Working with Webhooks
    • 25.1. GitHub webhook setup
    • 25.2. GitLab webhook setup
    • 25.3. Payload output
  • 26. Notifications
    • 26.1. Notification Hierarchy
    • 26.2. Workflow
    • 26.3. Create a Notification Template
    • 26.4. Notification Types
    • 26.5. Create custom notifications
    • 26.6. Enable and Disable Notifications
    • 26.7. Configure the host hostname for notifications
    • 26.8. Notifications API
  • 27. Supported Attributes for Custom Notifications
  • 28. Schedules
    • 28.1. Add a new schedule
  • 29. Setting up Insights Remediations
    • 29.1. Create Insights Credential
    • 29.2. Create an Insights Project
    • 29.3. Create Insights Inventory
    • 29.4. Remediate Insights Inventory
  • 30. Best Practices
    • 30.1. Use Source Control
    • 30.2. Ansible file and directory structure
    • 30.3. Use Dynamic Inventory Sources
    • 30.4. Variable Management for Inventory
    • 30.5. Autoscaling
    • 30.6. Larger Host Counts
    • 30.7. Continuous integration / Continuous Deployment
    • 30.8. LDAP authentication performance tips
  • 31. Security
    • 31.1. Playbook Access and Information Sharing
    • 31.2. Role-Based Access Controls
    • 31.3. Function of roles: editing and creating
  • 32. Glossary
 
Automation Controller User Guide

6. Search¶

The automation controller has a powerful search tool that provides both search and filter capabilities that span across multiple functions. Acceptable search criteria are provided in an expandable “cheat-sheet” accessible from the Advanced option from the Name drop-down menu in the search field. From there, use the combination of Set Type, Key, Lookup type to filter.

key sheet

6.1. Searching Tips¶

These searching tips assume that you are not searching hosts. Most of this section still applies to hosts but with some subtle differences. A typical syntax of a search consists a field (left-hand side) and a value (right-hand side). A colon is used to separate the field that you want to search from the value. If a search doesn’t have a colon (see example 3) it is treated as a simple string search where ?search=foobar is sent. Here are the examples of syntax used for searching:

  1. name:localhost In this example, the string before the colon represents the field that you want to search on. If that string does not match something from Fields or Related Fields then it’s treated the same way Example 3 is (string search). The string after the colon is the string that you want to search for within the name attribute.

  2. organization.name:Default This example shows a Related Field Search. The period in the left-hand portion separates the model from the field in this case. Depending on how deep/complex the search is, you could have multiple periods in that left-hand portion.

  3. foobar Simple string (key term) search that will find all instances of that term using an icontains search against the name and description fields. If a space is used between terms (e.g. foo bar), then any results that contain both terms will be returned. If the terms are wrapped in quotes (e.g. “foo bar”), the controller will search for the entire string with the terms appearing together. Specific name searches will search against the API name. For example, Management job in the user interface is system_job in the API.

  4. organization:Default This example shows a Related Field search but without specifying a field to go along with the organization. This is supported by the API and is analogous to a simple string search but done against the organization (will do an icontains search against both the name and description).

6.1.1. Values for search fields¶

To find values for certain fields, refer to the API endpoint for extensive options and their valid values. For example, if you want to search against /api/v2/jobs -> type field, you can find the values by performing an OPTIONS request to /api/v2/jobs and look for entries in the API for "type". Additionally, you can view the related searches by scrolling to the bottom of each screen. In the example for /api/v2/jobs, the related search shows:

"related_search_fields": [
   "modified_by__search",
   "project__search",
   "project_update__search",
   "credentials__search",
   "unified_job_template__search",
   "created_by__search",
   "inventory__search",
   "labels__search",
   "schedule__search",
   "webhook_credential__search",
   "job_template__search",
   "job_events__search",
   "dependent_jobs__search",
   "launch_config__search",
   "unifiedjob_ptr__search",
   "notifications__search",
   "unified_job_node__search",
   "instance_group__search",
   "hosts__search",
   "job_host_summaries__search"

The values for Fields come from the keys in a GET request. url, related, and summary_fields are not used. The values for Related Fields also come from the OPTIONS response, but from a different attribute. Related Fields is populated by taking all the values from related_search_fields and stripping off the __search from the end.

Any search that does not start with a value from Fields or a value from the Related Fields, will be treated as a generic string search. Searching for something like localhost will result in the UI sending ?search=localhost as a query parameter to the API endpoint. This is a shortcut for an icontains search on the name and description fields.

6.1.2. Searching using values from Related Fields¶

Searching a Related Field requires you to start the search string with the Related Field. This example describes how to search using values from the Related Field, organization.

The left-hand side of the search string must start with organization (ex: organization:Default). Depending on the related field, you might want to provide more specific direction for the search by providing secondary/tertiary fields. An example of this would be to specify that you want to search for all job templates that use a project matching a certain name. The syntax on this would look like: job_template.project.name:"A Project".

Note

This query would execute against the unified_job_templates endpoint which is why it starts with job_template. If we were searching against the job_templates endpoint, then you wouldn’t need the job_template portion of that query.

6.1.3. Other search considerations¶

The following are a few things about searching in the controller that you should be aware of:

  • There’s currently no supported syntax for OR queries. All search terms get AND’d in the query parameters.

  • The left-hand portion of a search parameter can be wrapped in quotes to support searching for strings with spaces.

  • Currently, the values in the Fields are direct attributes expected to be returned in a GET request. Whenever you search against one of the values, the controller essentially does an __icontains search. So, for example, name:localhost would send back ?name__icontains=localhost. The controller currently performs this search for every Field value, even id, which is not ideal.

6.2. Sort¶

Where applicable, use the arrows in each column to sort by ascending or descending order (following is an example from the schedules list).

sort arrow

The direction of the arrow indicates the sort order of the column.

Next Previous

Copyright © Red Hat, Inc.