Service Catalogs and the User Self-Service Portal

One of the most interesting features of CloudForms is the ability to define services that can include one or more virtual machines (VMs) or instances and can be deployed across hybrid environments. Services can be made available to users through a self-service portal that allows users to order predefined IT services without IT operations getting involved, thereby delivering on one of the major promises of cloud computing.

The intention of this post is to provide you with step-by-step instructions to get you started with a simple service catalog. After you have gone through the basic concepts, you should have the skills to dive deeper into more complex setups.

Getting started with Service Catalogs

Let’s set the stage for this post: You added your Amazon Web Services (AWS) account to CloudForms as a cloud provider. Your AWS account includes a Red Hat Enterprise Linux (RHEL) image ready to use. Now you want to give your users the ability to deploy RHEL instances on AWS but you want to limit or predefine most of the options they could choose when deploying these instances.

Service Basics

Four items are required to make a service available to users from the CloudForms self-service portal:

  • A Provisioning Dialog which presents the basic configuration options for a VM or instance.
  • A Service Dialog where you allow users to configure VM or instance options.
  • A Service Catalog which is used to group Services Dialogs together.
  • A Service Catalog Item (ie. the actual Service) which joins a Service Dialog with a Provisioning Dialog.

Provisioning Dialogs

To work with services in CloudForms it is important to understand the concept of Provisioning Dialogs. When you begin the process of provisioning a VM or instance via CloudForms, you are presented with a Provisioning Dialog where you set certain options for the VM or instance. The options presented are dependent on the provider you are using. For instance, a cloud provider might have “flavors” of instances, whereas an infrastructure provider might allow you to set the Memory size or number of CPUs on a VM.

Every provider in CloudForms comes with a sample provisioning dialog covering the options specific to that provider. To have a look at some sample Provisioning Dialogs, go to Automate > Customization > Provisioning Dialogs > VM Provision and select “Sample Provisioning Dialogs”. This is a textual representation of the dialog you will get when you provision a VM or instance.

For this post, we need to make sure instance provisioning to AWS is working, so go to Compute > Clouds > Instances and create a new AWS instance by choosing “Provision Instances” from the “Lifecycle” drop-down. Select the image you are going to use, click “Continue” and walk through the Provisioning Dialog.



Service Dialogs

A Service Dialog determines which options the users get to change. The choice of options that are presented to the user is up to you. You could just give them the option to set the service name, or you could have them change all of the Provisioning Dialog options. You have to create a Service Dialog to define the options users are allowed to see and set. To help with creating a Service Dialog, CloudForms includes a simple form designer.

Anatomy of a Service Dialog

A Service Dialog contains three components:

  • One or more “Tabs”
  • Inside the “Tabs”, one or more “Boxes”
  • Inside the “Boxes”, one or more “Elements”
  • The “Elements” contain methods, like check boxes, drop-down lists or text fields, to fill in the options on the Provisioning Dialog. Here is the most important part: The names of the Elements have to correspond to the options used in the Provisioning Dialog!

What are the Element Names?

Very good question. As mentioned the options and values we provide in the Service Dialog must match those used in the Provisioning Dialog. There are some rather generic names like “vm_name” or “service_name”, while others might be specific to the provider in question.

So how do you find the options and values you can pass in a Service Dialog? The easiest way is to look at the Provisioning Dialog. In this case, for our Amazon EC2 instance:

  • As an administrator, go to Automate > Customization
  • Open the “Provisioning Dialogs” accordion and locate the “VM Provision” folder
  • Find the appropriate dialog, “Sample Amazon Instance Provisioning Dialog”
  • Now you can use your browser’s search capabilities to find options and their potential values. For practice just look for e.g. “vm_name”.

Creating a Service Dialog

Enough theory, let’s dive in and create our first simple Service Dialog. The Service Dialog should let users choose a service and instance name for an AWS instance.

  • As an administrator, go to Automate > Customization
  • Open the “Service Dialogs” accordion. You will find two example Service Dialogs.
  • Add a new Service Dialog: Configuration > Add a new Dialog
  • Type “aws_single_rhel7_instance” into the Label field, this will be the name of the Service Dialog in CloudForms. Add a description if you want, this is not mandatory but good practice.
  • For Buttons, check “Submit” and “Cancel”.


From this starting point, you can now add content to the Dialog:

  • From the drop-down with the “+” sign choose “Add a new Tab to this Dialog”.


  • For Label use “instance_settings”, as Description use “Instance Settings”.
  • With the “instance_settings” Tab selected choose “Add a new Box to this Tab” from the “+” drop-down.
  • Give the new Box a Label and Description of “Instance and Service Name”.
  • From the “+” drop-down choose “Add a new Element to this Box”.
  • Fill in Label and Description with “Service Name” and Name with “service_name”.
  • For the Type, choose “Text Box” with Value Type “String”.


Following the same procedure add a second Element to the Box. The Name field should be “vm_name” and the Label and Description fields should be “Instance Name”. Similarly, Type should be “Text Box” with Value Type “String”.


That’s it! Now you can finally hit the “Add” button at the lower right corner.

Create a Catalog

Now that you have created your Service Dialog, we can add it to a Service Catalog by creating its associated Catalog Item.

First, we will create a Catalog:

  • Go to Services > Catalogs and expand the “Catalogs” accordion.
  • Select the “All Catalogs” folder and click Configuration > Add a new Catalog.
  • For Name and Description fill in “Amazon EC2”.
  • We will assign Catalog Items to this Catalog later.

Create a Catalog Item

Now we have the Catalog without any content, the Service Dialog, and the Provisioning Dialog. To allow users to order the service from the self-service catalog, we have to create a Catalog Item. Let’s create a Catalog Item to order a RHEL instance using our Service Dialog:

  • Go to Services > Catalogs and expand the “Catalog Items” accordion.
  • Select the “Amazon EC2” catalog and click Configuration > Add a new Catalog Item.
  • From the “Catalog Item Type” drop-down select “Amazon”.
  • For Name and Description use “RHEL Instance” and check the box labelled “Display in Catalog”
  • From the “Catalog” drop-down choose “Amazon EC2”
  • From the “Dialog” drop-down choose “aws_single_rhel7_instance”. This is the Service Dialog you created earlier.
  • The three fields below point to methods used when provisioning/reconfiguring or retiring the service. For now, just configure these to use built-in methods as follows:
    • Click into the “Provisioning Entry Point State Machine” field, you will be taken to the Datastore Explorer.
    • Under the “ManageIQ” subtree, navigate to the following method and hit “Apply”: “/Service/Provisioning/StateMachines/ServiceProvision_Template/CatalogItemInitialization”
    • Click into the “Retirement Entry Point State Machine” field, navigate to this method and hit apply: “/Service/Retirement/StateMachines/ServiceRetirement/Default”


  • Switch to the “Details” tab. In real life you would put a detailed description of your Service here. You could use HTML for better formatting, but for the purpose of this post “Single Amazon EC2 instance” will do.
  • Switch to the “Request Info” tab. Here you preset all of the options from the Provisioning Dialog. (Remember that the user is only allowed to set Service Name and the Instance Name options via the Service Dialog):
    • On the “Catalog” tab, set the image Name to your AWS image name (“rhel7” in this case) and the Instance Name to “changeme”


  • On the “Properties” tab set the Instance Type to “T2 Micro”. If you ever plan to access the instance you should of course select a “Guest Access Key Pair”, too.


  • On the “Customize” tab set the Root Password. And in Customize Template choose the “Basic root pass template” as a script for cloud-init.


  • Click Add at the bottom right.

As you can see your new Catalog Item is listed with a generic icon. Let’s change this by uploading an icon in the “Custom Image” section. You can pick any image you like.

Recap or “What have we done so far”?

We created a Provisioning Dialog that defines the options that can be set on a VM or instance. We created a Service Dialog which allows us to expose certain options to be set by the user. For our example, only the instance name and service name are configurable. Then we created a Service Catalog and finally a Catalog Item. The Catalog Item joins the Service Dialog with all of the options in the Provisioning Dialog. Now, users should be able to order RHEL instance from the self-service catalog.

Let’s Order a RHEL Instance

To order your new service:


  • You should now see your service. Select it and you will be taken to the form you have defined in your Service Dialog:


  • Fill in the “Service Name” and “Instance Name” fields. Recall that these are the only two options that you made available to users in your Service Dialog.
  • Click “Add to Shopping Cart” and access the “Shopping Cart” by clicking the icon on the top right (there should now be a number on it).
  • Click “Order”. You have created a new provisioning request. You can follow the request by selecting “My Requests” from the menu bar and selecting the specific request to see its progression and details.


Once the “Request State” is shown as “finished”, your AWS instance is provisioned.


As you can see, creating a basic service catalog and to use the self-service portal in CloudForms is not rocket science. Of course, there is a lot more to learn, but there are also a lot of good resources to help you on your journey. For example, articles on this blog, the official documentation, and of course the excellent “Mastering CloudForms Automation” book written by  Peter McGowan that I cannot recommend highly enough.

  1. This is awesome! You managed to summarize into few easy to understand paragraphs, something that takes a lot of time to figure out yourself…


Leave a Reply to Asaf Waizman Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s