Scriptable service catalog variables

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Scriptable Service Catalog Variables

    This guide explains how ServiceNow customers can use scripting to reference and manipulate service catalog variables within both scoped and non-scoped environments. It covers accessing variables by name, working with variable sets, and handling multi-row variable sets. Understanding these scripting capabilities enables customers to automate and customize catalog item processing, improve data handling, and integrate with other CMDB or asset management records efficiently.

    Show full answer Show less

    Key Features

    • Variable Access: Reference any request item variable using current.variables.<variablename>. For variables in variable sets, use current.variables.<variablesetname>.<variablename>.
    • Role-Based Access: Variable sets have read, write, and create roles that override individual variable roles, enforcing consistent access control.
    • Scripting Examples: Demonstrates how to print variables, set variables dynamically, and create inventory items (e.g., computers) with fields populated from catalog variables.
    • GlideRecord Variables API: Provides methods to retrieve variables and their properties, including:
      • getVariableValue() for values
      • getElements() for listing variables (with option to include multi-row variable sets)
      • Methods like isMultiRow(), getLabel(), canRead(), canWrite(), and getDecryptedValue() for detailed variable inspection
      • Multi-row variable set row and cell operations such as getRows(), getRowCount(), addRow(), and deleteRow()
    • Multi-row Variable Set Handling: Supports accessing and modifying multi-row sets both as JSON arrays and through row/cell manipulation methods, enabling detailed data management within catalog requests.

    Key Considerations

    • Variables must have unique names to avoid collisions; duplicate variable names will overwrite previous ones.
    • Variables can only be set in before business rules; after business rules do not persist variable changes to the database.
    • Date/time variables are stored in GMT internally but displayed in the user’s local timezone and format.
    • The getElements() method excludes formatter variables like labels and containers, focusing on user-input variables.

    Practical Application for ServiceNow Customers

    Using these scripting capabilities, customers can programmatically read and write service catalog variables to tailor catalog item behavior, automate asset creation from request data, and handle complex variable sets including multi-row tables. The detailed API methods allow fine-grained control over variable access and manipulation, which is essential for building robust and secure catalog workflows aligned with business needs.

    You can use scripting to reference any request item variable from a table in scoped and non-scoped environment.

    An example of a variable reference follows.
    current.variables.<variable_name>
    Where current refers to the current record, and <variable_name> is the name of your variable.
    Note:
    In order to reference a variable from JavaScript, it must have a name.

    When a variable is part of a variable set, you can reference it as current.variables.<variable_name> or current.variables.<variable_set_name>.<variable_name>.

    Variable set is also a first-class citizen in Service Catalog. Like variables, a variable set has read, write, and create roles. If roles are provided for a variable set, the roles are applicable for the variables within the set. Roles of an individual variable are overridden by the roles of the variable set.

    Print a variable

    var original = current.variables.original_number;
gs.print(original);

    Set a variable

    current.variables.name = "Auto-Generated:" + current.variables.asset_tag;

    Create an inventory item with fields set from variables

    doCreation(); 

function doCreation ( ) { 
var create = current.variables.create_item; 
if (create == 'true') { // we want to create an asset 
  var computer = new GlideRecord('cmdb_ci_computer');
  computer.initialize();
  computer.asset_tag = current.variables.asset_tag;
  computer.serial_number = current.variables.serial_number;
  computer.name = current.variables.name;
  computer.manufacturer = current.variables.company;
  computer.insert(); } }

    Get GlideElementVariable of variables and variable sets associated with a GlideRecord

    now_GR.variables

    Get the name value pair of variables associated with a GlideRecord

    now_GR.variables.getVariableValue();

    Get a list of GlideElementVariable for variables within a task record

    now_GR.variables.getElements();

    Get a list of GlideElementVariable for variables (including multi-row variable set) within a task record

    now_GR.variables.getElements(true);
    Note:
    The getElements() method returns all the variables present on the given task record except for the formatter variables like label, break, container end, container split, and so on.

    APIs for GlideElementVariable

    • now_GR.variables.<var_name>.isMultiRow(): Get whether the GlideElementVariable is a multi-row variable set or a variable.
    • now_GR.variables.<var_name>.getQuestion(): Get the Question object for a variable. Applicable only for a variable (isMultiRow() is false) and not for a multi-row variable set.
    • now_GR.variables.<var_name>.getLabel(): Get the label of the GlideElementVariable. For a variable, the label of the variable is returned. For multi-row variable set, the title of the variable set is returned.
    • now_GR.variables.<var_name>.canRead(): Get whether the user can view a variable or multi-row variable set.
    • now_GR.variables.<var_name>.canWrite(): Get whether the user can edit a variable or multi-row variable set.
    • now_GR.variables.<var_name>.getDecryptedValue(): Get the decrypted value for a masked variable. Applicable only for a masked variable.
    • now_GR.variables.<var_name>.getRows(): Get the list of row objects for a multi-row variable set. Applicable only for a multi-row variable set (isMultiRow() is true).
    • now_GR.variables.<var_name>.getRowCount(): Get the number of rows for multi-row variable set. Applicable only for a multi-row variable set (isMultiRow() is true).

    Example to access variables of GlideRecord for the Task table

    var now_GR = new GlideRecord('sc_req_item'); 
if (now_GR.get('635a1f5387320300e0ef0cf888cb0b73')) { 
    var variables = now_GR.variables.getElements(); 
    for (var i=0;i<variables.length;i++) { 
        var question = variables[i].getQuestion(); 
        gs.log(question.getLabel() + ":" + question.getValue()) 
    } 
}

    Example to access a multi-row variable set of GlideRecord for the Task table

    var now_GR = new GlideRecord('sc_req_item');
now_GR.get('02c38dcd87013300e0ef0cf888cb0bb2');

var vars = now_GR.variables.getElements(true);

for (var i=0; i<vars.length; i++) {
    var now_V = vars[i];
    if (now_V.isMultiRow()) {
        var rows = now_V.getRows();
        for (var j=0; j<now_V.getRowCount(); j++) {
            var row = rows[j];
            var cells = row.getCells();
            for (var k=0; k<cells.length; k++) {
                var cell = cells[k];
                gs.info(cell.getLabel() + ":" + cell.getCellDisplayValue())
            }
        }
    }
}

    Multi-row variable set

    Table 1. Multi-row variable set
    Operation Usage
    Table operations
    Return JSON array value as String 
    now_GR.variables.table_var
    Set value of a multi-row variable set 
    now_GR.variables.table_var = <val>
    Note:
    An array of ordered (key, value) pairs is also applicable as input.
    Get value of column, var1, of a multi-row variable set 
    now_GR.variables.table_var.var1
    Set value of a variable set, var1 
    now_GR.variables.table_var.var1 = <val>
    Note:
    An array of ordered (key, value) pairs is also applicable as input.
    Row operations
    Get the current row count 
    now_GR.variables.table_var.getRowCount()
    Returns the row specified by the variable "i" - getRow(<int> i) 
    var row = now_GR.variables.table_var.getRow(<int> i);
    Get the cell value for a question column mapped to <var_name> 
    row.<var_name>
    Set the cell value for a question column mapped to <var_name> 
    row.setCellValue('<var_name>',value)
    Set the cell value for a question column mapped to <var_name> 
    row.<var_name> = value
    Add an empty row at the end of the table and return a scriptable object 
    var row = now_GR.variables.table_var.addRow()
    Delete a row 
    row.deleteRow()

    Notes and limitations

    • //Single column of table_Var
    • now_GR.variables.table_var.var1
    • now_GR.variables.table_var.var1 = <val>
    1. You can only set a variable in a before business rule. Variables set in an after rule are not written to the database.
    2. There is nothing in place to prevent namespace collision with variables. Creating two variables named computer_speed would result in only one of them showing up; the second one would overwrite the first one.
    3. Date/time variables use the same time zone formatting and storage rules as all other dates in the system. They are stored internally in GMT, but translated into the user's local time zone and format for display.