Service Catalogs

The CloudBees Flow Service Catalogs help you accelerate application deployment. This feature lets you automate routine deployment tasks and publish them as templates so that end users can use them by providing minimal information and without learning to use CloudBees Flow.

Key Benefits of Service Catalogs

CloudBees Flow Service Catalogs have the following key benefits to your organization:

  • Promotes best practices in your organization.

  • Accelerates ROI from your deployment solution.

  • Improves deployment efficiency by reducing the learning curve.

Using Service Catalogs

End users click the Service Catalog button to open the Service Catalog UI to see all the available catalog items. As shipped, CloudBees Flow includes five standard catalogs: Applications, Cloud Provisioning, Containers, Pipelines, and Utilities; all standard catalogs are included in the CloudBees project.

The following is an example of the Self-Service catalog UI.

03000002

To use a catalog item, click the button (such as Create, Execute, Import, Discover, or Provision ) on an item, enters the required parameters, and then click OK to process the underlying catalog template.

The following is an example form for end users to enter parameters after clicking Create. This example is for the Multi-stage CD Pipeline catalog item, bundled in the Pipelines catalog:

03000011

Once the DSL template processing is complete, CloudBees Flow displays the following, giving the user an option to navigate to the new object:

This Template Sucessfully created this pipeline. Continue to its location?

For this example, the end user is taken to the new pipeline object and completes pipeline stage and task configuration. The pipeline is then available for use in releases.

You can extend a catalog by creating catalog items that are specific to your business. Sample DSL to create catalog items is included in CloudBees Flow as a starting point.

Catalog Items

CloudBees Flow includes three major types of Service Catalog items:

  • DSL-based

  • Plugin-based

  • Procedure-based

DSL-Based Catalog Items

DSL-based catalog items are the easiest to create. This type of catalog item is made up of DSL templates accompanied by UI form metadata or formal parameters to capture the user input required by the DSL.

  • You use the CloudBees Flow UI to author a model, export the DSL, and then convert the DSL to a template before exposing it to end users as a catalog item.

  • You have a choice to use form XML metadata or the formal parameter panel to specify user input parameters.

Sample DSL Catalog Item Model

The following is a simple DSL template. This template creates an application in the Default project folder:

 /* args.appName is user entered value passed in as argument */
def appName = args.appName;

application appName, {
   projectName = "Default"
}

See Example: Sample Catalog Item DSL for an expanded DSL example.

Input Parameters

You can define formal parameters to collect user input at catalog item create-time either Via Formal Parameter Panel or Via Form XML .

Via Formal Parameter Panel

During the creation phase, select Use Formal Parameters in the Definition section of the Edit Catalog Item dialog:

use formal paramaeters

End-Target Navigation

First, specify the end-target navigation. This is where CloudBees Flow takes the user after she has created the service catalog instance. Specify a DSL string in the End Target JSON section of the the catalog item. It has the following form:

"endTarget": {
     "source": "<source>",
      "object": "<objectType>",
      "objectName ": "<objectName>",
      "objectProjectName ": "<objectProjectName>",
      "objectId" : "<objectId>"
}

where:

  • <source> is one of:

  • parameter —use values supplied with objectName, objectProjectName, and objectId ` as fields in the formal parameter; set `useFormalParameter to true.

  • form —use values supplied with objectName, objectProjectName, and objectId ` as fields in the form XML; set `useFormalParameter to false.

  • property —use values supplied with objectName, objectProjectName, and `objectId ` as properties.

  • name —use values supplied with objectName, objectProjectName, and `objectId ` as literal strings.

  • `<objectType> ` is the type of object.

  • <objectName> is the name of the object. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectProjectName> is the project. Can be a literal string, property, or formal parameter field based on <source> type.

  • <objectId> is the object id. Can be a literal string, property, or formal parameter field based on <source> type.

Define Formal Parameters

Once finished specifying the DSL specifics for the catalog item template, click OK to save your work. Then, click menu dark on the upper left corner of the catalog item editor and select Parameters: the Parameters dialog opens.

See Parameters for full details about creating formal parameters from the parameter panel.

Via Form XML

During the creation phase, select Use Form XML in the Definition section of the Edit Catalog Item dialog. You populate the Parameter Form section of the dialog with form XML that collects the user input. The example below shows details for the for the Pipeline Name parameter:

 {
    "sections":
    {
       "section":
    [{
        "name": "Pipeline Details",
        "ec_parameterForm": "
                <editor>
                  <formElement>
                    <property>pipelineProjName</property>
                    <label>Pipeline Project Name</label>
                    <type>project</type>
                    <required>1</required>
                  </formElement>
                  <formElement>
                    <property>pipelineName</property>
                    <label>Pipeline Name</label>
                    <type>entry</type>
                    <required>1</required>
                  </formElement>
                </editor>"
    }]
       "endTarget": {
            "source": "form",
            "object": "pipeline",
            "objectName": "pipelineName",
            "objectProjectName": "pipelineProjName"
    }

     }
   }
  • section allows groupings of user input parameters into different sections.

  • ec_parameterForm specifies the form XML that defines the user input form relevant to a section.

  • `endTarget ` specifies where to take the user once she has created the service catalog instance. See End-Target Navigation for details.

Plugin-Based Catalog Items

With plugin-based catalog items, you can expose any existing plugin procedure as a Service Catalog item. You can expose any useful procedure or plugins directly to end users.

As with DSL, for each procedure to expose in a Service Catalog, you must create additional metadata. For a simple use case, you just create the ec_customEditorData/selfServiceUIForm property. This property tells the catalog where to find the UI form to render that corresponds to the procedure. The Service Catalog UI uses this information to render the form. When the user fills in the form, that information is passed to the procedure.

Following is an example form for entering parameters for the bundled Import Docker Compose File catalog item, which is plugin-based:

03000013

Following is an example form for entering parameters for the bundled Import Kubernetes YAML File catalog item, which is also plugin-based:

03000012

If the ec_customEditorData/selfServiceUIForm property is not found, then the system will try to render the UI form based on the parameter definition with the exception for Credentials, Credential Parameters, and Projects types.

Procedure-Based Catalog Items

With procedure-based catalog items, you can expose any existing procedure as a Service Catalog item directly to end users.

As with DSL, for each procedure to expose in a Service Catalog, you must create additional metadata. For a simple use case, you just need to create the ec_customEditorData/selfServiceUIForm property. This property tells the catalog where to find the UI form to render that corresponds to the procedure. When the user fills in the form, that information is passed to the procedure.

If the ec_customEditorData/selfServiceUIForm property is not found, then the system tries to render the UI form based on the parameter definition with the exception for Credentials, Credential Parameters, and Projects types.

Deployment Package Manager Catalog Items

This is a special type of catalog item that lets you deploy Java or .NET applications quickly.

Before you create this type of item, you must create the deployment package outside of CloudBees Flow. A deployment package is a manifest.json file plus one or more components that make up an application. After you create the deployment package, you can use it to create an application model that corresponds to the uploaded application package with little CloudBees Flow knowledge. For details, see Deployment Package Manager .

Managing Service Catalogs and Catalog Items

You can create self-service catalogs and catalog items directly from the UI.

Creating a User-defined Catalog

In the self-service catalog UI, select the Add button to create a new catalog.

  1. From the new Catalog dialog, select Create New.

  2. Enter a name, an optional description, select a project where you want to create the new catalog item, and select OK.

Once the new catalog item is created, the new catalog appears in the Catalogs drop-down menu:

03000008

You cannot edit catalogs or catalog items that are bundled with CloudBees Flow. However, you can use the Copy Existing option to create new catalogs from catalogs bundled with CloudBees Flow.

Creating Catalog Item Templates

Select the user-defined catalog, using the catalog drop-down, into which you want the new catalog item. You cannot create catalog items in catalogs bundled with CloudBees Flow.

Select Catalog Editor to switch to the edit mode. After editing catalog items, you can use the View Catalog mode to switch the UI back to the view mode to test the new items.

03000009

Enter a Name and an optional Description for the new item that you are creating. You can create another item or continue with defining the new item:

0300000a

Icon upload is not supported.

Click Define and enter the relevant information as follows. The key attributes that are relevant to a catalog item definition are:

  • Section 1: Display

    • Select Button Label : select from the button label drop down.

    • Icon : this represents the catalog item and can be selected from the icon library or a URL link.

  • Section 2: Additional Information : This content appears in the Instructions section of the template. This gives the end user additional details regarding the usage of the catalog item.

  • Section 3: Definition : See Catalog Items above for the details on the UI form metadata

0300000b

Editing Catalog Items

Once a catalog item is created, you can use the cross bar icon to reorder the catalog item. A menu associated with the catalog item provides additional options to edit item details or item definitions or to delete an existing catalog item. Options to export DSL or edit DSL are also available from the menu:

0300000d

Example: Sample Catalog Item DSL

Here is sample code to create a catalog item in a catalog named Custom. This is a DSL-based catalog item that creates a simple application object:

catalog 'Foo', {
  description = 'Catalog item description'
  iconUrl = 'icon'
  projectName = 'CloudBees'
  catalogItem 'Sample Catalog Item', {
    description = '''<xml>
         <title>This is the short description that is shown in the Service catalog UI as part of this catalog item</title>
         <htmlData>
           <![CDATA[<div>
              This is the html stylized text based on catalog item details that gets show when the user clicks the more link.
           </div>]>
         </htmlData>
    </xml>'''
    buttonLabel = 'Create'
    catalogName = 'Custom'
    dslParamForm = '''{
      \"sections\": {
        \"section\": [{
          \"name\": \"Application details\",
          \"instruction\": \"Provide Application details\",
          \"ec_parameterForm\": \"<editor> <formElement> <label>Application Name</label> <property>appName</property> <documentation>Name of the application to be created.</documentation> <type>entry</type> <required>1</required> </formElement> </editor>\"
        }],
        \"endTarget\": {
          \"object\": \"application\",
          \"formValue\": \"appName\"
        }
      }
    }'''
    dslString = '''def appName = args.appName;
        application appName, {
           projectName = "Default"
     }'''
    iconUrl = 'public/app/assets/img/taskicon.png'
    projectName = 'CloudBees'
    subpluginKey = null
    subprocedure = null
    subproject = null
  }
}

For More Information