Manage service catalog items

CloudBees CD/RO Service catalog items help streamline and standardize various tasks across your environments. These tasks can reduce manual effort through tested automation and help increase consistent development.

While CloudBees CD/RO provides many built-in catalog items to get you started, you can also create custom items tailored to your environment’s specific needs. Custom items provide more flexibility and control, and can be defined to execute nearly any task CloudBees CD/RO is capable of.

Additionally, these items are assigned to specific catalogs, which allows you to develop dedicated catalogs for different purposes, teams, and projects. This organizational structure makes it easier to manage access, streamline workflows, and ensure each team has the appropriate tools and resources aligned with their specific requirements.

View catalog items

To view all catalog items that you have permission to view, select Service catalog in the CloudBees CD/RO top navigation. This opens the Catalog items page.

From here you can filter catalog items and perform searches for specific items based on the filter settings.

For more information about filters, refer to Manage custom filters for catalogs and catalog items.

To view the items assigned to a specific catalog, either:

On the Catalog items page, select the Service catalogs filter, and then select the name of the catalog. This updates the page to only display the items assigned to that catalog.
On the Catalog items page, select the Catalogs tab, and then select the name of the catalog from the list. This opens the catalog page, which contains all catalog items assigned to it.

Manage catalog item tags

You can manage catalog item tags from the catalog item Options menu. To add or delete tags:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to manage tags for, select the Options menu on the right side, and then select Details. This opens the Edit Catalog Item window.
In the Tags section, select the icon. This opens the Tags window.
To manage tags:
- To add a new tag, enter a tag name.
- To delete a tag, select the X button.
  
  Tags cannot be edited. To fix an issue with an existing tag, you must delete the tag and create a new one.
Select OK.

Create new catalog items

All catalog items are contained within specific catalogs, and managed as part of the assigned catalog. To create a new catalog item within a catalog:

Navigate to Service catalog Catalogs, and then select the catalog where you want to assign the catalog item. This opens the catalog page.
Select either:
- Add catalog item on the catalog page.
- The Catalog editor tab, and then select Add catalog item.
Both options create a new object in the catalog.
Enter an item title in the Name field.
Enter the item details in the Description field.
Do one of the following:
- To save these fields and configure the item later, select Create.
  
  The item is created, but has a Requires Definition button. You can navigate back to the item later, and then select Requires Definition to continue defining the item.
- To configure the item now, select Define. This opens the catalog item configuration window. To continue, refer to:

Configure catalog item display

Service catalog items include a Display section in the item definition where you can configure:

The icon displayed for the item.
The action button label users select to run the item.

To configure these elements:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to configure, select the Options menu on the right side, and then select Item Definition. This opens the item Edit window.
Choose an item action button label from the Select Button Label menu.
Select a display icon for the item:
- Use available icons by selecting Icon Library.
- Choose a custom icon by selecting URL link and entering the icon address into the URL text field.
  
  This URL must be available for the item at runtime. If it is not available, no icon is shown for the item.
To continue, either:
- Select OK to save your changes, and continue later.
- Continue configuring your catalog item:
  - Configure catalog item additional information
  - Configure catalog item definitions

Configure catalog item additional information

Service catalog items include a configuration section called Additional Information. This section allows you to include detailed descriptions and instructions on how to use the catalog item.

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to configure, select the Options menu on the right side, and then select Item Definition. This opens the item Edit window.
Scroll down to the Additional Information section.
Enter any information or instructions user may need to run the catalog.

The Additional Information section is interpreted as HTML. To preview the formatted HTML, select the View HTML icon.
Select OK to save your changes.

By default, when users run the catalog item, this information appears in the Instructions section in an Additional Information subsection of the item window.

Configure catalog item definitions

Catalog item definitions are the actual configuration for what the item does when users select it. The following options are available for defining catalog items:

Define DSL-based catalog items
Define a plugin procedure as a catalog item
Define a procedure as a catalog item

Catalog item definitions can be further extended by adding parameters. For more information, refer to Manage catalog item parameters.

Define DSL-based catalog items

DSL-based catalog items provide the most versatile approach to catalog items. DSL-based catalog items are made up of a DSL script accompanied by UI form metadata or formal parameters to capture the user input required by the DSL.

For more information, refer to Using the CloudBees CD/RO DSL.

To define a DSL-based catalog item:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to define, select the Options menu on the right side, and then select Item Definition. This opens the item Edit window.
Scroll down to the Definitions section.
In the left panel, select DSL. This opens the DSL configuration options in the window.

Modify item formal parameters, using one of the following options:

Configure formal parameters using DSL by entering parameter definitions into DSL Editor field.

For sample code, refer to Catalog item examples:

DSL Example 1: Create an application in a project
DSL Example 2: Create an application object in a custom catalog
DSL Example 3: Create a catalog item with access to another catalog item

Enter formal parameters using XML.
1. Select Use Form XML.
2. Enter parameter definitions in XML into Parameter Form field.
  
  For sample code, refer to JSON Example 1: Create a pipeline parameter.

For complex UI forms, you may have to create the ec_customEditorData/selfServiceUIForm server property for them to render correctly. The Service Catalog UI uses this property information to render the form displayed when the Catalog item link is selected. To create it:

Navigate to Administration Server properties.
Select the Create property button on the right side on the screen.
For Property name, enter ec_customEditorData.
For Value, enter selfServiceUIForm.
Select Save changes.

If the property is not found, then the Service Catalog UI tries to render the form based on the parameter definition with exceptions for Credentials, Credential Parameters, and Projects types.

(Optional) Specify end-target navigation. This is where CloudBees CD/RO navigates the user after the service catalog item is run and completes successfully. For object end-target navigation examples, refer to End target navigation.
1. Select Use Formal Parameters.
2. Enter end-navigation data in the End Target JSON field.
Select OK.

The end-target navigation of catalog items is specified in the End Target JSON field of the DSL object. This location is where CloudBees CD/RO navigates users, to continue defining the selected service catalog object.

For example, if a multi-stage pipeline catalog template is selected, then CloudBees CD/RO would navigate the user to the pipeline editor. For the end-target navigation for all objects, refer to Default end-target navigation list.

The following example defines the JSON format of the end-target navigation:

JSON end-target navigation example

{
  "source": "<source>",(1)
  "object": "<objectType>",(2)
  "objectName": "<objectName>",(3)
  "objectProjectName": "<objectProjectName>",(4)
  "objectId" : "<objectId>"(5)
}▼

1	`<source>` is one of: `parameter` uses values supplied with `objectName`, `objectProjectName`, and `objectId` as fields in the formal parameter; set `useFormalParameter` to `true`. `form` uses values supplied with `objectName`, `objectProjectName`, and `objectId` as fields in the form XML; set `useFormalParameter` to `false`. `property` uses values supplied with `objectName`, `objectProjectName`, and `objectId` as properties. `name` uses values supplied with `objectName`, `objectProjectName`, and `objectId` as literal strings.
2	`<objectType>` is the type of object.
3	`<objectName>` is the name of the object; it can be a literal string, property, or formal parameter field based on `<source>` type.
4	`<objectProjectName>` is the project; it can be a literal string, property, or formal parameter field based on `<source>` type.
5	`<objectId>` is the object ID; it can be a literal string, property, or formal parameter field based on `<source>` type.

The following table contains the default JSON formatted end-target navigation for service catalog template objects:

Default end-target navigation reference

Table 1. Default end-target navigation values
Catalog object	End-target navigation
application job	`application-process-runs/${objectId}/steps`
catalog	`catalogs/${objectId}`
ciConfiguration	`configurations/ci-configurations/filters/${search}`
credential	`credential-management/credentials/filters/${search}`
credentialProvider	`credential-management/credential-providers/filters/${search}`
dashboard	`dashboards/${objectId}`
dataRetentionPolicy	`data-retention-policies/${objectId}`
directoryProvider	`configurations/directory-providers/filters/${search}`
emailConfig	`configurations/email-configurations/filters/${search}`
environment	`environments/${objectId}`
environmentTemplate	`environments/environments-templates/${objectId}`
flowRuntime	`pipeline-run/${pipelineId}/${objectId}`
gateway	`cloud-gateways/filters/${search}`
group	`groups/${objectId}/users`
persona	`personas/filters/${search}`
pipeline	`pipelines/${objectId}`
pluginConfiguration	`plugin-management/configurations/filters/${search}`
procedure	`procedure/${objectId}`
procedure job	`procedure-runs/${objectId}/steps`
project	`projects/filters/${search}`
release	`releases/${objectId}`
report	`dashboard-reports/${objectId}/edit`
resource	`resources-list/filters/${search}`
resourcePool	`pools/filters/${search}`
resourceTemplate	`environments/resources-templates/filters/${search}`
schedule	`schedules/filters/${search}`
scmSync	`configurations/source-code-synchronization/filters/${search}`
scmSync job	`configurations/source-code-synchronization-runs/${objectId}/steps`
serviceAccount	`configurations/service-accounts/filters/${search}`
user	`users/filters/${search}`
workspace	`workspaces/filters/${search}`
zone	`zone-list/filters/${search}`

Define a plugin procedure as a catalog item

Plugin procedures can be templated and run as catalog items.

To define a plugin procedure as a catalog item:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to define, select the Options menu on the right side, and then select Item Definition. This opens the item Edit window.
Scroll down to the Definitions section.
In the left panel, select Plugin. This opens the Plugin configuration options in the window.
Select the category from the Select Category menu.
Select plugin name from the Select Plugin menu.
Select the procedure name from the Select Procedure menu.
Select OK.

Navigate to Administration Server properties.
Select the Create property button on the right side on the screen.
For Property name, enter ec_customEditorData.
For Value, enter selfServiceUIForm.
Select Save changes.

If the property is not found, then the Service Catalog UI tries to render the form based on the parameter definition with exceptions for Credentials, Credential Parameters, and Projects types.

Define a procedure as a catalog item

Procedures can be templated and run as catalog items.

To define a procedure as a catalog item:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to define, select the Options menu on the right side, and then select Item Definition. This opens the item Edit window.
Scroll down to the Definitions section.
In the left panel, select Procedure. This opens the Procedure configuration options in the window.
Select project name from the Select project menu.
Select the procedure name from the Select Procedure menu.
Select OK.

Navigate to Administration Server properties.
Select the Create property button on the right side on the screen.
For Property name, enter ec_customEditorData.
For Value, enter selfServiceUIForm.
Select Save changes.

If the property is not found, then the Service Catalog UI tries to render the form based on the parameter definition with exceptions for Credentials, Credential Parameters, and Projects types.

Manage catalog item parameters

Configuring parameters within catalog items allows an easy interface for running catalog items by prompting users to provide required values. This section explains how to add, edit, and delete these parameters.

If you are using DSL catalog items, you can also define parameters as part of the item definition.

Add parameters to catalog items

To add parameters to catalog items:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to configure, select the Options menu on the right side, and then select Parameters. This opens the Parameters window.
Either:
- If no parameters have been added for the catalog item, select There are no Parameters. Add one . This opens the New Input Parameter window.
- If parameters are present, select the Input icon on the right side of the window. This opens the New Input Parameter window.
Enter the parameter configuration.
Select OK to create the parameter.

Edit catalog item parameters

To edit catalog item parameters:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to configure, select the Options menu on the right side, and then select Parameters. This opens the Parameters window.
On the row of the parameter you need to edit, select the Edit item icon. This opens the Edit Input Parameter window.
Make the necessary changes to the parameter, and then select OK to apply them.

Delete catalog item parameters

To delete catalog items parameters:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to configure, select the Options menu on the right side, and then select Parameters. This opens the Parameters window.
Select the row of the parameter you want to delete. The Delete icon in the upper right becomes active.
Select the Delete icon, and then select Delete to confirm.

Catalog item examples

These section provides DSL and JSON examples for various catalog items.

DSL Example 1: Create an application in a project

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

Create an application in a project

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

application appName, {
   projectName = "Default"
}▼

DSL Example 2: Create an application object in a custom catalog

This is sample code to create a catalog item in a custom catalog. This DSL-based catalog item creates a simple application object:

Create an application object in a custom catalog

catalog 'Custom', {
  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
  }
}▼

DSL Example 3: Create a catalog item with access to another catalog item

This is sample code to create a catalog item with access to the myProject catalog item:

Create a catalog item with access to another catalog item

catalog 'CD 10.7 SSC Parameter Enhancements', {
    projectName = 'Default'

    catalogItem 'myProject usage', {
        description = "Creates a pipeline in the catalog project"
        dslString = '''\
            def projName = getProperty("/myProject/projectName").value
            pipeline "createdFromSSC", projectName: projName
        '''.stripIndent()
    }
}▼

JSON Example 1: Create a pipeline parameter

The example below shows details for the Pipeline Name parameter:

Create a pipeline parameter

 {
    "sections":(1)
    {
       "section":
        [{
            "name": "Pipeline Details",
            "ec_parameterForm": "(2)
                    <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": {(3)
            "source": "form",
            "object": "pipeline",
            "objectName": "pipelineName",
            "objectProjectName": "pipelineProjName"
    }
  }
}▼

1	`section` allows groupings of user input parameters into different sections.
2	`ec_parameterForm` specifies the form XML that defines the user input form relevant to a section.
3	`endTarget` specifies where to take the user once the service catalog item runs and has completed successfully. For details, refer to End target navigation.

Convert service catalog items to release templates

You can convert a service catalog item into a release template. Once converted, this template is available to create new releases from the catalog item. For more information on creating release templates, refer to Create new release from template.

To convert a service catalog items to a release template:

Navigate to Service catalog Catalogs.
Select the catalog that contains the catalog item. This opens the catalog page.
Select the Catalog editor tab.
On the catalog item you want to convert, select the Options menu on the right side, and then select DSL editor. This opens the DSL editor window.
Change the templateObjectType attribute from none to release.
Select OK.

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 CD/RO.

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 CD/RO knowledge.

For details, refer to Generate a deployment package.

Manage service catalog items

View catalog items

Manage catalog item tags

Create new catalog items

Configure catalog item display

Configure catalog item additional information

Configure catalog item definitions

Define DSL-based catalog items

End target navigation

Default end-target navigation list

Define a plugin procedure as a catalog item

Define a procedure as a catalog item

Manage catalog item parameters

Add parameters to catalog items

Edit catalog item parameters

Delete catalog item parameters

Catalog item examples

DSL Example 1: Create an application in a project

DSL Example 2: Create an application object in a custom catalog

DSL Example 3: Create a catalog item with access to another catalog item

JSON Example 1: Create a pipeline parameter

Convert service catalog items to release templates

Deployment package manager catalog items