Property Browser

Properties are a very powerful CloudBees CD/RO feature, but it can be time-consuming to navigate to and view all properties associated with an object or a set of objects. Managing deep hierarchies of properties and updating or moving properties can be challenging for a large project.

The Property Browser makes navigation of properties easier by letting you view all properties in a hierarchy of objects. Functions to copy and move properties or folders make it simple to create complex structures across an object. This feature saves time for experienced users who otherwise need to browse, search for, and update properties. The Property Browser helps new users learn and understand the value of properties in CloudBees CD/RO by making them easily accessible and viewable.

Opening the Property Browser

The Property Browser is part of the hierarchy menu and is therefore available in the Application Editor, the Microservice Editor, the Environment Editor, the Pipeline Editor, and releases. For more information about the hierarchy menu, refer to Learn about the object model. The Property Browser is also available from within the Properties dialog for a specific object.

Opening the Property Browser from the hierarchy menu

To open the Property Browser from the hierarchy menu, you must first open the Application Editor, the Microservice Editor, the Environment Editor, or the Pipeline Editor in the project. The hierarchy menu is expanded and visible by default:

Figure 1. Hierarchy menu

Figure 2. Hierarchy menu - close up

Then select the Property Browser button in the hierarchy menu:

Figure 3. Property Browser button

The Property Browser opens. For example:

Figure 4. Property Browser

Opening the Property Browser from a properties dialog

To open the Property Browser from within the Properties dialog for a specific object, select Go To Browser. For example:

Figure 5. Go To Browser

Searching for properties

Toggle Search Form allows you to search for properties in the project:

Figure 6. Toggle Search Form

Select Toggle Search Form to open a field and enter search terms:

Figure 7. Search field

To start the search, simply enter the search term in the field. As you type, the search results are highlighted in the property list. For example:

Figure 8. Search results

Filtering objects with no attached properties

By default, all objects appear in the list. If at least one object in the project has one or more properties, then the Show…, All Objects, and Only with Properties buttons allow you to toggle between a view of all objects in the project or a view of only the objects with properties:

Figure 9. Filtering objects

Viewing or navigating to related objects

To view all objects, such as environments, that are related to the properties in this project, select Related Objects. For example, if the application is mapped to various environments, you can view those objects and their child objects:

Figure 10. Viewing related objects

Here is an example of a list of related objects that appears:

Figure 11. Related objects list

To navigate to a related object in the list, simply select the object. For example, if you select the heatclinic-dsl environment in the example above, the properties for that environment appear:

Figure 12. Navigating to related objects

Notice that the breadcrumbs are updated to indicate the navigation path that you used to browse to your current location:

Figure 13. Navigational breadcrumbs

Adding a properties directory

The Add Directory button allows you to create a hierarchy of directories, or property sheets, for properties in the project. For example:

Figure 14. Add Directory

Select Add Directory to enter the details for the new directory:

Figure 15. Enter directory details

Configure the follows items:

Field or menu Description

Field or menu	Description
Directory Name	Name of the property. For naming guidelines, refer to Special characters in CloudBees CD/RO object names..
Place into…	The directory, or property sheet, that contains the property. While you build out the properties that belong to an object, this allows you to edit the structure or hierarchy of the object’s property data. By default, properties are in the object’s `Root` directory, at the top of its property hierarchy. If this menu is grayed out, then you have not yet created any directories to populate this menu with other choices. If you want to create a directory, select Add Directory .

Directory Name

Name of the property. For naming guidelines, refer to Special characters in CloudBees CD/RO object names..

Place into…

The directory, or property sheet, that contains the property. While you build out the properties that belong to an object, this allows you to edit the structure or hierarchy of the object’s property data.

By default, properties are in the object’s Root directory, at the top of its property hierarchy. If this menu is grayed out, then you have not yet created any directories to populate this menu with other choices. If you want to create a directory, select Add Directory .

Creating or editing a property

To add a property, select Add Directory :

Figure 16. Add property

To edit a property, select the corresponding property browser modify button:

Figure 17. Edit a property

Then, select Edit from the popup menu that appears:

Figure 18. Select Edit

Either of these options opens a dialog for entering the property details. For example:

Figure 19. Edit details

When you create or edit a property, configure the items as follows:

Field or Menu Description

Property Name

Name of the property. For naming guidelines, refer to Special characters in CloudBees CD/RO object names..

Description

Description of the property. The contents of this field are ignored by CloudBees CD/RO.

Value

Value for the property.

Expandable

Allows the property to be referenced via expansion in other properties. For example, if you create a property named foo with a value of hello $[bar] and then create an expandable property named bar with a value of world. If you reference foo (by using $[foo] or ectool getProperty foo), the value hello world is returned.

Track Changes to Value

Uncheck to disable tracking of changes to this property value into the change history of modifications where the only change was to the value of this property. Unchecking it is useful where an automated process (such as a job step, pipeline stage, or workflow transition) makes numerous value-only changes.

Unchecking it is strongly recommended for properties that are used as build counters, most recent build or artifact names, or are used to store runtime output from jobs, pipelines, or workflows into a property attached to a change-tracked non-runtime entity. Otherwise, these will rapidly fill the change history with numerous irrelevant events.

This checkbox does not appear if change tracking is not enabled or is not tracking this property.

Unchecking this checkbox also modifies the behavior of the ectool export --revisionNumber revision_number option for exporting previous states of entities containing properties with this checkbox cleared. The current value of the property is exported, so that immediately reimporting it does not reset the property value.

See the KBEC-00422 - Locating and Fixing Properties with Excessive Unwanted Change History Generated by Automated Processes KB article for details about locating properties for which this should have been done (but was not) and thus have a large change history.

In an XML output <property> tag and in the ectool createProperty, modifyProperty, and setProperty commands, this option is named suppressChangeTracking, and its Boolean truth value is inverted.

Place into…

Directory (property sheet) to contain the property. While you build out the properties that belong to an object, this menu lets you edit the structure or hierarchy of the object’s property data.

Properties are in the object’s Root directory (the top of its property hierarchy) by default. If this menu is grayed out, then you have not yet created any directories to populate this menu with other choices. If you want to create a directory, select Add Directory .

Select OK to save your changes.

Moving a property

To move a property to another directory, select its corresponding property browser modify button, and then select Move to from the popup menu:

The Move <property_name> to… dialog appears. For example:

Then in the dialog, select the new location (another object or directory), and then select Move.

Copying a Property

To create a property by copying an existing property:

Select its corresponding button, and then select Copy to:

Figure 20. Copy a property

The Copy <property_name> to… dialog appears. For example:
Select the new location, typically another object or directory, and then select Copy.

Deleting a property

To delete a property:

Select its corresponding button, and then select Delete:

Figure 21. Delete a property

A confirmation appears:

Figure 22. Confirmation
Select Delete to confirm the deletion.

Property Browser Usage Examples

Following are a few examples of how you can use the Property Browser.

Determining the location of a property

In this example, you have an application that consists of various application tiers, components, and application and component processes. The application is mapped to a set of environments that consist of various environment tiers. You can use the Property Browser to view all properties and current values associated with the objects that comprise the application and its mapped environments. This helps you determine where a property is located, so you can reference it while you continue authoring.

Troubleshooting deployments

For the application and setup described above, if the deployment has issues, you can use the Property Browser to troubleshoot why a run of that application behaved in an unexpected way. This could be traced to a number of configuration properties defined across the objects, and you can use the Property Browser to quickly check a number of properties to speed up investigation and debugging.

Adding a layer of property sheets

You can use the Property Browser to:

Change the property sheet and the nested structure of properties.
Add a new layer of property sheets, rather than deleting and recreating properties individually.

Searching-and-replacing properties

You can search-and-replace numerous properties that are stored in different locations.