Automatically deleting old task runs (robot jobs)

Three pre-built Python/HCL scripts are available that allow you to automate the process of deleting old task runs in Robots. If you have one or more robots that run frequently, the number of saved task runs can build up quickly. For organizations that use an on-premise Robots Agent, a buildup of old tasks runs with associated results data can cause your server to run out of space. Automating the deletion of old task runs saves you the labor of continual manual deletion, preserves server space, and keeps the Robots interface free of clutter.

Diligent One account requirement

The pre-built scripts require a HighBond access token as one of the script input parameters. To delete task runs, the Diligent One user account associated with the token must be assigned the Owner or Editor role for the target robot.

For more information, see Creating and managing HighBond access tokens and Robots app permissions.

How the pre-built deletion scripts work

You download one or more of the deletion scripts from the links provided below and then upload each script to its own dedicated HighBond robot. (One script per robot.) In the robot, you create a task to configure and schedule the deletion script. Configurable script parameters let you specify which task runs should be deleted.

Deletion robots and target robots

Think of the robot that contains a deletion script as the deletion robot. The task that you use to configure and schedule the deletion script is the deletion task. You use the deletion robot and the deletion task to delete old task runs in another robot. Think of the other robot as the target robot. If you restrict deletions to a specific task in the target robot, think of the task as the target task.

You can create as many deletion robots or deletion tasks as you need. The key thing to understand is that you set up a deletion script in one robot and use it to delete old task runs in another robot.

Deletion scripts work for any robot type

Although the deletion scripts are written using Python/HCL, and are contained in HighBond robots, you can use them to delete old task runs from any robot type, including ACL robots. You do not need to understand Python/HCL to use the deletion scripts. Step-by-step instructions for setting up the deletion scripts are provided below.

HCL HighBond API methods and the HighBond API

The deletion scripts use HCL HighBond API methods and the HighBond API to retrieve and delete task runs. If you know Python/HCL, you can modify the behavior of the deletion scripts, if required. For more information, see HCL HighBond API methods and the HighBond API Reference.

Deletion of task run data

Deleting a task run deletes only the results data associated with the run:

• Result tables

• Result files

• Result logs

Analytics data tables or Python/HCL working files produced during a task run are not deleted. Those tables and files are preserved in the Input/Output tab (ACL robots), or the Working data area (HighBond or Workflow robots), and if required can be individually deleted from those locations. For more information, see Managing working data stored in a robot.

Automatically deleting old task runs for the first time

Exercise caution when deleting old task runs for the first time. If you have a large number of old task runs, with large amounts of associated results data, trying to delete everything at once can bog down your server. Use any of the strategies outlined below to delete the old task runs in batches.

Find out the quantity and date range of old task runs

Use the Task runs global view to find out the quantity and date range of old task runs. Use this information when deciding what values to use as input parameters for deletion scripts.

In the Task runs global view:

• Update the Triggered At filter to an appropriate length of time. The filter initially defaults to the last 10 days, creating a date range that is probably too short for your needs.

• Use the Robot Name filter or the Task Name filter to isolate task runs for the target robot or the target task. The Task Runs By Status panel displays the total number of task runs for the robot or the task.

• In the Task Runs table, sort the Completed At column so that the oldest task run is at the top.

For more information, see Viewing robot tasks and task runs.

Run the deletion task manually

Do not schedule a deletion task initially. Configure and run the task manually to delete old task runs in batches. Manually deleting task runs in batches allows you to break up the deletion process into shorter duration segments. After you have deleted the large backlog of old task runs, you can schedule the deletion task to run automatically.

Delete task runs one month at a time

If you are deleting old task runs based on date, establish the date of the earliest task run, and configure a deletion date that is a month after the earliest date. Manually run the deletion task repeatedly, moving the deletion date forward by a month each time. If deleting a month's worth of task runs is relatively quick, you can try deleting task runs in three-month or six-month blocks.

Delete task runs 50 or 100 runs at a time

If you are deleting old task runs based on number of runs, establish the total number of task runs, and configure a maximum task run number that is 50 or 100 runs fewer than the total number. Manually run the deletion task repeatedly, reducing the maximum number by 50 or 100 each time. If deleting 50 or 100 task runs is relatively quick, you can try deleting task runs in larger blocks.

Delete task runs one task at a time

If you have one or more robots that contain multiple tasks, delete the task runs one task at a time, rather than for an entire robot at once.

Set up a deletion script

Follow this process to set up a deletion script to automatically delete old task runs:

1. Download one or more deletion scripts

2. Create a deletion robot

3. Create and schedule a deletion task in the deletion robot

Location of the deletion task

You can create the deletion task in either production mode or development mode. The deletion scripts work across the boundary separating the two modes, so you can choose to locate the deletion task and script in whichever mode suits you.

If you create the deletion task in production mode, you must first activate the deletion script from development mode to production mode. For more information, see Activate a script version.

Two of the deletion scripts delete eligible tasks runs from both production mode and development mode:

• HB robot - Delete jobs older than a number of days from robot.json

• HB robot - Keep a number of jobs from robot.json

The third deletion script deletes eligible task runs from the mode (production or development) in which the target task is located:

• HB robot - Delete jobs older than a number of days from task.json

In the case of the third deletion script, you are not required to locate the deletion task in the same mode as the target task. However, doing so could make it easier to keep deletion tasks and target tasks clearly organized.

Finding robot and task unique identifiers

All three scripts require the unique identifier of the target robot as an input parameter. The task-level deletion script also requires the unique identifier of the target task. In Robots, navigate to the target robot or task, and retrieve the unique identifier from the URL in the address bar of the browser.

Robot unique identifier

In the URL, the robot unique identifier immediately follows the production or development segment in the path. So in the two examples below, the robot unique identifier is 63034.

https://vincicorp.robotics.highbond.com/production/63034/working-data

https://vincicorp.robotics.highbond.com/development/63034/task-runs

Task unique identifier

In the URL, the task unique identifier immediately follows the tasks segment in the path. So in the two examples below, the task unique identifier is 57275 in the first example, and 54731 in the second example.

https://vincicorp.robotics.highbond.com/production/63034/tasks/57275

https://vincicorp.robotics.highbond.com/development/63034/tasks/54731

Download one or more deletion scripts

Download one or more of the deletion scripts linked below. Choose the script that best fits your needs. If required, you can set up multiple deletion scripts with different configuration settings.

1. Right-click any of the links below and select Save link as.

   Script link	Script description
   HB robot - Delete jobs older than a number of days from task.json	Deletes task runs (jobs) older than a specified number of days from a task. Deletes eligible task runs from the mode (production or development) in which the target task is located.
   HB robot - Delete jobs older than a number of days from robot.json	Deletes task runs (jobs) older than a specified number of days from all tasks in a robot. Deletes eligible task runs from both production mode and development mode.
   HB robot - Keep a number of jobs from robot.json	Deletes task runs (jobs) greater than a specified number of runs from all tasks in a robot. Starts with the oldest task run. Deletes eligible task runs from both production mode and development mode.

2. Save the deletion script to the Downloads folder, or another folder, on your computer.

   The deletion script is downloaded as a JSON file (*.json).

Create a deletion robot

Follow the standard process for creating a HighBond robot and upload a single deletion script from your computer to the robot. Create an additional HighBond robot for each additional deletion script that you want to use.

Create the 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 HighBond Robots tab.
3. If you want to create the robot in a folder, click the folder to open it.

   For information about creating folders, see Creating and managing a robot folder.

4. Click Create a HighBond robot.
5. Select an icon and enter a name for the robot.

   Tip

   You can use icons to organize robots into easily identifiable groups.

   Note

   Do not use currency symbols anywhere in the robot name, for example: $ , € .

6. Optional. In the Description field, describe the robot so that other users understand what the robot does.
7. Click Create a HighBond robot.

   The Robots script editor begins the start-up process.

   Note

   If the message Cannot create robot appears, you need to specify a different name for the robot. Another robot with the same name already exists.

   If you are not a collaborator with permissions for the existing robot, the robot is not visible to you.

8. In the upper-left corner of the script editor, click the name of the robot, and then click Don't commit.

   You are taken to the Script versions tab of the newly created robot in development mode.

Upload the deletion script

1. In the Script versions tab in the new robot, click Upload.

2. In the dialog box that appears, select a deletion script from your computer, or drag it to the Uploaded script area.

   Each deletion script is contained in a JSON file (*.json).

3. 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 deletion script and upload the fresh copy.

Create and schedule a deletion task in the deletion robot

Follow the standard process for creating and scheduling a robot task. You can create the deletion task in either production mode or development mode. For more information, see Location of the deletion task.

Choose the mode for the deletion task

Use the Production and Development buttons in the upper-right corner of the deletion robot to switch to the mode that you want to use.

If you want to create the deletion task in production mode, you must first activate the deletion script from development mode to production mode. For more information, see Activate a script version.

Create a task and select the deletion script

1. On the Tasks tab, click Create task.

   The Task Designer opens and you can begin configuring the task settings.

2. Type a name for the task, and click Save.
3. In the Select your scripts page, select Select all.

   The deletion script is selected.

Enter script parameter values and a HighBond access token

1. Click the down arrow to expand the parameter section and enter the values for the script.
2. If you want to allow other users to run, disable, or enable the deletion task, click Share passwords.
   • Share passwords is on any user with access to the robot can run, disable, or enable the task
   • Share passwords is off only you can run, disable, or enable the task

   Regardless of the setting, other users with access to the robot can edit the task to enter their own HighBond access token.

   For more information, see Scripts with passwords.

3. At the bottom of the page, click Continue.

Schedule the task

1. At the top of the page, select Put your task on a schedule.
2. Specify the schedule details:
   • Frequency the interval at which the task is repeatedly run
   • Starting at the time of day to start running the task, and the time zone to use

     Use your own time zone unless you want the start time to represent a different time zone.

   • Beginning on the date to start running the task
3. At the bottom of the page, click Continue.

Notify users if the task does not run

1. Select Send notifications on failure to notify one or more specific users if the task does not run.

   If enabled, a notification is automatically sent if the task does not run for any of the following reasons:

   • The script in the task fails

   • The task is skipped

   • The task is manually canceled

2. Click one or more users in the list to select them.

   Only users with sufficient permissions for the robot are available to select.

3. At the bottom of the page, click Continue.

Review the settings and finalize the task

1. Review the settings that you have configured for the task.
2. Optional. To update a setting, click and make the required changes.
3. When you are satisfied with the task configuration settings, click Confirm and create task.

   Result The task is created using the settings that you specified. The task starts running at the first scheduled occurrence.