Analytic development best practices

Analytic scripts support most of the commands that you can use in a regular script. However, you must ensure that analytic scripts run without user interaction, and that they do not include commands not supported by the engine that processes the analytic scripts in the Robots app in Diligent One.

Analytic scripts support all ACLScript functions.

General best practices

Use one Analytics project per robot

Create a new Analytics project for each robot. The project must contain all the analytic scripts that make up the robot, and any required subscripts.

Test locally

Test all analytic scripts locally before deploying them to the Robots app. Ensure that analytic scripts run as expected, and that they do not require user interaction.

For more information, see Developing analytic scripts.

Use consistent data connections for testing

To test an analytic script locally if it uses an ODBC data source, you must configure an ODBC connection on your local computer that is identical to the connection in the environment where the analytic script will run.

Avoid absolute file paths

Avoid using absolute file paths in analytic scripts (for example, C:\results) unless you are certain that identical file paths exist in the environment where the analytic script will run.

Using relative file paths such as \results allows you to develop and test analytic scripts locally and then deploy them in another environment without requiring that the other environment has an identical directory structure.

Use SET for preference settings

Use the SET command to specify any preference settings required by the analytic script. If you do not specify preferences in the analytic script, the default Analytics preferences are used. Position the SET command after the analytic header but before any of the analytic script logic.

Do not use computed fields in results or data output tables

Do not use computed fields in any output tables that you intend to keep beyond the session in which the analytic script runs.

Results and data tables that are kept for use in interpretations or as input for subsequent scripts may display unexpected values if they contain computed fields. Computed values are dependent on settings defined in the preference file (.prf), or by the SET command, and therefore different environments may produce different values.

If you need to retain the values in a computed field, use the EXTRACT command with the FIELDS or ALL option to convert the field to a physical field in a result or data table. For more information, see EXTRACT command.

Encrypt data connection passwords

To avoid having a data source password in plain text in an analytic script, use the //PASSWORD analytic tag. This tag prompts the user for a password before running the analytic script, and encrypts the entered value.

Use a password when importing from or exporting to Diligent One

The PASSWORD parameter is required in any command that imports from or exports to Diligent One:

  • IMPORT GRCRESULTS
  • IMPORT GRCPROJECT
  • EXPORT... ACLGRC
  • EXPORT... HBDATA

Without the PASSWORD parameter, the commands fail in Robots.

When you use the PASSWORD parameter in a command, you must also specify an associated //PASSWORD tag in the analytic header. For more information, see PASSWORD tag.

Note

The PASSWORD parameter is not required when running the import and export commands in Analytics because the current user's Diligent One access token, stored locally in the Windows registry, is automatically used.

Avoiding user interaction

Analytic scripts must be able to run without user interaction. If a command in an analytic script tries to create a dialog box, the engine in the deployment environment stops processing the analytic script, and an error is entered in the log.

Replace user interaction commands with analytic tags

Do not use Analytics commands that require user interaction. Replace them with equivalent analytic tags in the analytic header. Analytic tags allow users to provide input values before the analytic script runs.

Do not use Replace with
DIALOG //PARAM , //TABLE , //FIELD
ACCEPT //PARAM , //TABLE , //FIELD
PASSWORD //PASSWORD
PAUSE no equivalent

Guidelines

  • Interactive commands To prevent analytic script processing failures, remove all interactive commands.
  • SET SAFETY To ensure files can be overwritten as necessary without displaying a confirmation dialog box, add the SET SAFETY OFF command at the beginning of an analytic script.

    Add the SET SAFETY ON command at the end of the analytic script to restore the default behavior.

  • OK parameter To prevent confirmation dialogs from crashing the analytic script, add the OK parameter after any commands that normally display a confirmation dialog box:
    • RENAME
    • DELETE

Checking script syntax

Analytics provides a tool for detecting script syntax that causes analytic scripts to fail, or that requires alignment between your local environment and the environment where the analytic scripts are deployed. The tool provides a warning only, and you are still free to commit or import analytic scripts that have warnings.

What the tool checks

The tool checks all scripts in a project for the following items:

  • any command that requires user interaction
  • any absolute file path
  • any call of an external script

When the check is performed

Script syntax checking is performed automatically when you commit scripts to Robots.

Automatic syntax checking is enabled by default. If you want to turn it off, select Disable Script Syntax Check Before Commit Scripts in the Options dialog box (Tools > Options > Interface).

Perform checking manually

You can perform script syntax checking manually. You may need to first add the Check Scripts button to the Analytics toolbar.

  1. If necessary, add the Check Scripts button to the Analytics toolbar:
    1. Double-click an empty spot on the toolbar to open the Customize Toolbar dialog box.
    2. In the Available toolbar buttons list, select the Check Scripts button and click Add.
    3. In the Current toolbar buttons list, select the Check Scripts button and click Move Up or Move Down to change the location of the button.

      The order of the buttons from top to bottom corresponds to their location from left to right on the toolbar.

    4. Click Close to save your changes.

  2. On the toolbar, click Check Scripts .

    A message appears telling you that the script syntax in the project is valid, or specifying one or more warnings.

  3. Do one of the following:
    • Correct any script syntax that generates a warning, and click Check Scripts again to ensure that the warnings no longer appear.
    • Ensure that the deployment environment contains a directory structure, or external scripts, that align with the paths or external scripts specified in the analytic script.