The QuerySurge Base API: Using the Sample Shells
Installation of the QuerySurge Base API gives you command-line access to the QuerySurge execution engine. The API can be used to drive QuerySurge executions from any external tool that can access a command line. Included in the Base API installation is a directory of sample files illustrating how to call into the API. Following is a description of how to set up the sample files on a Linux box.
There are two sample shell files included in the distribution:
Note: You will need to install the QuerySurge Base API in order to access the samples that this article discusses. Installation information is available here.
- First, please note that the Base API components should be installed in the location that the API will be called from. Typically, this is not the QuerySurge Application server (although there is no restriction on installing the components on the QuerySurge Application server) because this is not where the calling process resides. For example, if you want to call into the API from a scheduling tool, then the API should be installed on the scheduler itself or on a box where a scheduler agent is deployed. If you want to call into the API from your ETL tool, then the API components should be installed on the location where your ETL tool is installed.
- Installation is done using the regular QuerySurge Installer, choosing only the Command Line API option (this is not one of the default options; you will have to de-select the default options and select this option).
- The sample files are located in the samples directory; in the default install, this is found at:
If you installed in a nondefault location, the generic path is:
/<QuerySurge Install Dir/QuerySurge/cli/samples
Setting Up the Sample Shells
- This discussion focuses on the CLI-run_test_suites.sh The basic setup steps for CLI-run_test_suites_advanced.sh example are the same. Locate the CLI-run_test_suites.sh file and display it.
- The Configuration Variables section of the file is the part of the file we need to modify. This section should be marked clearly in the sample file by ‘START OF CONFIGURATION VARIABLES’ and ‘END OF CONFIGURATION VARIABLES’.
- There are six variables listed in this section; only five of them require modification under most circumstances. The four that require modification are:
- The myHostname variable is set to ‘localhost’. This must be changed to either the server name of the QuerySurge Application server (the fully qualified name is recommended) or the IP address of the QuerySurge Application server. Note that single quotes around the value are used.
- The myPort variable is set to the default HTTP port 80. This should be changed to the HTTP port that you have installed your QuerySurge Application server on, if it is different. (Check a browser link to QuerySurge for the port; if no port number is showing, the default value of 80 should be used.)
- The myUsername variable is set to admin. This is the QuerySurge user login under which the API executions will run. Note that single quotes around the value are used.
- The cli variable is set to the location of the main shell, qscli.sh. This must be modified only if you have installed in a location other than the default location. If so, change the value to the location of the qscli.sh file.
- The suiteIdList variable is a comma-separated list of the ID numbers of the QuerySurge Suites that you want to execute. You can find these ID numbers in QuerySurge, in the Scheduling view, in the Test Suites panel. Each Suite has an ID (for example, in the in the figure, the first Suite has an ID of 2458). Create a comma-separated list of the ID’s of the Suites you want to execute via the API (no spaces) and uses this list as the value for suiteIdList. Note that double quotes around the list are used.
- The ‘advanced’ example (CLI-run_test_suites_advanced.sh) shows how to run Suites sequentially, meaning the script waits for each Suite to complete before calling the next Suite. This is controlled by the variable ordered. If ordered is set to true (the default value), Suites are submitted sequentially; otherwise, they are all submitted together.
- The Base API requires authentication with QuerySurge, using one of your QuerySurge logins. In step 6 above, you indicated the QuerySurge user login under which the API will run, with the myUsername variable.
- To complete the setup, the specified user’s password needs to be made available for the API to use. This is done via the properties file; this file’s default location is: /opt/QuerySurge/cli/qsapi.properties.
- For safety, make a copy of qsapi.properties before you modify it.
- Open the qsapi.properties file in a text editor, and go to the last line of the file. This line reads:
# Client API
- Add a line to the file after this line. On the new line, enter your username and password separated by an equals sign ("=") as a 'key=value' pair.
For the default admin user, the final lines of the file are:
# Client API
If you had a QuerySurge Admin username 'admin002' with password 'querysurgeadmin101600', then final lines of the file would be:
# Client API
- Save the file.
Note: On the first execution of the API, the credentials are encrypted and stored in the qsapi.properties file in an encrypted format. The plaintext credentials should therefore only remain in the file until the first execution.
- In the samples directory, execute the sample shell by entering the following command:
Note: If your User login does not have sufficient (read/write) access to the Base API install directory, you have two options:
(a) run the Base API with Admin rights (i.e. as root or with sudo or equivalent), or
(b) you can move the cli directory to a location where your login does have sufficient access rights.
If you choose option (b), then you'll need to modify some file paths. Carefully modify the file qscli.sh for the new path you have selected for the /../cli directory. Also, you will need to modify your shell files (start with the Sample files that you are using) for the new path for qscli.sh (the