Getting Started

This section will walk users through some common tasks including how to navigate around the objects within the Network model, lookup and/or set network object properties as well as leverage the simulation capabilities of Design. Sample code snippets are provided that can be run from within the WAE environment to further help users gain experience with the API.

Network Model Access

The OPM API attempts to follow a properties-based design, that is to say that object properties rather than methods are used for interacting with the model. Access to the network model and all of its network objects requires very few lines of code using the OPM Python API as will be seen in the sample code in this section. The following code snippet in Example 1 is provided to show how one would open a plan file from disk, gain access to the top-level network model object under which all of the network objects are found and finally write the plan back to disk.

Example 1 - Open Plan File, Access Top-Level Network Model, Write to Output Plan File

from com.cisco.wae.opm.network import open_plan

input_plan = 'some/plan/file.pln'
output_plan = 'some/plan/out-file.pln'
with open_plan(input_plan) as network:
    model = network.model
    # Do stuff with the network model ...
    network.write(output_plan)

A single import statement is used to gain access to the open_plan() function. This function takes a single required argument which is the path to the plan file on disk to be used by the API. Any valid plan file format can be referenced here including .pln, .txt or .db. The open_plan function is used as part of a standard python with statement as shown in Example 1, to ensure proper resource cleanup upon exiting. The open_plan function returns the topmost OPM API Network object from which the model object can be obtained containing all of the network objects (e.g., nodes, interfaces, demands, etc.). Once desired modifications have been made to the network model in the script, the updated plan can be written back to disk using the write() method on the Network object.

Network Objects and Their Properties

From the model object, all network objects are available either directly or hierarchically from the corresponding parent network object. The Example 2 code snippet demonstrates how to get a specific node object and print the names of all interfaces connected to it. The nodes property of the model returns an object based on the NetworkObjectManager class providing access to all node objects in the plan. One can iterate through them like a standard python list object or retrieve a specific node by providing an object key (in this case the node name) like a standard python dict using bracket syntax.

Example 2 - Retrieve interfaces connected to a specific node

from com.cisco.wae.opm.network import open_plan

filename = 'some/plan/file.pln'
with open_plan(filename) as network:
    model = network.model
    node = model.nodes['cr1.atl']
    for interface in node.interfaces:
        print 'Interface %s on node %s' % (interface.name, node.name)

With the specific node object obtained, we can then retrieve all interfaces connected to it with the node’s interfaces property as shown in the sample code. This is an example of the hierarchical representation of objects in a network model, since the interface objects returned here are only those with a parent object of the node cr1.atl.

With each interface, we can get any of its properties using the standard dot notation similar to how it’s done in the NSO Python API. For example, one would use interface.name to get the name of the interface, interface.capacity to get the capacity and so on. Refer to the documentation for each object class to see all of the properties available for each.

If we wanted all interfaces in the plan and not just those connection to a specific node, we could have used the line model.interfaces. As in example 2, this can be iterated over or if we wish to retrieve a specific interface, we can provide the interface key as a standard python dictionary using the bracket notation.

interface_of_interest = model.interfaces[{'name':'to_cr1.hst', 'node':'cr1.atl'}]

Object keys are used to identify an object using one or more properties that together are uniquely associated with that object. In the above line of code, the interface key is composed of two properties provided in python dict form. For single property object keys such as for nodes, a simple string representing the node name can be used. See each object’s key class documentation for more information about specific supported formats for that object. A corresponding key object based on the NetworkObjectKey class can be obtained for each network object using the key attribute. Example 3 demonstrates how to obtain a circuit key object for an existing circuit object (circuit_of_interest) and access its 4 attributes.

Example 3 - Retrieve Circuit Object Key and its Attributes

circuit_key = circuit_of_interest.key
node_a_name = circuit_key.node_a
interface_a_name = circuit_key.interface_a
node_b_name = circuit_key.node_b
interface_b_name = circuit_key.interface_b

Plan properties of network objects are both readable and writable while derived properties are read-only. To set a plan property, simply assign the property a value consistent with the Python data type defined for it. Example 4 shows how to set the destination node of an LSP, its setup bandwidth, the type to RSVP and its active state respectively.

Example 4 - Set plan properties of an existing LSP

from com.cisco.wae.opm.network import open_plan

filename = 'some/plan/file.pln'
with open_plan(filename) as network:
    model = network.model
    lsp = model.lsps[{'source':'cr1.wdc', 'name':'to_atl'}]
    lsp.destination = network.model.nodes['cr1.atl']
    lsp.setup_bandwidth = 10000.0
    lsp.lsp_type = 'rsvp'
    lsp.active = True

Network objects can be created and deleted using the NetworkObjectManager for that object type. To create an object, you can use the append() method on the NetworkObjectManager for the object type, passing it a dict containing the properties of the new object, with key objects required and plan properties optional. The append() method returns the newly created object. Removing objects is done using the remove() method on the NetworkObjectManager for the object type, passing it the object to remove. See Example 5 for sample code demonstrating the creation and deletion of a LSP.

Example 5 - Create and Remove LSPs

from com.cisco.wae.opm.network import open_plan

filename = 'some/plan/file.pln'
with open_plan(filename) as network:
    model = network.model

    # Get NetworkObjectManager for LSPs
    lsps = model.lsps

    # Add new LSP using append()
    new_lsp = lsps.append({
        'source':'cr1.wdc',
        'name':'test',
        'destination':network.model.nodes['cr1.atl'],
        'setup_bandwidth':1000.0,
        'lsp_type':'rsvp',
        'active':True
    })

    # Check for its existence
    if new_lsp in lsps:
        print 'New LSP found'

        # Remove new LSP
        lsps.remove(new_lsp)

        # Check if new LSP has been removed
        if new_lsp not in lsps:
            print 'New LSP removed'

NetIntTables

NetInt tables can be accessed through the netint_tables property on the Model object. Each NetInt table can be keyed by its name in the manager. Each table has a columns and rows property which define how the table is constructed. The columns property is an ordered list of Column objects that each represent a column on the table. The rows property is a set of Row objects. Each Row is a list of values that correspond with the columns in the table. Rows can also be accessed like dictionary objects where the key is the column of interest. NetInt tables are read-only!

Reading NetInt table data is straight forward and operates like working with dicts and lists.

Example 6 demonstrates iterating over the NetInt tables in a model.

from com.cisco.wae.opm.network import open_plan

with open_plan('someplan.pln') as network:
    #Print each NetInt table in the model in tableformat:
    for netint_table in network.model.netint_tables:
        print '<'+netint_table.name+'>'
        for column in netint_table.columns:
            print '# %s (%s)' % (column.name, str(column.column_type))
        print '\t'.join([column.name for column in netint_table.columns])
        for row in netint_table.rows:
            # This is actually a naive approach to printing the values.
            # It doesn't account for any corner cases.
            print '\t'.join([str(value) for value in row])

Columns have a number of properties to describe the data each column represents. Of course, a column has a name, but it also has a column_type property which contains a python native type which constrains the type of data that is stored in that column. The property can be either None, bool, str (the default), int, or real. If the column_type is real, then the decimals property will be set to an integer that defines the floating point precision of the column.

UserTables

User tables work similarly to NetInt tables. Each model has a user_tables property which serves to manager user tables. Reading is performed in the same way.

Creating User tables is generally done with the append method on the Model.user_tables property. The returned table can then be built up like any other object.

Example 7 demonstrates creating and populating a user table.

from com.cisco.wae.opm.network import open_plan
with open_plan('someplan.pln') as network:
    # Create a table with three columns and two rows.
    user_table = network.model.user_tables.append('New::Table::Name')
    user_table.columns.append('Column 1')
    user_table.columns.append('Column 2')
    user_table.columns['Column 2'].column_type = float
    user_table.columns['Column 2'].decimals = 4
    user_table.columns.append({
        'name':'Column 3',
        'column_type':bool,
        'description':'this is a boolean column'})
    user_table.rows.append({'Column 1':'some string', 'Column 2':3.1415, 'Column 3':True})
    network.model.user_tables['New::Table::Name'].rows.append(['another string', 12.34567, False])

Reports

Reports can be accessed through the Model.reports property. Each report has, among other properties, a sections property that contains all the parts of the report. Each section can be of type text, HTML, or a table. Table sections behave just like User Tables do. Each report is keyed by its name.

Example 8 demonstrates generating a report.

from com.cisco.wae.opm.network import open_plan
with open_plan('someplan.pln') as network:
    new_report = network.model.reports.append('Report Name')

    # Text section named 'Section 1' with no content.
    new_report.sections.append('Section 1')

    # Text section named 'Section 2' with 'Content' as its content.
    new_report.sections.append('Section 2\nContent')

    new_report.sections.append({
        'section_type':'HTML',
        'title':'Section 3'}).content = '<body>content</body>'

    table_section = new_report.sections.append({
        'section_type':'table',
        'title':'Section 4'})
    table_section.columns.extend(['A', 'B'])
    table_section.rows.extend([['1', '2'], ['foo', 'bar']])

Model Patches

The Model object supports generating and merging patch content. Patch files themselves do not have an object representation and instead be passed around simply as strings. The patch interface into a model is accessed through the addition and subtraction operators.

Example 9 demonstrates working with model patches.

from com.cisco.wae.opm.network import open_plan
with open_plan('original_plan.pln') as original_plan:
    with open_plan('changed_plan.pln') as changed_plan:
        if original_plan.model != changed_plan.model:
            model_changes = changed_plan.model - original_plan.model
            patched_model = original_plan.model + model_changes
            assert patched_model == changed_plan.model, 'patching failed!'

Access to Simulation Data

Simulation data including derived simulation properties of network objects (e.g., interface UtilSim) as well as simulated routes of demands, LSPs, etc., are also supported and easily accessible in the OPM Python API. To access common simulation attributes such as simulated utilization or simulated traffic of an interface, simply use the simulated_utilization or simulated_traffic attributes of the interface object respectively. Accessing these simulation attributes will trigger the OPM API to check if there is a valid Design RPC API route simulation and traffic simulation and if not it will generate one in the background without user intervention. Route/traffic simulations become invalid or obsolete due to certain changes being made to the network model that affect the simulated routes. The OPM API automatically provides access to valid simulation data based on the current state of the network model.

Network object failures are considered when generating simulation data. Failures can be set/unset directly from network objects that are capable of failure using the failed boolean attribute. To fail an object, just set this attribute to True. To recover, set it to False. Simulation data such as simulated utilization of interfaces are automatically updated when the relevant simulation attribue is accessed after the change in failure state.

Example 10 demonstrates how to access simulated utilization and simulated traffic for an interface in us_wan both before and after a circuit failure in the model.

Example 10 - Fail Circuit and Access Interface Simulated Utilization and Traffic

from com.cisco.wae.opm.network import open_plan

filename = 'us_wan.txt'
with open_plan(filename) as network:
    model = network.model

    # Retrieve the interface of interest
    interface = model.interfaces[{'name':'to_cr1.nyc', 'node':'cr2.wdc'}]

    # Get simulated utilization and simulated traffic values
    int_sim_util = interface.simulated_utilization
    int_sim_traff = interface.simulated_traffic
    print 'Interface %s has simulated utilization of %s and traffic of %s' % \
        (str(interface), str(int_sim_util), str(int_sim_traff))

    # Now fail a circuit to shift demands
    circuit_to_fail = model.circuits[{
        'node_a':'cr1.chi',
        'interface_a':'to_cr2.nyc',
        'node_b':'cr2.nyc',
        'interface_b':'to_cr1.chi'],
    }]
    print 'Failing circuit %s' % str(circuit_to_fail)
    circuit_to_fail.failed = True

    # Get updated simulated utilization and simulated traffic values
    int_sim_util = interface.simulated_utilization
    int_sim_traff = interface.simulated_traffic
    print 'Interface %s has updated simulated utilization of %s and traffic of %s' % \
        (str(interface), str(int_sim_util), str(int_sim_traff))

Simulated routes for objects such as demands and LSPs can also be retrieved directly from the objects themselves. Routable network objects such as these, have 2 attributes related to their simulated paths - routed and route. The routed attribute returns a boolean indicating if it is routed by the simulation. If this returns True, the route attribute will return a route object which has many attributes summarizing the path properties including maximum_latency and total_path_metric as well as an interfaces attribute which returns a list of interfaces over which the demand or LSP routes. Note that the interfaces provided are not ordered due to possibility of ECMP. Example 11 shows how to check if a LSP is routed, retrieve the path properties of a LSP and the list of interfaces over which it routes.

Example 11 - Retrieve Simulated Path and Path Properties of LSP

from com.cisco.wae.opm.network import open_plan

filename = 'us_wan_lsps.txt'
with open_plan(filename) as network:
    model = network.model

    # Retrieve the lsp of interest
    lsp = model.lsps[{'name':'cr1.atl_cr1.bos', 'source':'cr1.atl'}]

    if lsp.routed:
        print 'LSP %s is routed' % str(lsp)

        # Retrieve route object for lsp
        lsp_route = lsp.route

        # Get path properties
        latency = lsp_route.maximum_latency
        tot_metric = lsp_route.total_path_metric
        print '\tTotal latency is %s' % str(latency)
        print '\tTotal path metric is %s' % str(tot_metric)

        # Get list of interfaces over which it routes
        interfaces = lsp_route.interfaces
        print 'Interfaces over which LSP routes - %s' % str([str(iface) for iface in interfaces])

Filtering from network objects (e.g., interfaces) to the paths that route over them (e.g., demand paths) is straightforward in the OPM API. This is similar to the context-based filtering capabilities in the Design GUI where one can, for example, right-click an interface and select “Filter to Demands Through Interfaces”. To achieve this using the OPM API, simply use the demands_routed_through property of the interface object of interest. Example 12 shows how to filter various network objects to the paths that include them.

Example 12 - Filtering

from com.cisco.wae.opm.network import open_plan

filename = 'us_wan_L1.txt'
with open_plan(filename) as plan:

model = plan.model

# Filtering from interface to demands routing through
interface = model.interfaces['if{cr2.wdc|to_cr1.nyc}']
print 'Demands with path through interface {}:'.format(interface)
for demand in interface.demands_routed_through:
    print demand

# Filtering from interface to LSPs routing through
print '\nLSPs with path through interface {}:'.format(interface)
for lsp in interface.lsps_routed_through:
    print lsp

# Filtering from node to LSPs routing through
node = interface.node
print '\nLSPs with source of node {}:'.format(node)
for lsp in node.lsps_routed_through:
    print lsp

# Filtering from L1 link to L1 circuits routing through
l1_link = model.l1_links['l1link{kcy|slc|}']
print '\nL1 circuits with paths through L1 link {}:'.format(l1_link)
for l1_circuit in l1_link.l1_circuits_routed_through:
    print l1_circuit

Access to RPC API Objects

The underlying RPC API objects are accessible from the OPM Python API to enable more advanced use cases. These might include cases where low-level access is required for RPC API features not yet supported by the high level OPM API or where maximum efficiency is desired to reduce runtimes for scalability. Python applications developed within the WAE environment can leverage both the high level OPM and low-level RPC APIs in a seamless way. With the OPM Network object, one can retrieve the corresponding RPC Network object using the rpc_plan_network attribute. From there, all of the standard RPC objects can be accessed via their respective Managers. For example, the following code demonstrates how to access the RPC tool manager from which one can run any of the available Design Tools.

# Obtain the RPC Tool Manager from the OPM API Network object
tool_manager = network.rpc_tool_manager

In addition to switching from OPM to RPC APIs at the top Network level, RPC-based object keys, records and objects can be retrieved from the corresponding OPM API network object using its rpc_key, rpc_record and rpc_object attributes respectively.

Important Note: When modifying network data using the RPC API, one must inform the OPM API layer that any cached data is invalid. This can be done like so

network.model.cache_valid = False

Not Yet Supported

The following functionality found in the Design RPC API are not yet supported in the OPM API. For use cases requiring these functions, access to them can be obtained through the techniques outlined in the previous section.

• Design Tools (excepting Simulation Analysis and Patches)
• Plot Layout