Customize an existing CI type
XL Deploy’s type system allows you to customize any configuration item (CI) type by adding, hiding, or changing its properties. These properties become a part of the CI type and can be specified in the deployment package (DAR file) and shown in the XL 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 XL Deploy classpath. Changes to the CI types are loaded when the XL 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 XL 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 XL Deploy’s behavior. To learn how to do so, refer to Get started with rules.
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:
||Yes||The name of the property to modify.|
||No||The type of the property to modify. Possible values are:
||You must always specify the
||No||Describes the property.|
||No||Categorizes the property. Each category is shown in a separate tab in the XL Deploy GUI.|
||No||Sets the property’s label. If set, the label is shown in the XL Deploy GUI instead of the name.|
||No||Indicates whether the property is required or not.||You cannot change the
||No||Specifies the property size. Possible values are:
||Only relevant for properties of kind
||No||Specifies the default value of the property.|
||No||The Java enumeration class that contains the possible values for this property.||Only relevant for properties of kind
||No||The type of the referenced CI.||Only relevant for properties of kind
||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
||No||Indicates whether the property is hidden, which means that it does not appear in the XL 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.|
||No||Indicates whether the property is persisted in the repository or not.|
||No||Indicates that this property is used for inspection (discovery).|
Note: For security reasons, the
password property of a CI cannot be modified.
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>
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>
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:
- Define an
overthere.SshHostCI called HostA.
Add the following type modification:
<type-modification type="overthere.SshHost"> <property name="important" kind="string" default="no" hidden="false" /> </type-modification>
Restart XL Deploy.
HostA now has a property called
important, which contains the value “no”.
- Add a new
overthere.SshHostCI called HostB. It also has the
importantproperty with value “no”.
Change the default value of the
<type-modification type="overthere.SshHost"> <property name="important" kind="string" default="probably" hidden="false" /> </type-modification>
- Restart XL Deploy.
- The value of the
importantproperty in HostA is now “probably”, while the value of the
importantproperty 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.