Using Dependent Properties in Type Definitions

Dependent properties within the XML type-definitions enables dynamic user inputs that adapt based on user selections. This functionality is essential for tasks requiring context-specific input, ensuring that only relevant fields and options are presented, thereby enhancing the user experience.

The primary purpose of using dependent properties is to streamline user interactions and prevent errors. This is achieved by hiding irrelevant options and displaying only those properties that are relevant to what the user has chosen.

Examples

The following examples explain how dependent properties work:

Task Context

When configuring tasks like creating a persistent volume in Kubernetes, it's essential that user inputs adapt based on the selected volume source. This dynamic configuration ensures that only relevant fields are editable, thereby streamlining the user interface and minimizing potential errors.

Learn now to define the dependent properties.

Step 1 — Initialize the Trigger Property

Start by defining a property within the task that will act as a trigger for displaying dependent properties. This property should list all potential volume sources as enum values. For instance, persistentVolumeSource is used to initiate the display of dependent properties based on the selected source:

<type type="kubernetes.CreatePersistentVolume" label="Create Persistent Volume (Container)" extends="kubernetes.K8sCommand">
    <property name="persistentVolumeSource" label="Persistent Volume Source" kind="enum" category="input" default="HostPath">
        <enum-values>
            <value>HostPath</value>
            <value>Local</value>
            <value>GCEPersistentDisk</value>
            <value>AWSElasticBlockStore</value>
        </enum-values>
    </property>
</type>

Step 2 — Specify Dependent Properties

Following the trigger property, define the dependent properties with detailed attributes such as name, label, category, and requirements. These properties are to be displayed based on the volume source selected:

<type type="kubernetes.CreatePersistentVolume" label="Create Persistent Volume (Container)" extends="kubernetes.K8sCommand">
    <property name="persistentVolumeSource" label="Persistent Volume Source" kind="enum" category="input" default="HostPath">
        <enum-values>
            <value>HostPath</value>
            <value>Local</value>
            <value>GCEPersistentDisk</value>
            <value>AWSElasticBlockStore</value>
        </enum-values>
    </property>
	<property name="pvsPath" label="Path" category="input" kind="string" required="false"/>
	<property name="pvsType" label="Type" category="input" kind="string" required="false"/>
	<property name="pvsFsType" label="File System Type" category="input" kind="string" required="false"/>
	<property name="pvsPdName" label="PD Resource Name" category="input" kind="string" required="false" description="Unique name of the PD resource in GCE"/>
	<property name="pvsPartition" label="Partition" category="input" kind="integer" required="false" description="The partition in the volume that you want to mount"/>
	<property name="pvsReadOnly" label="ReadOnly" category="input" kind="boolean" required="false"/>
	<property name="pvsVolumeID" label="Volume ID" category="input" kind="string" required="false" description="Unique ID of the persistent disk resource in AWS"/>
</type>

Step 3 — Link Dependent Properties to Enum Values

Finally, define a new property that maps dependent properties to their respective enum values. This property, suffixed with _DependentProperties, uses the default attribute to create mappings between each enum value and its related fields. The format for this mapping is structured as default="EnumValue1:dependentProperty1;dependentProperty2,EnumValue2:dependentProperty1...":

<type type="kubernetes.CreatePersistentVolume" label="Create Persistent Volume (Container)" extends="kubernetes.K8sCommand">
    <property name="persistentVolumeSource" label="Persistent Volume Source" kind="enum" category="input" default="HostPath">
        <enum-values>
            <value>HostPath</value>
            <value>Local</value>
            <value>GCEPersistentDisk</value>
            <value>AWSElasticBlockStore</value>
        </enum-values>
    </property>
    <property name="persistentVolumeSource_DependentProperties"  
          category="input"  
          kind="map_string_string"  
          hidden="true"  
          required="false"  
          default="HostPath:pvsPath;pvsType,Local:pvsPath;pvsFsType,GCEPersistentDisk:pvsPdName;pvsFsType;pvsPartition;pvsReadOnly,AWSElasticBlockStore:pvsVolumeID;pvsFsType;pvsPartition;pvsReadOnly"/>
    <property name="pvsPath" label="Path" category="input" kind="string" required="false"/>
	<property name="pvsType" label="Type" category="input" kind="string" required="false"/>
	<property name="pvsFsType" label="File System Type" category="input" kind="string" required="false"/>
	<property name="pvsPdName" label="PD Resource Name" category="input" kind="string" required="false" description="Unique name of the PD resource in GCE"/>
	<property name="pvsPartition" label="Partition" category="input" kind="integer" required="false" description="The partition in the volume that you want to mount"/>
	<property name="pvsReadOnly" label="ReadOnly" category="input" kind="boolean" required="false"/>
	<property name="pvsVolumeID" label="Volume ID" category="input" kind="string" required="false" description="Unique ID of the persistent disk resource in AWS"/>
</type>

As a result, based on the selected value for Persistent Volume Source, only the relevant properties will be displayed for user input. This method significantly enhances the usability and accuracy of the configuration process.

Connections Context

In the context of configuring connections, such as setting up a connection to a Kubernetes API server, it's essential to adapt the configuration dynamically based on the chosen authentication method. This ensures that users provide all necessary credentials specific to their selected method without cluttering the interface with irrelevant fields.

Step 1 — Initialize the Trigger Property

Like in the previous example, take a trigger property on which other properties will depend on. This property should list all potential authentication methods as enum values. In this instance k8sAuthenticationMethod will be used to initiate the display of dependent properties based on the selected authentication method:

<type type="kubernetes.APIServer" label="Kubernetes API Server (Container)" extends="configuration.HttpConnection">
    <property name="k8sAuthenticationMethod" label="Authentication method" kind="enum" default="Token">
        <enum-values>
            <value>Token</value>
            <value>Client Certificate</value>
            <value>OAuth2 Client Credentials</value>
        </enum-values>
    </property>
</type>

Step 2 — Specify Dependent Properties

Now we will define the dependent properties with detailed attributes such as name, label, category, and requirements. These properties are to be displayed based on the value of the authentication method:

<type type="kubernetes.APIServer" label="Kubernetes API Server (Container)" extends="configuration.HttpConnection">
    <property name="k8sAuthenticationMethod" label="Authentication method" kind="enum" default="Token">
        <enum-values>
            <value>Token</value>
            <value>Client Certificate</value>
            <value>OAuth2 Client Credentials</value>
        </enum-values>
    </property>
    <property name="bearerToken" category="Authentication" password="true" kind="string" required="false"/>  
	<property name="clientCrt" category="Authentication" kind="string" required="false" description="Client Certificate file"/>  
	<property name="clientKey" category="Authentication" kind="string" required="false" description="Client Certificate Key"/>
	<property name="tokenUrl" category="Authentication" kind="string" required="false" description="OAuth2 Token Url"/>
	<property name="oauthClientId" category="Authentication" kind="string" required="false" description="Authentication ClientID"/>  
	<property name="oauthClientSecret" category="Authentication" kind="string" required="false" password="true" description="Authentication Client Secret"/>
	<property name="scopes" category="Authentication" kind="string" required="false" description="OAuth2 Scopes"/>
</type>   

Step 3 — Link Dependent Properties to Enum Values

At the end, define a new property that maps dependent properties to their respective enum values. This property, suffixed with _DependentProperties, uses the default attribute to create mappings between each enum value and its related fields. The format for this mapping is structured as default="EnumValue1:dependentProperty1;dependentProperty2,EnumValue2:dependentProperty1...":

<type type="kubernetes.APIServer" label="Kubernetes API Server (Container)" extends="configuration.HttpConnection">
    <property name="k8sAuthenticationMethod" label="Authentication method" kind="enum" default="Token">
        <enum-values>
            <value>Token</value>
            <value>Client Certificate</value>
            <value>OAuth2 Client Credentials</value>
        </enum-values>
    </property>
    <property name="k8sAuthenticationMethod_DependentProperties"  
          category="Authentication"  
          kind="map_string_string"  
          hidden="true"  
          required="false"  
          default="Token:bearerToken,Client&#x20;Certificate:clientCrt;clientKey,OAuth2&#x20;Client&#x20;Credentials:tokenUrl;oauthClientId;oauthClientSecret;scopes"/>
    <property name="bearerToken" category="Authentication" password="true" kind="string" required="false"/>  
	<property name="clientCrt" category="Authentication" kind="string" required="false" description="Client Certificate file"/>  
	<property name="clientKey" category="Authentication" kind="string" required="false" description="Client Certificate Key"/>
	<property name="tokenUrl" category="Authentication" kind="string" required="false" description="OAuth2 Token Url"/>
	<property name="oauthClientId" category="Authentication" kind="string" required="false" description="Authentication ClientID"/>  
	<property name="oauthClientSecret" category="Authentication" kind="string" required="false" password="true" description="Authentication Client Secret"/>
	<property name="scopes" category="Authentication" kind="string" required="false" description="OAuth2 Scopes"/>
</type>

As a result, the connection configuration interface dynamically adjusts to display only the input fields relevant to the selected authentication method. This tailored approach not only simplifies the configuration process but also enhances security by ensuring that all necessary credentials are provided appropriately.