Driver authoring best practices - Using the built-in 'connectivityInfo' variable

Note: In this article we are using CloudShell Authoring 6.2.3 and above.
For more information on whether specific capabilities were available in a previous version please submit a ticket to our Support team.
Also, while we will refer to CloudShell Authoring this is equally available in TestShell Driver Builder. 

As a Driver developer you will find that you often use the TestShell API from within your driver. 
When using the TestShell API you will have to provide multiple inputs to first connect your API session to the Quali Server and then control resources and / or reservations. 
You can certainly hard-code such values directly into your driver but you risk having to recompile if your environment changes. 

CloudShell offers several built-in variables that mitigate this problem. In this article we will cover the "connectivityInfo" variable. 

connectivityInfo

Creating a new Lab Management driver from CloudShell Authoring will include a "User Defined" variable called 'connectivityInfo' in the Init function (for Resource Drivers) or in any command, like Setup/Teardown (for Environment Drivers). 
The purpose of this matrix is to automatically inherit Quali Server connection information.

A major advantage of using this variable is that the Driver author doesn't need to know these values in advance. Instead they can just refer to the variable name (or specifically a cell within the matrix) and trust that it will be populated with the correct information at runtime. Another advantage is that by using built-in, populated-at-runtime variables the drivers become environment agnostic and will work across different deployments (say your Dev and Production environments) without the need to compile different versions or store connection information externally. 

While previous versions of CloudShell used to run resource/topology drivers only on the Quali Server machine, it was easy to set the server address as localhost or 127.0.0.1 when connecting to the API. With the new versions, commands can be distributed to run on remote execution servers, and it's not always true that the server address will be localhost. Hence the importance of using these runtime-populated values.

By default, this variable will be a 3x3 matrix but it can be expanded to 5x3 to add two additional rows for 'AdminUsername' and 'AdminPassword'. 
Note that if your Driver does not have this matrix pre-defined you can simply create it yourself, publish it as an input, set the default checkbox in the interface page, and it will work just the same. The variable is defined as follows:

At runtime (when the command is executed), column 2 will be populated as follows:

ServerAddress: IP address of the Quali Server
TestShellApiPort: The Server port used for TestShell API interactions
QualiApiPort: The Server port used for Quali API interactions

The following 2 parameters are available in 6.3 and above (for 6.2.3, you can get these values from the reservation matrix):
AdminUsername: The username of the built-in administrator, by default 'admin'
AdminPassword: The password  of the built-in administrator, again by default 'admin' but likely changed. 

While the first three parameters are obvious the last two may not be clear. 
There are several scenarios where you may want to allow the end-user to execute commands above their own permissions limitations. For example, if you are have a group of External Users, who are blocked from making API connections using their own credentials, you will likely want to connect the API session with elevated permissions. In this case you can simply use the built in parameters and they will always be populated with the current credentials of the 'admin' user. In this manner you can selectively expose functionality to your users even if they can not inherently access it. 

Best Practices

Resource/Service Drivers

As mentioned above, the 'connectivityInfo' matrix is a matrix variable defined under the "User Defined" section of each individual command. 
To avoid having to create / use it in each command you should make use of it in your Driver's Init command (or whichever one is marked as the "Start Session"). In this command you can assign the values from this automatically populated matrix to global Project-level variables. 
All other commands that require this information will be able to refer to the Project variables rather than having to create / use a local version of the connectivityInfo. 

Environment Drivers
Since an environment driver is brought up to run a command and then close down, there is no such Init function, so each command can get the information if it publishes this matrix (the topology driver template comes with it pre-defined for the Setup/Teardown/Example commands.
You can still store the data in project variables so that other inner functions will be able to access the information easily.

First you will need to define Project variables to hold each of the above values. 
Then, using an "Assign Variable" step or, more efficiently, using a "MatShell" step you can assign the values from the Init command's connectivityInfo to the Project variables as follows:

From then on, each command can use the Project variables to reference this information.