Getting started with Automation Services Catalog
Initial configurations and workflows
Abstract
Chapter 1. About Automation Services Catalog
Automation Services Catalog is a service within the Red Hat Ansible Automation Platform. Automation Services Catalog allows customers to organize and govern product catalog sources on Ansible Tower across various environments.
Using Automation Services Catalog you can:
- Apply multi-level approval to individual platform inventories
- Organize content in the form of products from your platforms into portfolios
- Choose portfolios to share with specific groups of users
- Set boundaries around values driving execution of user requests
Chapter 2. Getting started with Automation Services Catalog
This guide provides instructions to begin using Automation Services Catalog, including prerequisites and procedures for connecting your Ansible Tower provider, as well as configuring users and permissions. We also provide instructions for working with platforms, portfolios, and products.
After completing the setup described and following the steps in this guide, you will have a portfolio of products, governed by an approval process, accessible to users.
Entitlements
To begin using Automation Service Catalog, you need:
At least one Red Hat account user with Organization Administrator entitlements. The account number for this Red Hat corporate account.
Chapter 3. User access for Automation Services Catalog
When configuring Automation Services Catalog for your organization, consider the scope of your user environments, how those users are grouped, and the roles to assign. You can manage this workflow through User Access.
Automation Services Catalog features and workflows are governed by groups that have specific roles attached to them. The Organization Administrator role performs the initial creation of groups, assigns roles, and adds users.
Groups
Groups are user-defined and flexible to include many users and have multiple roles. Create new groups based on your organization’s requirements for working with Automation Services Catalog.
Roles
Roles provide a defined set of actions each group performs. Determine the required level of access for your users based on the following roles Automation Services Catalog uses:
Table 3.1. Role Reference Table
| Role | Description | |
|---|---|---|
| Administration | Organization Administrator |
|
| Approval | Approval Administrator |
|
| Approval Approver |
| |
| Approval User |
| |
| Catalog | Catalog Administrator |
|
| Catalog User |
|
By default, all users will have Catalog User and Approval User roles assigned to them.
Due of potential security implications, limit the number of users in cloud.redhat.com with Organization Administrator privileges.
3.1. Creating administrator groups
The Organization Administrator can create new groups of administrators and users in Automation Services Catalog. Catalog and Approval administrators are required to perform initial workflows in configuring Automation Services Catalog. In this section, we will create groups for both Catalog and Approval administrators.
3.1.1. Creating a Catalog Administrator group
The Catalog Administrator is a role that grants create, read, update and order permissions. This role is used in creating and managing processes associated with portfolios and products.
To create a Catalog Administrator group:
- Navigate to Settings ➔ User Access.
- Click Create group.
- Enter group name and set the description.
- Click Next.
- In the Add members modal, check each user to add to the group. Click Next when finished.
- Check Catalog Administrator on the Assign roles modal.
- Review details for the new group and click Confirm.
We have created a group of Catalog Administrators and will now create a group of Approval administrators.
3.1.2. Creating an Approval Administrator group
The Approval Administrator is a role that grants create, read, update and order permissions. This role is used in creating and managing processes associated with portfolios and products.
To create an Approval Administrator group:
- Navigate to Settings ➔ User Access.
- Click Create group.
- Enter group name and set the description.
- Click Next.
- In the Add members modal, check each user to add to the group. Click Next when finished.
- Check Approval Administrator on the Assign roles modal.
- Review details for the new group and click Confirm.
The new group of Approval Administrators has been created. Approval Administrators can create new approval processes to set to platforms, portfolios, and products.
3.1.3. Creating Approval Approver Groups
The Approval Approver is a role that grants create and read permissions to users who will approve or deny requests generated when a Automation Services Catalog user orders a product.
To create an Approval Approver group:
- Navigate to Settings ➔ User Access.
- Click Create group.
- Enter group name and set the description.
- Click Next.
- In the Add members modal, check each user to add to the group. Click Next when finished.
- Check Approval Approvers on the Assign roles modal.
- Review details for the new group and click Confirm.
The new group of Approval Approvers has been created..
3.1.4. Adding new users to existing Groups
The Catalog Administrator can add new users to existing groups. Once added, users will have the level of permissions associated with that group.
You can add users to a group in the Groups view in User Access.
- Navigate to Settings ➔ User Access.
- Click Groups.
- Select a group from the list.
- Click Members and then click Add Member.
- Check those users that appear in the modal that you wish to add to the group.
- Click Add to group.
A message will appear notifying you if the member was added successfully.
Chapter 4. Configuring Approval
Automation Services Catalog supports group-based approval processes applied to portfolios, products, and platform inventories, providing the flexibility to include selected organizational groups in approving requests utilizing the Approval service.
Approval administrators can create approval groups and processes, view request details, approve or deny requests, and monitor the status of existing requests.
4.1. Approval requests
Approval requests are created when a user orders a product that has an approval policy attached to it. The order will initiate the approval processes assigned to the product and users designated as approvers in each approval process receive an email notifying them that a request is ready.
Users logging in to Catalog can access approval requests via the following tabs:
- My requests - Requests that the user can approve based on their group permissions.
- All requests - All requests across all approver groups.
- Approval processes - List of approval processes that can be configured by the Approval Administrator. Accessible by the Approval Administrator only.
4.2. Approval processes
Approval processes consist of one or many groups required to approve a request. Each group is notified through the email address associated with that user when requests are created that require approval.
Approval administrators can design approval processes for a product to execute in serial or parallel when set to a portfolio. Simple serial and parallel approval processes are described below:
Set approval processes at the platform, portfolio, or product level. Approval processes set to a platform will apply to all products originating from that platform.
- Serial process - a product has multiple approval processes that must execute in a hierarchical sequence. If two approval processes are assigned to a product in serial, the approval group in the first approval process must approve the request before notification is sent to the second approval group. Priority of approval process execution is based on its position on the approval process list view. Approval processes at the top of the list will execute before the processes below it.
- Parallel process - a product has one approval process containing multiple groups. All groups are notified simultaneously when a request is created and the order is not granted until all groups approve it. Any group that declines the request ends the process and the user is notified the order has been denied.
To create and list groups when creating Approval processes, the Approval Administrator must also have Organization Administrator privileges.
4.2.1. Creating an approval process
Creating an approval process designates specific groups required to approve product orders placed by Automation Services Catalog users.
You can create an approval process from the Approval processes list view.
- Select Approval from the main navigation.
- Select the Approval processes tab.
- Click Create.
- Provide an approval process name and description.
- Select a group from the Set groups drop-down menu. You may set multiple groups for approval.
- Click Submit when finished.
Implement an approval process against a platform, portfolio, or product.
4.3. Approval process sequences
Each approval process is assigned a sequence ID that determines the priority in which it executes when included in a serial approval process set to a portfolio. An approval process with the sequence ID of 1 will execute and notify groups in that approval process of a new request before a process with a sequence ID greater than 1.
4.3.1. Editing an approval process sequence
You can edit the sequence number for an approval process from the Approval process list view.
- Select Approval from the main navigation.
- Click the Approval processes tab.
-
Navigate to the approval process, then click
.
- Click Edit.
- Enter the desired sequence number under Enter sequence.
- Click Save.
The approval process list view will update to reflect the newly sequence.
4.4. Automatic approval
You can designate products to approve automatically by not setting an approval process at the following levels:
- the inventory hosting the product
- the portfolio containing it
- the product itself
Products without an approval process at any of these levels will approve upon order creation.
Chapter 5. Working with platforms, portfolios, and products
This section demonstrates the basic workflows for platforms, portfolios, and products to get started using Automation Services Catalog
We will demonstrate how to:
- connect to a source platform
- create portfolios
- add products from the source platform into the portfolio
- set approval processes for the portfolio
- share the portfolio with users
5.1. Adding sources
Sources are the platforms Automation Services Catalog connects to in order to collect inventory information used to organize and present products available to users. To use Automation Services Catalog, you need to connect the application to at least one source.
5.2. Adding Ansible Tower as a source platform
Connect an Ansible Tower instance to Automation Services Catalog to create products from its inventory of playbooks and workflows your users can view and order from.
To begin, we will add an Ansible Tower instance as a source of products.
Part I. Adding Ansible Tower as a Source platform
Connect an Ansible Tower instance to Automation Services Catalog to create products from its inventory of playbooks and workflows your users can view and order from. To add an Ansible Towersource:
- Click menu:Settings.
- Select Sources
- Click Add source.
- Enter the source Name and click Next.
- Select Catalog from the available applications.
- Select Ansible Tower as the source type.
- Enter user name and Secret Key credentials.
- Provide the Ansible Tower endpoint URL
(Optional) Toggle the switch to verify the endpoint SSL certificate.
- Enter the SSL certificate in the Certificate Authority field.
- Click Next.
- Review your Ansible Tower source details.
- Click Finish to add your source.
After connecting your Ansible Tower instance, navigate back to Catalog to review templates available on that platform, and add those products to your portfolios.
1. Creating a portfolio and adding products to it
Now that we have a source for products, we can proceed to create an example portfolio and add a few products from our Ansible Tower to it.
Part II. Creating a portfolio and adding products to it
To create a portfolio:
- Click Create portfolio.
- Provide a New Portfolio Name and Description.
- Choose an Approval workflow from the drop-down list.
- Click Save.
Our initial portfolio is empty, and we can start adding products from this empty state.
Procedure
- Click in the Filter by Platform field to view connected platforms.
- Select a platform. The screen will populate with products from that platform.
- Check each product to add to the portfolio.
- Click Add.
1. Setting approval processes for the portfolio
We have now created a portfolio and added some products to it. Our next step is to set the approval process for the portfolio. Setting the approval process for our portfolio ensure that specific groups are designated to approve any orders placed by a user.
Part III. Setting approval processes for the portfolio
Procedure
- Navigate to Portfolios.
-
Click
on a portfolio tile and select Set approval.
- From the Set approval process drop-down menu, select an approval processes to set to the portfolio.
- Click Save.
1. Sharing the portfolio with users
The portfolio is now ready to share with groups of users. These designated user groups can order products collected in the portfolio, and their orders are approved or denied using the approval process set for the portfolio.
To share a portfolio:
- Click Portfolios.
-
Click
on a portfolio, then click Share. The icon:[Y] indicates a shared portfolio.
Adding groups:
- Under Invite group search groups to share the portfolio with.
- Select the level of permissions using the drop-down list.
Edit sharing settings for existing groups:
- Under Groups with access adjust permissions using the drop-down for each group.
- To stop sharing a portfolio with a group, click icon:[X].
- Click Send when finished.
Our portfolio is now accessible to the groups of users, who can order the products we collected in it. We can now duplicate this portfolio, change its name and add new products, to share with different user groups.
Chapter 6. Copying existing portfolios to edit and share with new groups
Copying portfolios allows you to quickly duplicate an already organized portfolio to offer to different groups of users. Once a copy is created, you can add or remove products, share with new groups, and apply new approval processes to meet organizational requirements.
We can also copy products from various portfolios to additional portfolios.
Chapter 7. Copying products to different portfolios
You can copy products from one portfolio to another as part of developing new portfolios to meet group needs. Once a product is copied you can edit its basic fields, update its survey, and apply different approval processes.
7.1. Workflows summary
The workflows in this section of the guide demonstrated how to perform the basic actions for platforms, portfolios and products necessary to get started using Automation Services Catalog:
- add entitlements to access Automation Service Catalog;
- create the necessary groups and users;
- connect to a source platform;
- create portfolios;
- add products from the source platform into the portfolio;
- set approval processes for the portfolio;
- share the portfolio with users;
- make a copy of our existing portfolio to share with different users;
- copy products from one portfolio to another.
In the next section, we will describe working with the survey editor, and provide an overview of working with requests and orders.
Chapter 8. Using the survey editor
When ordering a product in Automation Services Catalog, users may be required to provide additional information to complete the request. This prompt is created by a survey associated with the product. Initially created and edited in Ansible Tower, Catalog Administrators and portfolio users with update permissions can edit the survey in Automation Services Catalog. Once submitted and validated, the surveys pass user-submitted extra variables to the job or workflow template run on Ansible Tower on the execution of an order.
See Surveys in the Ansible Tower User Guide to learn more creating and editing surveys for job templates.
Using the survey properties editor, you can:
- Set labels, helper text or placeholders to enhance the user experience of users providing information
- Further restrict existing validation parameters.
- Change validation messages.
- Hide, disable or set to read-only chosen fields in the survey.
8.1. Survey properties editor
Values for surveys are defined in Ansible Tower and the Automation Services Catalog properties editor allows Catalog Administrators to restrict survey options, such as adjusting default values and removing items from drop-down menus.
Additionally, use the properties editor to hide, disable, or set a field to read only.
Provide an initial value for any required field set to Hidden or Disabled. This includes read only fields.
8.2. Editing surveys
You can edit fields in the surveys from the product detail view. Edit each field individually using the Properties editor.
Prerequisites
The product has an associated survey, created in Ansible Tower.
Procedure
- Click Products.
- Locate the product and click on its title.
-
Click
and select Edit survey.
- Select a field in the survey. The Properties editor will appear.
- Click Properties to view the elements to edit for that field.
- Select Validation to configure the validator types used to validate user input.
- Click Save when finished.
Chapter 9. Managing orders
Orders are created once a user successfully submits the request and provides any required validation. The approval process then governs the user’s order status.
9.1. Approving or denying requests
Once a user places an order it is created and available for review on the orders page. Groups assigned the Approval Approver role can then approve or deny orders. Detailed information is provided for each request, with information on the ordered product and its associated requester and project. A stage transcript is also provided. Denied requests require justification and the approver must enter a reason.
To approve or deny a request:
- Navigate to Approval.
- Click the Requests tab and then click on a request to expand it to detailed view.
- Click Approve or Deny. Provide a Reason when denying a request.
- Click Submit.
9.2. Commenting on requests
Comment on requests as an administrator or approver. Comments are captured by the system and visible at each stage of approval.
To comment on a request:
- Navigate to Approval.
- Click the Requests tab and then click on a request..
- Click Comment.
- Add a comment and click Submit.
Chapter 10. Conclusion
In the previous sections of this guide we walked through the primary workflows necessary to get started using Automation Services Catalog.
Following these workflows you have:
- Created the necessary groups and users to use both Catalog and Approval through the User access,
- Connected to a source platform,
- Created portfolios,
- Added products from the source platform into the portfolio,
- Created and set approval processes for the portfolio,
- Shared the portfolio with users,
- Approved or denied orders created by users,
- and comment on orders where necessary.
