Scripting in Robots

Note

Capabilities described in this topic are being introduced on a phased basis, starting in Spring 2021. Some of the features and functionality may not yet be available.

Currently, saving to a Results table is the only way to save output results from the two new robots types (Workflow robot and HighBond robot). New capabilities for securely and conveniently storing and accessing files and data are currently in development for future release.

The Robots app provides native, cloud-based scripting that you can use for data analysis or for automating portions of your organization's HighBond workflow. Robots scripting combines the full power of Python and all its supporting libraries with HighBond Command Language (HCL), our custom Python library for domain-focused data analysis and HighBond automation.

Robots continues to support data analysis and data automation using ACLScript and analytic scripts uploaded from Analytics. So you can benefit from any existing investment in ACL (Audit Command Language) and all the possibilities offered by Python, an industry-standard programming language, and HCL.

Three types of robots

The Robots app contains three types of robots. While similar in many ways, the different robot types support different scripting scenarios:

  • ACL robot Supports full-scale data analysis with scripts you upload from Analytics, and scheduled tasks. Scripts can run in the cloud, or on-premise.

  • HighBond robot Supports full-scale data analysis with HCL/Python scripts created directly in the robot, and scheduled tasks. Scripts can run in the cloud only.

  • Workflow robot Supports automating portions of your HighBond workflow with HCL/Python scripts created directly in the robot, and event-based or scheduled tasks. Scripts can run in the cloud only.

    Note

    To access Workflow robots, you must be assigned the System Admin role with a Professional subscription type.

Comparison of the robot types

The three robot types are intended for different purposes and are functionally separate from one another. You cannot mix ACLScript and HCL/Python in a single robot.

  ACL robot HighBond robot Workflow robot
Intended purpose data analysis and automation HighBond platform automation
Supported language ACLScript
  • Python

  • Pandas, NumPy, Requests, and other standard Python libraries

  • HCL custom Python library (HighBond Command Language)

Script authoring location Analytics Robots
Script execution location
  • cloud

  • on-premise

  • cloud

Options for running a task
  • scheduled

  • run ad-hoc (manually)

  • triggered by HighBond event

  • scheduled

  • run ad-hoc (manually)

Maximum run time
  • cloud-based Robots Agent: 60 minutes

  • on-premise Robots Agent: controlled by customer network

12 hours

Note

Proposed limit awaiting implementation

15 minutes
Maximum tasks running simultaneously 5 5 50
Required permissions
  • be a collaborator for the robot

  • degree of access controlled by the collaborator's robot role (Owner, Editor, Reviewer)

System Admin role with a Professional subscription type

Robots script editor

HighBond robots and Workflow robots contain an integrated script editor for authoring HCL/Python scripts. The script editor is modeled on the Jupyter Notebook App, a development environment popular in the data science community. The script editor uses a Cell-based approach to script authoring.

Number Description
1 Name of the robot containing the script
2 Version number of the script open in the script editor
3

Cell controls:

  • Run the cell

  • Add a new cell below (not shown)

  • Delete the cell (not shown)

4

Sequence indicators displaying the order in which each cell has been run

For more information, see Key characteristics of cell-based script authoring.

5

Cells for writing script code

For more information, see Cell-based approach to script authoring.

6 Displayed output of a cell
7

Top toolbar:

Add a new cell below the selected cell
Run the selected cell
Run all cells in top-to-bottom sequence
Stop script execution
Delete the selected cell
Revert the script to the previously committed version
8

Variables button: opens the Variables window for defining HCL variables

For more information, see Using variables in a Python/HCL script.

9

Commit button: saves the script and commits it as a new version

Cell-based approach to script authoring

The most obvious feature of the script editor is the ability to use multiple cells to contain the individual blocks of code that make up a single script. If you are not familiar with Jupyter Notebook, the cell-based approach to script authoring may initially look complicated. In fact, it is easy to use and has benefits you will quickly come to appreciate.

Note

Cells do not affect how scripts run. Scheduled, unattended script execution progresses line by line, from top to bottom, regardless of the presence of cells in the script editor.

Key characteristics of cell-based script authoring

  • Multiple cells are optional You do not have to use multiple cells if you do not want to. You can author and run an entire script using a single cell.

  • Logical divisions Cells allow you to divide a script into logical blocks of your own choosing, and to manually run the blocks individually, in any order, or as an entire sequence.

    For example, a basic four-cell arrangement for a script could be:

    • first cell import Python libraries

    • second cell import data

    • third cell perform analysis on the data

    • fourth cell output the results of the analysis

  • Benefit of cells Using cells for script development has these benefits:

    • You can work on individual cells in isolation, testing and improving them, while temporarily ignoring script logic contained in other cells.

    • After you run the initial import cells once you do not need to keep running them as you develop and repeatedly test subsequent cells.

    • You can use cells to impose a visual order on your scripts, making the relation between the different logical blocks easier for you, or someone else, to see and understand.

  • Sequence indicator Beside each cell is a numeric indicator that displays the order in which the cell has been run during a scripting session. For example: [7].

    When you run a cell, the indicator increments, taking into account any other cells that you have run in the interim. So, for example, an indicator could change from [7] to [10] if you had run two other cells in the interim, or one other cell twice.

  • Session memory and stored values Dataframes and variable values held in memory during a scripting session are updated based on the sequence in which you run cells.

    Typically, you structure cells to run sequentially from top to bottom during scheduled, unattended script execution. Certain dataframes or variable values may be progressively updated based on script logic. If you manually run cells out of order, the current state of a dataframe or a variable value may not be what you assume it to be and an error or an inaccurate result could occur. To restore the dataframe or the variable value to its intended state, just re-run all cells referencing the dataframe or the variable in their intended order.

  • Display of cell output By default, running a cell displays only the output of the last expression in the cell. If you want to see the output from multiple expressions in a cell, you can put the expressions in separate cells. However, a more convenient approach is to set a configuration option in the script editor.

    • Configure cells to display the output of all expressions:

      from IPython.core.interactiveshell import InteractiveShell
      InteractiveShell.ast_node_interactivity = "all"
    • Reset cells to display the output of only the last expression:

      from IPython.core.interactiveshell import InteractiveShell
      InteractiveShell.ast_node_interactivity = "last_expr"

    Tip

    You can use the configuration setting to switch back and forth between the two modes as required. For additional configuration options for cell output, consult Jupyter or IPython documentation online.

Jupyter Notebook features not included in the Robots script editor

As noted above, the Robots script editor is modeled on the Jupyter Notebook App. These Jupyter features are not included in the script editor, although some of them may be included over time as the product continues to evolve:

  • cell-level operations: undo/redo cell operations, copy/paste cells, move cells up/down, split/merge cells

  • run all cells above/below the selected cell

  • Markdown cells (for text content)

Making the transition from ACLScript to Python and HCL

Python is a general-purpose programming language and is significantly more complex than ACLScript, which is a relatively straightforward scripting language originally designed for the audit analytics domain.

Our intention is that over time HCL will replicate many of the commands and functions available in ACLScript. To get started with HCL, our custom Python library, requires that you have at least basic Python skills. The advice for those looking to make the transition from ACLScript to HCL/Python is to take a good introductory Python course.

Python coding conventions

You will need to get used to certain coding conventions that are not enforced in ACLScript but are enforced in Python and HCL:

  • Case sensitivity Python and HCL syntax is case-sensitive, whereas ACLScript syntax is not.

    In Python:

    • print("Hello World!") works

    • PRINT("Hello World!") gives an error

  • No abbreviating Python and HCL function, method, and parameter names must be spelled out in full. Unlike ACLScript, abbreviations are not supported.

  • Indentation matters Python uses indentation to implement control structures such as conditional statements and loops. Incorrect indentation causes errors. ACLScript ignores indentation.

Using HCL and Python to work with APIs

You can use HCL and Python to work with APIs – both third-party APIs and HighBond's own API.

Work with a third-party API

To work with a third-party API, begin by importing the Python Requests library in the HighBond script editor:

import requests

You can now make API requests using Python's request syntax and receive responses.

Explaining how to use Python with a third-party API is beyond the scope of our documentation. However, many online resources exist that can provide detailed guidance.

Work with the HighBond API

The HighBond API is the developer interface for the HighBond platform. You can use the API to automate HighBond interactions and workflow, build reporting, and integrate HighBond with other systems in your organization.

HCL includes methods that make interacting with the HighBond API straightforward. For more information, see HCL HighBond API methods.

You can also use the Python Requests library with the HighBond API. However, for ease and simplicity, we recommend using the HCL methods.