Part 1 of the tutorial introduces you to scripting in Robots and using the HighBond API to partially automate a process.
What will I learn?
You'll learn how to:
-
set up, create, and test a Python/HCL script in a HighBond robot
-
use the HighBond API to interact with a Diligent One object
-
use HCL to import and transform some data, and save the output to Results
Scenario: save output results to the Results app in Diligent One
Let's say you need to perform some recurring data analysis in Robots. After performing the analysis, you want to save the output results to the Results app for issue remediation or data visualization.
You want to schedule a Robots script containing the data analysis to run unattended on a nightly basis. You don't want to worry about whether a table exists in Results to receive the nightly output results, or have to manually retrieve a unique table ID. You want the script to automatically find the correct table, based on name, or create a new table if the named table does not exist.
In Part 1 of the tutorial we'll partially automate this end-to-end process. In Part 2 we'll fully automate it.
Note
We are going to use a table in Results to demonstrate how the HighBond API works. However, you can use the API to interact with many different types of Diligent One objects across multiple different Diligent One apps.
To learn more, scan the Core Resources in the HighBond API Reference to see which objects you can access.
Sign in to Diligent One and do some set-up tasks
The first thing you need to do is sign in to your organization's Diligent One instance and do some set-up tasks. The tasks are quick and easy to complete.
Just a reminder: you need to be a Launchpad System Admin, and have access to the Robots and Results apps, in order to perform all the tasks in this tutorial.
Sign in to Diligent One
Create a collection and an analysis in the Results app
Create a collection and an analysis in Results to store the table that you are going to create. A collection is the top-level container in Results, and an analysis is the second-level container.
Note
In Part 2 of the tutorial, you will extend the script to automate this portion of the set-up so that you do not have to perform it manually.
Create a collection
Create an analysis
Create a robot in the Robots app
Create a robot to contain the script that you are going to create.
Create a HighBond API token in Launchpad
You need a HighBond API token to be able to use the HighBond API. You can create a new token or use an existing one. Safeguard the token like a password and avoid sharing it with others.
Create and test the script in interactive mode
You create and test scripts in the Robots script editor. Manually running scripts or individual script cells in the script editor is considered interactive mode. You need to manually interact with the script in order to run it.
In Part 2 of the tutorial you'll schedule the script so that it runs unattended.
Note
If you are inactive in the script editor for more than a few minutes, the script editor process expires. If the script editor becomes unresponsive or hangs when you try to run a cell, save and commit the script, and exit and reenter the script editor. For more information, see Save the script and exit the script editor.
Create a password variable for the HighBond API token
Before you begin building the script, create a password variable for the HighBond API token.
Copy and paste code blocks into script editor cells
-
From the table below, copy and paste each code block into a separate cell in the script editor.
To add a new cell in the script editor, select Add cell below
on the script editor tool bar. You can add four additional empty cells right now, if you like.
-
After you paste the code for a cell, and perform any specified updates in the code, select Run selected cell
to see the output.
Learn more
You could put all the code in a single cell. However, organizing the code into separate cells imposes a visual order on the script, and makes the relation between the different logical blocks easier for you to see and understand. For additional benefits, see Key characteristics of cell-based script authoring.
Guidelines
-
Keep the same order Make sure the code in the script editor cells follows the same order as the code in the table below. The script will fail if any of the cells are out of order.
Note
A number appears beside each script editor cell when you run the cell. For example: [7]. The number is not a cell number. It's a dynamically updated sequence indicator that shows the order in which the cell has been run during a scripting session.
-
Use the Copy button In the code blocks below, hover over the block and select the Copy button to copy all the code in the block.
-
Copy and paste carefully When copying and pasting code, make sure you get all the code. Python is unforgiving about any missing items such as opening and closing parentheses
(
)
.Copy and paste only the code. Do not include the examples of cell output that appear after the code blocks below.
Careful copying and pasting helps you avoid runtime errors.
-
Work cell-by-cell Seeing the output cell-by-cell helps you understand the structure of the script logic. Even though the first cell has no visible output, you must run it before any of the other cells can run.
-
Read the comments in the code In addition to the commentary in the table below, read the comments in the code to understand what the code is doing.
Cell descriptions and code blocks
Note
If you get a Python error (a red error block) at any point, see Troubleshooting.
Cell # | Description and code block |
---|---|
Cell 1 |
Import required components The code in cell 1 imports some additional code components.
|
Cell 2 |
Define the variables used in the script The code in cell 2 defines several variables. Variables are required because certain values used by the script can change:
The |
Cell 3 |
Create a table in Results The code in cell 3 uses the HighBond API to find or create the Results table with the name that you specified in the previous cell (the value of Two HCL methods make the API requests:
Note This code block represents the core value of the script. By using the HighBond API, you can interact programmatically with the Results app with no need to manually open the app. This ability means you can achieve your goal of running the script unattended without worrying if a table exists in Results to receive the output results. In Part 2 of the tutorial, we'll extend the script to use this same API-based approach to automatically find or create a collection and an analysis. |
Cell 4 |
Perform some data analysis The code in cell 4 performs some simple data analysis that demonstrates a couple of HCL methods:
Dataframes are table-like structures that organize data in rows and columns. Note You could substitute any data analysis that outputs an HCL dataframe that you then save to the Results app. |
Cell 5 |
Save the output of the data analysis to the Results table The code in cell 5 saves the output of the data analysis to the Results table that was previously found or created by the script. The HCL method |
Check Results for the new table
Let's check the Results app to confirm that the new table was created, and that the table contains the output results from the sample data analysis.
Learn more
Feel free to experiment with the script and try out some different options for creating Results tables.
Save the script and exit the script editor
Robots development mode versus production mode
Development mode
When you exit the Robots script editor take a moment to orient yourself. You are in Robots development mode. Development mode is distinguished by a header with a dark background, and the Development button is selected.
You must come back to development mode whenever you want to edit a script or run it interactively, as you have just done. You cannot edit or run scripts interactively in Robots production mode.
Production mode
Use the Development and Production buttons to switch between development mode and production mode.
Production mode is distinguished by a header with a light background, and the Production button is selected. Whenever you reenter a robot, you are initially in production mode.
Learn more
For more information about the two modes, see Development mode and production mode in Robots.
What you learned
Congratulations! You now have a basic understanding of using native scripting in Robots with the HighBond API.
Specifically, you have learned how to:
-
create and test a Python/HCL script in a HighBond robot
-
use the HighBond API to interact with a Diligent One object
-
use HCL to import and transform some data, and save the output to Results
What's next?
In Part 2 of the tutorial, you'll fully automate the process you've been working with:
-
extend the script so that you don't have to manually create collections or analyses in the Results app
-
create a scheduled task so that you can run the script unattended
Go to > Part 2: Increase your knowledge
Learn more
Learn more about HCL and scripting in Robots:
Troubleshooting
If you get a Python error (a red error block) when running a cell or the entire script, perform the troubleshooting procedure below.