Parameter conditions
In a StyleBook definition, parameters define the input that StyleBook users provide to create a configuration pack. Sometimes, you might want to modify the parameters behavior like the following:
- Show some parameters to a user only if a condition is met.
- The allowed values of one parameter to depend on another parameter.
- Set a parameter as mandatory only under certain conditions.
In these cases, use the parameters-conditions section to define parameter conditions. A parameter condition has the following attributes:
-
target: Specify the parameter to which you want to apply a condition. -
action: Specify what actions to take if the target parameter matches the condition. This feature supports the following actions: -
condition: Specify a condition that has to be met. -
value: Set the values for the target parameters attribute depending on the action.
Note
Currently, the parameter conditions cannot be applied for the parameters within list objects.
‘show’ or ‘hide’
When the action is show and the specified condition returns True, the target parameter appears on the GUI.
When the action is hide and the specified condition returns True, the target parameter disappears from the GUI.
Example:
parameters-conditions:
-
target: $parameters.security-settings.cert-details
action: show
condition: $parameters.protocol in ["SSL", "SSL-BRIDGE"]
<!--NeedCopy-->
At first, the certificate details are hidden for the security-settings parameter. When a user selects SSL or SSL-Bridge protocols, the certificate details appear.
‘set-default’
When the action is set-default and the specified condition returns True, the target parameter’s value is set to the default value.
Example 1:
parameters-conditions:
-
target: $parameters.port
action: set-default
condition: $parameters.protocol == "SSL"
value: 443
-
target: $parameters.port
action: set-default
condition: $parameters.protocol != "SSL"
value: 80
<!--NeedCopy-->
Example 2:
parameters-conditions:
-
target: $parameters.port
action: set-default-value
value: if-then-else($parameters.protocol == "SSL", 443, 80)
<!--NeedCopy-->
When a user selects the SSL protocol, the default port value is set to 443. For other protocols, the default port value is set to 80. Example 1 and 2 gives you the same result.
‘set-required’
When the action is set-required and the specified condition returns True, the target parameter becomes a required field to create a configuration pack.
parameters-conditions:
-
target: $parameters.security-settings.cert-details
action: set-required
condition: $parameters.protocol in ["SSL", "SSL-BRIDGE"]
<!--NeedCopy-->
At first, the certificate details might not be required for the security-settings parameter. When a user selects SSL or SSL-Bridge protocols, the certificate details become a required field to create a configuration pack.
‘set-allowed-values’
When the action is set-allowed-values and the specified condition returns True, the target parameter allows you to select only specified values.
Example-1:
parameters-conditions:
-
target: $parameters.app-name
action: set-allowed-values
value:
- "SSL"
condition: $parameters.lb-virtual-port == 443
<!--NeedCopy-->
When a user specifies 443 as a load-balancer virtual port, the application’s name allows only SSL option.
Example-2;
parameters:
-
name: root-certificates
label: "Root Certificates"
type: object[]
parameters:
-
name: certkey-name
label: "SSL Root CertKey Name"
type: string
required: true
-
name: im-certificates
label: "Intermediate Certificates"
type: object[]
parameters:
-
name: certkey-name
label: "Name of Intermediate CertKey"
type: string
required: true
-
name: link-options
label: "Link to Root or Intermediate CertKey?"
type: string
allowed-values:
- Root
- Intermediate
default: Root
required: true
-
name: link-certkey
label: "Linked to Root/Intermediate CertKey Name"
type: string
required: true
parameters-conditions:
-
repeat: $parameters.im-certificates
repeat-item: imcert
parameters-conditions:
-
target: $imcert.link-certkey
action: set-allowed-values
condition: $imcert.link-options == "Root"
value: $parameters.root-certificates[*].certkey-name
-
target: $imcert.link-certkey
action: set-allowed-values
condition: $imcert.link-options == "Intermediate"
value: $parameters.im-certificates[*].certkey-name
<!--NeedCopy-->
This example is about setting a value for an SSL certificate. The repeat construct in parameter conditions iterates over all the intermediate certificates (im-certificates) and checks the link-options parameter of each certificate.
If the link-options parameter matches a certain value, the allowed values in the link-certkey parameter are added to the respective certificate list.
For example, if the link-options parameter is Root, the allowed values in the link-certkey parameter are added to the root-certificate list.
The following notations are used to add certificates to the list:
-
For root certificates:
$parameters.root-certificates[*].certkey-name <!--NeedCopy--> -
For intermediate certificates:
$parameters.im-certificates[*].certkey-name <!--NeedCopy-->
‘set-label’
When the action is set-label and the specified condition returns True, the target parameter’s label changes to the specified text.
Example:
parameters-conditions:
-
target: $parameters.app-name
action: set-label
value: if-then-else($parameters.lb-service-type == "TCP", "TCPApp","UDPApp")
<!--NeedCopy-->
When a user selects the load-balancer protocol as TCP, the application’s label changes to TCPApp. If the user selects a different option, the application’s label changes to UDPApp.
‘set-description’
When the action is set-description and the specified condition returns True, the target parameter’s description changes to the specified text. This description appears in the tool tip of a target parameter.
Example:
parameters-conditions:
-
target: $parameters.app-name
action: set-description
value: if-then-else($parameters.lb-service-type == "TCP", "Select a TCP application name","Select a UDP application name")
<!--NeedCopy-->
When a user selects the load-balancer protocol as TCP, the application’s tool tip displays a text: Select a TCP application name. If the user selects a different option, the application’s description displays Select a UDP application name.
‘collapse-pane’ or ‘expand-pane’
When the action is collapse-pane and the specified condition returns True, the target parameter’s pane collapses in the GUI.
When the action is expand-pane and the specified condition returns True, the target parameter’s pane expands in the GUI.
Example:
parameters-conditions:
-
target: $parameters.security-settings.cert-details
action: expand-pane
condition: $parameters.protocol in ["SSL", "SSL-BRIDGE"]
<!--NeedCopy-->
At first, the certificate details pane might not be expanded for the security-settings parameter. When a user selects SSL or SSL-Bridge protocols, the certificate details pane expands on the GUI.
‘set-pattern’
When the action is set-pattern and the specified condition returns True, the target parameter field is set to the specified pattern.
Example:
parameters-conditions:
-
target: $parameters.app-name
action: set-pattern
value: "[a-z]+"
<!--NeedCopy-->
In this example, the application’s name allow only lowercase alphabetical characters.
Nested parameter conditions
In a StyleBook definition, you can specify a parameter condition within a parameter condition. These conditions are called as nested parameter conditions and use a repeat construct to define these conditions. The nested parameter conditions are useful when you want to apply an action for a parameter from another parameter.
Example:
parameters-conditions:
-
repeat: $parameters.lbvservers
repeat-item: lbvserver
parameters-conditions:
-
target: $lbvserver.port
action: set-allowed-values
condition: $lbvserver.protocol == "HTTPS"
value: $parameters.ssl-ports
<!--NeedCopy-->
In this example, when the user selects the HTTPS protocol for a load balancing virtual server, the port values are dynamically populated. And, it applies for each load balancing virtual servers in the list.