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 () in the palette on the right.
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.
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).
Clicking the 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.
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
orFalse
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 organizationcontext
- Display, create, and edit context sharing settings for a scriptdelete
- Delete an AuQL scriptjob
- List AuQL script jobs and detailsshow
- Display an AuQL script in the AuQL script DSL or interpreted JSONevaluate
- Run an AuQL script from the shellupdate
- Update an AuQL script from a local fileversion
- List, view, and delete script versionsvisualize
- Output a visualization of an AuQL script as a graphparse
- Parse AuQL shell script DSL into JSONparse-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.