Templates

The idea is to start off by writing a device-template, apply it and inspect the changes to the devices, modify the template and do the same over again until the desired result is reached.

Create a device template l3vpn-ce, add some settings to it and commit the changes:

admin@ncs(config)# devices template l3vpn-ce config ios:interface GigabitEthernet 0/1
admin@ncs(config)# description "Link to PE"
admin@ncs(config)# ip address primary address 10.1.1.1 mask 255.255.255.252

Apply the device-template to the ce0 device and check the changes by doing a dry run using the native out format of the device:

admin@ncs(config)# devices device ce0 apply-template template-name l3vpn-ce
admin@ncs(config)# commit dry-run outformat native
native {
    device {
        name ce0
        data interface GigabitEthernet0/1
              description Link to PE
              ip address 10.1.1.1 255.255.255.252
             exit
    }
}

If you spot an error, revert the changes done by the template, add the missing configuration to the template and commit.

When you are satisfied with the result, save the device-template to a file:

admin@ncs(config)#
        show full-configuration devices template l3vpn-ce | display xml | save l3vpn-ce.xml

Pick up the file l3vpn-ce.xml in any editor. Change the beginning of the file from:

<config xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
  <template>
    <name>l3vpn-ce</name>

to:

<config-template xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
    <device>
      <name>ce0</name>

Note the name of the device, it just serves as an example. The device name can be a static value, an XPath variable or the result of an XPath expression.

At the end the XML elements needs to be closed, change from:

    </template>
  </devices>
</config>

to:

    </device>
  </devices>
</config-template>

The final result should look like Example 120, “Created Config-template l3vpn-ce.xml”.

The idea is to make direct changes to the configuration and dry-run the changes to confirm the right commands are sent to the devices. From these changes a template can, as shown below. be constructed.

Make changes:

admin@ncs(config)# devices device ce0 config ios:interface GigabitEthernet 0/1
admin@ncs(config)# description "Link to PE"
admin@ncs(config)# ip address 10.1.1.1 255.255.255.252

Check that modifications of the network is the desired. Here is what is actually sent to the device by using the native format:

admin@ncs(config)# commit dry-run outformat native
native {
    device {
        name ce0
        data interface GigabitEthernet0/1
              description Link to PE
              ip address 10.1.1.1 255.255.255.252
             exit
    }
}

The same changes in the XML format serves as a good skeleton for a template. Save the modifications to a file:

admin@ncs(config)# commit dry-run outformat xml | save l3vpn-ce.xml

pick up the file l3vpn-ce.xml in any text editor. Remove the leaf name result-xml. Insert the template specific tag at the beginning of the file:

<config-template xmlns="http://tail-f.com/ns/config/1.0"
  <devices xmlns="http://tail-f.com/ns/ncs">

and to close the XML put at the end of the file:

  </devices>
</config-template>

The final result should look like Example 120, “Created Config-template l3vpn-ce.xml”.

<config-template xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
    <device>
      <name>ce0</name>
        <interface xmlns="urn:ios">
          <GigabitEthernet>
            <name>0/1</name>
            <description>Link to PE</description>
            <ip>
              <address>
                <primary>
                  <address>10.1.1.1</address>
                  <mask>255.255.255.252</mask>
                </primary>
              </address>
            </ip>
          </GigabitEthernet>
        </interface>
    </device>
  </devices>
</config-template>

Each value in a template is stored as a string. This string value is converted to the actual value type of the YANG model when the template is applied.

If the value contains a pair of {...} the string between the curly braces is treated as an XPath 1.0 expression. The simplest form of an XPath expression is a plain XPath variable:

<config-template xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
    <device>
      <name>{$CE}</name>
      ...
    </device>
  </devices>
</config-template>

Any value assigned to the variable CE, which can be done via the Java API, will be used when the template is applied:

...
TemplateVariables var = new TemplateVariables();
var.putQuoted("CE","ce0");
...

A value can contain any number of {...} and strings, the total result will be the concatenation of all the strings and all the XPath expressions.

<config-template xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
    <device>
      <name>{$CE}</name>
      ...
      <config>
      <interface xmlns="urn:ios">
        <GigabitEthernet>
        ...
        <description>Link to PE / {$PE} - {$PE_INT_NAME}</description>
    </device>
  </devices>
</config-template>

This would for example, when applied, evaluate the XPath expressions {$PE} and {$PE_INT_NAME} to "pe0" and "GigabitEthernet0/0/0/3". giving the the total result of

        <description>Link to PE / pe0 - GigabitEthernet0/0/0/3</description>

As the text between the {...} is an XPath 1.0 expression we can select any reachable node:

/endpoint/ce/device

this selects a leaf node, device. The value of the selected leaf will be used to assign a new value where it is used when the template is applied.

The result of a selection is internally converted to string representation. All concatenations are done on strings. When the string value is assigned to a leaf element a string to value conversion takes places in the context of the target node.

If the result of the selection is an empty node-set nothing is set.

NSO template engine supports a number of processing instructions to allow for more dynamic templates. The following table lists the available processing instructions.

The variable value in both set and for processing instructions is evaluated in the same way as the values within XML tags in a template (see the section called “Values in a template”). So, it can be a mix of literal values and XPath expressions surrounded by {...}.

The variable value is always stored as a string, so any XPath expression will be converted to literal using XPath string() function. Namely, if the expression results in an integer or a boolean, then the resulting value would be a string representation of the integer or boolean. If the expression results in a node-set, then the value of the variable is a concatenated string of values of nodes in this node-set.

It is important to keep in mind that while in some cases XPath converts the literal to another type implicitly (for example, in an expression {$x < 3} a possible value x='1' would be converted to integer 1 implicitly), in other cases an explicit conversion is needed. For example, in the following expression {$x > $y} if x='9' and y='11', then the result of the expression is true due to alphabetic order. In order to compare the values as numbers an explicit conversion of at least one argument is required: {number($x) > $y}.

When the evaluation of a template starts the XPath context node is set to the root of the service instance data that was created as described above.

The root context node can also be changed from within template with help of set-root-node processing instruction. It takes an XPath expression as a parameter, and this expression is evaluated in a special context, where the root node is the root of the datastore. This makes it possible to change to a node outside the current evaluation context. For example: <?set-root-node {/}?> changes the accessible tree to the whole datastore. As with other processing instruction, the effect of set-root-node only applies until the closing parent tag.

Under certain criteria the evaluation context node is changed to make it easier to work with lists in the templates. To understand the evaluation of templates it is important to understand how and when the context node is changed.

The evaluation context will change if the value being set in the template is the key of a list, and the XPath expression evaluates to a node set. However if the expression evaluates to a value, the context will not change. To explain the algorithm above, let's look at the following example.

The device YANG model has the following snippet.

container vrf {
 list definition {
    key "name";
    leaf name {
      type string;
    }
  }
}

If the template looks like this:

<vrf xmlns="urn:ios" tags="merge">
  <definition>
    <name>{/vpn-service[name='volvo']/leg[node='branch']/name}</name>
    <rd>{as-number}:1</rd>
  </definition>
</vrf>

Since /vpn-service[name='volvo']/leg[node='branch']/name evaluates to a node, the evaluation context node will be changed to the parent of that node. I.e. /vpn-service[name='volvo']/leg[node='branch']. This means that the second template parameter {as-number} will be relative to the context change, i.e. /vpn-service[name='volvo']/leg[node='branch']/as-number

In some cases it is not desirable to change the context. This can be achieved by forcing the XPath expression to be evaluated to a value rather than a node. If the template looks like this:

<vrf xmlns="urn:ios" tags="merge">
  <definition>
    <name>{string(/vpn-service[name='volvo']/leg[node='branch']/name)}</name>
    <rd>{as-number}:1</rd>
  </definition>
</vrf>

The XPath function string() is used within the first expression. This evaluates to a value which means the context will remain unchanged. This also means that the second template parameter {as-number} will still be relative to what the context was before, i.e. it remains unchanged.

Another way to write the latter example would be:

<vrf xmlns="urn:ios" tags="merge">
  <?set-root-node {.}?>
  <definition>
    <name>{/vpn-service[name='volvo']/leg[node='branch']/name}</name>
    <rd>{/as-number}:1</rd>
  </definition>
</vrf>

This example temporarily changes the accessible tree to the subtree under the current context node which makes it easier to write paths under the current node. The accessible tree is restored after the closing </vrf> tag.

It is also possible to change the current context node using the processing instruction context. For example: <?set-context-node {..}?> will change the context node to the parent of the current context node.

Sometimes it is necessary to control which parts of a template that should be evaluated. The if and elif processing instructions make it possible to set a conditional statement that controls if the sub-tree should be evaluated or not.

<policy-map xmlns="urn:ios" tags="merge">
  <name>{$POLICY_NAME}</name>
  <class>
    <name>{$CLASS_NAME}</name>
    <?if {qos-class/priority = 'realtime'}?>
      <priority-realtime>
        <percent>{$CLASS_BW}</percent>
      </priority-realtime>
    <?elif {qos-class/priority = 'critical'}?>
      <priority-critical>
        <percent>{$CLASS_BW}</percent>
      </priority-critical>
    <?else?>
      <bandwidth>
        <percent>{$CLASS_BW}</percent>
      </bandwidth>
    <?end?>
    <set>
      <ip>
        <dscp>{$CLASS_DSCP}</dscp>
      </ip>
    </set>
  </class>
</policy-map>

The template example above shows the use of the if, elif and else processing instructions to select between tags priority-realtime, priority-critical and bandwidth. The sub-tree containing the priority-realtime tag will only be evaluated if the XPath statement, qos-class/priority, in the if processing instruction evaluates to the string 'realtime'. The subtree under the elif processing instruction will be executed if the preceding if expression evaluated to false, i.e. qos-class/priority is not equal to the string 'realtime', and the XPath statement inside of the elif processing instruction evaluates to the string 'critical'. The subtree under the else processing instruction will be executed when both the preceding if and elif expressions evaluated to false, i.e. qos-class/priority is neither equal to the string 'realtime' nor 'critical'.

The evaluation of the XPath statements used in the if and elif processing instructions follow the XPath standard for computing boolean values. In summary the conditional expression will evaluate to false when:

Sometimes statements in a sub-tree needs to be applied several times. foreach and for processing instructions can be used to accomplish this iteration.

<ip xmlns="urn:ios">
  <route>
    <vrf>
      <name>VPN{/vpn-number}</name>
      <?foreach {tunnel}?>
        <ip-route-forwarding-list>
          <prefix>{network}</prefix>
          <mask>{netmask}</mask>
          <forwarding-address>10.255.254.{(tunnel-number-1)*4+2}</forwarding-address>
        </ip-route-forwarding-list>
      <?end?>
    </vrf>
  </route>
</ip>

The template example above shows the use of the foreach processing instruction to populate the list ip-route-forwarding-list. If the result of the XPath expression tunnel is a non-empty node-set then the sub-tree containing ip-route-forwarding-list tag will be evaluated for every node in that node-set.

For each iteration the initial context will be set to the node in that iteration. The XPath function current() can be used to retrieve that initial context.

There can be only one XPath statement in the foreach processing instruction and the result needs to be a node-set, not a simple value. It is however possible to use XPath union operator to join multiple node-sets in a single expression: {some-list-1 | some-leaf-list-2}

for is a processing instruction that allows to control flow by means of changing a variable rather than changing context node. For example, the following template snippet could be used to disable a range of interfaces:

          <interface xmlns="urn:ios">
            <?for i=0; {$i < 4}; i={$i + 1}?>
              <FastEthernet>
                <name>0/{$i}</name>
                <shutdown/>
              </FastEthernet>
            <?end?>
          </interface>

In this example the for keyword is followed by three semicolon-separated clauses with the following meaning:

When a device makes itself known to NSO it presents a list of capabilities, see: the section called “Capabilities, Modules and Revision Management” in NSO 5.7 User Guide, which includes what YANG modules that particular device support. Since each YANG module define a unique namespace, this information can be used in a Template. Hence, a Template may refer to many diverse devices, where only those pieces of the Template with a matching namespace will be applied for a particular device.

Templates allow for defining different behaviour when applying the template. This is accomplished by setting tags, as an attribute. Existing tags are: merge, replace, delete, create or nocreate on relevant nodes in the template.

Tags mergemerge and nocreate are inherited to their sub-nodes until a new tag is introduced. Tag delete applies only to the current node and any children (except keys specifying the list/leaf-list entry to delete) are ignored. Tags create and replace are not inherited and only apply to the node they are specified on. Children of the nodes with create or replace tags have merge behaviour.

For ordered-by user lists and leaf-lists, the insert attribute can be used to specify where in the list, or leaf-list, the node should be inserted. You need to specify if the node should be inserted first or last in the node-set, or before or after a specific instance. For example, if you have a list of rules where order is important>

...
<rule insert="first">
  <name>{$FIRSTRULE}</name>
  ...
</rule>
...
<rule insert="last">
  <name>{$LASTRULE}</name>
  ...
</rule>
...
<rule insert="after" value={$FIRSTRULE}>
  <name>{$SECONDRULE}</name>
  ...
</rule>
...
<rule insert="before" value={$LASTRULE}>
  <name>{$SECONDTOLASTRULE}</name>
  ...
</rule>
...

It is not uncommon that there are multiple services managing the same ordered-by user list or leaf-list. The relative order of elements inserted by these services might not matter, but there are constraints on element positions that need to be fulfilled. Following the list of rules example, suppose that initially the list contains only the "deny-all" rule:

<rule>
  <ip>0.0.0.0</ip>
  <mask>0.0.0.0</mask>
  <action>deny</action>
</rule>

There are services that prepend permit rules to the beginning of the list using insert="first" operation. If there are two services creating one entry each, 10.0.0.0/8 and 192.168.0.0/24 respectively, then the resulting configuration looks like:

<rule>
  <ip>192.168.0.0</ip>
  <mask>255.255.255.0</mask>
  <action>permit</action>
</rule>
<rule>
  <ip>10.0.0.0</ip>
  <mask>255.0.0.0</mask>
  <action>permit</action>
</rule>
<rule>
  <ip>0.0.0.0</ip>
  <mask>0.0.0.0</mask>
  <action>deny</action>
</rule>

If we now try to check-sync the first service (10.0.0.0/8), then it will report out-of-sync, and re-deploying it would move the 10.0.0.0/8 rule first. But all we want is for the deny-all rule to be last. This is when guard attribute comes in handy. If both insert and guard attributes are specified on a list entry in template, then the template engine will first check whether the list entry already exists in the resulting configuration between the target position (as indicated by the insert attribute) and the position of an element indicated by the guard.

So, assuming the following data model in the example above

...
list rule {
  key "ip mask";
  ordered-by user;
  leaf ip {
    type inet:ipv4-address;
  }
  leaf mask {
    type inet:ipv4-address;
  }
  leaf action {
    type enumeration {
      enum permit;
      enum deny;
    }
    mandatory true;
  }
...
}
...

The template could look as following:

...
<rule insert="first" guard="0.0.0.0 0.0.0.0">
  <ip>{$IP}</ip>
  <mask>{$MASK}</mask>
  <action>permit</action>
</rule>
...

A guard can be specified literally (e.g. guard="0.0.0.0 0.0.0.0" if "ip mask" is the key of the list) or using an XPath expression (e.g. guard="{$GUARDIP} {$GUARDMASK}"). If the guard evaluates to a node-set consisting of multiple elements, then only the first element in this node-set is considered as the guard. The constraint defined by the guard is evaluated as follows:

Sometimes there is a need of some extra information when applying templates in order to understand what is going on. When applying or committing a template there is a cli pipe command debug that enables debug information:

admin@ncs(config)# commit dry-run | debug template

admin@ncs(config)# commit dry-run | debug xpath

debug template will output XPath expression results from the template, under which context it is evaluated, what operation is used and how it effects the configuration, for all templates invoked. It can be narrowed down to only show debugging information for a specific template:

admin@ncs(config)# commit dry-run | debug template l3vpn

debug xpath will output all XPath evaluations for the transaction, and is not limited to the XPath expressions inside templates.

Template and xpath debugging can be combined:

admin@ncs(config)# commit dry-run | debug template | debug xpath

admin@ncs(config)# commit dry-run | debug template
Evaluating "/endpoint/ce/device" (from file "l3vpn.xml", line 5)
Context node: /vpn/l3vpn[name='volvo']
Result:
For /vpn/l3vpn[name='volvo']/endpoint[id='c1']/ce, it evaluates to "ce0"
For /vpn/l3vpn[name='volvo']/endpoint[id='c2']/ce, it evaluates to "ce2"
Operation 'nocreate' on node /devices/device[name='ce0'] (from file "l3vpn.xml", line 5)
Node exists, continuing...
...

4  <device tags="nocreate" >
5   <name>{/endpoint/ce/device}</name>
6   <config tags="merge">

Operation 'merge' on non-existing node: /devices/device[name='ce0']/.../description
(from file "l3vpn.xml", line 11)
Fetching literal "Link to PE" (from file "l3vpn.xml", line 11)
Setting /devices/device[name='ce0']/../description to "Link to PE"

11  <description tags="merge">Link to PE</description>

Operation 'nocreate' on node /devices/device[name='pe2']
(from file "l3vpn.xml", line 52)
Node exists, continuing...
The device /devices/device[name='pe2'] does not support
namespace 'urn:ios' for node "interface" (from file "l3vpn.xml", line 69)

69  <interface xmlns="urn:ios" tags="nocreate">

% show full-configuration devices device c0 config ios:interface  | display xpath
/devices/device[name='c0']/config/ios:interface/FastEthernet[name='1/0']
/devices/device[name='c0']/config/ios:interface/FastEthernet[name='1/1']
/devices/device[name='c0']/config/ios:interface/FastEthernet[name='1/2']
/devices/device[name='c0']/config/ios:interface/FastEthernet[name='2/1']
/devices/device[name='c0']/config/ios:interface/FastEthernet[name='2/2']

$ ncs_cmd -c \
  "x /devices/device[name='c0']/config/ios:interface/FastEthernet/name"
/devices/device{c0}/config/interface/FastEthernet{1/0}/name [1/0]
/devices/device{c0}/config/interface/FastEthernet{1/1}/name [1/1]
/devices/device{c0}/config/interface/FastEthernet{1/2}/name [1/2]
/devices/device{c0}/config/interface/FastEthernet{2/1}/name [2/1]
/devices/device{c0}/config/interface/FastEthernet{2/2}/name [2/2]

$ tail -f logs/xpath.trace

Service templates can define macros - named XML snippets that can be expanded in the template. The example template shown in Example 122, “Service to Device Model mapping using Templates” can also be written to define and use macros, as shown in Example 125, “Service Template using Macros”

M   1:<config-template xmlns="http://tail-f.com/ns/config/1.0"
M   2:  servicepoint="l3vpn-template">
M   3:    <?macro GbEth name='{interface-number}' mask='255.255.255.0' desc?>
M   4:    <GigabitEthernet tags="nocreate">
M   5:      <name>$name</name>
M   6:      <description tags="merge">$desc</description>
M   7:      <ip tags="merge">
M   8:        <address>
M   9:          <primary>
M  10:            <address>{ip-address}</address>
M  11:            <mask>$mask</mask>
M  12:          </primary>
M  13:        </address>
M  14:      </ip>
M  15:    </GigabitEthernet>
M  16:    <?endmacro?>
M  17:
M  18:    <?macro GbEthWithVrf name='{interface-number}'
M  19:        mask=255.255.255.252 desc forwarding?>
M  20:      <?expand GbEth name=$name desc='$desc' mask=$mask?>
M  21:      <GigabitEthernet tags="nocreate">
M  22:        <name>$name</name>
M  23:        <vrf tags="merge">
M  24:          <forwarding>$forwarding</forwarding>
M  25:        </vrf>
M  26:      </GigabitEthernet>
M  27:    <?endmacro?>
M  28:
M  29:  <devices xmlns="http://tail-f.com/ns/ncs">
M  30:    <?foreach {endpoint/ce}?>
M  31:      <device tags="nocreate">
M  32:        <name>{device}</name>
M  33:        <config tags="merge">
M  34:          <!-- CE template for Cisco IOS routers -->
M  35:          <interface xmlns="urn:ios">
M  36:            <?foreach {link}?>
M  37:              <?expand GbEth descr='Link to PE' mask='255.255.255.252'?>
M  38:            <?end?>
M  39:            <?foreach {local}?>
M  40:              <?expand GbEth descr='Local network'?>
M  41:            <?end?>
M  42:          </interface>

              ...

M  57:        </config>
M  58:      </device>
M  59:    <?end?>

          ...

M 185:  </devices>
M 186:</config-template>}

Macro definitions and usage should adhere to the following rules.

When reporting errors, if the template uses macros, the line numbers for the macro invocations are also included, so that the actual location of the error can be traced. For example, an error message could be something like service.xml:19:8 Invalid parameters for processing instruction set. - this means that there was a macro expansion on line 19 in service.xml and an error occurred at line 8 in the file defining that macro.

Pre- and post-modification templates are applied before and after, respectively, applying the service template. The template displayed in Example 126, “Post Modification Template”, demonstrates how to define a post-modification callback using a template for the service template defined in Example 122, “Service to Device Model mapping using Templates”. Pre-modification templates are defined similarly but with the cbtype attribute set to pre-modification instead of post-modification. The $OPERATION variable is set internally by NSO in pre- and post-modification templates and contains the service operation, i.e., create, update or delete, that triggered the callback. The $OPERATION variable can be used together with template conditional statements (see the section called “Conditional Statements”) to apply different parts of the template depending on the triggering operation.

For more information on service pre- and post-modification callbacks, refer to the section called “ Pre and post hooks ”.

1: <config-template xmlns="http://tail-f.com/ns/config/1.0"
2:  servicepoint="l3vpn-template"
3:  cbtype="post-modification">
4:   <?if {$OPERATION = 'create'}?>
5:      <devices xmlns="http://tail-f.com/ns/ncs">
6:        <device>
7:          <name>{/device}</name>
8:          <config>

            ...

15:         </config>
16:       </device>
17:     </devices>
18:   <?else?>
19:     <?if {$OPERATION = 'update'}?>

         ...

21:     <?else?>
22:       <!-- $OPERATION = 'delete' -->

          ...

30:     <?end?>
31:   <?end?>
32: </config-template>

A feature template is a config-template used to configure a specific feature. By using feature templates, the service code can be completely device-vendor agnostic. Feature templates is a nice way to decompose a problem into smaller, reusable, chunks.

In the example $NCS_DIR/examples.ncs/service-provider/mpls-vpn a l3vpn-acl template is used to create ACL entries for all service specific match rules, and is applied from the Java service code. Below you will find the l3vpn-acl.xml as well as parts of the Java logic which shows how the template variables are set and then how the template is applied.

The l3vpn-acl template:

<config-template xmlns="http://tail-f.com/ns/config/1.0">
  <devices xmlns="http://tail-f.com/ns/ncs">
    <device tags="nocreate">
      <name>{$CE}</name>
      <config>
        <ip xmlns="urn:ios" tags="merge">
          <access-list>
            <extended>
              <ext-named-acl>
                <name>{$ACL_NAME}</name>
                <ext-access-nlist-rule>
                  <rule>permit {$PROTOCOL} {$SOURCE_IP_ADR}
                  {$SOURCE_WMASK} {$DEST_IP_ADR} {$DEST_WMASK}
                  range {$PORT_START} {$PORT_END}</rule>
                </ext-access-list-rule>
              </ext-named-acl>
            </extended>
          </access-list>
        </ip>
      </config>
    </device>
  </devices>
</config-template>

The setting of the variables and applying of the template from Java code:

private TemplateVariables setAclVars(NavuContainer match,
                                    String namePrefix)
    throws NavuException, UnknownHostException {
    TemplateVariables aclVar = new TemplateVariables();

    aclVar.putQuoted("ACL_NAME", namePrefix + "-" +
                                match.leaf("name").
                                   valueAsString());
    aclVar.putQuoted("PROTOCOL", match.leaf("protocol").
        valueAsString());
    aclVar.putQuoted("SOURCE_IP", match.leaf("source-ip").
            valueAsString());
    if ("any".equals(match.leaf("source-ip").valueAsString())) {
        aclVar.putQuoted("SOURCE_IP_ADR","any");
        aclVar.putQuoted("SOURCE_WMASK"," ");
    }
    else {
        aclVar.putQuoted("SOURCE_IP_ADR",
                getIPAddress(match.leaf("source-ip").
                        valueAsString()));
        aclVar.putQuoted("SOURCE_WMASK",
                prefixToWildcardMask(getIPPrefix(
                        match.leaf("source-ip").
                        valueAsString())));
    }
    if ("any".equals(match.leaf("destination-ip").
            valueAsString())) {
        aclVar.putQuoted("DEST_IP_ADR","any");
        aclVar.putQuoted("DEST_WMASK"," ");
    }
    else {
        aclVar.putQuoted("DEST_IP_ADR",
                getIPAddress(match.leaf("destination-ip").
                        valueAsString()));
        aclVar.putQuoted("DEST_WMASK",
                prefixToWildcardMask(getIPPrefix(
                        match.leaf("destination-ip").
                        valueAsString())));
    }
    aclVar.putQuoted("PORT_START", match.leaf("port-start").
            valueAsString());
    aclVar.putQuoted("PORT_END", match.leaf("port-end").
            valueAsString());
    return aclVar;
}
...
    TemplateVariables aclVar = setAclVars(match,namePrefix);
    aclTemplate.apply(service, aclVar);
...

There is a well-known mechanism to pass parameters to a template via API which is template variables. One limitation of this mechanism is that a variable can only hold one string value. However sometimes there is a need to pass not just one value, but a list, map or even more complex data structure from API to be accessible in the template.

One way to handle this is to use smaller templates with variables and invoke them repeatedly passing the parameters from the list one by one, or pair by pair in case of a map. However there are certain disadvantages with this approach. One of them is the performance: every invocation of the template from the API requires a context switch between the user application process and NSO core process, which can be costly. Another disadvantage is that the logic of the service is split between Java/Python code and the template, which makes it harder to write and understand such services.

An approach suggested in this section involves modelling the auxiliary data used by the service as operational data and populating it by the service code in Java or Python. After that the service callback passes control to the template that handles main service logic. Such auxiliary data would then be available to select by means of XPath, just like any other service input data.

There could be different approaches to modelling the auxiliary data. It can reside in the service tree as it is private to the service instance: either integrated in the existing data tree, or as a separate subtree under the service instance. It can also be located outside of the service instance, however it is important to keep in mind that operational data cannot be shared by multiple services because there is no refcounters or backpointers stored on operational data.

After the service is deployed, the auxiliary leafs remain in the database which facilitates debugging because they can be seen via all northbound interfaces. If this is not the intention, they can be hidden with help of tailf:hidden statement. Because operational data is also a part of FASTMAP diff, these values will be deleted when the service is deleted and need to be recomputed when the service is re-deployed. This also means that in most cases there should be no need to write any additional code to clean up this data.

One example of a task that is hard to solve in the template itself using native XPath functions is converting a network prefix into a network mask or vice versa. Below is a snippet of data model that is part of a service input data and contains a list of interfaces along with IP addresses to be configured on those interfaces. If the format of the IP address on the input is an IP address with prefix but the device accepts an IP address with network mask instead, then we can use an auxiliary leaf mask to be able to convert prefix to the suitable format before the service template takes control.

list interface {
  key name;
  leaf name {
    type string;
  }
  leaf address {
    type tailf:ipv4-address-and-prefix-length;
    description
      "IP address with prefix in the following format, e.g.: 10.2.3.4/24";
  }
  leaf mask {
    config false;
    type inet:ipv4-address;
    description
      "Auxiliary data populated by service code, represents network mask
       corresponding to the prefix in the address field, e.g.: 255.255.255.0";
  }
}

The service code would need to populate the mask. It uses NAVU API in this example to do that, but if the list is known to be large it might be useful to use Maapi.setValues() instead to set the leafs in one go.

          for (NavuListEntry interface : interfaces) {
            String address = interface.leaf("address").valueAsString();
            String prefix = address.split("/")[1];
            String mask = prefixToNetMask(prefix);
            // sharedSet() does not take effect on operational data
            // using set() instead
            interface.leaf("mask").set(mask);
          }
          ...
          // TemplateVariables don't need to contain mask
          // it is passed via database
          TemplateVariables tv = new TemplateVariables();
          template.apply(service, tv);

The template would then do the following:

          <interface>
            <name>{/interface/name}</name>
            <ip-address>{substring-before(address, '/')}</ip-address>
            <ip-mask>{mask}</ip-mask>
          </interface>