Defining Junos PyEZ Views for Configuration Tables

 

Junos PyEZ configuration Tables can extract specific data from the selected configuration database of a device running Junos OS, or they can define structured resources that can be used to programmatically configure a device running Junos OS. A Table is associated with a View, which is used to select and reference elements in the Table data. You associate a Table with a particular View by including the view property in the Table definition, which takes the View name as its argument.

A View maps your user-defined field names to XML elements in the selected Table items. A View enables you to access specific fields in the data as variables with properties that can be manipulated in Python. Junos PyEZ handles the extraction of the data into Python as well as any type conversion or data normalization.

When retrieving configuration data using Tables that have the get or the set property, the View fields specify which configuration data the application should retrieve for the object. For Tables that include the set property and define resources that you can configure on a device, the fields defined in the View restrict which statements that you can configure for that resource.

Junos PyEZ Views, like Tables, are formatted using YAML. View definitions that are associated with configuration Tables can include a number of parameters, which are summarized in Table 1.

Table 1: Junos PyEZ Configuration View Parameters

View Parameter Name

View Parameter

Table Type

Description

View name

get or set

User-defined View identifier.

Field items

fields

get or set

Associative array, or dictionary, of key-value pairs that map user-defined field names to XPath expressions that select elements in the configuration data. The field names must be valid Python variable names. The XPath expressions are relative to the context defined by the get or set property for that Table.

When the Table scope uses get, the fields identify the data to extract from the configuration. When the Table scope uses set, the fields identify the elements that you can configure or retrieve, depending on the operation.

Field groups

fields_group

get or set

Associative array, or dictionary, of key-value pairs that map user-defined field names to XPath expressions that select elements in the configuration data. The field names must be valid Python variable names. The XPath expressions are relative to the context set by the corresponding groups parameter.

When the Table scope uses get, the fields identify the data to extract from the configuration. When the Table scope uses set, the fields identify the elements that you can configure or retrieve, depending on the operation.

Groups

groups

get or set

Associative array, or dictionary, of key-value pairs that map a user-defined group name to an XPath expression that sets the XPath context for fields in that group. The Xpath expression is relative to the context defined by the get or set property for that Table.

Consider the following Junos PyEZ configuration Tables and Views. UserTable, which includes the get property, extracts configuration data for user accounts on the target device. UserConfigTable, which includes the set property, defines a structured configuration resource that can be used to configure user accounts on the target device as well as retrieve configuration data for user accounts.

The following sections discuss the different components of the View:

View Name

The View name is a user-defined identifier for the View. You associate a Table with a particular View by including the view property in the Table definition and providing the View name as its argument. For example:

Fields (fields)

You customize Views so that they only reference the necessary elements in the selected configuration data. To do this you include the fields property and an associative array containing the mapping of user-defined field names to the XPath expressions that select the desired elements from the configuration Table items. The field names must be valid Python variable names. The XPath expressions are relative to the configuration scope defined by the get or set property in the Table definition.

When retrieving configuration data using Tables that include either the get or the set property, the fields defined in the View identify the statements to extract from the configuration. For Tables that include the set property and define resources that you can configure on a device, the fields identify the statements that you can configure for that resource. You must explicitly define fields for all identifier elements for a configuration resource. These identifier fields are then referenced in the key-field property in the corresponding Table definition.

Consider the following sample configuration hierarchy:

user@router> show configuration system login | display xml

If the Table get or set parameter defines the scope as system/login/user, the XPath expression for each field in the View definition is relative to that context. The following View definition maps the user-defined field names username, userclass, and uid to child elements of the <user> element:

If the Table definition includes the set property, you must explicitly define fields for any identifier elements that uniquely identify the object, which in this case is <name>. The Table’s key-field property must reference all View fields that map to identifier elements for an object. You must always define at least one identifier element in the fields and key-field properties in set Tables.

In the Python script, you can then access a View item as a variable property.

Note

When retrieving configuration data, each object that has a <name> element in the data has a default name property that you can use to access the value for that element.

View fields can include different options depending on the type of the Table that references that View. Tables that define structured configuration resources (set) can include type and constraint checks for each field to ensure that the Junos PyEZ application provides valid data when configuring the resource on a device. Tables that retrieve configuration data (get) can include options that return attribute values for specific elements or that specify the data type to use in the application. Field Options ('get' Tables) and Field Options ('set' Tables) outline the options that can be included when using get and set Tables, respectively.

Field Options ('get' Tables)

Tables that include the get property and solely retrieve configuration data from a device can define a number of options or operators for fields in the associated View. This section outlines the various options.

The field format determines the type for a field’s value. By default, field values are stored as strings. You can specify a different type for the value in the field mapping. The following example defines the value of the uid element to be an integer:

You can also set the field item’s value to a Boolean by using the following syntax:

The element’s value is evaluated against the regular expression passed to regex(). If the element’s value matches the expression, the field item’s value is set to the Boolean defined in the format. In the following example, the superuser field is set to True if the value of the class element contains 'super-user':

Junos PyEZ also provides the group operator for fields in configuration Views. The operator enables you to access the value of the junos:group attribute for elements that are inherited from user-defined groups. This value indicates the group from which that element was inherited.

You include the group operator in the field mapping to reference the value of the junos:group attribute instead of the value of the element. The following example defines the uidgroup and fullgroup fields with the group operator. When you access these field names in a script, the field references the value of the junos:group attribute associated with the uid or full-name element.

Field Options ('set' Tables)

Tables that define structured configuration resources (set) can include type and constraint checks for each field in the associated View to ensure that the Junos PyEZ application provides valid data when configuring the resource on a device. Type checks ensure that the Junos PyEZ application supplies the correct data type when it configures the statements for a specific resource. Constraint checks enable you to define a default value for statements and ensure that the application supplies values that are in the correct range for those statements. The supported type and constraint checks, which are included as options for the fields of the associated View, are outlined in this section.

Table 2 and Table 3 summarize the type and constraint checks, respectively, that you can define for fields in the View of a set configuration Table. Type checks are mutually exclusive, but multiple constraint checks can be defined for each field.

Table 2: Type Checks for 'set' Configuration Tables

type Value

Description

Example

bool

Field only accepts Boolean values of True or False

enable: { 'enable' : { 'type': 'bool' } }

enum

Field only accepts one of the values defined in the enum list

enc : { 'encapsulation' : {'type' : { 'enum' : ['vlan-ccc','vlan-vpls'] }}}

float

Field only accepts floating point values

drift : { 'clock-drift' : { 'type' : 'float' } }

int

Field only accepts integer values

uid: { 'uid' : { 'type' : 'int' } }

str

Field only accepts string values

name: { 'name': {'type': 'str' } }

Table 3: Constraint Checks for 'set' Configuration Tables

Constraint Check Name

Description

Example

default

Default value for a field.

A field uses its default value when the user does not explicitly configure the field. If the user calls the reset() method to reset field values in the application, fields that have a defined default are set to that value.

native_vlan : { 'native-vlan-id' : { 'type' : 'int', 'default' : 501 } }

maxValue

Maximum value for a field, which is interpreted based on the field type.

native_vlan : { 'native-vlan-id' : { 'type' : 'int', 'minValue' : 0, 'maxValue' : 4094 } }

minValue

Minimum value for a field, which is interpreted based on the field type.

native_vlan : { 'native-vlan-id' : { 'type' : 'int', 'minValue' : 0, 'maxValue' : 4094 } }

You can only define a single type check for a field, but you can define multiple constraint checks. Thus a field could include a default value, a minimum value (minValue), and a maximum value (maxValue).

The minValue and maxValue options are interpreted based on the value for the type option. By default, field values are strings. For strings, minValue and maxValue are the minimum and maximum lengths for the string. For integers and floats, the values are the minimum and maximum values for that type.

If you include type or constraint checks for a field, and the user supplies configuration data that fails the checks, the Junos PyEZ application raises the appropriate TypeError or ValueError exception with a message that describes the error.

Groups (groups) and Field Groups (fields_)

Groups provide a shortcut method to select and reference elements within a specific node-set in a Table item.

In the following configuration data, the <authentication> element contains a child element corresponding to the user’s authentication method:

Within the View definition, you can use the fields property to access the child elements by providing the full XPath expression to each element relative to the selected configuration hierarchy. For example, if the Table get or set property selects <user> elements at the [edit system login] hierarchy level, the field item mapping would use the following XPath expression:

Alternatively, you can create a group that sets the XPath context to the <authentication> element and then define field group items that just provide the XPath expression relative to that context. You can define any number of groups within a View definition.

To create a group, include the groups property and map a user-defined group name to the XPath expression that defines the new context. Then define a field group whose name is fields_ followed by the group name. The field group is an associative array containing the mapping of user-defined field names to XPath expressions that now are relative to the context set within groups. The field names must be valid Python variable names.

The following example defines the group auth and the corresponding field group fields_auth. The auth group sets the context to the system/login/user/authentication hierarchy level, and the password field references the value of the encrypted-password element.

Whether you use fields or field groups, you access the value in the same manner within the Junos PyEZ script by using the user-defined field names.