Groovy Scripting
This section explains the Groovy scripting support that Prime Cable Provisioning provides for device configuration and device management. This section features:
Overview
Prime Cable Provisioning uses Groovy scripting, apart from templates, for generating the configuration file, which helps you to deploy dynamic files for any CableLabs standard supported by Prime Cable Provisioning including DOCSIS, PacketCable, CableHome, and OpenCable STB. This scripting interface allows you to access the discovered DHCP data and device properties, which will help in deciding the TFTP file that has to be generated. The Prime Cable Provisioning RDU generates the configuration file using either the template or Groovy scripting. The RDU identifies the Groovy file by the extension, .groovy. Groovy sample script files are available in the BPR_HOME/rdu/samples/groovy directory, which can be used for testing.
To create your Groovy script file, you should be familiar with the Groovy scripting language, in addition to the requirements for templates creation.
Groovy Script Language
A Groovy script can include the following options:
Groovy Script
|
Option |
Description |
Example |
|---|---|---|
|
<comment> |
// [ascii-string] /* * Multi-line comments */ |
// Config File Start/End / * configFile—of type DOCSISTFTPFile * services—of type ExtensionServices * discoveredData—of type DHCPDataAccess * deviceProperties—of type CSRCProperties * option—of type DOCSISoptionfactory * device—of type IPDevice * context—of type ConfigContext */ |
|
<option-description> |
<option-with-no-suboptions> | <compound-option> |
|
|
<option-with-no- sub options> |
configFile.add(option.createOptionValue (<custom-value>, "<option-num>","<option-value>")); |
configFile.add(option.createOptionValue ("3", "1")); For custom values: configFile.add(option.createOptionValue (OptionSyntaxHEX., "217.53","010868446146484A4737")); |
|
<compound-option> |
def <variable-name> = option .createOptionValue("<option-num>"); <variable-name>.add(option .createOptionValue(<custom-value>, "<optionnum>","<option-value>")); configFile.add(<variable-name>); |
def option24 = option.createOptionValue("24"); option24.add(option.createOptionValue("24.8", "4194304")); configFile.add(option24); |
|
<custom-value> optional |
OptionSyntax.HEX | OptionSyntax.ASCII | OptionSyntax.SNMP |
|
|
<option-num> |
<unsigned-byte>[.<unsigned-byte>]* |
"24" |
|
<option-value> |
<option-value-string> [,<option-value-string>] * |
"1" or [".docsDevNmAccessCommunity.1", "Octet String", "private"] as String[] |
Bindings that are visible to the Groovy environment are:
-
configFile—of type DOCSISTFTPFile
-
services—of type ExtensionServices
-
discoveredData—of type DHCPDataAccess
-
deviceProperties—of type CSRCProperties
-
option—of type DOCSISoptionfactory
-
device—of type IPDevice
-
context—of type ConfigContext
 Note |
Device object binding is not available while executing the Groovy script from CLI File Utility. |
Note |
|
Adding a Groovy Script to Prime Cable Provisioning RDU
To add a Groovy script file to a Prime Cable Provisioning RDU:
Procedure
| Step 1 |
Choose Configuration > Files. The View Files page appears. |
| Step 2 |
Click Add. The Add Files page appears. |
| Step 3 |
Choose the CableLabs Configuration Script option from the File Type drop-down list. |
| Step 4 |
Browse for the Source File Name |
| Step 5 |
Add the <filename>.groovy file in the File Name field. |
| Step 6 |
Click Submit. |
Using Configuration File Utility for Groovy
Configuration file utility is used to convert groovy file to a binary configuration file and vice versa. It can also be used to view and validate the configuration and groovy files. The configuration file utility is installed in the BPR_HOME/rdu/bin directory. The groovy file and the binary file must be available in the directory from where the configuration file utility is invoked.
Note |
Since Prime Cable Provisioning uses the configuration utility only to generate binary to groovy file and vice versa, it will not support other scripting languages. |
This section discusses the following topics:
-
Testing Groovy Script Processing for a Local Groovy Script File
-
Testing Groovy Script Processing for an External Groovy Script File
-
Testing Groovy Script Processing for a Local Groovy Script File and Adding Shared Secret
-
Testing Groovy Script Processing for a Local Groovy Script File and Adding EMIC Shared Secret
Running the Configuration File Utility
To run the configuration file utility, run the command from the BPR_HOME/rdu/bin directory:
runCfgUtil.sh options
The available options include:
-
-?—Prints this usage message.
-
-e—Performs encoding of a BACC groovy/template file (default).
-
-d—Performs decoding of a binary file.
-
-g—Performs generation of a groovy/template file from a binary file.
-
-snmp—Performs generation of a template or dynamic script file from a binary file with OptionSyntax.SNMP enabled.
-
-c shared—The CMTS shared secret to use when parsing a BACC groovy/template file (the default is cisco).
-
-h host:port—Specifies where the RDU is located (the default is localhost:49187).
-
-i device ID—Specifies the device to use for macro variables substitutions when parsing a groovy/template.
-
-m macros—Specifies the macro variables to be substituted when parsing a groovy/template.
-
-s—Displays the parsed groovy/template or the contents of the binary file in a human readable format.
-
-o filename—Saves the parsed groovy/template or the human readable output in the specified filename.
-
-l filename—Specifies the input file to be on the local file system.
-
-r filename—Specifies the input file to be remote on the RDU.
-
-pkt—Specifies the file to be processed as a PacketCable MTA configuration file.
-
-t type—Specifies the PacketCable encoding type (default is secure).
-
-loc locale—Specifies the PacketCable locale such as na, euro, and, ietf (default is na). The default is na. If the MTA is euro-MTA, then the locale should be set to euro.
-
-cablehome—Specifies the file to be processed as a CableHome configuration file.
-
-docsis—Specifies the file to be processed as a DOCSIS configuration file (default).
-
-E—Enable Extended CMTS MIC (EMIC) calculation and identifies the default options for EMIC calculation. The default options are:
-
HMAC type—MMH16
-
EMIC Digest type—Explicit
-
EMIC shared secret as cisco.
-
-
-Ei—Specifies [implicit] presentation that will be used for Extended CMTS MIC Digest Subtype.
-
-Eh HMACType—Specifies the hashing algorithm used to compute Extended CMTS MIC. The supported algorithms are MD5 and MMH16 (default is MMH16).
-
-Es secret—The CMTS shared secret to use for Extended CMTS MIC calculation (the default is cisco).
-
-u username—Specifies the username to use when connecting to the RDU.
-
-p password—Specifies the password to use when connecting to the RDU.
-
-v version—Specifies the version of the technology to process the input file.
-
-prop filename—Specifies the property file that has the key and value for the variables used in dynamic script.
Note
You should always specify either -DDV4 or -DDV6 filename along with -prop filename to pass Discovered data.
-
-dis filename—Specifies the discovered data to be used in the dynamic script in the form key and value pair.
-
-DDv4 filename—Specifies the discovered DHCPv4 data to be used in dynamic script in the form key and value pair.
-
-DDv6 filename—Specifies the discovered DHCPv6 data to be used in dynamic script in the form key and value pair.
-
-cp classpath—Specifies the path of the extension jars and script files referred in dynamic script.
-
-b—Specifies bulk processing option for generating multiple output files. All the binary files in the given directory (using -l option) will be processed and the generated files will be available in the output directory indicated in -o option.
-
-ft—The file type (groovy or tmpl)to be generated. This option will be used when bulk processing is enabled (using -b option) for generation(-g option) operation. (The default file type is tmpl.)
Validating a Groovy Script Using runCfgUtil
To use the configuration file utility to test Prime Cable Provisioning Groovy script:
Procedure
| Step 1 |
Develop the Groovy script. If the Groovy script extends to other Groovy scripts, make sure all the referenced Groovy scripts are in the same directory. |
| Step 2 |
Run the configuration file utility on the local file system. You can check the syntax for the Groovy script, or have the configuration file utility process the Groovy script as CRS would, and return output. If the Groovy script contains dynamic variables or the discovered data, perform these operations in the order specified:
|
| Step 3 |
Add the Groovy script (and any extended Groovy scripts that are used) to the RDU. |
| Step 4 |
Run the configuration file utility to parse a file. See Testing Groovy Script Processing for an External Groovy Script File. If the Groovy script contains dynamic variables or the discovered data, perform these operations in the order specified:
|
| Step 5 |
After all tests succeed, configure a Class of Service to use the Groovy script. |
Converting a Binary File to a Groovy Script File
Use the runCfgUtil.sh command to convert binary configuration memory files into Groovy script files. Prime Cable Provisioning dynamic configuration generation is based on Groovy scripts that are created. Automatically converting existing, tested, binary files to Groovy script files speeds the process and reduces the possibility of introducing errors.
Note |
Using the runCfgUtil.sh tool, you cannot convert a template directly into Groovy scripts and vice versa. You must first convert the template into a binary file, and then convert the binary file into a Groovy script. When you convert a Groovy script to template, you must first convert the Groovy script into a binary file, and then convert the binary file into a template. Syntax Description |
runCfgUtil.sh -g -l binary_file -o groovy_file
-
-g —Specifies that a Groovy script file needs to be generated from an input binary file
-
-l binary_file —Specifies the local input file, including the pathname; bronze.cm for example.
-
-o groovy_file —Specifies the output Groovy script file, including the pathname. In all cases, the output Groovy script file will have a .groovy file extension; for example, test.groovy.
To convert a binary file into a Groovy script file:
Procedure
| Step 1 |
Change directory to /opt/CSCObac/rdu/samples/docsis. |
| Step 2 |
Select a Groovy script file to use. This example uses an existing binary file called unprov.cm. |
| Step 3 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -g -l unprov.cm -o test.groovy -docsis -docsis—Specifies that the input file is a DOCSIS configuration file. |
Converting a Binary File to a Groovy Script File Without Dependency on MIBs
Use the runCfgUtil.sh command with the option -snmp to convert binary configuration memory files into Groovy script files without dependency on the MIBs. When this command is executed with the -snmp option, it adds OptionSyntax.SNMP for all TLVs that contain SnmpVarBind. Ensure that you specify the correct value based on the type for TLV, for example, integer numbers (1).
Note |
The OID must be in numeric format to completely remove the MIB dependency, for example, .1.3.44491.1.2.3. |
Syntax Description
runCfgUtil.sh -docsis -g -snmp -l binary_file -o groovy_file
-
-g —Identifies the input file as a PacketCable MTA file.
-
-snmp —Specifies that the generated dynamic script file from the binary file has OptionSyntax.SNMP enabled.
-
-l binary_file —Specifies the local input file, including the pathname. In all cases, the input binary filename will have a .cm file extension; bronze.cm for example.
-
-o groovy_file —Specifies the output Groovy script file, including the pathname. In all cases, the output Groovy script file will have a .groovy file extension; for example, test.groovy
To convert a binary file into a Groovy script file without dependency on MIBs:
Procedure
| Step 1 |
Back up the MIBs. |
||
| Step 2 |
Add the property
|
||
| Step 3 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -g -snmp -l example.cm -o example.cm.groovy
|
Testing Groovy Script Processing for a Local Groovy Script File
Use the runCfgUtil.sh command to test the processing for Groovy script files stored on the local file system.
Syntax Description
runCfgUtil.sh -pkt -l file
-
-pkt —Identifies the input file as a PacketCable MTA file.
-
-l —Specifies that the input file is on the local file system.
-
file —Identifies the input Groovy script file being parsed.
To parse a Groovy script file that is on the local file system:
Procedure
| Step 1 |
Change directory to /opt/CSCObac/rdu/samples/packet_cable. |
| Step 2 |
Select a Groovy script file to use. This example uses an existing Groovy script file called unprov_packet_cable.groovy. The -pkt option is used because this is a PacketCable MTA Groovy script. |
| Step 3 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -pkt -l unprov_packet_cable.groovy unprov_packet_cable.groovy—Identifies the input Groovy script file being parsed. |
Testing Groovy Script Processing for an External Groovy Script File
Use the runCfgUtil.sh command to test processing of external Groovy script files.
Syntax Description
runCfgUtil.sh -docsis -r file -u username -p password
-
-r —Identifies the input file as a file that has been added to the RDU.
-
file— Identifies the input Groovy script file being parsed.
-
-u username —Specifies the username to use when connecting to the RDU.
-
-p password — Specifies the password to use when connecting to the RDU.
-
-docsis—Identifies the file as a DOCSIS Groovy script.
To parse a Groovy script file that has been added to the RDU:
Procedure
| Step 1 |
Select a Groovy script file to use. This example uses an existing Groovy script file called unprov.groovy. The -docsis option is used because a DOCSIS Groovy script is being used. |
| Step 2 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -docsis -r unprov.groovy -u admin -p changeme
|
Testing Groovy Script Processing for a Local Groovy Script File and Adding Shared Secret
Use the runCfgUtil.sh command to test the processing for a Groovy script file and add a shared secret that you specify.
Syntax Description
runCfgUtil.sh -e -docsis -l file -c shared
-
-e —Identifies the encode option.
-
-docsis —Identifies the input file as a DOCSIS Groovy script file.
-
-l —Specifies that the input file is on the local file system.
-
file —Identifies the input Groovy script file being parsed.
-
-c —Specifies the CMTS shared secret when parsing a DOCSIS Groovy script file.
-
shared— Identifies the shared secret. The default shared secret is cisco.
To parse a locally saved Groovy script file, and set a user-specified shared secret:
Procedure
| Step 1 |
Change directory to /opt/CSCObac/rdu/groovy. |
| Step 2 |
Select a Groovy script file to parse. This example uses an existing Groovy script file called unprov.groovy. The -docsis option is used because this is a DOCSIS Groovy script. |
| Step 3 |
Run the configuration file utility using this command:
|
Testing Groovy Script Processing for a Local Groovy Script File and Adding EMIC Shared Secret
Use the runCfgUtil.sh command to test the processing for a Groovy script file and add a Extended CMTS MIC (EMIC) shared secret that you specify.
Syntax Description
runCfgUtil.sh -E -docsis -l filename
-
-E —Enables EMIC calculation.
-
-docsis —Identifies the input file as a DOCSIS Groovy script file.
-
-l filename —Specifies the input Groovy script file, including the pathname. In all cases, the input Groovy script file will have a .groovy file extension; for example, test.groovy.
To calculate the EMIC with default settings:
Procedure
| Step 1 |
Select a Groovy script file to use. This example uses an existing Groovy script file called unprov.groovy. The -docsis option is used because a DOCSIS Groovy script is being used. |
| Step 2 |
Run the configuration file utility using this command:
|
Specifying Dynamic Variables at the Command Line
Use the runCfgUtil.sh command to specify dynamic variables.
Syntax Description
runCfgUtil.sh -e -l file -prop “file”
-
-e —Identifies the encode option.
-
-l —Specifies the input file is on the local file system.
-
file —Identifies the input Groovy script file being parsed.
-
-prop —Specifies the property file that has key and value for variables used in dynamic script.
-
“file” —Identifies the desired dynamic variable. If multiple dynamic variables are required, then each key value pair should be given one after the other.
To specify values for dynamic variables at the command line:
Procedure
| Step 1 |
Change directory to /opt/CSCObac/rdu/groovy. |
| Step 2 |
Select a Groovy script file to use. |
| Step 3 |
Identify the dynamic variables in the Groovy script. |
| Step 4 |
Identify the values for the variables. |
| Step 5 |
Run the configuration file utility using this command:
|
Specifying a Device for Dynamic Variables
Use the runCfgUtil.sh command to specify a device for dynamic variables.
Syntax Description
runCfgUtil.sh -e -r file -i MAC -u username -p password
-
-e —Identifies the encode option. Accepts key and if not mentioned, it takes the default key.
-
-r —Identifies the input file as a file that has been added to the RDU.
-
file —Identifies the input Groovy script file being parsed.
-
-i —Specifies the device to use when parsing dynamic variables.
-
MAC —Identifies the MAC address of the device.
-
-u username —Specifies the username to use when connecting to the RDU.
-
-p password — Specifies the password to use when connecting to the RDU.
To specify a device to be used for dynamic variable substitution:
Procedure
| Step 1 |
Select a Groovy script file to use. This example uses the existing Groovy script file, macro.groovy. |
||
| Step 2 |
Identify the dynamic variables in the Groovy script. |
||
| Step 3 |
Identify the device to use. This example assumes that the device exists in the RDU and has the dynamic variables set as properties. |
||
| Step 4 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -e -r macro.groovy -i "1,6,00:01:02:03:04:05" -u admin -p changeme
|
Specifying Discovered Data at the Command Line
Use the runCfgUtil.sh command to specify Discovered Data.
Syntax Description
runCfgUtil.sh -e -l file -dis “file”
-
-e —Identifies the encode option. Accepts key and if not mentioned, it takes the default key.
-
-l —Specifies the input file is on the local file system.
-
file —Identifies the input Groovy script file being parsed.
-
-dis —Specifies the discovered data to be used in dynamic script in the form key and value pair.
-
“file” —Identifies the desired discovered data.
To specify values for discovered data at the command line:
Procedure
| Step 1 |
Select a Groovy script file to use. |
| Step 2 |
Identify the discovered data in the Groovy script. |
| Step 3 |
Identify the values for the discovered data. |
| Step 4 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -e -l macro.groovy -dis dis.properties
|
Specifying a Device for Discovered Data
Use the runCfgUtil.sh command to specify a device and use its discovered data for configuration file generation.
Syntax Description
runCfgUtil.sh -e -r file -i MAC -u username -p password
-
-e —Identifies the encode option. Accepts key and if not mentioned, it takes the default key.
-
-r —Identifies the input file as a file that has been added to the RDU.
-
file —Identifies the input Groovy script file being parsed.
-
-i —Specifies the device to use when parsing discovered data.
-
MAC —Identifies the MAC address of the device.
-
-u username —Specifies the username to use when connecting to the RDU.
-
-p password — Specifies the password to use when connecting to the RDU.
To specify a device to be used for discovered data substitution:
Procedure
| Step 1 |
Select a Groovy script file to use. This example uses the existing Groovy script file, macro.groovy. |
| Step 2 |
Identify the discovered data in the Groovy script. |
| Step 3 |
Identify the device to use. This example assumes that the device exists in the RDU and has the discovered data set as properties. |
| Step 4 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -e -r macro.groovy -i "1,6,00:01:02:03:04:05" -u admin -p changeme
|
Generate Binary File from Groovy
Use the runCfgUtil.sh command to specify the output of a parsed Groovy script as a binary file.
Syntax Description
runCfgUtil.sh -l input_file -o output_file
-
-l —Specifies that the input file is on the local file system.
-
input_file —Identifies the input Groovy script file being parsed.
-
-o —Specifies that the parsed Groovy script file is to be saved as a binary file.
-
output_file —Identifies the name of the file in which the binary contents of the parsed Groovy script file are stored.
To specify the output from parsing a Groovy script to a binary file:
Procedure
| Step 1 |
Select a Groovy script file to use. |
| Step 2 |
Identify the name of the output file. This example uses unprov.cm. |
| Step 3 |
Run the configuration file utility using this command: /opt/CSCObac/rdu/bin# runCfgUtil.sh -l unprov.groovy -o unprov.cm
|
Viewing a Local Binary File
See Viewing a Local Binary File for details.
Viewing an External Binary File
See Viewing an External Binary File for details.
Activating PacketCable Basic Flow
See Activating PacketCable Basic Flow for details.
Generating TLV 43s for Multivendor Support
See Generating TLV 43s for Multivendor Support for details.
Dynamic TFTP File-Naming Convention
The TFTP File-Naming Convention helps you customize the variable components of the dynamic TFTP filenames, and their order. The Groovy script generates the TFTP filename by using components like the DHCP discovered data as well as the other interfaces that are being exposed to it. The script can include any important information such as, the class of service name, discovered vendor name, downstream speed and so on. You can configure the script either in technology defaults or in system defaults. The default maximum filename length is 127 characters.
If a CableLabs configuration filename script is modified, configuration regeneration is triggered for the list of affected devices to reflect the changes.
You can find Groovy script samples in BAC_HOME/rdu/samples/groovy.
Example 19-1 Sample TFTP Filename Groovy Script
/**
* example_extended_filename.groovy
*
* A sample CableLabs Configuration Filename Script that demonstrates how
* to create an extended filename. This example includes the following
* strings in the extended filename: DeviceType, Selected ClassOfService,
* and provisioning group. For DOCSIS device types, the default DOCSIS
* version is included after device type. The resulting extended filename
* string is:
*
* "<device-type>_<default-docsis-version>_<selected-cos>_<pg>"
* (e.g., "cm_11_goldcos_westpg", "pc_silvercos_eastpg").
*
* A CableLabs Configuration Filename Script specifies an extended filename
* label that is appended to the standard BAC dynamic configuration filename.
* In BAC 4.2 and later releases, the dynamic configurations have a filename
* consisting of the fixed/standard prefix. The script can be configured at
* System Defaults (preferred) and/or Technology Defaults.
*
* BAC properties:
* DocsisDefaultKeys.DOCSIS_DEFAULT_VERSION
*
* Variable bindings:
* configFileName - Extended Filename of type StringBuilder
* services - of type ExtensionServices
* discoveredData - of type DHCPDataAccess
* deviceProperties - of type CSRCProperties
* device - of type IPDevice
* context - of type ConfigContext
*/
import com.cisco.provisioning.cpe.constants.DocsisDefaultKeys
import com.cisco.provisioning.cpe.extensions.constants.CNRNames
import com.cisco.provisioning.cpe.extensions.services.DeviceType
/*
* A Groovy list is used to collect the ordered list of string fields
* that will comprise the extended filename. Once all the fields have been
* added to the list, the "join" method is used to concatenate the
* fields with a underscore ('_') separator character.
*/
def label = []
/*
* Add Device Type (abbreviated).
*
* The device type string is too verbose for a filename component, so an
* abbreviation is used instead. For example, the DOCSIS device type value
* "DOCSISModem" is abbreviated as "cm". If no abbreviation is defined,
* a default abbreviation of "xx" is used.
*/
def deviceType = device.getDeviceType().getName()
def deviceTypeMap = [
(DeviceType.DOCSIS_MODEM) : "cm",
(DeviceType.PACKET_CABLE_MTA) : "pc",
(DeviceType.CABLEHOME_WAN_MAN) : "ch",
(DeviceType.STB) : "st",
(DeviceType.CUSTOM_CPE): "cu"
]
label << deviceTypeMap[deviceType] ?: "xx"
/*
* Add default DOCSIS version number (exclude embedded "dot").
*
* For DOCSIS device types, the default DOCSIS version number specifies the
* maximum DOCSIS version supported by the CM and CMTS. This version number
* indicates the DOCSIS version grammar used when constructing the dynamic
* configuration file. The embedded "dot" is stripped from the version number
* (i.e., "3.0" --> "30").
*/
if (deviceType == DeviceType.DOCSIS_MODEM)
{
label << deviceProperties.getProperty(
DocsisDefaultKeys.DOCSIS_DEFAULT_VERSION, "1.0") - "."
}
/*
* Add Selected Class of Service name.
*/
label << device.getSelectedClassOfService().getClassOfServiceName()
/*
* Add Provisioning Group name.
*/
label << device.getProvGroup().getProvGroupId()
/*
* Convert the list of filename components into a string value with underscore
* ('_') characters separating the filename components. Add the resulting
* string to the configFileName StringBuilder binding.
*/
configFileName << label.join("_")Dynamic TFTP File-Naming via Extensions
The TFTP File-Naming ability has been enhanced to support customization at the RDU extension level. Prior to Prime Cable Provisioning 5.2 release, the TFTP filename can be named dynamically only using the TFTP filename generation Groovy scripts. Prime Cable Provisioning 5.2 release allows user to set the configuration filename in a shared context which is available across the service-level extensions, configuration generation extensions and configuration generation scripts.
The filename set in the shared context can be configured at technology or system defaults level which will have the higher precedence over the filename set at the TFTP filename generation Groovy scripts.
Shared Context Filename
A shared context
(
com.cisco.provisioning.cpe.extensions.configuration.SharedConfig ) is
now included in the ConfigContext
(com.cisco.provisioning.cpe.extensions.configuration.ConfigContext) which is
shared across the service-level extensions, configuration generation extensions
and configuration generation Groovy scripts. The new shared context object has
a setter method
(
setConfigFileName (String) ) which can be used to populate the
filename. The sample code snippet given below explains the filename population
in shared context on extension.
SharedConfig sharedConfig = configContext.getSharedConfig(); sharedConfig.setConfigFileName("<fillup_the_filename_here>");In addition to set and get methods for the filename, the shared context object also has a map object (can be accessed using the get method <Map<String, Object> getSharedConfigMap()) which can be used as a container to save data and share between extensions .
The shared context is
included in device detection context
(com.cisco.provisioning.cpe.extensions.detection.DeviceDetectionContext)
which is used by the device detector extensions. The shared context that is
populated by device detection extensions will be pre-populated in the
configuration context that is shared by the service level extensions and
configuration generation extensions. If the shared context is populated by the
device detection extension, it will be pre-populated in the configuration
context which can be used by the service level selection and configuration
generation extensions.
The Device disruptor
context
(com.cisco.provisioning.cpe.extensions.disruption.DeviceDisruptionContext)
now encapsulates a shared context. However, this is not relevant to the
configuration context or the file naming. The shared context
(com.cisco.provisioning.cpe.extensions.configuration.SharedContext) included in
the device disruption context can be used by multiple device disruptor
extensions.
Basic flow of Dynamic TFTP filename generation
The following is the sequence of steps that explains the basic flow of filename generation:
-
RDU receives a configuration generation request.
-
The RDU runs the configuration generation for the device, during which, the generation extension determines that a dynamic TFTP file needs to be assigned to the device. The file could be a template (for example, docsis.tmpl) or a script (for example, docsis.groovy), (for example, silver.cm)
-
After running all the custom extensions, the configuration engine looks for the availability of the filename in the shared context. If the filename is populated in the shared context, and the Provisioning Group capability "/provgroup/capability/dpe/tftp/filename/extensions" (ProvGroupCapabilitiesKeys.TFTP_DYNAMIC_FILENAME_USING_EXTENSIONS) is enabled, then it will follow the step 5. If the filename is not populated in the shared context, then it will follow the filename generation as per the Extended TFTP filename Groovy script workflow, as mentioned in step 4.
-
The generation extension looks for the CableLabs Configuration Filename Script property in the technology defaults. If not found, it looks in the system defaults. The value of this property is the name of the script to be executed. The script is executed and it returns the additional strings to be included in the dynamic TFTP filename.
-
The generation extension uses this value and creates a dynamic TFTP filename for the device. After the filename generation is complete, the configuration is sent to the DPEs, which is then cached.
Basic pointers about filename generation via shared context
-
Like the TFTP filename Groovy script functionality, the name populated in the shared context will have the dynamic portion of the actual TFTP configuration filename
-
The default maximum filename length is 127 characters and the filename will be truncated if it exceeds the limit. The space and special character removal are as same as the existing TFTP dynamic filename generation feature.
-
If the filename was not populated in the shared context by any of the custom extensions or the configuration generation scripts, then the filename generation will follow the existing TFTP filename generation via configuration filename generation Groovy scripts workflow.
Sample Service-Level extension to populate the filename in Shared Context
package com.cisco.provisioning.cpe.extensions.samples;
import java.util.Map;
import com.cisco.provisioning.cpe.extensions.ExtensionException;
import com.cisco.provisioning.cpe.extensions.configuration.ConfigContext;
import com.cisco.provisioning.cpe.extensions.configuration.ServiceLevel;
import com.cisco.provisioning.cpe.extensions.configuration.SharedConfig;
import com.cisco.provisioning.cpe.extensions.services.ExtensionServices;
import com.cisco.provisioning.cpe.extensions.services.IPDevice;
/**
* This class will demonstrate usage of Shared Context and the filename
* availability in the configuration context object. The PCP extensions will
* make use of the Shared Context and also have the feasibility of setting the
* filename from the extensions.
*
*/
public class SampleSharedContextServiceLevelSelectionExtension implements
com.cisco.provisioning.cpe.extensions.configuration.ServiceLevelSelector
{
@Override
public void selectServiceLevel(IPDevice device,
ConfigContext configContext, ServiceLevel serviceLevel,
ExtensionServices extensionServices) throws ExtensionException
{
final String extensionName =
SampleSharedContextServiceLevelSelectionExtension.class.getName();
com.cisco.provisioning.cpe.extensions.services.LogManager logManager =
extensionServices.getLogManager();
logManager.log(
com.cisco.provisioning.cpe.extensions.services.LogLevel.INFO,
extensionName, " Executing custom code here..");
long duration = System.currentTimeMillis();
/*
* Get the SharedConfig object from ConfigContext
*/
SharedConfig sharedConfig = configContext.getSharedConfig();
/*
* Get the sharedContext map from SharedConfig object
*/
Map<String, Object> sharedContextMap =
sharedConfig.getSharedConfigMap();
/*
* Set the generated token into the Shared Context map
*/
sharedContextMap.put("customToken_1", generateTokenXYZ());
logManager.log(
com.cisco.provisioning.cpe.extensions.services.LogLevel.INFO,
extensionName, " Shared Context Map after token generation "
+ sharedContextMap);
/*
* Setting the file name in SharedConfig object
*/
logManager.log(
com.cisco.provisioning.cpe.extensions.services.LogLevel.INFO,
extensionName, " Settinng the file name here...");
sharedConfig.setConfigFileName("SetBy" + this.getClass().getCanonicalName());
/*
*
* Set a token that is used by sample configuration script
* example_shared_context.groovy
*/
sharedContextMap.put("maxCPE","7");
logManager.log(
com.cisco.provisioning.cpe.extensions.services.LogLevel.INFO,
extensionName, " Shared Context Map after new token "
+ sharedContextMap);
logManager.log(
com.cisco.provisioning.cpe.extensions.services.LogLevel.INFO,
extensionName, " It took ["
+ (System.currentTimeMillis() - duration)
+ "] milliseconds to complete this extension ");
}
/**
* This method models a custom token generation
* @return the generated token as String
*/
private String generateTokenXYZ()
{
/*
* operation.
*/
return "dummyTokenValue";
}
}
¢
Sample Configuration Script to access Shared Context and populate filename in Shared Context
/**
* A sample CableLabs Configuration Script that demonstrates the Shared Context
availability in Groovy script. And also it demonstrate to populate the filename in Shared Context
*
*
* PCP properties:
* DocsisDefaultKeys.DOCSIS_DEFAULT_VERSION
* SNMPPropertyKeys.READ_COMMUNITY_STRING
* SNMPPropertyKeys.WRITE_COMMUNITY_STRING
*
* Variable bindings:
* configFile - of type DOCSISTFTPFile
* option - of type DOCSISOptionFactory
* services - of type ExtensionServices
* discoveredData - of type DhcpDataAccess
* deviceProperties - of type CSRCProperties
* device - of type IPDevice
* context - of type ConfigContext
*
* @see com.cisco.provisioning.cpe.extensions.configuration.DOCSISTFTPFile
* @see com.cisco.provisioning.cpe.extensions.configuration.DOCSISOptionFactory
* @see com.cisco.provisioning.cpe.extensions.services.ExtensionServices *
* @see com.cisco.provisioning.cpe.extensions.configuration.DhcpDataAccess
* @see com.cisco.provisioning.cpe.extensions.services.CSRCProperties
* @see com.cisco.provisioning.cpe.extensions.services.IPDevice
* @see com.cisco.provisioning.cpe.extensions.configuration.ConfigContext
*/
import com.cisco.provisioning.cpe.constants.SNMPPropertyKeys
import com.cisco.provisioning.cpe.extensions.configuration.SharedConfig
def TLV = option.&createOptionValue
/* 1. Accessing Shared Context */
/*
* This script tries to set the maxCPE value based on the tokens available at the Shared Context
* Populate the maxCPE property in Shared Context by using extensions to use this
demonstration.
/*
* Get the SharedConfig object from ConfigContext
*/
SharedConfig sharedConfigObj = context.getSharedConfig();
/*
* Get the sharedContext map from SharedConfig object
*/
Map<String, Object> sharedContextMapObj =
sharedConfigObj.getSharedConfigMap();
def maxCPE = TLV("18", "3")
if (sharedContextMapObj.containsKey("maxCPE"))
{
maxCPE = TLV("18", (String)sharedContextMapObj.get("maxCPE"))
}
configFile.add(maxCPE)
/* 2. Filename can also be set at this configuration script by using the Shared Context
*/
/** Sets the dynamic filename */
sharedConfigObj.setConfigFileName("samplenamesetByCfgScript");
Feedback