Developing analytic scripts

The recommended method for developing an analytic script is to first create and test a regular script in Analytics. Once the script is working correctly, add the analytic header to convert the script to an analytic script that can run in Robots.

For information about creating regular scripts, see Get started with scripting.

Identify script inputs and outputs

In the analytic header, you use analytic tags to declare script inputs, and any script outputs that you want to make available to end users, or use as input for subsequent scripts. The different types of inputs and outputs are described below, with the associated analytic tags in parentheses.

Inputs	Outputs
non-Analytics files such as Excel or delimited (FILE tag) input parameters such as cutoff amount, date, or ID codes (PARAM tag) passwords (PASSWORD tag) Analytics tables and fields (TABLE tag, FIELD tag)	Analytics and non-Analytics results tables (RESULT tag) log files for successful scripts (RESULT tag) Analytics output tables that will be used as input for subsequent scripts (DATA tag)

Script inputs and outputs – the big picture

The diagram below illustrates all the possible inputs to, and outputs from, an analytic script. Each input or output shows:

• the type of data or user input involved
• the associated analytic tag (if applicable)
• the associated ACLScript command or commands
• the location of the input or output data, tables, or files

Depending on its design and purpose, a single analytic script might have multiple different inputs and outputs.

Accessing source data

There are two basic approaches to accessing the source data required by an analytic script:

• Automated connectivity
• Manual upload

You are free to use both approaches in the same analytic script, if required.

Automated connectivity

The advantage of this approach is that data imports to Robots can be fully automated including being run on a schedule.

In the body of the analytic script, use one of the ACLScript commands for connecting to an external data source, importing data, and creating an Analytics table with a copy of the data:

• ACCESSDATA
• IMPORT ODBC
• IMPORT GRCRESULTS
• IMPORT GRCPROJECT
• DEFINE TABLE DB

Workflow for creating and testing an analytic script

Create the Analytics script

Create a script in Analytics without using any custom dialog boxes for user input, or any other features that require user interaction during the running of the script. Analytic scripts allow user input prior to running the script, but unlike regular scripts do not support user interaction during script execution.

To store test input values in the Analytics script, temporarily create variables at the top of the script. For example:

ASSIGN v_AnalysisTable = "Trans_May"

Test and debug the script until it executes without errors.

Add the analytic header and tags

Add an analytic header to the script. Copy the variable names from the top of the script to the corresponding tags in the Analytic Header Designer.

An example of a resulting tag in the analytic header:

//TABLE v_AnalysisTable "Table to classify"

For more information, see Working with analytic headers.

Include the log in the analytic script results

The log is a crucial tool for diagnosing the cause of analytic script failures. It can also be important when analytic scripts succeed but give unexpected results. The log is automatically output when an analytic script fails, but it is only output when an analytic script succeeds if you specify the RESULT analytic tag.

In the Analytic Header Designer, turn on Keep log file to ensure that a log is available every time the analytic script is run. The corresponding tag is added to the analytic header:

//RESULT LOG

Validate the analytic header

Validate the analytic header. You can validate the analytic header as frequently as you want.

For more information, see Validating analytic headers.

Assign temporary test values to the analytic tags

Using the special assignment operator ( := ), assign temporary test values to all analytic tags that require user input. You can copy the test values from the temporary variable assignments at the top of the script. For example:

//TABLE v_AnalysisTable "Table to classify" := "Trans_May"

To assign temporary test values using the Analytic Header Designer, enter the value in the Test value field for all analytic tags that require user input.

For more information about assigning temporary test values, see Specifying test input values in Analytics.

Delete the temporary variables

Delete the temporary variables from the top of the script, or comment them out if you think you might want to use them again.

Step through the analytic script

Step through the analytic script by clicking Step , or by pressing F10 repeatedly. Review the contents of the Variables tab in the Navigator to ensure that all variables in the analytic header are being created correctly, with the correct assignment of test values.

Test and debug the analytic script until it executes without errors.

Delete the temporary test values

When you are finished testing, you can delete the temporary test values and the special assignment operator from all analytic tags. Or you can choose to keep them if you anticipate that additional testing might be required. Test values are ignored in deployment environments.

Deploy the analytic script

To deploy the analytic script, commit the script to Robots.

For more information, see Committing ACL scripts (uploading) to Robots.