Adding script automation to a robot

After you have created a robot, you add one or more scripts to the robot to create the automation that you want. How you add scripts depends on which type of robot you are using:

  • ACL robot create one or more ACL scripts in Analytics and then upload them to Robots

  • HighBond robot or Workflow robot create a Python/HCL script in the Robots script editor

    Note

    Currently you are limited to one Python/HCL script per robot.

    To access Workflow robots, you must be assigned the System Admin user type with a Professional subscription.

Script development workflow

When you add or update scripts from Analytics, or from the Robots script editor, the new or updated scripts appear as a new version in Robots development mode. You can then:

  1. See the development history of the scripts in the robot.

  2. Create and run tasks in development mode to test the scripts and validate that they work as expected.

  3. Activate any of the script versions to transfer it to production mode.

This process supports iterative script development and gives you the opportunity to test changes without affecting any active business processes. For more information, see Data segregation considerations.

Add an ACL script to a robot

Two different methods exist for adding an ACL script or scripts to an ACL robot for the first time:

  • Use Robots to upload existing ACL scripts from an Analytics project

  • Use Robots to automatically create a new Analytics project that you populate with scripts and then commit back to Robots

To subsequently add scripts to an ACL robot, see Committing ACL scripts (uploading) to Robots.

Comparison of the methods

The end result of each method for adding scripts is the same: a first version of the scripts is created in the new robot. However, these differences exist between the methods:

  • Syntax validation Automatic syntax validation is performed when you commit scripts from Analytics to Robots. No validation occurs when you use Robots to upload existing ACL scripts.

  • Project-robot association The Analytics project that contains the scripts, and the new robot, are automatically associated when you commit scripts from Analytics. No association occurs when you use Robots to upload existing ACL scripts.

ACL scripts already exist in Analytics

  1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

    If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

  2. From the dashboard in Robots, select ACL Robots.

  3. Click a newly created ACL robot to open it.

  4. Click Upload existing project.

  5. In the dialog box that appears, do the following:

    1. Click choose from your computer and navigate to the Analytics project that contains the scripts.

    2. Select the project and click Open.

      You can also drag an Analytics project to the Uploaded script area.

  6. Enter a Commit message and click Upload and commit.

    The scripts are uploaded to the robot and create version 1 (v1) at the top of the Script versions list.

  7. Optional. Select the script version to open the Version details panel.

    The panel contains various details related to the script version, including a list of all the individual scripts in the version. The panel also contains the Activate button, which you use to activate a script version to production mode. For more information, see Activate a script version.

ACL scripts do not exist yet

  1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

    If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

  2. From the dashboard in Robots, select ACL Robots.

  3. Click a newly created ACL robot to open it.

  4. Click Download robot.

    A newly created Analytics project is downloaded to the default Downloads folder on your computer. The project has the same name as the robot you downloaded from. The project and the robot are automatically associated.

  5. Navigate to the download location and double-click the Analytics project (<robot_name>.acl) to open it.

  6. Create the scripts.

    For information about authoring scripts in Analytics for use in Robots, see Analytic scripts.

  7. From the Analytics main menu, select File > Commit Scripts.

    If an error message appears, there may be a problem with the analytic header, or the script syntax, in one or more of the scripts in the project.

    For more information, see ACL script development workflow in Analytics and Robots.

  8. Enter a short commit message that describes the committed scripts, and click OK.

    Version 1 of the scripts is committed to the newly created robot. The scripts exist in development mode only at this point.

  9. In the Commit Scripts Successful dialog box, click the second link beneath version 1.

    In Robots, the Script versions tab opens in Development mode. The tab contains version 1 (v1) of the script or scripts that you just added.

  10. Optional. Select the script version to open the Version details panel.

    The panel contains various details related to the script version, including a list of all the individual scripts in the version. The panel also contains the Activate button, which you use to activate a script version to production mode. For more information, see Activate a script version.

Add a Python/HCL script to a robot

If you have just created a HighBond robot or a Workflow robot, the Robots script editor opens automatically and begins the start-up process. If you previously created the robot, you need to open the robot and navigate to the script editor.

  1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

    If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

  2. From the dashboard in Robots, select the tab for the appropriate robot type:

    • HighBond Robots

    • Workflow Robots

  3. Navigate to a robot, and select the robot to open it.

  4. In the upper-right corner of the robot, click Development to switch to development mode.

  5. In the Script versions tab, select v0 of the script, and in the Version details panel click Edit script.

    The Robots script editor begins the start-up process. You can edit and save a script during the start-up process but you cannot run a script, or a script cell, until the process is complete.

  6. Create the Python/HCL script.

    For more information, see Python and HCL scripting in Robots.

  7. When you are satisfied that the script is executing correctly, save the script and exit the script editor:

    1. On the script editor tool bar, click Save and commit.

    2. Enter a meaningful commit message to describe your changes.

    3. Optional. Select Save script output to the task run log file.

      When you run a script using a robot task, this option saves all the script output to a log file. The saved output can be useful to review when you are developing and troubleshooting scripts. For more information, see Saving script output to a log file.

    4. Click Commit to save and commit the script.

      The message Your script has been committed successfully appears.

    5. On the page header, click the robot name.

      Result You are returned to the Script versions tab in the robot. Every time that you commit and save a script, the saved version is added to this tab.

Copy a Python/HCL script between robots

To copy a Python/HCL script between robots, download the script from the source robot and upload it to the destination robot.

Robots automatically formats the downloaded script as a JSON file (*.json). The file contains the script content from all cells in the Robots script editor, as well as all variable definitions and values stored with the script.

Note

If you have permissions to access Workflow robots, you are not prevented from copying scripts back and forth between Workflow robots and HighBond robots. Keep in mind that the two robots types have different specifications and limitations, which may prevent a copied script from running successfully. For more information, see Robots specifications and limits.

Download the script from the source robot

  1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

    If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

  2. From the dashboard in Robots, select the tab for the appropriate robot type:

    • HighBond Robots

    • Workflow Robots

  3. Click the source robot to open it.

  4. In the upper-right corner of the robot, click Development to switch to development mode.

  5. In the Script versions tab, select the version of the script that you want to copy.

  6. In the Version details panel, click Download.

    The script is downloaded to your computer as a JSON file (*.json).

Upload the script to the destination robot

  1. From the dashboard in Robots, select the tab for the appropriate robot type:

    • HighBond Robots

    • Workflow Robots

  2. Click the destination robot to open it.

  3. In the upper-right corner of the robot, click Development to switch to development mode.

  4. In the Script versions tab, click Upload.

  5. In the dialog box that appears, select the JSON file (*.json) from your computer, or drag it to the Uploaded script area.

  6. Enter a Commit message and click Upload and commit.

    The script is added as the most recent version in the Script versions tab. A notification appears confirming that the script was successfully committed.

    A notification also appears if the upload and commit process fails. Try uploading again. If the upload fails again, try downloading a fresh copy of the script from the source robot and upload the fresh copy.

Activate a script version

Once you verify that scripts run properly in development mode, you can activate them and run them in production mode against production data. For more information, see Development mode and production mode in Robots.

You can activate any script version in a robot's development history. When you activate a version, the script or scripts in that version become the scripts that run in production tasks.

  1. From the Launchpad home page (www.highbond.com), select the Robots app to open it.

    If you are already in Diligent One, you can use the left-hand navigation menu to switch to the Robots app.

  2. From the dashboard in Robots, select the tab for the appropriate robot type.

  3. Navigate to the robot that contains the script version you want to activate, and select the robot to open it.

  4. In the upper-right corner of the robot, click Development to switch to development mode.

  5. In the Script versions tab, select the script version that you want to activate.

  6. In the Version details panel, click Activate.

  7. Optional. Enter a comment in the version history to explain what you are activating.

    Tip

    Entering an informative comment when you activate a script version is a best practice that can be very helpful when reviewing automated analysis at a later date.

  8. Click Activate versionNumber.

    The script version is activated and becomes available in production mode.

    (ACL robots only) The Scripts tab in production mode lists the individual analytic scripts, and any auxiliary scripts, in the script version.

Handling version activation conflicts (ACL robots only)

When you activate a script version from development mode to production mode in an ACL robot you may encounter a conflict warning. Two different situations can cause a conflict warning:

  • script name conflicts
  • parameter conflicts

You have the option of overriding a conflict warning and forcing the activation of a script version, but you need to be aware of the implications of forcing the activation.

What is the purpose of the conflict warning?

The conflict warning alerts you that there are differences between the production and development script versions that may prevent an existing production task or tasks from running. For example, a task will not run if it specifies a script name that no longer exists, or if a newly added input parameter is left empty in the task.

Script name conflicts

The script version you want to activate may introduce script name changes that conflict with the current production script version.

A name conflict occurs when an ACL  script that is selected to run in an existing production task or tasks has been:

  • renamed in the development script version
  • removed from the development script version

Parameter conflicts

The script version you want to activate may introduce input parameter changes that conflict with the current production script version. Users supply values for input parameters when they run or schedule tasks.

A parameter conflict occurs when:

  • a new input parameter has been added in the development script version
  • the attributes of an existing input parameter have been changed in the development script version

The input parameters are compared between the current production version of the scripts and the version that you are activating. Specifically, the following analytic tags in the analytic headers in identically named scripts are compared:

  • PARAM
  • PASSWORD
  • TABLE
  • FIELD

Any addition of one of these tags causes a conflict. Any change to an attribute of an existing tag also causes a conflict. For example: a change or removal of any of the supplied parameter values that populate pick lists, a change of a variable name, a change of a user interface label or a description, and so on.

Removing any of these analytic tags from the development script version does not cause a conflict. The corresponding input parameters are automatically removed from the existing production task.

Only the input parameters and attributes from the development script version that you are activating are considered.

Resolving conflicts

If a script name or parameter conflict occurs, you are notified when you try to activate the development script version. You have two options if you encounter a conflict:

  • Edit the development script version Edit the scripts in Analytics to make sure that no conflicts exist and then commit and activate the updated script version.
  • Force the activation Force the activation by clicking Force activate versionNumber to overwrite the production scripts with the selected development script version.

    Forcing the activation automatically disables any existing production task that is affected by the conflict.

    Edit the disabled production task to select new script names or provide updated parameter input and then enable the task.