Creating and editing scripts

You have several options for creating scripts:

  • Script Editor type script syntax in the Script Editor window
  • Command log copy script syntax from the command log
  • Script Recorder record the syntax for commands as you execute them
  • Syntax capture insert the syntax for commands as you select them in the user interface without executing them
  • Table history copy script syntax from the history of an output table

You can use these options in combination. For example, you could begin a script by copying syntax from the command log, and then add additional lines of syntax directly in the Script Editor window.

To edit an existing script in Analytics, you must use the Script Editor.

You also have the option of using a text editor of your choice, and copying and pasting syntax into an Analytics script.

Code completion

As you type script syntax in the Script Editor, Analytics performs different types of code completion. Code completion reduces the labor associated with typing syntax, and also presents the valid form of ACLScript commands, functions, keywords, and parameters.

  • Auto-completion of commands, functions, and keywords As you begin to type, the auto-completion feature offers a progressively updated pick list of ACLScript commands, functions, and keywords that match the typed characters. You can select an item from the list to automatically complete the syntax item.

  • Pop-up help for function parameters When you type the opening parenthesis after a valid function name, pop-up help displays the data type of the output returned by the function, and the required format for the function parameters.

  • Auto-close of paired syntax items When you type the opening character of any of the paired syntax items below, the closing character is automatically supplied:

    • Double quotation marks ""

    • Single quotation marks ''

    • Back quotation marks ``

    • Parentheses ()

You can turn off auto-completion of commands, functions, and keywords by selecting Disable auto complete in scripts in the Interface tab in the Options dialog box (Tools > Options).

Pop-up help for function parameters, and auto-close of common syntax items, cannot be disabled.

Create or edit a script in the Script Editor

Create or edit scripts by typing the required ACLScript syntax directly into the Script Editor, or by using one of the other supported methods for entering syntax.

Note

When you create or edit a script you must ensure that each ACLScript command is entered on a separate line.

Create or edit the script

  1. Complete one of the following steps to open the script in the Script Editor:
    • To create a new script, select File > New > Script.

      The script is created with the name New_Script. Right-click the name and select Rename to rename the script.

      Note

      Script names are limited to 64 alphanumeric characters. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

    • To open an existing script, double-click the script in the Overview tab in the Navigator.
  2. Add, modify, or delete ACLScript syntax in the Script Editor.

    Tip

    You can use these shortcut keys for common actions:

    • Ctrl+Z undo one or more actions
    • Ctrl+Y redo one or more actions
    • Ctrl+S save the Analytics project, including the open script
  3. (Optional) Position the cursor at an appropriate place in the script and complete any of the following steps to insert one or more specific items:
    ItemSteps

    Project item name

    (table, script, view, workspace, or index)

    1. Right-click and select Insert > Project Item.
    2. Select the type of item from the Item Type dropdown list.
    3. Select one or more item name(s), and click OK.
    Field name
    1. From the Script Editor toolbar, click Insert Field .
    2. Select one or more field name(s) and click OK.
    Expression
    1. From the Script Editor toolbar, click Insert Expression .
    2. Create an expression and click OK.
    Dialog box
    1. From the Script Editor toolbar, click Build New Dialog .
    2. Create a custom dialog box, click Close, and click OK.

    For more information, see Creating custom dialog boxes.

    Date and time
    1. Right-click and select Insert > Date & Time.
    2. Enter or select a date, datetime, or time and click OK.
    Diligent One token

    For more information, see Acquire a Diligent One access token.

  4. Select File > Save Project.
  5. Click Yes in the confirmation dialog box.

Highlight repeated terms or syntax items

You can highlight repeated terms throughout a script such as table, field, variable, or keyword names. You can also highlight repeated syntax items such as parentheses or quotation marks.

The ability to highlight all occurrences of a particular term or syntax item is a useful script development and debugging feature.

  • Terms To highlight multiple instances of a term, double-click a single instance of the term anywhere in the script.

  • Phrases To highlight multiple instances of a phrase, select a single instance of the phrase anywhere in the script.

Note

The highlighting behavior may not always align with your expectations. For example, if you select the surrounding percentage signs % with a variable name, additional instances of the variable may not be highlighted. Double-click the name of the variable instead for more consistent highlighting throughout a script.

Highlight matching parentheses

You can highlight matching parentheses in an expression such as a function with nested parameters. The ability to highlight matching opening and closing parentheses in complex expressions speeds up coding, and reduces the chance that you will introduce a bug by creating an expression with mismatched parentheses.

To highlight matching parentheses, position the cursor immediately before, or immediately after, a single parenthesis in a script. Both the opening and the closing parentheses are highlighted. If matching parentheses are not highlighted, you know that one of the parentheses pair is missing.

Edit command syntax using a dialog box

Instead of manually editing commands in a script, you can edit them using the associated dialog box.

Note

This method is available only for commands that have dialog boxes.

  1. Select an existing ACLScript command in the script.
  2. From the Script Editor toolbar, click Edit Command .

    The command dialog box opens.

  3. In the dialog box, make the required changes to the command parameters and click OK.

    The script syntax is updated.

Open two scripts side by side

You can open two scripts side by side in the Script Editor, which allows easy comparison and copying of script syntax back and forth.

  1. In the Overview tab of the Navigator, select the two scripts that you want to open side by side.

    You can Ctrl+click to select two non-adjacent scripts, or Shift+click to select adjacent scripts.

  2. Right-click one of the selected scripts and select Side by Side Edit.

    The two scripts open in side-by-side mode.

  3. Click into the body of either script to move between the scripts.

    If you are using the default background color in the Script Editor, the currently active script has a lighter background.

  4. To save changes to one or both scripts, do one of the following:

    • Press Ctrl+S and click Yes in the confirmation dialog box or boxes that appear.

    • On the Analytics toolbar, click Save the Open Project , and click Yes in the confirmation dialog box or boxes that appear.

  5. To exit side-by-side mode, click the close icon on the script tab.

    The two scripts are opened in separate Script Editor tabs.

Test the script

If you want to test a script by running it, or by stepping through it, click Run  or Step  in the Script Editor toolbar.

Note

If you run or step through a script, all open scripts are automatically saved.

Create a script from the command log

You can copy log entries from the Log tab in the Navigator as the starting point for creating a new script, or to add to an existing script. The syntax of each command previously executed in Analytics is recorded in an individual log entry.

You can select the following types of log entries and copy them to a new or existing script:

  • individual entries
  • a series of entries associated with a table
  • larger groups of entries associated with a session or a time period
  1. In the Navigator, click the Log tab to display the log.
  2. Select the log entry, or group of entries, that you want to include in the script.

    If you select higher level items in the treeview, the sub-entries are automatically selected.

  3. Do one of the following:
    Create a new script
    1. Right-click in the Log tab and select Save Selected Items > Script.
    2. In the Save Script As dialog box, enter a name for the new script and click OK.

      Note

      Script names are limited to 64 alphanumeric characters. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

      The new script is added to the Overview tab in the Navigator. The script is saved in the folder containing the active Analytics table, or in the root project folder if no table is open.

    Copy syntax to an existing script
    1. Right-click in the Log tab and select Copy.
    2. Open an existing script if one is not already open.
    3. In the Script Editor, position the cursor where you want to insert the copied syntax.
    4. Right-click and select Paste.

Create a script with the Script Recorder

The AnalyticsScript Recorder allows you to create a script by recording your actions as you work with tables and commands in the Analytics user interface. The advantage of using the Script Recorder to create scripts is that you do not need to manually enter the required syntax for each ACLScript command, or even know the syntax.

Only commands are captured by the Script Recorder. As a general rule, if the command appears in the command log, it can be captured by the Script Recorder.

Tip

The Script Recorder is also a useful tool for learning ACLScript. You can record a series of analysis steps using the Script Recorder and then view the resulting script to see the series of commands and syntax required to reproduce the behavior in a script.

  1. From the Analytics main menu, select Tools > Set Script Recorder On.

    The Script Recorder icon is displayed in the status bar, and a checkbox is displayed to the left of the menu item, to indicate that the Script Recorder is on.

  2. Perform the analysis steps or processing you want to record.

    Analytics records each processed command in a new script.

  3. When you have finished analyzing or processing data, select Tools > Set Script Recorder On again to turn the Script Recorder off.

    Analytics prompts you to save the script.

  4. Enter a meaningful name for the script in the text box and click OK.

    Note

    Script names are limited to 64 alphanumeric characters. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

Create a script with syntax capture

Syntax capture allows you to use Analytics menus and dialog boxes to automatically insert ACLScript syntax into a script.

  1. Open the script that you want to work with.
  2. (Optional) Open the table that you want to work with.

    Tip

    If you start syntax capture before you open a table, the table does not physically open in the View tab because commands are not actually executed during syntax capture. You may find it difficult to visualize subsequent commands without an open table for guidance.

  3. From the Script Editor toolbar, click Start Syntax Capture .
  4. Perform the analysis steps or processing that you want to record.

    The associated syntax is automatically inserted into the script. The commands themselves are not executed.

  5. Click End Syntax Capture  to stop inserting command syntax in the script.

Create a script from table history

You can create a script based on the history associated with an Analytics output or results table.

For example, if you add a monthly inventory table to an Analytics project and extract relevant divisions and items to a new table, you could script this process based on the table history associated with the first output table you created.

Each table created as the output of an Analytics command keeps a record of the commands used to create the table, including commands that create any intermediate tables between the original Analytics table and the output table. You can copy this table history to a new script that you can then use to automate creation of subsequent output tables.

  1. Open an output table that is the result of a process you want to automate in a script.

  2. Select Tools > Create Script from Table History.

    If Default_View is active, Analytics prompts you to rename the view to prevent you from overwriting it when you run the new script.

  3. If Analytics prompts you to rename the view, click Rename, enter a new name, and click OK.

  4. Enter a name for the new script in the Save As dialog box and click OK.

    Note

    Script names are limited to 64 alphanumeric characters. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

  5. (Optional) Open and edit the new script if you want to adjust any of the script behavior.

    For example, instead of overwriting the original table you could choose to save the output to a table with a different name.

Acquire a Diligent One access token

Caution

The generated access token matches the account used to sign in to Diligent One. As a scriptwriter, specifying your own access token in a script may not be appropriate if the script will be used by other people.

Safeguard access tokens like any account password.

Use an existing access token unless you have a reason for creating a new one. If the existing token does not work, create a new one. Using an existing token cuts down on the number of tokens you need to manage.

  1. Do one of the following:

    • From the Analytics main menu, select Tools > Diligent One Access Token.

    • In the Script Editor, right-click and select Insert > Diligent One Token.

    The Manage API tokens page opens in your browser. You may be required to first sign in to Diligent One.

    Access to the Manage API tokens page through Analytics is a convenience feature. You can also sign in to Diligent One and access the page through your user profile without using Analytics.

  2. Do one of the following:

    • Use an existing token

      1. In the Token column, click the partially masked token that you want to use.

      2. Enter your Diligent One account password and click Confirm.

        The unmasked token is displayed.

      3. Click Copy to copy the token.

        Tip

        Do not close the dialog box containing the token until you have successfully pasted the token.

    • Create a new token

      1. Click Add token > Analytics.

      2. In the New Analytics token side panel, specify the following information:

        Field or option Description
        Description

        Enter a description that provides useful information, such as:

        • The purpose of the token
        • Where the token is used – for example, the name and location of the Analytics script, or the name and location of the robot task
        Token expiry
        • Enabled the token expires after the number of days that you specify
        • Disabled the token never expires

        Note

        Your organization may have a security policy that requires tokens to expire after a certain amount of time. Creating tokens with an expiry is a good practice. Diligent One sends you an automated email notification in advance of the expiry date.

        Expires in Specify the number of days before the token expires (1 to 365).
        Password Enter your Diligent One account password.

      3. Click Generate token.

      4. Click Copy to copy the token.

        Tip

        Do not close the side panel containing the token until you have successfully pasted the token.

  3. Depending on which password definition method you are using, do one of the following:

    • PASSWORD analytic tag In the Task Designer in an ACL robot, paste the copied token into a password parameter field.

    • PASSWORD command In Analytics, paste the copied token into a password prompt that appears during script execution.

    • SET PASSWORD command In Analytics, paste the copied token at the appropriate point in the SET PASSWORD command syntax in a script.

  4. In Launchpad, close the dialog box or the side panel containing the token.

    If you created a new token, a partially masked version of the token is added to the top of your list of tokens.

    For more information, see Creating and managing Diligent One access tokens.