Menu
[fibosearch]
The Tower User Interface offers a friendly graphical framework for your IT orchestration needs. The left navigation bar provides quick access to resources, such as Projects, Inventories, Job Templates, and Jobs.
Across the top-right side of the interface, you can access your user profile, the About page, view related documentation, and log out. Right below these options, you can view the activity stream for that user by clicking on the Activity Stream 
button.
Most screens in Tower have an Activity Stream () button. Clicking this brings up the Activity Stream for this object.
An Activity Stream shows all changes for a particular object. For each change, the Activity Stream shows the time of the event, the user that initiated the event, and the action. The information displayed varies depending on the type of event. Clicking on the Examine (
) button shows the event log for the change.
The Activity Stream can be filtered by the initiating user (or the system, if it was system initiated), and by any related Tower object, such as a particular credential, job template, or schedule.
The Activity Stream on the main Dashboard shows the Activity Stream for the entire Tower instance. Most pages in Tower allow viewing an activity stream filtered for that specific object.
The Tower User Interface provides several options for viewing information.
The Dashboard view begins with a summary of your hosts, inventories, and projects. Each of these is linked to the corresponding objects in Tower for easy access.
On the main Tower Dashboard screen, a summary appears listing your current Job Status. Also available for review are summaries of Recently Used Templates and Recent Job Runs.
The Job Status graph displays the number of successful and failed jobs over a specified time period. You can choose to limit the job types that are viewed, and to change the time horizon of the graph.
The Recently Used Templates section of this display shows a summary of the most recently used templates. You can also access this summary by clicking the Templates (
) icon from the left navigation bar.
The Recent Job Runs section displays which jobs were most recently run, their status, and time when they were run as well.
Note:
Clicking on the Dashboard (dashboard) icon from the left navigation bar or the Ansible Tower logo at any time returns you to the Dashboard.
Access the Jobs view by clicking the Jobs (
) icon from the left navigation bar. This view shows all the jobs that have ran in Tower, including projects, templates, management jobs, SCM updates, playbook runs, etc.
Access the Schedules view by clicking the Schedules (
) icon from the left navigation bar. This view shows all the scheduled jobs that are configured.
My View, is a user’s single-page view of jobs and job templates. It can be accessed by clicking the My View (
) icon from the left navigation bar or by navigating to https://<Tower server name>/portal.
My View is a simplified interface for users who need to run Ansible jobs, but that do not need an advanced knowledge of Ansible or Tower. My View could be used by, for instance, development teams, or even departmental users in non-technical fields.
My View offers Tower users a simplified, clean interface to the jobs that they are able to run, and the results of jobs that they have run in the past.
Pressing the 
button beside a job in My View launches it, potentially asking some survey questions if the job is configured to do so.
My View displays two main sections–Job Templates and Jobs. The Job Templates panel shows the job templates that are available to be run. To launch a job template, click the button. This launches the job, which can be viewed in the Jobs panel.
The Jobs pane shows the list of jobs that have run in the past. Sort for jobs specific to you by clicking the My Jobs button or review all jobs you have access to view by clicking the All Jobs button, above the search bar.
My Jobs: View jobs that you (as the user) ran.
All Jobs: View your team members’ completed jobs, viewable based on your RBAC permissions.
For each job, you can view and sort by any number of the job’s attributes shown. Clicking on the link for the job opens a new window with the Job Details for that job (refer to Jobs for more information).
Other portions of the interface are hidden from view until My View is exited.
The Resources and Access menus provide you access to the various components of Ansible Tower and allow you to configure who has permissions for which of those resources.
The Administration menu provides access to the various administrative options:
From here, you can create, view, and edit custom credential types, notifications, management jobs, tokens and applications, and configure Tower settings. Configuring Tower settings is accomplished through the Settings menu, which is described in further detail in the proceeding section.
Starting with Ansible Tower 3.0, the Settings (
) menu offers access to administrative configuration options. Users of older versions of Ansible Tower (2.4.5 or older) can access most of these through the top-level navigational menu or from their “Setup” menu button.
To enter the Settings window for Ansible Tower, click the Settings icon at the bottom of the left navigation bar. This page allows you to modify your Tower’s configuration, such as settings associated with authentication, jobs, system, user interface, and view or import your license.
For more information on configuring these settings, refer to Tower Configuration section of the Ansible Tower Administration Guide.
Ansible Tower 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 Key button.
Use the Clear All to clear the search criteria.
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:
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.
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.
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”), Tower 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.
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).
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.
Note:
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.
The following are a few things about searching in Tower 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, Tower essentially does an __icontains search. So, for example, name:localhost would send back ?name__icontains=localhost. Tower currently performs this search for every Field value, even id, which is not ideal.
Where applicable, use the arrows in each column to sort by ascending or descending order (following is an example from the schedules list).
The direction of the arrow indicates the sort order of the column.
An Organization is a logical collection of Users, Teams, Projects, and Inventories, and is the highest level in the Tower object hierarchy.
Access the Organizations page by clicking the Organizations (
) icon from the left navigation bar. The Organizations page displays all of the existing organizations for your installation of Tower. Organizations can be searched by Name or Description. Modify and remove organizations using the Edit and Delete buttons.
Note
Tower creates a default organization automatically. Users of Tower with a Self-Support level license only have the default organization available and should not delete it.
You can create a new organization by selecting the 
button.
An organization has several attributes that may be configured:
Enter the Name for your organization (required).
Enter a Description for the organization.
Enter an Instance Group on which to run this organization.
Select from the drop-down menu list a custom virtual Ansible Environment on which to run this organization. This field is only present if custom environments were previously created. See Using virtualenv with Ansible Tower in the Ansible Tower Upgrade and Migration Guide.
The Max Hosts is only editable by a superuser to set an upper limit on the number of license hosts that an organization can have. Setting this value to 0 signifies no limit. If you try to add a host to an organization that has reached or exceeded its cap on hosts, an error message displays:
The inventory sync output view also shows the host limit error. Click the 
icon for additional detail about the error.
Click Save to finish creating the organization.
Once created, Tower displays the Organization details, and allows for the managing of users and administrators for the organization.
Clicking on Users (beside Details when viewing your organization), displays all the Users associated with this Organization. A User is someone with access to Tower with associated roles and Credentials. Adding a user to an organization adds them as a member only, specifying a role for the user can be done in the the Permissions tab, as shown in the example below.
As you can manage the user membership for this Organization here, you can manage user membership on a per-user basis from the Users page by clicking the Users (
) icon from the left navigation bar. The user list from the Organizations view may be sorted by username. Use the Tower Search to search for users by various attributes. Click Key for using the search, or refer to the Search chapter for more information.
Clicking on a user brings up that user’s details, allowing you to review, grant, edit, and remove associated permissions for that user. For more information, refer to Users.
In order to add a user to an organization, the user must already be created in Tower. Refer to Create a User to create a user. To add existing users to the Organization:
Click the button.
Select one or more users from the list of available users by clicking the check box next to the user(s) to add them as members of the organization.
In this example, two users have been selected to be added to this organization.
Click the Save button when done.
Clicking on Permissions (beside Users when viewing your organization), allows you to easily manage the permissions for this organization.
Organizations have a unique set of roles not described here. You can assign specific users certain levels of permissions within your organization, or allow them to act as an admin for a particular resource. Refer to Role-Based Access Controls for more information.
Note
A credential with roles associated will retain them even after the credential has been reassigned to another organization.
The Permissions tab allows you to review, grant, edit, and remove associated permissions for users as well as team members. To assign permissions to a particular user for this resource:
Click the Permissions tab.
Click the button to open the Add Users/Teams window.
Specify the users or teams that will have access then assign them specific roles:
Click to select one or multiple check boxes beside the name(s) of the user(s) or team(s) to select them.
Note
You can select multiple users and teams at the same time by navigating between the Users and Teams tabs without saving.
After selections are made, the window expands to allow you to select a role from the drop-down menu list for each user or team you chose.
The example above shows options associated with inventories. Different resources have different options available:
Admin allows read, run, and edit privileges (applies to all resources)
Use allows use of a resource in a job template (applies all resources except job templates)
Update allows updating of project via the SCM Update (applies to projects and inventories)
Ad Hoc allows use of Ad Hoc commands (applies to inventories)
Execute allows launching of a job template (applies to job templates)
Read allows view-only access (applies to all resources)
Tip
Use the Key button in the roles selection pane to display a description of each of the roles. For more information, refer to the Roles section of this guide.
Select the role to apply to the selected user or team.
Note
You can assign roles to multiple users and teams by navigating between the Users and Teams tabs without saving.
Review your role assignments for each user and team.
Click Save when done, and the Add Users/Teams window closes to display the updated roles assigned for each user and team.
To remove Permissions for a particular user, click the Disassociate (x) button next to its resource.
This launches a confirmation dialog, asking you to confirm the disassociation.
Clicking the Notifications tab allows you to review any notification integrations you have setup.
Use the toggles to enable or disable the notifications to use with your particular organization. For more detail, see Enable and Disable Notifications.
If no notifications have been set up, click the NOTIFICATIONS link from above or inside the gray box to add or create a new notification.
Refer to Notification Types for additional details on configuring various notification types.
An at-a-glance view of various resources associated with an organization displays at the bottom of each Organization view, called the Organization Summary.
Click on each of the categories to view a list of resources associated with them. Some allow resources to be added, edited, or deleted, such as Users and Admins, while others require editing from another area of the user interface.
From the summary, you can edit the details of an organization (
) or delete it altogether (
).
Note
If deleting items that are used by other work items, a message opens listing the items are affected by the deletion and prompts you to confirm the deletion. Some screens will contain items that are invalid or previously deleted, so they will fail to run. Below is an example of such a message:
A User is someone who has access to Tower with associated permissions and credentials. Access the Users page by clicking the Users () icon from the left navigation bar. The Users page allows you to manage all Tower users. The User list may be sorted and searched by Username, First Name, or Last Name and click the headers to toggle your sorting preference.
To create a new user:
Click the button, which opens the Create User dialog.
Enter the appropriate details into the following required fields:
First Name
Last Name
Organization (Choose from an existing organization–this is the default organization if you are using a Self-Supported level license.)
Username
Password
Confirmation Password
User Type
Note
When modifying your own password, log out and log back in again in order for it to take effect.
Three types of Tower Users can be assigned:
Normal User: Normal Users have read and write access limited to the resources (such as inventory, projects, and job templates) for which that user has been granted the appropriate roles and privileges.
System Auditor: Auditors implicitly inherit the read-only capability for all objects within the Tower environment.
System Administrator: A Tower System Administrator (also known as Superuser) has full system administration privileges for Tower – with full read and write privileges over the entire Tower installation. A System Administrator is typically responsible for managing all aspects of Tower and delegating responsibilities for day-to-day work to various Users. Assign with caution!
Note
The initial user (usually “admin”) created by the Tower installation process is a Superuser. One Superuser must always exist. To delete the “admin” user account, you must first create another Superuser account.
Select Save when finished.
Once the user is successfully created, the User dialog opens for that newly created User.
The count for the number of users has also been updated, and a new entry for the new user is added to the list of users below the edit form. The same window opens whether you click on the user’s name, or the Edit () button beside the user. Here, the User’s Organizations, Teams, and Permissions, as well as other user membership details, may be reviewed and modified.
Note
If the user is not a newly-created user, the user’s edit screen displays the last login activity of that user. This information persists at the top of the screen regardless of which tab you’re viewing.
When you log in as yourself, and view the details of your own user profile, you can manage tokens from your user profile. See Users – Tokens for more detail.
Once a user has been created, you can easily view permissions and user type information by looking beside their user name in the User overview screen.
If the user account is associated with an enterprise-level authentication method (such as SAML, RADIUS, or LDAP), the user type may look like:
If the user account is associated with a social authentication method, the user type will look like:
This displays the list of organizations of which that user is a member. This list may be searched by Organization Name or Description. Organization membership cannot be modified from this display panel.
This displays the list of teams of which that user is a member. This list may be searched by Team Name or Description. Team membership cannot be modified from this display panel. For more information, refer to Teams.
Until a Team has been created and the user has been assigned to that team, the assigned Teams Details for the User appears blank.
The set of Permissions assigned to this user (role-based access controls) that provide the ability to read, modify, and administer projects, inventories, job templates, and other Tower elements are Privileges.
Note
It is important to note that the job template administrator may not have access to any inventory, project, or credentials associated with the template. Without access to these, certain fields in the job template aren’t editable.
This screen displays a list of the roles that are currently assigned to the selected User and can be sorted and searched by Name, Type, or Role.
To add permissions to a particular user:
Click the button, which opens the Add Permissions Wizard.
Click to select the Tower object for which the user will have access:
Job Templates. This is the default tab displayed in the Add Permissions Wizard.
Workflow Templates
Projects
Inventories
Credentials
Organizations
Note
You can assign different roles to different resources all at once to avoid having to click the button. To do so, simply go from one tab to another after making your selections without saving.
Perform the following steps to assign the user specific roles for each type of resource:
In the desired tab, click the checkbox beside the name of the resource to select it.
The dialog expands to allow you to select the role for the resource you chose.
Select the role from the drop-down menu list provided. Only some roles are applicable to certain resources.
Tip
Use the Key button to display the help text for each of the roles applicable to the resource selected.
Review your role assignments for each of the Tower objects by clicking on their respective buttons in the expanded section 2 of the Add Permissions Wizard.
Click Save when done, and the Add Permissions Wizard closes to display the updated profile for the user with the roles assigned for each selected resource.
To remove Permissions for a particular User, click the Disassociate (
) button under Actions. This launches a Remove Role dialog, asking you to confirm the disassociation.
Note
You can also add teams, individual, or multiple users and assign them permissions at the object level (projects, inventories, job templates, and workflow templates) as well. This feature reduces the time for an organization to onboard many users at one time.
The Tokens tab will only be present for your user (yourself). Before you add a token for your user, you may want to create an application if you want to associate your token to it. You may also create a personal access token (PAT) without associating it with any application. To create a token for your user:
If not already selected, click on your user from the Users list view to configure your OAuth 2 tokens.
Click the Tokens tab from your user’s profile.
When no tokens are present, the Tokens screen prompts you to add them:
Click the button, which opens the Create Token window.
Enter the following details in Create Token window:
Application: enter the name of the application with which you want to associate your token. Alternatively, you can search for it by clicking the
button. This opens a separate window that allows you to choose from the available options. Use the Search bar to filter by name if the list is extensive. Leave this field blank if you want to create a Personal Access Token (PAT) that is not linked to any application.
Description: optionally provide a short description for your token.
Scope (required): specify the level of access you want this token to have.
When done, click Save or Cancel to abandon your changes.
After the token is saved, the newly created token for the user displays with the token information and when it expires.
Note
This is the only time the token value and associated refresh token value will ever be shown.
In the user’s profile, the application for which it is assigned to and its expiration displays in the token list view.
PCC-IT International, Division of Power Capital Management, Inc. © 2024 All rights reserved.
