Scripting can sound scary and difficult to those who are just getting started with ACL Analytics, but with detailed instructions and a little practice, you’ll be reaping the benefits of scripting in no time. But first… what is an ACL script? It is a series of instructions (i.e. ACL commands) that are executed sequentially and used to automate work within ACL Analytics. Any ACL command can be contained in a script.

How can scripting help you? There are a variety of benefits to using a script:

  1. Automate your processes
  2. Increase efficiency
  3. Improve accuracy of analyses
  4. Schedule processes
  5. Unlock advanced functionality

In Part I of this two-part series, we’ll focus on scripting basics. By the end of this newsletter, you’ll be ready to write your first script in ACL Analytics!

Breaking down the ACL Analytics script syntax

The first step to scripting is understanding what a script means. Consider this example:

CLASSIFY ON CustoNum SUBTOTAL TotalAmt SalesTax TO "classify_results.FIL"

This syntax reads as:

“CLASSIFY on the CustoNum field, subtotal the TotalAmt and SalesTax fields and send the results to a new table, named classify_results“.

Within this syntax, we can break the script down into three types of elements: Command, Parameter name, and Parameter value.

Elements in script

Element

Description

Example

Command

The command name is always the first entry in the command line; it tells ACL Analytics, “This is the command to run.”

  • CLASSIFY tells ACL Analytics to run the Classify command.

Parameter name

Commands contain different combinations of parameters to determine how they will run.

The parameter name tells ACL Analytics which parameter what to do with the subsequent value.

  • The SUBTOTAL parameter tells ACL Analytics to generate a subtotal, but we need to tell it which fields to subtotal. This is an optional parameter, meaning that the command can run without it.
  • The ON parameter tells ACL Analytics which field to run the command on.
  • The TO parameter tells ACL Analytics how to output the result. In this example, TO “classify_results” means that the result of the command will be sent to a table named “classify_results”.

Parameter value

Parameter values are the value assigned to the preceding parameter name.

  • CustoNum is a field. In this example, it’s the field that the Classify command runs on. When combined, the syntax becomes CLASSIFY ON CustoNum which means “Run the Classify command on the CustoNum field.”
  • SUBTOTAL TotalAmt SalesTax tells ACL Analytics to subtotal the TotalAmt and SalesTax field.
  • “classify_results.FIL”:
    The result of the command will be sent to a table named “classify_results”.

*For a full list of Commands, visit our Help Docs.

Take advantage of the ACL Script Editor

Every script you open in ACL Analytics will bring you to the ACL Script Editor. There are a number of tools in the Script Editor that will help you create, edit, or debug scripts. Some of these tools will allow you to automatically create the script without requiring that you know the syntax in advance.

Let’s take a look at the different tools in the Script Editor toolbar:

ACL Script Editor

Icon

Name

Function

1

Start Syntax Capture

Allows you to create a script by recording your actions in the GUI.

2

Build New Dialog

Allows you to create custom dialog boxes, which can be used when your script requires user input.

3

Insert Expression

Opens the Expression Builder dialog.

4

Insert Field

Opens a dialog containing all available fields in the open table.

5

Edit Command

With an existing command in the script selected, allows you to edit the command parameters using the associated dialog box.

6

Toggle breakpoint

Sets a breakpoint, which will pause a script during execution. Useful for debugging.

7

Step

Executes a single line of your script.

8

Run

Executes your entire script.

9

Validate Analytic Header

Validates an analytic header, a special type of comment that contains tags needed for scripts you plan to run on AX Server and on the Analysis App.

10

Open as Analysis App

Allows you to open the project as an analysis app.

11

Word Wrap

Enables or disables Word Wrap. Long commands will wrap over to a new line in the editor.

12

ScriptHub Access

Allows you to import scripts or snippets from ScriptHub.

When you are manually entering the script syntax, the Script Editor includes auto-completion for ACL script commands and keywords, and automatic on-screen help for function parameters. Having the auto-completion feature enabled can help you create scripts that are free of mistakes. Another method to ensure your scripts are mistake-free is to use the Syntax Capture feature. This feature will automatically create script syntax by recording any ACL commands that you ran in the ACL user interface.

Did you find a ScriptHub script or snippet that you want to use in your analysis? You can import them directly into ACL Analytics through the Script Editor. Take a look at our Help Docs for detailed instructions on how to import from ScriptHub – some restrictions do apply. Last but not least, there are debugging features, such as set a breakpoint, or step through script one line at a time that can help test or debug scripts. For a list of features that can help you test and debug scripts, visit our Help Docs.

Creating a basic script from the ACL Log

The ACL log is a component that records every action you make in ACL Analytics in the form of scripts and texts. Instead of creating a script from scratch, you can perform the action first and then copy the entry from the log into a script.

Here is how you would approach creating a script from the ACL Log:

  1. Create the script
    a. In the Navigator, from the Overview tab, right-click the Scripts folder and select New > Script. New_Script is created.
    b. Right-click New_Script > Rename. Rename your script.
  2. Add the script logic
    a. Run the command you want to script so that it is written to the log.
    b. Open the log and select the entry from the command you just ran. Ensure the OPEN table_name entry is selected as well, otherwise your script won’t know which table to run the command on. Once selected, right-click and select Copy. Click on the new script you have created under the Overview tab and paste the copied script into the Script Editor.
  3. Run the script
    a. With the script open in the Script Editor, click the Run button.

Specifying settings using the SET command

There are many configurable options in ACL Analytics, and the SET command is a very handy command you can use within your scripts to adjust these options and settings. You can use SET command to:

  • Avoid table overwrite warnings
  • Start a new log session
  • Specify which folder to save tables to
  • Specify the date format to use
  • Specify which log to save entries to
  • Turn Exact Character Comparison (ECC) on or off
  • Close open tables

Here are some common examples of how you can use the SET command in your scripts:

  1. Turning SAFETY off (so you are no longer bombarded with table overwrite warnings)
    Are you tired of clicking ‘OK’ every single time to accept overwriting tables generated by the script you are running? Use the script ‘SET SAFETY OFF’ in your syntax to turn this off and automatically overwrite tables. Use ‘SET SAFETY ON’ at the end of your script to turn it back on.
    SET SAFETY {ON | OFF}
  2. Applying a filter to a table view
    Use ‘SET FILTER TO’ script to apply a filter to an open table. To remove the filter, specify SET FILTER without any parameter.
    SET FILTER TO {filter_name|logical expression}
  3. Specifying which folder to save tables to
    Use ‘SET FOLDER’ script to specify which folder any tables produced by your script will be saved to in order to keep organized.
    SET FOLDER /folder_name
  4. Specifying the date format
    Depending on your organization’s reporting structure and region, you may need to adjust the date format and you can use the ‘SET DATE’ script to make the adjustment. The two most common formats can be called using:
    1 – date format is set to ‘MM/DD/YY’
    2 – date format is set to ‘DD/MM/YY’
    You can also specify your own date format such as ‘MMYYYY’
    SET DATE {1|2|"string"}

*For a full list, see SET command syntax in our Help Docs.

Frequently Asked Questions

Here are some Frequently Asked Questions for ACL scripting:

1. Where can I learn more about the basics of ACL scripting?

Take the ACL Analytics Introduction to Scripting course in ACL Academy and follow the step-by-step instructions to kick-start your ACL scripting journey. Psst… you are eligible to earn up to 2 CPE credits if you successfully pass the related exam.”

2. Other than taking the Introduction to Scripting course, is there another way to learn about ACL scripting?

Follow the instructions on Your first ACL Script page to write your first script or check out the ACL scripting basics page in our Help Docs.

3. What is ScriptHub?

It is a library of ACL tested and approved scripts, readily available for you to use in your ACL projects. Every ACL user with an active subscription will have access to ScriptHub.

4. I have completed the Introduction to Script course, how else can I advance my ACL scripting knowledge?

Another helpful course you can take in ACL Academy is the ACL Analytics Scripting course. In this course, you will learn how to write a script to import your data, how to compose an analysis script, how to structure your scripts, and best practices in ACL scripting.

  Tip of the Month

Remember these ACL script syntax rules and best practices:

  1. The first word in a script line must be a command name.
  2. For most commands, the order of parameters that follow the command name does not matter.
  3. Most commands must be contained within one line – don’t try to separate them onto different lines. You can use Word Wrap if the script is too long.
  4. Script in the same order that elements are written to the log – this makes it easy for others to understand your script logic and makes it easier to identify syntax issues if the script isn’t working properly.
  5. While ACL script syntax is not case-sensitive, ACL recommends using upper case for command and parameter names and lower or proper case for parameter values.
  6. Most commands require that you open the target table before executing the command, precede these commands with:
    OPEN table_name

  Announcements

On-demand ACDA Bootcamp webinar

On-Demand ACDA Bootcamp Webinar

Interested to see a demo on how to create a basic script? Watch our ACDA Bootcamp on-demand webinar.

Watch now

Connections 2018 News

Interested to learn ACL scripting in person with an ACL expert? We are offering an “Introduction to Scripting” training workshop at Connections 2018! Come join us in Philadelphia on October 14 – 17 for our biggest training event of the year! Simply register before June 30, 2018 to secure our early-bird rate of $1195.

Register nowLearn more

Did you miss previous editions of the blog? Don’t worry, just visit here to check out the past editions.

Share This