Using a text editor is the preferred method of producing driver scripts as it enables scripts to be written, compiled and checked outside IP Service Activator.

Note the following:

• Oracle recommends that you base the scripts you create on the template file outlined in "Using the Template File".

• To ensure consistency, follow the guidelines given in "Structure of a Script".

• Import the completed script into IP Service Activator, as described in "Importing Scripts".

• If necessary, you can edit the scripts from the client.

The client provides only a basic text editor and does not provide any of the features available in more advanced code editing software. We recommend that you create driver scripts (apart from very simple scripts), using other third-party software and import them using the driver script import feature as described in "Importing Scripts".

If you create a script from within the client, you can either create a standalone script (that is, not initially linked to any object) or a script that is directly associated with an object.

To create a standalone script:

1. From the Custom tab, select the Driver Scripts folder, or a folder within it.

2. Right-click and choose Add Driver Scripts from the context menu.

3. On the Driver Script page, enter a name for the script in the Name box, and select the driver type from the drop-down list.

4. On the Role page, choose the target objects that the script will configure. For all scripts, you must select the device role to which the script is to apply. You can choose one system-defined device role (Core, Access, Gateway or Shadow) and one user-defined device role. Choosing Any Role applies the script to any device assigned a role.

   For Interface, Sub-interface, ATM PVC and Frame PVC scripts, select the interface role to which the script is to apply. You can choose one system-defined interface role (Local, Access, Core or Disabled) and one user-defined interface role. Choosing Any Role applies the script to any interface assigned a role.

   If roles are not defined, the script will not be implemented.

5. On the Schedule page, specify when the script is to be run: before or after standard configuration changes, once or repeatedly, and whether or not it is to be run when a device is restarted. When you specify to run the driver script once only, you can further specify to create concretes once only, on first execution.

6. Enter the lines of the script directly on the Preamble, Common, Install and Remove pages, following the guidelines described in "Structure of a Script".

It is also possible to create a script for a particular object, for example, to create a script specific to a single device.

To create a script for a specific object:

1. Select the appropriate network object and choose Add Driver Script from the context menu.

2. Enter the details of the script on the Driver Script dialog box property pages, as described in "To create a standalone script:".

The script is automatically linked to the selected network object, and will be installed when the appropriate transaction is run.

The script also appears in the Driver Scripts folder on the Custom tab, allowing it to be easily re-used.

The preamble section is used to identify the script and define any variables used. It is Python code, and by convention should have the following format:

#Title: <Script Name>
Version = "<Version>"
#IP Service Activator version: #.#.#
#Date: <Date>
#Copyright (c) <Company> <Year>
#<Short description of purpose and use of script, up to 3 lines>
#
#
#begin preamble section
default definitions of any variables used in the script from the object context

The first eight lines of the Preamble section appear on the Driver Script page of the Script dialog box in the read-only Preview field. By convention these lines should therefore contain only the header comments. These lines must always be as follows:

• Line 1 provides a short title for the script.

• Line 2 sets the Version variable, which identifies the version of the script. The version umber must be amended whenever the script is updated.

• Line 3 specifies the IP Service Activator release for which this script was written. Scripts may need to be amended for different releases.

• Line 4 lists the date that the script was last amended in dd-mmm-yyyy format.

• Line 5 provides the copyright statement, if applicable.

• Lines 6 to 8 explain the script. It is useful to limit the width of text so that it displays correctly in the client.

• Line 9 must always include the comment #begin preamble section. Unlike the other section comments, this line is not used as a section delimiter, but indicates the start of the variable definition section.

If there is no preamble, then the comment #N/A should appear on the next line.

If the script uses variables that are expected to be set in the context of objects to which the script is applied, then by convention the preamble section should set each to a default value, one per line.

On the IP Service Activator client, the Preamble section can be viewed (and edited if necessary) on the Preamble page of the Driver Script dialog box as in Figure 4-1.

The Behavior section of a script is a set of variable definitions that control when and how the script is run. When a script is imported, this section is parsed and the various fields on the Role and Schedule pages of the Driver Script dialog box are set. When a script is exported to a file, the current field settings are written out in the definitions. If a Behavior section is not specified in a script, default values are applied.

Table 4-1 displays the variables that can be set in the Behavior section. The variables are case-sensitive.

The Behavior section cannot be viewed directly on a property page, but the settings can be viewed (and edited if necessary) on the Driver Script, Role, and Schedule property pages of the Driver Script dialog box.

For example, Figure 4-2 shows the setting of script_name and script_driver_type in the Driver Script page.

The Common section is Python code available whenever the script is run. It is used to define functions that can be called from both the Install and Remove sections.

By convention, the Common section should start with the comment:

#begin common section

The Common section is optional; if you do not need to define any common functions, the comment #N/A should appear on the next line.

On the IP Service Activator client, the Common section can be viewed (and edited if necessary) on the Common page of the Driver Script dialog box, as shown in Figure 4-3.

The Install section is Python code that is run when the driver script is associated with an object. This will be at the first propagate after the script is associated with the object and optionally on each subsequent propagate or device restart (for details, see "About Scheduling of Scripts").

By convention, the Install section should start with the comment

#begin install section

On the IP Service Activator client, the Install section can be viewed (and edited if necessary) on the Install page of the Driver Script dialog box, as shown in Figure 4-4.

The Remove section is Python code that is run when the association between the driver script and an object is removed, either by unlinking the script from an object or by deleting the script. Its purpose is to remove any configuration that was installed by the Install section.

The Remove section is not mandatory, but for a script that installs configuration on devices, Oracle strongly recommends that you define code that removes the configuration that has been placed by the Install code.

By convention, the Remove section should start with the comment:

#begin remove section

If you do not need to define a Remove section, the comment #N/A should appear on the next line.

On the IP Service Activator client, the Remove section can be viewed (and edited if necessary) on the Remove page of the Driver Script dialog box, as shown in Figure 4-5.

For examples of actual scripts, see "Pre-defined Scripts".

When writing scripts, do not define variables starting with an underscore character as this is restricted to variables defined by IP Service Activator, such as _result and _device.

For general discussions about Python programming style, see the Python documentation index at:

http://www.python.org/doc/essays/

When applying commands to a router, use the full form of all commands rather than abbreviated commands. As well as helping to ensure compatibility with different operating system versions, using full commands makes the script more understandable.

The device driver explicitly catches all errors and returns a status of Failed, together with the error and line number. For more fine-grained error handling, use multiple Try/Except blocks for specific exceptions.

In the following example, a call is made to an exception handler defined in the Common section.

#begin common section
def handleException(details):
  _result.setCode(_result.FAILED)
  _result.setDetails(details)
 
#begin install section
try:
  _device.openSession()
except RuntimeError, err:
  handleException(err)
  return

Because IP Service Activator can display only one line of text in an error message, when diagnosing script errors it can be useful to copy the text of the error into a text editor, which can display multiple lines including end-of-line characters.

To copy the error text into a text editor:

1. Open the Device Configuration Log.

2. Locate the relevant CDK error.

3. Right-click on the error and select Copy.

4. Open the text editor.

5. Select Paste.

The error is then displayed correctly formatted.

If the script is to apply commands to a router by calling deliverCommand(''), then it must first call _device.openSession() and finish by calling _device.closeSession().

For example:

_device.openSession()
_device.deliverCommand('copy running-config startup-config')
_device.closeSession()

It is good practice to validate all the values that can be set by users, since if a value is set incorrectly no command is delivered. Oracle recommends including validation checks in the Common section of a script to ensure that no configuration is installed until all the values have been checked. Checking each command in turn in the Install section can result in the router being left in a partially-configured state if one command fails.

The -NoCommandDelivery flag on the Cisco driver typically prevents the driver from sending a configuration to a device, sending it to the audit log files (pre-pended by no-command-delivery) instead.

Commands sent by scripts are not executed when the driver is in NoCommandDelivery mode.

An optional second parameter to deliverCommand lets script writers identify commands as read or write. This is useful when developing scripts with the driver in NoCommandDelivery mode to prevent accidental changes.

Read commands should not modify the device and so are valid to send when not delivering commands. This is similar to the behavior of the device driver itself which will send show commands regardless of state. (While this is the intent, it is on the honor system. IP Service Activator does not try to validate whether or not the command will actually modify the device.)

The command access can be specified with _device.deliverCommand(command. _device.read) or _device.deliverCommand(command, _device.write)

A read command is always executed. A write command is logged in the audit log with a prefix of CDK-no-command-delivery if the driver is not delivering commands and is executed normally otherwise.

Script writers can check if write commands will be delivered:

_device.deliveringCommands() returns true or false to reflect the driver state.

They can also check the result of deliverCommand which is always NoCommandDelivery enabled if the driver is not delivering commands.

If you want to get and process the output of an operating system command, then you need to store the result of deliverCommand('').

For example:

Result = _device.deliverCommand('show running-config')

You can then use normal Python techniques to extract the information you need.

By default the return code will be TRUE. You need to write the script to catch exceptions and deal with any other errors by returning FAILED. You can also provide a detail string which is logged by the server.

For example:

_result.setCode(_result.OK)
_result.setDetails('An error has occurred')

When writing a script, bear in mind that the configuration you wish to place on the device might already be there. If possible you therefore need to write a script that is intelligent enough to check for and deal with configuration that is already applied.

Any variable created in Python outside the scope of a Python class or method is considered a global variable. This fact can cause a variable that is only applicable to the current script to be misapplied to subsequent scripts. This section describes a method to ensure that local variables are applied to the local context only.

The recommended method is to wrap any CDK script in a function definition before execution. In this way, all classes, functions and variables defined will be local to the wrapper function.

For example, you can wrap script context code in a class definition, as follows:

class ScriptContext:
  x=5
  y=6
  z=7

and then in the CDK script you would reference those variables as follows:

ScriptContext.x
ScriptContext.y
ScriptContext.z

A Python script is typically formatted as follows:

import DriverScript
import OrchestreamExceptions
import traceback
_scriptInfo = "user's cdk script (including script context)"
 
try:
     exec(_scriptInfo.getScript())\n"
except:\n"
     traceback.print_exc(file = _scriptInfo)\n"

To manage script context, the Python script should be formatted as follows:

import DriverScript
import OrchestreamExceptions
import traceback
 
def runPython():
    _scriptInfo = "user's cdk script (including script context)"
    try:
         exec(_scriptInfo.getScript())\n"
    except:\n"
         traceback.print_exc(file = _scriptInfo)\n"
 
runPython()