Committing ACL scripts (uploading) to Robots

Two different methods exist for committing, or uploading, ACL scripts to the Robots app:

  • Commit the scripts from Analytics to Robots

  • Use Robots to upload ACL scripts

    Note

    This method of using Robots to upload ACL scripts is not the same as using Robots to perform a first-time upload of ACL scripts to a newly created robot. For more information, see Adding script automation to a robot.

Comparison of the methods

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

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

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

Syntax validation and project-robot association are useful features, so the recommended approach is to commit scripts from Analytics to Robots. You can use uploading from within Robots as a convenience feature after a project-robot association has been established, and for minor script updates where bypassing syntax validation is less of an issue.

How committing scripts works

When you commit scripts to the Robots app, all scripts in the Analytics project are committed and together become "a version" in the associated ACL robot. You cannot selectively commit scripts from a project. For more information, see ACL script development workflow in Analytics and Robots.

To commit scripts to Robots, you must be assigned to the appropriate role in the Robots app. For more information, see Robots app permissions.

Committing scripts from Analytics to Robots

Several possibilities exist when you commit, or upload, scripts from Analytics to an ACL robot in the Robots app.

The easiest way to understand the various possibilities is to think of an Analytics project and an ACL robot as two containers, each holding scripts, that can be associated. Once they are associated, you can commit successive versions of scripts from the project to the robot.

Action Result upon commit
Commit scripts to a new ACL robot

A new ACL robot is created that contains version 1 of the committed scripts.
Commit scripts to an existing ACL robot

The existing ACL robot contains the committed scripts, with a version number that depends on whether the robot already contains scripts.
Commit edited scripts to an ACL robot

A new version of the scripts is committed to the ACL robot associated with the project.
Commit scripts to a different ACL robot

The scripts are committed to either a newly created ACL robot, or an existing ACL robot.

The association between the project and the previous robot is deleted.

Commit scripts to a new ACL robot

Commit scripts to the Robots app for the first time to create a new ACL robot that contains the committed scripts.

  1. From your computer, open the Analytics project that contains the scripts.

  2. 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.

  3. If required, in the Select Destination dialog box, double-click the appropriate Diligent One instance.

    The Robot Collection appears with the list of existing robots.

  4. Type a robot name in the New Robot field, and click Create.

    The robot is created, and a robot ID is automatically generated.

    The Analytics project that contains the scripts, and the new robot, are now associated so that subsequent commits do not require that you manually locate the robot.

    Note

    Do not use the following characters anywhere in the robot name: "$", "€".

  5. 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.

  6. Optional. In the Commit Scripts Successful dialog box, click either of the links to inspect the newly created robot or the committed scripts.
  7. Click OK to exit the dialog box.

Commit scripts to an existing ACL robot

Commit scripts to an ACL robot that already exists to populate the robot. The existing robot can already contain scripts, or it can be empty.

Note

Use this method if the project is not yet associated with a robot. If the project is already associated with a robot, see Commit scripts to a different ACL robot.

  1. From your computer, open the Analytics project that contains the scripts.

  2. 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.

  3. If required, in the Select Destination dialog box, double-click the appropriate Diligent One instance.

    The Robot Collection appears with the list of existing robots.

  4. In the list of robots, select the robot that you want to commit the scripts to and click OK.

    The Analytics project that contains the scripts, and the existing robot, are now associated so that subsequent commits do not require that you manually locate the robot.

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

    The scripts are committed to the existing robot. The version number of the scripts depends on whether the robot already contains scripts, or whether it was previously empty.

    The scripts exist in development mode only at this point.

  6. Optional. In the Commit Scripts Successful dialog box, click either of the links to inspect the existing robot or the committed scripts.
  7. Click OK to exit the dialog box.

Commit edited scripts to an ACL robot

Commit edited scripts to create a new version of the scripts in the associated ACL robot.

Two methods exist for editing scripts before committing them. You can edit the scripts in the associated project, or you can download the scripts from Robots to a new Analytics project, and edit the scripts in the new project.

Note

Downloading the scripts from Robots before beginning any editing work is a best practice. You can be sure that the downloaded scripts have not been altered, unlike scripts that are stored locally.

During a single scriptwriting session, if you are the only person working on the scripts, it is generally safe to commit iterative versions of the scripts directly from the project, without downloading between iterations.

Download the scripts from Robots

Perform this portion of the procedure if you want to work with scripts contained in Robots, rather than scripts already on your local computer.

  1. Open the Robots app.
  2. From the dashboard in Robots, select ACL Robots.
  3. Navigate to the robot that contains the scripts you want to download, and select the robot to open it.

  4. In the top right corner of the robot, click Production or Development to select the mode to use.

    For more information, see Development mode and production mode in Robots.

  5. Do one of the following:

    • Download the currently activated script version

      In production mode, click Download robot.

    • Download the most recent development script version

      In development mode, click Download robot.

    • Download an earlier script version

      1. In development mode, select the Script versions tab.

      2. In the Script versions list, select the version that you want to download.

      3. In the Version details panel, click Download.

    The scripts are downloaded to the default Downloads folder on your computer. The scripts are contained in a newly created Analytics project with the same name as the robot you downloaded from. The project and the robot are automatically associated.

    Note

    The robot is now associated with two projects: the project that was just created by downloading, and the project previously used to commit the scripts. One robot can be associated with multiple projects.

  6. Optional. Move the project containing the downloaded scripts if you want to work with it in another folder.

Edit the scripts in Analytics and commit them

  1. From your computer, open the Analytics project that contains the scripts.

  2. Edit the scripts and save your changes.

    Note

    You can also add or delete scripts, if required.

  3. 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.

  4. Enter a short commit message that describes the change to the committed scripts, and click OK.

    The scripts are committed to the associated robot where they are saved as a new version. Existing versions of the scripts in the robot are not overwritten.

    If an error message appears stating that the associated robot is not found, check that the robot exists in Robots, and that your role allows committing scripts.

  5. Optional. In the Commit Scripts Successful dialog box, click either of the links to inspect the robot, or the new version of the scripts.
  6. Click OK to exit the dialog box.

Commit scripts to a different ACL robot

Commit scripts to a different ACL robot to add a version of the scripts to the robot, and to change the robot associated with the project. The scripts can be either edited or unedited.

Two possibilities exist when you commit scripts to a different robot:

  • commit scripts to a new robot
  • commit scripts to an existing robot

  1. From your computer, open the Analytics project that contains the scripts.

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

    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.

  3. If required, in the Select Destination dialog box, navigate to the appropriate Diligent One instance.

    The Robot Collection appears with the list of existing robots.

  4. Do one of the following:
    • Commit scripts to a new robot Type a robot name in the New Robot field, and click Create.

      The robot is created, and a robot ID is automatically generated. The Analytics project that contains the scripts, and the new robot, are now associated.

      Note

      Do not use the following characters anywhere in the robot name: "$", "€".

    • Commit scripts to an existing robot In the list of robots, select the robot that you want to commit the scripts to and click OK.

      The Analytics project that contains the scripts, and the existing robot, are now associated.

    The association between the project and the previous robot is deleted.

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

    The scripts are committed to the newly created or the existing robot. The version number of the scripts depends on whether the robot already contains scripts, or whether it was previously empty.

    The scripts exist in development mode only at this point.

  6. Optional. In the Commit Scripts Successful dialog box, click either of the links to inspect the newly created or the existing robot, or the committed scripts.
  7. Click OK to exit the dialog box.

Using Robots to upload ACL scripts

You can use Robots to upload ACL scripts without needing to open Analytics. This method of uploading scripts bypasses syntax validation, so you should use it only for uploading minor script updates of previously validated scripts.

Note

This method is not available for a first-time upload of ACL scripts to a newly created robot.

  1. Open the Robots app.

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

  3. Click an ACL robot to open it.

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

  5. In the Script versions tab, click Upload.

  6. 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.

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

    The scripts are uploaded to the robot and create a new script version at the top of the Script versions list.