Managing AuQL Scripts with Aunsight

AuQL scripts live within the Aunsight platform as objects that can be created,stored, manipulated, and deleted by Aunsight platform interfaces and tools. There are a variety of tools exposed by the interfaces that can manage AuQL scripts within an Aunsight organization context. AuQL scripts can be accessed or manipulated by:

This article describes these features, especially the Web Interface in detail. Once you understand how to deploy scripts, you may wish to learn more about the syntax

The Aunsight Web User Interface

The Aunsight Webapp has support for managing and evaluating AuQL Scripts. To After logging in to the Web interface and selecting the relevant context you wish to work in, click the "Script Engine" icon (Script Engine icon) in the palette on the right.

Script Engine workspace

On the left side of the Script Engine workspace, you can search, sort, or create a new script. Click on the name of a script to bring up its details in the right part of the interface window. Script Engine showing a script selected

Details

The script details page offers a variety of tabs. The "Details" tab displays basic details about the script.

  • Modify - The "Modify tab" opens an editor where the AuQL script in the AuQL Domain Specific Language can be edited.
  • Run - The "Run" tab allows users to run the script and specify parameters and hardware resources manually.
  • Versions - Script Engine automatically tracks script versions, enabling users to view older versions of their scripts.
  • Jobs - The "Jobs" tab displays a list of recent jobs which you can sort, search, and filter.

Monitoring Script Jobs

The Jobs list provides a convenient way to monitor the state of jobs started to run a script. The "Jobs" tab provides a filtered view of data tracked in the Jobs workspace so that users can easily monitor when and how their scripts were run, and what the results were. The AuQL Script Engine Jobs tab shows job state ("In Progress", "Succeeded", or "Failed"), activity dates for the job, and the name of the user who ran the job (or the user who created the token used to run the job).

Script engine showing the jobs tab

Clicking the arrow icon (arrow icon) on the job will leave the Script Engine workspace for the Jobs workspace where you can review details of the job status. Additionally, you can view the script's output (the data returned by the return() statement of the script's main() function) at the bottom of the "Script Job Info" section of the job details tab.

Jobs Worskpace showing details of an AuQL script executed successfully

Using AuQL Scripts in Workflows

The Workflow Builder has several components related to the AuQL Scripting Engine:

  • Get Script: returns an AuQL Script Aunsight object. Get Script does not run a script, but the script can later be called by Run Script.
  • Run Script: Executes an AuQL Script of a generic type, returning the job and any script output. Output can be used as input for another component. For example, output of a script can create the text or HTML for an email message sent to users.
  • Evaluate Rule: Executes an AuQL Script with the Rule type, returning the job and True or False outputs. Rule components provide decision-based flow-control to workflow execution.

Toolbelt

The Toolbelt command line interface (CLI) has a set of commands for managing AuQL Scripts under the auql top-level command.

An example of running a script with parameters using the toolbelt:

au2 auql evaluate --id my-script --parameters '{"param1": 10000, "param2": "abc123"}'

Toolbelt exposes the following subcommands under the au2 auql command:

  • create - Upload an AuQL script from file and add to an organization
  • context - Display, create, and edit context sharing settings for a script
  • delete - Delete an AuQL script
  • job - List AuQL script jobs and details
  • show - Display an AuQL script in the AuQL script DSL or interpreted JSON
  • evaluate - Run an AuQL script from the shell
  • update - Update an AuQL script from a local file
  • version - List, view, and delete script versions
  • visualize - Output a visualization of an AuQL script as a graph
  • parse - Parse AuQL shell script DSL into JSON
  • parse-json - Parse AuQL JSON to DSL

The lib-aunsight-js SDK

Developers working with Aunsight can make use of the Javascript API to interact with Aunsight's Script Engine service. The Node.js Aunsight library has an AuQLScript model. See the repository for more information on this SDK and its use.