JSON

To query JSON outputs users can take advantage of a tool called Dq. You can find the complete tutorial of Dq by following this link.

Actions parse,``learn``and``api`` are benefiting from this feature the most, as they are the one that are most likely to have a JSON output. You can query a JSON using Dq and see whether the result of a query is included or excluded in our output.

Below you can see an example of using include and exclude on the parsed output of the command show version.

- apply_configuration:
          - parse:
              command: show version
              device: PE2
              include:

                # we want to se if the result of this query
                # is not a empty dictionary
                - contains('WebUI[\S\s]+', regex=True)
              exclude:

                # The output of the query is 'VIRTUAL XE'
                # but we hope that the key 'platform' has no value
                # or does not exist within the dictionary by using
                # the exclude keyword
                - get_values('platform')

Below you can see an example of calling the get_interface_mtu_config_range api within the trigger_datafile and checking if certain query results are included or excluded in the output.

- apply_configuration:
    - api: #
        function: get_interface_mtu_config_range
        arguments:
            interface: GigabitEthernet1
        include:

            # Check if the output of this query is not an empty dictionary
            - contains('max')

            # Check if the key 'range' has the value of <1200, 1800>
            - contains_key_value('range', <1200, 1800>)
        exclude:

            # Check if the output of these queries are actually an empty dictionary
            - contains('min-max')

Note

There is no need to use Dq to validate if a dictionary output is equal to an expected dictionary. See below example.

# Description: This would check whether the output of the parser is equal to the specified dictionary.
# No Dq query is needed to perform such validation.

- parse:
    device: 'N93_3'
    command: 'show module'
    save:
        - variable_name: banana
          filter: contains('lc')
    include:
        -  {'slot': {'lc': {'2': {'40G Ethernet Expansion Module': {'ports': '12',
            'model': 'N9K-M12PQ',
            'status': 'ok',
            'software': 'NA',
            'hardware': '1.2',
            'slot/world_wide_name': 'GEM',
            'mac_address': '88-1d-fc-71-de-38 to 88-1d-fc-71-de-43',
            'serial_number': 'SAL1928K4EG',
            'online_diag_status': 'Pass'}}},
            'rp': {'1': {'1/10G SFP+ Ethernet Module': {'ports': '48',
               'model': 'N9K-C9396PX',
               'status': 'active',
               'software': '9.3(3)IDI9(0.509)',
               'hardware': '2.2',
                'slot/world_wide_name': 'NA',
                'mac_address': '84-b8-02-f0-83-90 to 84-b8-02-f0-83-c7',
               'serial_number': 'SAL1914CNL6',
               'online_diag_status': 'Pass'}}}}}
        - contains('lc')
        - get_values('rp')

List

It is also possible to check and see if certain items exist within a output that is a list.

- api:
    device: PE1
    function: get_list_items
    arguments:
        name: [1,2,3,4,5,6,7]       # the output is [1,2,3,4,5,6,7]
    include:
        - 5                         # checks if 5 is in the list
    exclude:
        - 99                        # checks if 99 is NOT in the list

Additionally, you can set a regex and see if that regex matches any item within the list output.

- api:
    device: PE1
    function: get_platform_logging
    include:
        - \*Dec 10 03:2.*     # Check if any item within a list matches this regex
        - "23:31:16.651"
    exclude:
        - name                # Check if any item within a list not matches this regex
        - \*Dec 10 03:2.*

Numerical

At this moment, it is only action api that supports this feature, as it is the only action that have integer``and``float outputs.

In below example , we want to verify that the numerical output of get_interface_mtu_size is smaller or equal 2000

# code_block_5

- api: # ACTION
    function: get_interface_mtu_size
    arguments:
        interface: GigabitEthernet1
    include:
        - <= 2000
    ...

For numerical outputs we support all the common mathematical operations {=, >=, <=, >, <, !=}.

You also can check whether a value is within a certain range. Below is an example of this feature. We want to see if the action output is greater than 1200 and smaller or equal 1500.

- api: # ACTION
    function: get_interface_mtu_size
    arguments:
        interface: GigabitEthernet1
    include:
        - ">1200  && <=1500"

If you use the keyword include without specifying any operation the default operation would be set to ==``and by using keyword exclude the operation would be set to!=``. Below you can see an example of this.

- api: # ACTION
    function: get_interface_mtu_size
    arguments:
        interface: GigabitEthernet1
    include:
        - 1500
    exclude:
        - 9999

Boolean

For the actions that have boolean output, it is possible to verify if the output of the action is equal True/False.

In below example, we want to verify if the apis’ output is True.

# code_block_5

- api: # ACTION
    function: verify_device_is_active
    arguments:
        device: PE1
    include:
        - True
    ...