Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Script Annotations

Script annotations are used to specify the metadata of a script. They are embedded in scripts. They are parsed and stored in the Junos Space Network Management Platform database while scripts are modified or imported. An annotation uses the following syntax:

/* @[ANNOTATION]= "<ANNOTATION CONTENT>" */

An annotation can be provided anywhere in the script.

Annotations are used to specify the name, description, and confirmation text of a script and the context in which the script can be applied. For an example script with an annotation, see Script Example. Table 1 displays the types of script annotations with their descriptions.

Table 1: Types of Script Annotations

Annotation

Description

@CONTEXT

This annotation is used to specify the context in which the script can be applied. When the context is not specified, the default context is taken as /device.Example:

/* @CONTEXT = "/device/chassis-inventory/chassis/chassis-module[starts-with
(name,"FPC")]/chassis-sub-module[starts-with(name,"PIC")]" */
Note:

You can execute scripts on more than 200 devices only if the script context is /, //, or /device and no device-specific or entity-specific parameters are specified.

@NAME

This annotation is used to specify the descriptive name of the script. Example:

/* @NAME = "Put PIC Offline" */

@CATEGORY

This annotation is used to specify the category to which the script belongs. This annotation enables you to group scripts based on any criteria. The annotation cannot exceed 255 characters. It can contain only letters and numbers and can include hyphen (-), underscore (_), space ( ), or period (.).Example:

/* @CATEGORY = "Interface Configuration" */

@DESCRIPTION

This annotation is used to specify a description of the script.Example:

/* @DESCRIPTION = "Take PIC offline." */

@CONFIRMATION

This annotation is used to specify the confirmation text of the script. That is, the text that must be displayed when an attempt is made to execute the script. When this field is not provided, no confirmation text is shown when the script is executed. This can be used to create warnings for certain scripts.Example:

/* @CONFIRMATION = "Are you sure that you want to take the PIC offline?" */

@EXECUTIONTYPE

This annotation is used to specify the type of execution. The types of execution are GROUPEDEXECUTION and SINGLEEXECUTION. When this annotation is not specified, the default option is SINGLEEXECUTION.Example:

/* @EXECUTIONTYPE = "SINGLEEXECUTION" */

@GROUPBYDEVICE

This annotation is used to specify whether the script must be executed simultaneously or sequentially on the selected devices. The annotation works only for scripts for which the execution type is GROUPEDEXECUTION and @ISLOCAL is true. You can add the GROUPBYDEVICE annotation from Junos Space Network Management Platform Release 15.2R1 onward.

If the annotation is set to TRUE, the script is executed on the selected devices at the same time. If set to FALSE or if the annotation is not included in the script, the script is executed sequentially on the selected devices.Example:

/* @EXECUTIONTYPE = "GROUPEDEXECUTION" */ /* @GROUPBYDEVICE="TRUE" */ /* @ISLOCAL = "true" */

@ISLOCAL

This annotation is used to define whether the script is to be executed locally or staged on the device. This could be True or False. Example:

/*@ISLOCAL="true"*/

@VARIABLECONTEXT

This annotation is used to define the context of a variable.Example:

/*@VARIABLECONTEXT="[{'name':'XPATHVARIABLE1','defaultvalue'
:'mydefaultvalue','parameterscope':'devicespecific'},{'name'
:'XPATHVARIABLE2','configuredvaluexpath':'/device/interface-information/
physical-interface/name/text()','parameterscope':'entityspecific'},{'
name':'XPATHVARIABLE3','selectionvaluesxpath':'/device/
interface-information/physical-interface/name/text()','parameterscope':'global'}]"*/

@PASSSPACEAUTHHEADER

This annotation is specific to local scripts. If the annotation is set to True, then the $JSESSIONSSO and $JSESSIONID script variables are set. Example:

/*@PASSSPACEAUTHHEADER="true"*/

This annotation also provides the virtual IP address of the cluster in $VIP.

@PASSDEVICECREDENTIALS

This annotation is specific to local scripts. If the annotation is set to true, Junos Space Platform sets the device credentials to $credentials and $deviceipmap variable (that is, $deviceipmap= '{"192.168.0.210":"Device1",...}')..Example:

/*@ PASSDEVICECREDENTIALS ="true"*/

@PROMOTE

This annotation is used to define whether the script is available for execution as a right-click action. This only works for scripts with the @EXECUTIONTYPE = "SINGLEEXECUTION" annotation.

@ONCLOSESTRING

This annotation is used when the user wants the script execution result page to be closed automatically after the expected result is received. The @ONCLOSESTRING annotation contains a string. This string is compared with the script execution results. When the specified string appears in the script output, the script execution result page is automatically closed. The @ONCLOSESTRING annotation is useful for script promotion.

For example, if a user has included the @ONCLOSESTRING annotation in the Reboot script containing a string that is displayed on successful execution of the script and executes the promoted Reboot script. The script execution result page closes by itself automatically and the reboot command is sent to the device successfully. If the script is not executed successfully, the reason for failure is displayed in the script execution result window. This further improves user experience by reducing the number of clicks required by the user to complete an action.

@FAILJOBSTRING

This annotation is used to specify an arbitrary string which if present in the script output identifies the script execution as failure. The @FAILJOBSRTING annotation can take an arbitrary string value that does not exceed 255 characters. Because the string comparison is case sensitive, ensure that the string specified for @FAILJOBSTRING and the one in the script output use the same casing.

The value of the @FAILJOBSRTING annotation can also be used as a tag name. If the script output contains the tag, the corresponding job is marked as failure.

/* @FAILJOBSTRING = "Reason for Job Failure" */

/* @FAILJOBSTRING = "Failed while creating vlan" */

Script Execution Types

With the SINGLEEXECUTION script execution type, the script can be executed only on a single element at a time. This is helpful if the script developer wants to ensure that the script execution is not executed for multiple elements simultaneously.

With the GROUPEDEXECUTION script execution type, the script is executed for a group of devices simultaneously. The context of the elements belonging to the group is passed as an expression to the $CONTEXT variable in the script. This way, the script is provided with the elements for which the script should be executed.

For example, for GROUPEDEXECUTION, the context structure could be as follows:

Variable Context

The variable context defines what input the script is expecting from the user. This context can be used to autopopulate user-input options. This behavior is similar to that of the parameters in CLI Configlets. The variable context is defined using the @VARIABLECONTEXT annotation. The options are given in the following format:

@VARIABLECONTEXT = "[{'name':'<variable-name-1>', '<option-1-1>':'<value-1-1>','<option-1-2>':'<value-1-2>',....,},.....,{'name':'<variable-name-n>', '<option-n-1>':'<value-n-1>','<option-n-2>':'<value-n-2>',....,}]"

Table 2 explains the possible options.

Table 2: Variable Context Options

Option

Description

configuredvaluexpath

This specifies the XPath (with reference to the device XML) from which the value of the parameter must be fetched.

defaultvalue

The behavior is the same as that of configured value of XPath except that the value is given explicitly. This is considered only when "configuredvaluexpath" is not specified.

selectionvaluesxpath

This contains the XPath (with reference to the device XML) to fetch the set of values for populating the options.

selectionvalues

This is the same as the "selectionvalues" except that the comma-separated values are given explicitly.

parameterscope

This is used to specify the scope of a parameter.

  • entityspecific – A value is required for each individual entity.

  • devicespecific – A value is required for each individual device.

  • global – Only a single value is required for all entities.

password

Use this option to allow the user to enter a password before executing the scripts. This obscures or displays the input parameters that you enter when you execute an op script. If you configure an op script with the @VARIABLECONTEXT script annotation for an input parameter with the "password" option, the input parameters that you enter in this field are obscured or displayed depending on the following values:

  • no – The input parameter entered is not obscured.

  • yes – The input parameter entered in this field is obscured. The configuredvaluexpath, defaultvalue, selectionvaluesxpath, and selectionvalues options are ignored.

  • Confirm – You need to enter the same input parameter twice. The input parameter entered is obscured. The configuredvaluexpath, defaultvalue, selectionvaluesxpath, and selectionvalues options are ignored.

Local Script Execution

With Junos Space, you can execute op scripts in one or more devices simultaneously without staging and enabling the scripts. To do this, you use the local script execution feature. This feature enables you to execute the script locally in the Junos Space server. The @ISLOCAL annotation in the script must be set to true to differentiate normal script from the local script:

/*@ISLOCAL="true"*/

Local scripts run directly in the Junos Space server, so you do not need to stage, enable, or disable these scripts. If a script that is already staged is modified using the @ISLOCAL annotation, the update is rejected.

You can execute local scripts on one or more selected devices. For a cluster setup, you need to execute the scripts on a VIP node.

For the GROUPEDEXECUTION execution type, the device IP address list is passed as a parameter. The script opens an internal connection before interacting with the device.

You can execute local scripts with the GROUPEDEXECUTION execution type on multiple devices simultaneously by setting GROUPBYDEVICE to TRUE. If the GROUPBYDEVICE annotation is set to FALSE or if the annotation does not appear in the script, the script is executed sequentially on the selected devices.

Note:

Local scripts can be executed on devices with Junos Space–initiated connection.

Nesting Variables

You can use the XPath context to define the default option or the selectable options of a variable that are displayed on the script execution page. This XPath could have dependencies on other variables. Consider the following example:

A script requires two inputs: Physical Interface (Input-1) and a Logical Interface (Input-2) that is part of the selected Physical Interface (Input-1). You first define a variable PHYINT to get the name of the physical interface and a variable LOGINT to get the name of the logical interface. You then define the SELECTIONVALUESXPATH for PHYINT as /device/interface-information/physical-interface/name/text(). Select a value from the options listed by the XPath. Because the selection values listed for the LOGINT variable is dependent on the value selected for PHYINT, you define the SELECTIONVALUESXPATH of LOGINT as /device/configuration/interfaces/interface[name='$PHYINT']/unit/name/text(). This ensures that only the logical interfaces of the selected physical interface are listed.

Note:

When using the $INTERFACE, $UNIT, Configured Value XPath, Invisible Params, and Selection fields, the variable definition in the CLI Configlet Editor should contain .get(0) to fetch the value from the array. For example, $INTERFACE.get(0).

Related Documentation

Release History Table
Release
Description
15.2R1
You can add the GROUPBYDEVICE annotation from Junos Space Network Management Platform Release 15.2R1 onward.