Order Form Customization

CloudBolt admins design the order form to accomodate factors like departmental policies, technical proficiency of users, physical resources available, and business rules.

The choices available are determined from a combination of the group and target environment. The order process always begins with the selection of a group. Then, for each server being added to this order, users select the target environment, if it has not been preselected. This results in an order form that combines group-specific customizations with environment-specific customizations.

Groups may also inherit parameters. Parameters, options, and constraints can be managed for orders on subgroups through a parent group. More information can be found below.

Below is an example of ordering a custom server, accessed with the New Server link. It shows the parameters and options determined by the group and environment. Admins can customize the sequence of these form fields in Admin > Parameter Display Sequence.

_images/order-custom-server.png

Parameters

Parameters pass along additional data like text, numbers, and dates with an order. Parameters may be:

  • Limited to a set of options
  • Constrained by minimum, maximum, regex match, depending on type
  • Unconstrained, allowing requesters to enter an arbitrary value
  • Given a Global Default value
  • Required or optional
  • Set to show on servers where they’ve been explicitly made available or to always be available to show on all servers.
  • Configured to show as an attribute on the main overview or details tab for a resource or server that they are associated with.
  • Set to allow multiple values to be selected at once, instead of choosing a single option.

These parameters are added to specific groups and environments, where they have options, constraints, and other values configured.

CloudBolt admins can manage all parameters Admin > Parameters.

Subgroup Inheritance of Parameters

The hierarchical structure of groups in CloudBolt includes the inheritance of parameters among subgroups. This allows for easy management of orders across groups.

This feature may be disabled globally from Miscellaneous Settings > Inherit Group Parameters

For example, given the following group structure:

_images/heirarchical-groups.png

Groups inherit parameters from parent groups.

If we set the ‘CPUs’ parameter on group A, then groups B, C, and D will inherit that parameter. The CPUs parameter, with any options and constraints that were set on A, would show up on orders for group A and all of its subgroups.

Subgroups may add and override their parent’s parameters.

For example, if we also set the ‘CPUs’ parameter on group B with options, although it already exists on its parent, group A, orders for group B would use that value.

Parameters are always inherited from the nearest ancestor.

So once we’ve overridden ‘CPUs’ on group B, then orders from groups C and D will show the options and/or constraints from group B.

You can always view inherited parameters from a subgroup’s Parameters tab.

Example 1: Limit VM memory size to specific options

In the Acme group, the Mem Size parameter value may be limited to a list of options like 512MB, 1 GB, 2 GB, 4 GB.

  1. Click Groups in the Nav Bar
  2. Select the group.
  3. Click the Parameters tab.
  4. Click Add.
  5. Select Mem Size (Decimal).
  6. Click Add.
  7. Click on the pencil icon in that row’s Options column to add options
  8. This brings up the options dialog to enter values in gigabytes that equate to the desired options.

The order form now shows a dropdown control for memory size, instead of the original type-in text field.

Note

When selecting a parameter to add to an environment, any parameters that are already in use in a preconfiguration will not be presented as options.

Example 2: Adding an expiration date input to an environment

The San Jose QA Lab environment’s order form may need to include a required Expiration Date parameter. This is a special parameter that is used by CloudBolt to remind users about decommissioning their resources in a timely fashion.

  1. Select Environments in the Nav Bar and choose the San Jose QA Lab.
  2. Click on the Parameters tab.
  3. Click Add.
  4. Select Expiration Date (Date & Time) from the global list of parameters.
  5. Click Add.

Parameter Options

Parameters may be limited to a static set of options on the group, environment, blueprint for Blueprint-level Parameters, or globally. The options for a parameter may also be generated by a Generated Parameter Options action (see Orchestration Actions).

In the context of Blueprint-level Parameters, those options take precedence. Next comes group and environment. If both have options defined for a parameter, CloudBolt will combine (take the union of) all of the options on the group and environment. For a parameter with generated options, those will be used unless there are also limited options configured on the blueprint or group/ environment, in which case the overall options will be the intersection of the generated options and the other ones. When there are no options found by the process above, CloudBolt will use global options that are defined for the parameter. If none of these are set, the user will be presented with a free-form entry field (confined within any constraints, as described below).

Sometimes, the process for determining options will decide that there is only one option available for a parameter in that context. In that case, the parameter will be considered to have its value provided and will not be shown on the order form. Note that parameters that are not marked as being required will never have just a single option, due to the inclusion of a blank/ none option.

Parameter Constraints

Constraints consist of minimum, maximum, and/or regex match, depending on parameter type. Global constraints are set in Admin > Parameters. Group and environment constraints can be configured from the Parameters tab of the group or environment.

The order of precedence CloudBolt uses to determine which constraints apply goes from global (lowest precedence) to group to environment (highest precedence).

As an example, imagine the Expiration Date is constrained to a maximum of 7 days globally, 5 days in the Acme group, and 14 days for the San Jose QA Lab environment. When ordering a server in neither the Acme group nor the San Jose QA Lab environment, users will not be allowed to enter an Expiration Date more than 7 days in the future. If ordering in the Acme group and an environment with no constraint for this parameter, the Expiration Date must not be more than 5 days away. For a server in the San Jose QA Lab environment, regardless of group, the limit for an Expiration Date in the order dialog will be 14 days in the future. Note that these constraints apply to ordering blueprints and setting parameter values on servers in the same manner.

When a maximum is set on an integer or decimal parameter, it will be rendered in forms as a slider, instead of a text field. If a minimum is not specified, a default minimum of 1 will be used for required parameters, and a default minimum of 0 will be used for non-required parameters.

Parameter Dependencies

Dependencies may be set up between parameters so that when a user enters a specific value in one input field, another will appear dynamically. For example, the order form could have an option for ‘Service Level’, with ‘Gold’, ‘Silver’, and ‘Bronze’ options. When ‘Gold’ is selected, additional options could be made to appear for ‘Enable Monitoring’, ‘Enable Backups’. If they check the ‘Enable Backups’ checkbox, another option could appear to ask how many days they would like to retain the backups. To get started, navigate to a Admin > Parameters and choose a parameter that you want to make dependent on another. From there, you can create and manage a dependency.

Controlling parameters can be of any type other than dates or code, and dependent parameters can be of any type. One controlling parameter can have multiple dependent parameters. Ex. checking one checkbox could cause multiple additional fields to appear.

Show/Hide Parameter Dependencies

Parameters can be configured to only show when a specific value is entered for another parameter. You can set this up from the Dependencies section of a parameter details page, by adding a controlling parameter with a ‘show/hide’ dependency type. You can then specify whether you want the parameter to show based on a specific value or have it show when any value is entered.

OS Family Parameter Dependencies

Parameters can also be configured to be dependent on OS Families, so they will only show up on the order form when an OS Build of a particular OS Family is chosen (ex. only show the ‘Windows Firewall’ parameter when a Windows OS Build is chosen).

Regenerate Options Parameter Dependencies

A parameter can be configured such that options that show up in one parameter depend on the value selected for another parameter.

For example, the options available for Miscrosoft Azure availability sets depend on which resource group you are ordering with. Thus, these two parameters come out of the box with a regenerated parameter options dependency relationship, so that when you select a resource group on the order form, the options for availability sets regenerate based on what is available for that resource group. In this case, we would call ‘resource group’ the ‘controlling’ field, and ‘availability set’ the ‘dependent’ field.

Setting up a regenerated parameter options dependency requires a few steps:

  1. Create two parameters: a controlling and a dependent field.

2. Set up the dependency relationship: On the parameter detail page for the dependent field, add a dependency to the controlling field. To do so, go to the Dependencies section in the bottom right of the detail page. Click the pencil next to the line stating This parameter is not dependent on any other parameters. A dialog will pop up with a form, where you may select the controlling field and ‘Regenerate Options’ for the dependency type.

3. Set up a Generated Parameter Options Orchestration Action: From the Admin > Orchestration Actions page, scroll to Generated Parameter Options section and click Add an Action. Select ‘CloudBolt plug-in’ for the action type, and add a new CloudBolt plug-in.

4. Associate the base action with the dependent field: From the action details page, click the Edit button, and under Custom Fields, select the dependent field.

5. Write your plugin.: The plugin must define the get_options_list function and accept some keyword arguments, including field and control_value or control_values. The options returned must be a list of tuples, and they can either be returned directly or in a dictionary under the ‘options’ key. See some examples below.

Examples

1. A Simple Case: A regenerated options parameter dependency where you can select one value for the control field and one for the dependent field.

def get_options_list(field, control_value=None, **kwargs):
    """
    A plug-in for regenerating 'Species' options based on the value of the controlling field 'Genus'
    """
    options = []

    if control_value == 'Acer':
        options = [
            ('rubrum', 'rubrum'),
            ('saccharinum', 'saccharinum'),
            ('macrophyllum', 'macrophyllum')
        ]
    elif control_value == 'Sequoia':
        options = [
            ('magnifica', 'magnifica'),
            ('langsdorfii', 'langsdorfii'),
            ('giganteum', 'giganteum')
        ]
    return {
        'options': options,
        'override': True
    }

2. Using Multiple Choice Fields: A regenerated parameter options dependency where you’ve set ‘allow_multiple’ to True on the control field. In this case, you’d need to use the control_values kwarg to accept a list of values from the controlling field.

def get_options_list(field, control_values=[], **kwargs):
   """
   A plug-in for building a list of options for 'Plants'
   based on the values selected for the controlling field 'Plant Type'
   """
   options = []

   if 'Trees' in control_values:
      options.extend([
         ('red_maple', 'Red Maple'),
         ('coastal_redwood', 'Coastal Redwood'),
         ('douglas_fir', 'Douglas Fir'),
         ])

   if 'Shrubs' in control_values:
      options.extend([
         ('red_twig_dogwood', 'Red Twig Dogwood'),
         ('wild_lilac', 'Wild Lilac'),
         ('summersweet', 'Summersweet'),
      ])

   return options

Preconfigurations

Preconfigurations are pre-defined sets of order options offered to end users to simplify the ordering process

For example, you can create a preconfiguration called Server Size with options small, medium, and large to define particular combinations of memory size, CPUs, and disk size values.

The following example shows how to create this type of preconfiguration:

  1. Click Admin.
  2. Click the link Preconfigurations.
  3. Click New preconfiguration.
  4. In the dialog, enter label “Server Size”.
  5. Select the individual parameters to be bundled; e.g., Mem Size, CPUs, Disk Size, and leave the OS build and application checkboxes unchecked.
  6. Click Save.
  7. A new row for “Server Size” is added to the table. Add options by clicking on the pencil icon in the Options column.
  8. Add an option called “Small”.
  9. Set Mem Size to .5 GB, CPU to 1, and Disk Size to 10.
  10. Repeat steps 8–9 for “Medium” and “Large”.
  11. Click Save and confirm your new options by hovering over them in the preconfigurations table.

Another useful preconfiguration is bundling specific combinations of operating system and applications. This allows users to easily provision services such as database, web, or mail.

  1. Create a preconfiguration called “Server type”, checking both the Include OS build and Include applications checkboxes. Leave the parameters unselected.
  2. Click Save.
  3. In the Options column of this new preconfiguration, click on the pencil icon to add options.
  4. Add an option called Database, select RHEL 6.2 for OS build and Oracle 11g for application.

Parameter Templates

Some parameters support coded templates, which allow the administrator or user to programatically determine the value of the parameter.

For example, Hostname can be dynamically set for each new server without asking the user for details. It could be based on the user’s name ({{ server.owner}}) and an auto-incrementing ID number (-00X) so that the server’s name is guaranteed to be unique and identifying to that user.

These sections describe parameter templates for each field that supports them:

CloudBolt’s template format

Instead of inventing a new template format, CloudBolt uses Django’s simple yet powerful template format. It is also well-documented and you can use these resources:


Annotations Specification

Annotations (or server Notes) can be chosen for new servers in three ways:

  1. The user can enter Annotations manually when ordering a new server.
  2. The administrator can constrain Annotations to values determined by a Parameter Template.
  3. A pre-create resource orchestration action can be provided to run code to determine the hostname.

#1 is CloudBolt’s default behavior. #3 is covered in the section on CloudBolt Plug-ins. The remainder of this section will explore #2, using Parameter Templates for Annotations.

Annotations are supported on VMware with the native Notes on servers, and on AWS with a custom Tag called Annotations. Annotations are synchronized back to the server after creation.

Using Annotation Templates

The Annotations parameter provides a way to specify how annotations should be generated for new servers. Using an annotation parameter template allows dynamic generation of annotations based on attributes of the order. These generated annotations can be based on parameters of the server, portal, job, and owner. For example, the annotation could be based on the order and job ID, as well as a link back to CloudBolt to view the server there.

Specific context variables available within annotation templates

  • server - the server that was ordered
  • portal - the CloudBolt portal through which the server was ordered (for example, portal.site_url gets the URL of CloudBolt)
  • job - the job in which the server was ordered
  • order - the order in which the job provisioned the server

Annotation Template Examples

  • {{ server.owner }} - expands to the name (or username) of the creator
  • {{ portal.site_url }} - expands to the CloudBolt portal URL
  • {{ server.add_date|date:”SHORT_DATE_FORMAT” }} - expands to the date the server was added, formatted nicely
  • {{ job.id }} - expands to the Job ID in which the server was ordered
  • {{ order.id }} - expands to the Order ID in which the server was ordered

Hostname Specification

There are four main ways in which hostnames can be chosen for new servers:

  1. The user can enter a hostname manually when ordering a new server.
  2. A resource pool of hostnames can be associated with the environment.
  3. A Hostname Template can be specified.
  4. A pre-create resource orchestration action can be provided to run code to determine the hostname.

#1 is CloudBolt’s default behavior. #2 can be set up from the Admin section of the UI. #4 is covered in the section on CloudBolt Plug-ins. The remainder of this section will explore #3, using Hostname Templates.

Using Hostname Templates

The Hostname Template parameter provides a way to specify how hostnames should be generated for new servers. Rather than having a set of static hostname pools, using a hostname template allows dynamic generation of hostnames based on attributes of the order. These generated hostnames can be based on parameters on the group, environment, and on the order form itself. For example, the hostname could be based on a group code, an environment code, location code, and a user-provided purpose (ex. ‘web’).

Specific context variables available within hostname templates

  • environment - the environment chosen in the order form
  • group - the group chosen in the order form
  • os_build - the OS build chosen in the order form (ex. Windows 2008R2 Template)
  • os_family - the OS family of the OS build chosen (ex. CentOS)
  • all parameters - hidden ones and ones visible in the order form. These are referenced by their name and not their label (ex. “dc_code” instead of “Datacenter Code”)
  • resource - (only when ordering a resource) - this is the deployed resource object that was created as part of this order
  • requestor - the user profile object for the requestor of this server or resource

Uniquification

If the hostname template contains one or more zeros followed by a capital X, CloudBolt will replace that during the provisioning job with the first number that makes that hostname unique, padded with zeros to make it the same number of digits.

For example, the hostname template svr-00X would expand to svr-002 if there was already a server in CloudBolt with the name svr-001.

If the hostname template does not include a 0X component, CloudBolt will append the lowest integer to the end of the hostname template that makes the hostname unique.

For example, the hostname template prodsvr- would expand to prodsvr-3 if there were already servers in CloudBolt with the names prodsvr-1 and prodsvr-2.

Hostname Template Examples

  • svr0X - expands to a hostname like “svr05”
  • {{ group.name }}{{ environment.name}}00X - expands to a hostname like “AcmeQA002”
  • {{requestor.user.username }}-{{ os_family.get_base_name|lower|first }}svr00X - expands to a hostname like “auggy-lsvr005” or “bernard-wsvr005”
  • {{ lifecycle }}svr000X - expands to a hostname like “prodsvr0020” or “qasvr1796”. ‘lifecycle’ is a parameter created by the CB admin which may be set on the environment or group, or may be chosen by the user when ordering the server.
  • {{ dc_code }}{{ env_code }}{{ os_family.name|first|lower }}{{ app_code }}00X{{ cluster_code }} - expands to a hostname like “nydlweb001b” (verbally: New York dev linux web server 001 b)
  • svr-{{resource.name|slugify}}-00X - injects the deployed resource name into the hostname
  • svr-{% get_str_id %} - randomly generates a six-character hostname. Append a number to specify the number of characters in your hostname. For example: svr-{% get_str_id 10 %} will generate a 10-character hostname.

Networking

The order form lets a user choose which network each network interface card (NIC) will be connected to, as well as how the NICs will have their IP addresses configured (static vs. DHCP).

The available networks are determined by which group and environment are currently selected in the order form. To choose which networks a group has access to:

  1. Click Groups in the Nav Bar, then click a group’s name to view its details.
  2. Click the Networks tab. You will see a table with a row for each network that is associated with the group. The columns represent the four possible NICs, and the cells describe whether or not that corresponding network is to be made available on that NIC#.
  3. Click Make Changes to toggle the NIC–network availability or to associate some other pre-existing network to the group.
  4. Click Save Changes when you’re done.

A similar process can be followed to choose which networks an environment has access to.

To learn how to create entirely new networks or how to configure which IP addressing options are available for a given network, see Networks.

Custom Validation

If you have advanced requirements for validating an order form, such as checking values against an external system, use the “Order Form Validation” trigger point in Admin > Orchestration Actions > Order Related. CloudBolt ships with a sample plugin documenting the inputs and return values to implement.

Ordering on Behalf of a Recipient User

One optional feature of the order form is the ability to set a recipient for the order, who will own the Server(s) and/or Resource(s) created by the order, instead of the order requester who would own them by default.

The recipient field will only appear on the order form for users with the order.choose_recipient permission in the selected Group. The only role that has that permission out of the box is Super Admins. To allow additional users to take advantage of this feature, give them a role with the appropriate permission.

Note that the options for the recipient will only include those with the order.submit permission in the selected Group. If there are no viable options once the Group is selected, the field will remain hidden.

If a recipient is selected, they will receive an email on order completion (assuming it completed successfully or only with a warning) notifying them about the Server(s) and/or Resource(s) that they now own. This is done with an Email Template that can be edited from the Email Settings page if desired.