Automation and SuperADMIN

SuperADMIN includes macro functionality. You can use this to automate repetitive tasks.

Creating a Macro File

There are two options:

Use the macro command in SuperADMIN to record a series of commands to a macro file.
Create the macro file in a text editor. Make sure you save the file in the macros directory and use the file extension .sam.

Macros are stored in the SuperADMIN console\macros directory. In a default installation the macros directory is: C:\ProgramData\STR\SuperADMIN\console\macros

See the macro command reference for more details about how to create a macro file.

Comments in Macro Files

You can add comments in your macro files for readability and maintainability. There are two ways to include a comment:

Type a # character at the start of the line: the line will not be treated as a command, but the remainder of the text on the line will be output to the SuperADMIN console and any logs.
Type a semi colon at the start of the line. The line will be ignored and will not be output to the console.

For example, suppose you have the following lines in a macro file:

CODE

# This comment will be output to the console and logs
; This comment appears in the macro file but will not be output

This would be executed in SuperADMIN as follows:

CODE

> macro play MyMacro
 This comment will be output to the console and logs
>

You can also use blank lines in your macro file, for readability. These will be ignored when the macro is executed.

Macros Calling Macros

You can use the macro play <name> command inside a macro to call another macro file. When the embedded macro completes execution, control passes back to the initial macro, which then continues to execute. It is not possible to pass parameters from one macro to another.

Playing a Macro File

Once you have created your macro file, you can play it back in the SuperADMIN console. SuperADMIN will execute each command as if you had typed them manually.

Use the following command (replace <name> with the name of the macro file you want to play):

TEXT

macro play <name>

Automating SuperADMIN

The SuperADMIN console also has a command line option you can use to play a macro file at startup. This allows you to fully automate SuperADMIN tasks.

To run SuperADMIN and execute a macro file, use the following command line option (replace <name> with the filename of the macro file you want to play; you do not need to include the .sam filename extension):

TEXT

console.bat "-Dmacro=<name>"

For example:

TEXT

C:\ProgramData\STR\SuperADMIN\console>console.bat "-Dmacro=superadmin-automation-macro"

Managing Logins When Automating SuperADMIN

If you are running macros using the above command line option, then you will need to ensure that your macro includes the commands to log in and out of SuperADMIN.

The recommended approach when programmatically generating macro files is to use the loginToken command. With this command, your macro can use a single-use token, rather than a username and password. As this token can only be used once, there is minimal risk to including it in the macro file on disk as it will be of no use once the macro has used the token.

SuperADMIN exposes a REST endpoint on port 9000 at /v1/auth/login that your code can query to obtain a token before each macro run. For example, when connected directly to the machine running SuperADMIN, the endpoint will be available at http://localhost:9000/v1/auth/login

Port 9000 needs to be internally accessible to the SuperSTAR components, but must not be externally accessible. See the SuperSTAR port usage recommendations for further details.

Therefore, to use the loginToken command in a macro, your code should:

Send a GET request to the login endpoint with the username and password passed via HTTP basic auth.
Extract the value of refreshToken from the response.
Write a loginToken command to your macro file in the following format (replacing <token> with the value of refreshToken returned by the endpoint):
CODE
```
loginToken <token>
```
Run the macro using the command line option shown above.

The tokens themselves have a limited lifespan. By default, the refresh token lifespan is set to 1 hour after they were generated (see Security for more details), so you will typically need to generate a token around the time you are running the macro. The response from the login endpoint also contains a refreshTokenExpiry value, which is a UNIX timestamp indicating the exact time when the provided token will expire.

By design, these tokens can only be used for a single login, so you will need to generate a new token every time you need to run the macro.

You are not recommended to use the login command in macro files, as this requires you to include the username and password of the user running the macro in plaintext, which is a potential security risk. However, should you choose to do this, then you will need to use the short form of the login command to automate the process (login <username> <password>), otherwise the SuperADMIN console will pause and prompt for the login credentials before completing the macro commands.