Robots upgrade to Python 3.11

Diligent is performing a phased upgrade of the version of Python used by Robots. The cloud-based Robots Agent will be upgraded from Python 3.8.x to Python 3.11.x. During a transition period, both versions of Python will be supported by Robots. For details, see Phased upgrade schedule in Robots.

The upgrade also includes updating a number of libraries associated with Python, including Pandas (from version 1.2.4 to 2.2.0), and Requests (from version 2.26.0 to 2.31.0). For a list of libraries updated in Robots, see New versions of Python and associated libraries.

If your organization uses HighBond robots or Workflow robots, read this topic to familiarize yourself with the implications of the upgrade. Robots customers cannot opt out of the Python upgrade.

The Python Software Foundation has announced that Python 3.8 is officially end-of-life on 14 October 2024.

Impact on customers

Potential for incompatible script logic

One or more of your Python/HCL scripts could potentially be impacted by the upgrade to Python 3.11. If script logic that runs in Python 3.8 no longer runs in Python 3.11, or runs but produces incorrect output results, you need to update the script logic.

The easiest way to check if your existing scripts run without issue in Python 3.11 is to open them in the Robots script editor and try running them. For more information, see Test and recommit existing Python/HCL scripts.

Out-of-date script header information

Header information in Python/HCL scripts specifies the version numbers of the HCL package (HighBond Command Language), Python, and associated libraries used by Robots at the time the script was committed (saved) in the Robots script editor. You can download any script and open it in a text editor to see the header information.

The examples below show header information for scripts committed with previous and current HCL packages and Python runtime environments.

Previous: HCL 1.0 and Python 3.8

"environment": {
    "runtime": "python3.8",
    "requirements": ["boxsdk==3.0.1", "openpyxl==3.0.9", "Jinja2==3.0.3", "simple-salesforce==1.11.5", "jira==3.1.1", "hcl==1.0.*"]
}

Current: HCL 3.0 and Python 3.11

"environment": {
    "runtime": "python3.11",
    "requirements": ["boxsdk==3.9.2", "openpyxl==3.1.2", "Jinja2==3.1.3", "simple-salesforce==1.12.5", "jira==3.8.0", "hcl==3.0.*"],
    "showCommitToastMessage": true
}

Issues with out-of-date scripts

Scripts with out-of-date header information are not prohibited from running in HCL 3.0 and the Python 3.11 runtime environment. However, you should update the scripts as soon as possible to avoid the following issues:

• Scripts may fail A script committed under Python 3.8 and older versions of associated libraries may contain deprecated code that causes the script to fail in Python 3.11.

• Scripts may produce incorrect output A script may run, but the output may not match the output produced in the Python 3.8 runtime environment.

• Warning notifications appear Until a script's header information is updated, warning notifications in the Robots user interface appear with the script, and with the robot that contains the script. For more information, see Warning notifications in the Robots user interface.

• Activation is prohibited Until a script's header information is updated, you are prohibited from activating the script from development to production mode.

How to update a script

To update a script to the current version of HCL and Python, follow this process:

1. Open the script in the Robots script editor and run it.

2. Make any necessary updates to the script logic.

3. Save and commit the script.

   Committing the script updates the script header to the current versions of HCL, Python, and associated libraries.

4. If the script is used in a production robot, activate the script to update it in production mode.

For detailed steps, see Test and recommit existing Python/HCL scripts.

Warning notifications in the Robots user interface

In the Robots user interface, several warning notifications appear alerting you to robots and script versions that are still associated with Python 3.8.

The warning notifications disappear for a robot and a script version once you recommit and reactivate the script under the Python 3.11 runtime environment.

• Robots dashboard When you access the Robots dashboard, a table appears listing all robots with a current production script that was committed and activated under the Python 3.8 runtime environment.

• Individual robots on the dashboard A warning icon appears on individual HighBond or Workflow robots with a current production script that was committed and activated under the Python 3.8 runtime environment.

• Individual script versions In development mode, a warning message appears with any script version that was committed under the Python 3.8 runtime environment.

Test and recommit existing Python/HCL scripts

To ensure that your organization's existing Python/HCL scripts are ready for the transition to Python 3.11, test and recommit them in the Robots script editor.

Open an existing script in 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 the version of the script that you want to test.

   Typically, you should select the version of the script that has been activated to production mode. If no version has been activated, select the most recent script version, unless you have a reason to select a different version.

6. In the Version details panel, click Edit script or Edit.

   The Robots script editor begins the start-up process, and loads the Python 3.11 runtime environment.

Run the script to test it

Run the script to test if it is compatible with the Python 3.11 runtime environment.

1. When the script editor start-up process is complete, run the script to test it.

2. If the script runs successfully, review any output results to ensure that they are correct.

   If the script runs successfully, and the output results are correct, the script is compatible with Python 3.11 and its associated libraries. No further testing of the script is required. You can save and commit the script to associate it with HCL 3.0 and the Python 3.11 runtime environment. See Save and commit the script.

3. If the script fails, or if the output results are incorrect, update the script logic to address the problem.

   Note

   Script failure, or incorrect output, may or may not be related to the Python upgrade in Robots. For more information, see Guidance for Robots script developers.

Save and commit the script

1. On the script editor toolbar, click Save and commit.

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

   Tip

   You may find it useful to add "Runs in Python 3.11" in the commit message.

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.

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

6. Optional. Verify that the script is associated with the Python 3.11 runtime environment:

   1. Select the script version that you just saved.

   2. In the Version details panel, click Download.

      The script is downloaded to your computer.

   3. Open the script in a text editor.

      The associated Python runtime environment appears at the top of the script:

      "runtime":"python3.11"

7. If the script is used in a production robot, reactivate the script to update it in production mode:

   1. Select the script version that you just saved.

   2. In the Version details panel, click Activate.

   3. Enter a comment in the version history to explain why you are reactivating the script.

   4. Click Activate versionNumber.

      The script version is activated and updated in production mode.

Phased upgrade schedule in Robots

The table below provides dates and details for the phased upgrade of Python and associated libraries in Robots.

New versions of Python and associated libraries

The table below lists the current and previous versions of Python and associated libraries supported by Robots. Consult the linked resources for information about specific changes in the new versions.

Guidance for Robots script developers

Detailed information about changes in the versions of Python and associated libraries in HCL 3.0 is beyond the scope of this Help topic. Some general guidance is provided below. For detailed information, start by consulting the linked resources above.

Script failure not associated with the Python upgrade

Failure of a Robots script may or may not be caused by the upgrade of Python in Robots from version 3.8 to 3.11. For example:

• Script failure with a 401 status code (Unauthorized) is most likely caused by a problem with the HighBond access token specified by the script. For more information, see Managing access tokens .

• Script failure with a 404 status code (Not Found) may be caused by a missing or incorrect variable assignment in the script. For more information, see Using variables in a Python/HCL script.

Script failure, or incorrect output, possibly associated with the Python upgrade

If a scheduled script has been running successfully and then fails during the final week of October 2024, the failure is probably related to the upgrade of Python and its associated libraries. The same is true if a script continues to run successfully but begins outputting incorrect or unexpected results.

• Deprecated functions and methods A deprecated function or method in Python, Pandas, or one of the other associated libraries may be the root of the problem. Run the failing script in the Robots script editor and carefully examine any error messages returned by the script. Try using the AI Script Assistant during your troubleshooting.

• Multiple intervening versions A number of intervening versions of Python, Pandas, and other associated libraries were released between the versions used in the HCL 1.0 and HCL 3.0 packages. You may have to review information associated with multiple versions of a library to identify the source of a problem.

• Pandas breaking changes Some of the changes introduced by successive versions of the Pandas library can cause HCL 1.0 scripts to fail in Robots. Breaking changes include, but are not limited to, the changes below.

  • append() – method deprecated

  • astype() – changed behavior

  • groupby() – changed behavior of operation

  • read_csv() – parameter changes

  • split() – parameter changes

  • str.replace() – parameter change