NetScaler® Console service

Substitutions

September 27, 2025

Contributed by:

C S

Substitutions are used to define shorthand names that can replace complex expressions in the StyleBook making the StyleBook more readable.

Substitutions are also useful when the same expression or value is used repeatedly in the StyleBook, for example, a constant value. Using a substitution name for a parameter allows you to update only the substitution value instead of updating all occurrences of the parameter in the StyleBook which might be prone to error.

Substitutions are also used for defining mappings between values as described in examples later in this document.

Each substitution in the list is made up of a key and a value. The value can be a simple value, an expression, a function, or a map.

In the following example, two substitutions are defined. The first one is http-port that can be used as a shorthand for 8181. By using a substitution, you can refer to this in the rest of the StyleBook as $substitutions.http-port instead of 8181.

substitutions:

http-port: 8181

This allows you to specify a mnemonic name to a port number and define this port number in one place in the StyleBook, irrespective of the number of times it is used. If you want to modify the port number to 8080, you can modify it in the substitution section, and the change takes effect wherever the mnemonic name http-port is used. The following example shows how a substitution is used in a component.

components:

 -

     name: my-lbvserver-comp

     type: ns::lbvserver

     properties:

          name: $parameters.name + "-lb"

          servicetype: HTTP

          ipv46: $parameters.ip

          port: $substitutions.http-port

          lbmethod: $parameters.lb-alg
<!--NeedCopy-->

A substitution can also be a complex expression. The following example shows how two substitutions use expressions.

substitutions:

  app-rule: HTTP.REQ.HEADER("X-Test-Application").EXISTS

  app-name: str("acme-") + $parameters.name + str("-app")
<!--NeedCopy-->

A substitution expression can also use existing substitution expressions as shown in the following example.

substitutions:

  http-port: 8181

  app-name: str("acme-") + $parameters.name + str($substitutions.http-port) + str("-app")
<!--NeedCopy-->

Another useful feature of substitutions is maps, where you can map keys to values. The following is an example of a map substitution.

substitutions:

    secure-port:

        true: int("443")

        false: int("80")

    secure-protocol:

        true: SSL

        false: HTTP
<!--NeedCopy-->

The following example shows how to use the maps secure-port and secure-protocol.

components:

 -

     name: my-lbvserver-comp

     type: ns::lbvserver

     properties:

          name: $parameters.name + "-lb"

          servicetype: $substitutions.secure-protocol[$parameters.is-secure]

          ipv46: $parameters.ip

          port: $substitutions.secure-port[$parameters.is-secure]

          lbmethod: $parameters.lb-alg
<!--NeedCopy-->

Here, if the user of the StyleBook specifies the Boolean value “true” to the parameter is-secure, or selects the check box corresponding to this parameter in the NetScaler Console GUI, the servicetype property of this component is assigned the value SSL and the port property is assigned the value 443. However, if the user specifies “false” for this parameter or clears the corresponding check box in the NetScaler Console GUI, the servicetype property is assigned the value HTTP and the port is assigned the value 80.

The following example shows how to use substitutions as a function. A substitution function can take one or more arguments. Arguments can be of simple type for example, string, number, ipaddress, boolean, and other types.

substitutions:

form-lb-name(name): $name + “-lb”

In this example, we define a substitution function “form-lb-name” that takes a string argument called “name” and uses it to create a string that suffixes “-lb” to the string in the name argument. An expression using this substitution function can be written as:

$substitutions.form-lb-name("my")

It returns my-lb

Consider another example:

substitutions:

cspol-priority(priority): 10100 - 100 * $priority

The substitution cspol-priority is a function that takes an argument called priority and uses it to calculate a value. In the rest of the StyleBook, this substitution can be used as shown in the following example:

components:

  -

    name: cspolicy-binding-comp

    type: ns::csvserver_cspolicy_binding

    condition: not $parameters.is-default

    properties:

         name: $parameters.csvserver-name

         policyname: $components.cspolicy-comp.properties.policyname

         priority: $substitutions.cspol-priority($parameters.pool.priority)
<!--NeedCopy-->

The following is an example of a substitution called slist whose value is a list:

substitutions:

  slist:

    - a

    - b

    - c
<!--NeedCopy-->

The value of a substitution can also be a dictionary of key-value pairs as seen in the following example of a substitution called sdict below:

substitutions:

  sdict:

    a: 1

    b: 2

    c: 3
<!--NeedCopy-->

You can create more complex attributes by combining the lists and dictionaries. For example, a substitution called slistofdict returns a list of key - value pairs.

  slistofdict:

    -

      a: $parameters.cs1.lb1.port

      b: $parameters.cs1.lb2.port

    -

      a: $parameters.cs2.lb1.port

      b: $parameters.cs2.lb2.port
<!--NeedCopy-->

But, in the following example, a substitution sdictoflist returns a key-value pair, where the value itself is another list.

  sdictoflist:

    a:

      - 1

      - 2

    b:

      - 3

      - 4
<!--NeedCopy-->

In components, these substitutions may be used in condition, properties, repeat, repeat-condition constructs.

The following example of a component shows how a substitution can be used to specify the properties:

    properties:

      a: $substitutions.slist

      b: $substitutions.sdict

      c: $substitutions.slistofdict

      d: $substitutions.sdictoflist
<!--NeedCopy-->

A use case for defining a substitution whose value is a list or a dictionary is when you are configuring a content switching virtual server and multiple load balancing virtual servers. Since all lb virtual servers tied to the same cs virtual server might have an identical configuration, you can use the substitution list and dictionary to build this configuration to avoid repeating that configuration for each lb virtual server.

The following example shows the substitution and the component in the cs-lb-mon StyleBooks to create a content switching virtual server configuration. While constructing the properties of cs-lb-mon StyleBooks, the complex substitution “lb-properties” specifies the properties of the lb virtual servers associated with the cs virtual server. The “lb-properties” substitution is a function that takes the name, service type, virtual IP address, port, and servers as parameters and generates a key-value pair as the value. In cs-pools component, we assign the value of this substitution to a lb-pool parameter for each pool.

substitutions:

  cs-port[]:

    true: int("80")

    false: int("443")

  lb-properties(name, servicetype, vip, port, servers):

    lb-appname: $name

    lb-service-type: $servicetype

    lb-virtual-ip: $vip

    lb-virtual-port: $port

    svc-servers: $servers

    svc-service-type: $servicetype

    monitors:

      -

        monitorname: $name

        type: PING

        interval: $parameters.monitor-interval

        interval_units: SEC

        retries: 3

components:

  -

    name: cs-pools

    type: stlb::cs-lb-mon

    description: | Updates the cs-lb-mon configuration with the different pools provided. Each pool with rule result in a dummy LB vserver, cs action, cs policy, and csvserver_cspolicy_binding configuration.

    condition: $parameters.server-pools

    repeat: $parameters.server-pools

    repeat-item: pool

    repeat-condition: $pool.rule

    repeat-index: ndx

    properties:

      appname: $parameters.appname + "-cs"

      cs-virtual-ip: $parameters.vip

      cs-virtual-port: $substitutions.cs-port($parameters.protocol == "HTTP")

      cs-service-type: $parameters.protocol

      pools:

        -

          lb-pool: $substitutions.lb-properties($pool.pool-name, "HTTP", "0.0.0.0", 0, $pool.servers)

          rule: $pool.rule

          priority: $ndx + 1
<!--NeedCopy-->

Substitution map

You can create substitutions that map keys to values. For example, consider a scenario where you want to define the default port (value) to be used for each protocol (key). For this task, write a substitution map as follows.

substitutions:

     port:

          HTTP: 80

          DNS: 53

          SSL: 443
<!--NeedCopy-->

In this example, HTTP is mapped to 80, DNS is mapped to 53, and SSL is mapped to 443. To retrieve the port of a certain protocol that is given as a parameter, use the expression

$substitutions.port[$parameters.protocol]

The expression returns a value based on the protocol specified by the user.

If the key is HTTP, the expression returns 80
If the key is DNS, the expression returns 53
If the key is SSL, the expression returns 443
If the key is not present in the map, the expression does not return any value

Iterate through substitution lists

In the following example, the StyleBook iterates through a substitution list called apps to create a set of lbvserver components and their corresponding service groups and bound servers.

substitutions:
  apps:
    -
      name: lb1
      vip: 1.2.3.4
      vport: 80
      protocol: HTTP
      servers:
        -
          ip: 10.8.11.11
          port: 8080
        -
          ip: 10.8.11.12
          port: 8080
    -
      name: lb2
      vip: 1.2.3.5
      vport: 81
      protocol: HTTP
      servers:
        -
          ip: 10.9.11.28
          port: 8080
        -
          ip: 10.9.11.29
          port: 8181
components:
  -
    name: lbvserver-comp
    type: ns::lbvserver
    repeat: $substitutions.apps
    repeat-item: app
    properties:
      name: $app["name"]
      ipv46: $app["vip"]
      port: $app["vport"]
      servicetype: $app["protocol"]
    components:
      -
        name: servicegroup-comp
        type: ns::servicegroup
        properties:
          servicegroupname: $parent.properties.name + "-svg"
          servicetype: HTTP
        components:
          -
            name: servers-comp
            type: ns::server
            repeat: $app["servers"]
            repeat-item: server
            properties:
              name: $server["ip"]
              ipaddress: $server["ip"]
            components:
              -
                name: servicegroup-servicegroupmember-binding-comp
                type: ns::servicegroup_servicegroupmember_binding
                properties:
                  servicegroupname: $parent.parent.properties.servicegroupname
                  servername: $parent.properties.name
                  port: $server["port"]
<!--NeedCopy-->

The official version of this product documentation is in English. Any non-English version is solely provided for your convenience and may include machine-translated content. For more information, please refer to the Machine Translation Disclaimer on Cloud Software Group home.

Was this helpful

NetScaler Secure Deployment Guide

Substitutions

September 27, 2025

Contributed by:

C S

September 27, 2025

Contributed by:

C S

Substitutions

Substitution map

Iterate through substitution lists

In this article