Customize an existing CI type

This topic covers how to customize Configuration Item (CI) types in Deploy by adding or modifying properties using synthetic properties. These properties become a part of the CI type and can be specified in the deployment package (DAR file) and shown in the Deploy GUI.

New CI type properties are called synthetic properties because they are not defined in a Java class. You define properties and make changes in an XML file called synthetic.xml which is added to the Deploy classpath. Changes to the CI types are loaded when the Deploy server starts.

There are several reasons to modify a CI type:

• A CI property is always given the same value in your environment. Using synthetic properties, you can give the property a default value and hide it in the GUI.

• There are additional properties of an existing CI that you want to specify.

  For example, suppose there is a CI representing a deployed datasource for a specific middleware platform. The middleware platform allows you to specify a connection pool size and connection timeout, but Deploy only supports the connection pool size by default. In this case, modifying the CI to add a synthetic property allows you to specify the connection timeout.

note

To use a newly defined property in a deployment, you must modify Deploy's behavior. To learn how to do so, refer to Get started with rules.

Specify CI properties

For each CI, you must specify a type. Any property that is modified is listed as a nested property element. For each property, the following information can be specified:

Property	Required	Description	Notes
name	Yes	The name of the property to modify.
kind	No	The type of the property to modify. Possible values are: enum, boolean, integer, string, ci, set_of_ci, set_of_string, map_string_string, list_of_ci, list_of_string, and date (internal use only).	You must always specify the kind of the parent CI. You can find the kind next to the property name in the plugin reference documentation.
description	No	Describes the property.
category	No	Categorizes the property. Each category is shown in a separate tab in the Deploy GUI.
label	No	Sets the property's label. If set, the label is shown in the Deploy GUI instead of the name.
required	No	Indicates whether the property is required or not.	You cannot change the required attribute of an existing CI; that is, if a CI's required property is set to "true", you cannot later change it to "false".
size	No	Specifies the property size. Possible values are: default, small, medium, and large. Large text fields will be shown as a text area in the Deploy GUI.	Only relevant for properties of kind string.
default	No	Specifies the default value of the property.
enum-class	No	The full classpath to the Java enumeration class that defines the possible values for this property.	Only relevant for properties of kind enum.
referenced-type	No	The type of the referenced CI.	Only relevant for properties of kind ci, set_of_ci, or list_of_ci.
as-containment	No	Indicates whether the property is modeled as containment in the repository. If true, the referenced CI or CIs are stored under the parent CI.	Only relevant for properties of kind ci, set_of_ci, or list_of_ci.
hidden	No	Indicates whether the property is hidden, which means that it does not appear in the Deploy GUI and cannot be set by the manifest or by the Jenkins, Maven, or Bamboo plugin.	A hidden property must have a default value.
transient	No	Indicates whether the property is persisted in the repository or not.
inspectionProperty	No	Indicates that this property is used for inspection (discovery).

note

For security reasons, the password property of a CI cannot be modified.

Hide a CI property

The following example hides the connectionTimeoutMillis property for Hosts from the UI and gives it a default value:

<type-modification type="base.Host">
    <property name="connectionTimeoutMillis" kind="integer" default="1200000" hidden="true" />
</type-modification>

Extend a CI

The following example adds a "notes" field to a CI to record notes:

<type-modification type="overthere.Host">
    <property name="notes" kind="string"/>
</type-modification>

Change a default value

If you add a type modification to a CI with a default value and then change that value, CIs that were created before the modification will not pick up the new default value. For example:

1. Define an overthere.SshHost CI called HostA.

2. Add the following type modification:

   <type-modification type="overthere.SshHost">
       <property name="important" kind="string" default="no" hidden="false" />
   </type-modification>

3. Restart Deploy.

   HostA now has a property called important, which contains the value "no".

4. Add a new overthere.SshHost CI called HostB. It also has the important property with value "no".

5. Change the default value of the important property:

   <type-modification type="overthere.SshHost">
       <property name="important" kind="string" default="probably" hidden="false" />
   </type-modification>

6. Restart Deploy.

7. The value of the important property in HostA is now "probably", while the value of the important property in HostB is still "no".

This is because HostA was created before the important property was added, while HostB was created afterwards. HostA does not actually know about the important property, although it appears in the repository (with its default value) for display purposes. However, HostB is aware of the important property, so its value will be persisted.

To ensure that the important value in HostA is persisted, you must open HostA in the repository and then save it.