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 Details tab displays basic details about the script as well as the context for the script.

The general details include the name, ID, created and updated dates and users.

The context section displays information about the script’s ownership. The script's primary owning contexts (organization and project) are displayed as well as any other contexts with which the script is currently being shared.

Sharing Scripts

From the project containing the script you wish to share with another project, click the +Share with new context button.

The Share with Context dialog opens. Use this to define the desired sharing.

  • Select the Context (organization/project) to share the current script to. Available contexts are based on your access.
  • Policies are what the shared to context can do with the shared script.
  • View AuQL Script – provides the ability to view the AuQL script as read-only.
  • Run AuQL Script – gives the ability to view and evaluate the AuQL script.
  • Edit AuQL Script – grants the ability to view, evaluate and change the AuQL Script.
  • Manage AuQL Script – allows the ability to view, evaluate, change, or delete the AuQL Script.
  • Checking the Reshare box permits the context receiving the share to share the AuQL Script with other context.

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. Resources are set to Use Default but can be changed if needed.

Versions

Script Engine automatically tracks script versions, enabling users to view older versions of their scripts on the Versions tab. Selecting a script version initially displays the script, but also provides an option to review the differences between the selected version and the current version.

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.