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.

Syntax auto-completion

As you type syntax in the Script Editor, Analytics provides auto-completion for ACLScript commands and keywords, and automatic on-screen help for function parameters.

You can turn off auto-completion by selecting Disable auto complete in scripts in the Interface tab in the Options dialog box (Tools > Options). On-screen help for function parameters cannot be disabled.

Import scripts or snippets from ScriptHub

Another option for creating scripts is to make use of the content in ScriptHub. ScriptHub is a web-based library of Analytics scripted items developed by Diligent employees and the Diligent user community. As part of your subscription, you can download and use any of the content in ScriptHub.

For more information, see Importing from ScriptHub.

Create or edit a script in the Script Editor

You can 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.
    HighBond token

    For more information, see Acquire a HighBond access token.

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

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.

Test the script

If you want to test the 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 HighBond access token

Caution

The generated access token matches the account used to sign in to HighBond. 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 > HighBond Access Token.

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

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

    Access to the Manage API tokens page through Analytics is a convenience feature. You can also sign in to HighBond 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 HighBond 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. HighBond 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 HighBond 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 HighBond access tokens.