Analytic scripts

Scripts are not limited to running in Analytics only. By converting regular scripts to analytic scripts, you can schedule and run scripts in the Robots app on the HighBond platform, or in Analytics Exchange. You can also run analytic scripts in the Analysis App window, a freestanding component of Analytics.

What are analytic scripts?

An analytic script, or "an analytic", is a regular script with an analytic header. The analytic header is a series of declarative tags that allow the script to run in Robots, on AX Server, or in the Analysis App window. The analytic header includes input parameters that a user populates in advance, which allows the analytic script to run unattended, either immediately, or at a scheduled time.

Tip

Analytic scripts are almost exclusively developed and tested in Analytics, which supports easier development. Use AX Client to make simple updates to existing analytic scripts that are stored on AX Server.

What are analysis apps?

An analysis app is an Analytics project that is packaged for use in Analytics Exchange or the Analysis App window. Analysis apps contain one or more analytic scripts, and can also contain data tables and interpretations.

Note

Analysis apps are typically created or developed by an organization's in-house scripting experts, or by arrangement with Diligent consultants.

Turning regular scripts into analytic scripts

Analytic scripts begin as regular scripts. To run a regular script in Robots, on AX Server, or in the Analysis App window, you must convert the regular script into an analytic script:

  1. Create and test a script in Analytics.
  2. Add the appropriate analytic header tags to make the script an analytic script.
  3. Package the analytic script to run on AX Server or in the Analysis App window. You do not package analytic scripts run in Robots.

For more information, see Developing analytic scripts.

Adding analytic headers

Analytic headers are defined in a comment block that starts on the first line of the script. At a minimum, an analytic header declares the script is an analytic script:

COMMENT
//ANALYTIC Identify missing checks
This analytic script identifies missing check numbers
END

For more information, see Working with analytic headers.

What are auxiliary scripts?

An auxiliary script is a regular script without an analytic header that is designed to work in conjunction with an analytic script. In a typical design, an analytic script uses the DO SCRIPT command to call one or more auxiliary scripts. Once an auxiliary script completes, processing returns to the analytic script, which continues to execute.

Auxiliary scripts can also be referred to as subscripts, secondary scripts, utility scripts, or helper scripts. You do not have to use auxiliary scripts. They offer an option for compartmentalizing blocks of script logic that might be conditional, reusable, or simply unwieldy to include in the parent analytic script.

Auxiliary script restrictions

Auxiliary scripts can be used in a variety of different ways, but because no analytic header exists, two restrictions apply:

  • No input or output tags you cannot specify input or output analytic tags, which means you cannot create input or output parameters in the auxiliary script itself. Any required parameters must be created in the analytic header in the parent analytic script.
  • Cannot be run directly users cannot schedule or run auxiliary scripts directly. They can only be called from an analytic script – either directly, or indirectly through another auxiliary script.

Distributing and running analytic scripts

There are several options for distributing and running analytic scripts, depending on which Diligent products and components your organization uses.

App/product/component Method for distributing and running an analytic script
Robots
  • commit one or more analytic scripts, and any auxiliary scripts, as a script version to development mode in Robots, and schedule and run an activated script version in production mode
AX Server

Either of these methods:

  • import the Analytics project (.acl file) directly into AX Server, and schedule and run an analytic script using AX Client
  • package the project into a compressed analysis app file (.aclapp file), import it into AX Server, and run an analytic script using AX Web Client

    For more information, see Packaging analysis apps for import to AX Server.
Analysis App window

Determining the environment where an analytic script is running

If you want to create an analytic script that can run in Analytics, Analytics Exchange, or the Analysis App window, you can determine the runtime environment during script execution. You can use this information to make decisions about which commands to run based on where the script is running.

Use the FTYPE( ) function to determine where the script is running:

FTYPE("ax_main") = "b"

If the script is running in either Analytics Exchange or the Analysis App window, the expression evaluates to true (T). For scripts running in Analytics, the expression evaluates to false (F). For more information, see FTYPE( ) function.

Identifying the user running the script on AX Server

For analytic scripts run on AX Server, you can use the system variable AXRunByUser to identify the name of the user who is currently running the script, in the format domain\username:

EXTRACT FIELDS TIME() AS "Time", DATE() AS "Date", AXRunByUser AS "Current User" TO R_RunRecord APPEND

Note

AXRunByUser is only available when running analytic scripts on AX Server. The variable is unrecognized when running scripts in Analytics.