We are well aware of the value that scripts provide to MSPs on a daily basis. That’s why we built a powerful scripting module to empower you to write, run, and schedule scripts to run on autopilot with ease.
Before we get started, the scripting module will need certain permissions from the admin to function:
The asset owner must grant authorization for the SuperOps.ai agent to access the device’s Command Prompt / PowerShell on Windows devices and Terminal for Mac and Linux devices.
The administrator must grant folder permissions for the script to be downloaded or uploaded.
In Windows, Powershell and WMI must be enabled and the SuperOps.ai agent should have the required permissions to access it. For Mac, Full Disk Access and Screen Recording need to be provided for Superops present under /Library/superops/bin.
Ensure that no antivirus software or firewalls on the asset block the SuperOps.ai agent. You can do so by whitelisting the following URLs used by the agent to download script module files and auto-updates.
wss://ws.superops.ai/*
📝Note: For Windows, we support PowerShell, VB Script, and Bat scripting languages.
For Mac and Linux, we only support Bash.
Overview:
Here’s everything we’ll be looking at in the scripting module:
1. Creating a new script
Navigate to Modules > Scripts, click the +Script icon at the top of the page
Or click Create from the navigation bar and select Scripts under Asset Management.
2. Give the script a title and description.
3. You can also add single or multiple tags describing the script by clicking on the "+Add Tag" icon below the description.
4. Under Script data, you’ll be able to choose the script command language for the script to run and set a Script timeout duration. SuperOps supports Bat, VBScript, and PowerShell for Windows and Bash for macOS devices.
5. You can also choose to run the script as a Root user or a Logged in user. You can also set Script timeout. The script will be executed only for the mentioned duration.
6. SuperOps.ai also lets you add scripting variables and attach files to the script.
7. You can add a Readme for the script too, which helps the users understand the script in more detail.
8. Once everything is done, you can start writing the script in the script editor.
9. After completing the script, click the Save icon at the top corner of the page.
10. You can also add the script to ‘Favorites’ by clicking the star icon near the script's title.
2. How to run an existing script
SuperOps.ai has made it simple and easy for you to run a script with just a few clicks. To run a script at the asset level,
Navigate to Modules > Assets
Choose the asset you want to run the script for, and click the "Run script" button at the top of the page.
3. You can either run the script immediately or schedule it to run at a selected time.
2.1 Running a script on multiple assets:
You can run scripts for multiple assets at a time with SuperOps.ai. To do that,
Navigate to Modules > Assets
Under All Assets, select the assets you want to run the script for by clicking on the checkbox near each asset.
You’ll see a Run Script button at the top of the page. Once you are done selecting the assets, click Run script.
4. Choose when to run the script for the selected assets. You can either run them immediately or schedule them for a particular date and time.
5. Also, select whether to run the script on Mac or Windows devices. When you’re running scripts on multiple assets, remember that Powershell, Bat, and VB scripts won’t execute on any Mac assets, and Bash scripts won’t execute on any Windows assets.
6. The drop-down list allows you to choose the script that will be executed.
7. Once you are done, click "Run" to execute the script on multiple devices.
3. Scheduling a script at the Policy level
You can now schedule a script at the policy level with SuperOps.ai. To do that,
Navigate to Modules > Assets
Select the asset you want to schedule the script for.
Choose Schedule Actions under the Policies tab
4. Click the +Policy on the right corner of the screen.
5. Give a name and description of the action.
6. Choose whether to run the action once or on schedule.
7. Select a script from the drop-down list as shown below.
8. Once you are done, click Save to schedule the script at the global level.
📝Note: You can also schedule a script at the client, site, or asset level. To do that, you need to choose a client, site, and/or asset from the drop-down menu, as shown below. Once you are done, you can continue to schedule a script.
3.1 How to view scheduled scripts
You can view the scheduled or executed scripts for any asset in the scripts tab of the asset.
2. If you scroll right on the scheduled scripts, you will see an edit option available for each script.
3. This makes it easier for you to edit the scheduled scripts from the asset page itself.
4. How to view script output:
Similarly, you can see the script output of any executed scripts by scrolling right under Executed scripts widget and clicking on the Script Output button.
5. Adding files to a script
You can add files to the scripts by either attaching files that are already uploaded or by uploading new files from your device.
To upload a new file,
Click +Upload file and choose the file you want to attach to the script.
Enter the destination path with the file name for the file to be downloaded.
Once you are done uploading, save the script.
6. Script Variables
Script variables make scripting so much easier. Without having to completely rewrite the script each time a modification is required, the values of the script's variables can be changed.
There are two types of script variables: Runtime and Placeholder variables.
6.1 Runtime variables:
These variables let you change the variable's value each time the script is run.
For example, while running a script from the asset details page, you will be asked to enter a value for the runtime variables configured in the script. This value will be passed to the script for this asset only this time. The next time you run the same script for this asset, you will have to enter a new value for the runtime variable.
📝Note: When you run the script through policy, you will be asked to enter a value for the runtime variable only once.
6.2 Placeholder variables:
These variables change the variable's value with respect to particular asset details every time the script is run.
For example, if you have a placeholder variable named $clientname configured in a script and you run that script for different assets, the placeholder variable will be replaced by the asset’s client name.
6.3 How to add runtime variables to your script:
Click the "+ Add run time variables" button.
Give the variable a name. You’ll be including this variable in the script that you write.
You can add one or more runtime variables to a script. Once you are done, click save.
You’ll be asked to give values for the runtime variables when the script is run.
6.4 How to add placeholder variables to your script:
Click the + Add placeholder variables button.
Give the variable a name and choose a placeholder from the dropdown list. The drop-down list contains default asset fields and custom client fields.
You can add one or more placeholder variables to a script.
6.5 Overriding Runtime variables in policies:
In SuperOps.ai, you can override the values of the runtime variables that have been set in a global-level policy for a particular asset, site, or client.
Here’s how:
Navigate to Settings > Policy management
Select a hierarchical policy, for example, Windows workstation policies, and go to Schedule Actions
Select the site and/or asset and/or client and/or for which you want the runtime variable to be overridden.
Now select the policy to edit the value of the runtime variable and hit Save.
5. You will see an “Overridden” tag near the policy once the changes have been saved.
7. Environmental Variables:
In scripts, you can use environment variables (Windows only) to specify the location of files that you want to upload.
Using environmental variables in a script to upload files:
Define the environmental variable before you start using them in scripts.
For example, in Windows assets, you can define the environment variables in “System Properties” from the Control Panel.
2. Once this is done, you can now use the environment variable to specify the location of the file that you need to upload.
For example, if the location where you want to upload the file is C:\users\test\onedrive\desktop\image.png and the environment variable is defined as $env:ProgramData in the system properties, you need to assign the dynamic part of the file location to the environment variable - $env:ProgramData = C:\users\test. Now while uploading the file, you’ll enter the location of the file as $env:john\image.png or %john%\image.png. The file (image.png) will now be uploaded to the mentioned location. The dynamic part of the path assigned as the environment variable will differ for every system.
You can also use the environment variables that are already available on your Windows devices instead of creating a new one as mentioned above. The following is the list of static environment variables:
ALLUSERSPROFILE=C:\ProgramData
APPDATA=C:\Users\john\AppData\Roaming
CommonProgramFiles=C:\Program Files\Common Files
CommonProgramFiles(x86)=C:\Program Files (x86)\Common Files
CommonProgramW6432=C:\Program Files\Common Files
COMPUTERNAME=DESKTOP-216RAEI
ComSpec=C:\WINDOWS\system32\cmd.exe
DriverData=C:\Windows\System32\Drivers\DriverData
HOMEDRIVE=C:
HOMEPATH=\Users\john
LOCALAPPDATA=C:\Users\john\AppData\Local
LOGONSERVER=\\DESKTOP-216RAEI
NUMBER_OF_PROCESSORS=8
OneDrive=C:\Users\john\OneDrive
OS=Windows_NT
Path=C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\WINDOWS\System32\OpenSSH\;C:\ProgramData\superopsintegrations\chocolatey\bin;C:\Users\john\AppData\Local\Microsoft\WindowsApps
PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC
PROCESSOR_ARCHITECTURE=AMD64
PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 140 Stepping 1, GenuineIntel
PROCESSOR_LEVEL=6
PROCESSOR_REVISION=8c01
ProgramData=C:\ProgramData
ProgramFiles=C:\Program Files
ProgramFiles(x86)=C:\Program Files (x86)
ProgramW6432=C:\Program Files
PROMPT=$P$G
PSModulePath=C:\Program Files\WindowsPowerShell\Modules;C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
PUBLIC=C:\Users\Public
SystemDrive=C:
SystemRoot=C:\WINDOWS
TEMP=C:\Users\john\AppData\Local\Temp
TMP=C:\Users\john\AppData\Local\Temp
USERDOMAIN=DESKTOP-216RAEI
USERDOMAIN_ROAMINGPROFILE=DESKTOP-216RAEI
USERNAME=john
USERPROFILE=C:\Users\john
windir=C:\WINDOWS
ZES_ENABLE_SYSMAN=1
8. Working with the SuperOps.ai module:
8.1 What is a module?
A module is a package that contains PowerShell / Bash members, such as cmdlets, providers, functions, workflows, variables, and aliases.
These modules can be organized and shared to work in conjunction with other PowerShell / Bash scripts as a built-in function. These modules, when combined with scripts, can help technicians automate and perform a variety of complex tasks with ease.
Now that we've covered what a module is, let's move on to importing modules into the platform, along with some sample scripts for you to start using.
8.2 Importing the SuperOps.ai module:
To make sure that the script is properly imported into the platform, the following line needs to be in the first line of the script.
For Windows assets: Import-Module $SuperOpsModule
For Mac and Linux assets: source $SuperOpsModule
8.3 Functions of the SuperOps.ai Module:
You can use the following built-in functions from the SuperOps.ai module to automate various tasks:
For Windows:
1. Uploading files in SuperOps.ai
Syntax:
Send-File -FileName <Exact location of the file>
Example:
Send-File -FileName "c:\working\test.png"
📝Note: This file can be viewed on the IT documentation page of the asset.
2. Capturing a screenshot of the logged-in user’s asset
Syntax:
Get-UsersScreenShot -DestinationPath <full path of destinationLocation>
Example:
Get-UsersScreenShot -DestinationPath "C:\working\test.png"
📝Note:
The captured screenshot will be saved in the provided destination folder.
This function works only when there is a user logged into the device.
3. Populating a custom field with values fetched from the asset
Syntax:
Send-CustomField -CustomFieldName <CustomFieldName in RMM Monitoring class> -Value <Value to be sent>
Example:
Send-CustomField -CustomFieldName "CustomNumber1" -Value $TextNumberValue
📝Note: This works only for text, long text, decimal, and number data type fields. Click here to learn more about adding asset custom fields.
4. Creating a ticket in SuperOps.ai
Syntax:
$res = Send-CreateTicket -Subject "$Subject" -Email "$Email" -Description "$Description"
5. Updating a ticket in SuperOps.ai
Syntax:
$res = Send-UpdateTicket -ticketId "$ticketId" -Status "$Status"
6. Creating a worklog in SuperOps.ai
Syntax:
Send-CreateWorklog -itemName "$ItemName" -ticketId $res $ticketId -isBillable $billable -isAfterHours $afterHours -qty $qty -technicianMail "$Email" -notes "$Notes"
write-Host $res
For Mac and Linux:
1. Populating a custom field with values fetched from the asset:
Syntax:
Send-CustomField $fieldName $value
Example:
Send-CustomField "CustomText1" "test"
📝Note: This works only for text, long text, decimal, and number data type fields. Click here to learn more about adding asset custom fields.
2. Creating a ticket in SuperOps.ai
Syntax:
Send-CreateTicket -Subject "$Subject" -Email "$Email" -Description "$Description"
Example:
Send-CreateTicket -Subject "ticket test" -Email "john@gmail.com" -Description "testing ticket"
📝Note: wget must be installed in the Linux device for the function to work.
3. Updating a ticket in SuperOps.ai
Syntax:
Send-UpdateTicket -ticketId $ticketId -Status $Status
Example:
Send-UpdateTicket -ticketId "12345" -Status "Closed"
4. Creating a worklog in SuperOps.ai
Syntax:
Send-CreateWorklog -itemName "$ItemName" -ticketId "$ticketId " -isBillable "$billable" -isAfterHours "$afterHours" -qty "$qty" -technicianMail "$Email" -notes "$Notes"
Example:
Send-CreateWorklog -itemName "Troubleshooting" -ticketId "12345" -isBillable "true" -isAfterHours "true" -qty "12" -technicianMail "john@gmail.com" -notes "sample notes"
5. Uploading files in SuperOps.ai
Syntax:
Send-File $fileLocation
Example:
Send-File "/home/user/sample.txt"
6. Capturing a screenshot of the logged-in user’s asset
Syntax:
Get-UsersScreenShot $location
Example:
Get-UsersScreenShot "/Library/test.png"
📝Note:
The captured screenshot will be saved in the provided destination folder.
This function works only when there is a user logged into the device.
We do not support this function in Linux
9. Community script library:
You can view default scripts given by SuperOps.ai as well as a variety of different scripts posted by other users in the script community.
You can also download the scripts from the community and run them on your assets. This saves you a lot of time since you don’t have to write a script from scratch. Additionally, you can submit your scripts to the library if you believe they would be useful to others.
9.1 How to import a script from the community library:
Go to Modules > Scripts and click on "Community" under Script Library
Search, or scroll through the scripts and select the script that you want to import.
You’ll see an Import option at the top right corner of the page. Click that to import the script.
4. Once you've imported the script, you’ll be able to edit the script. You can save the script once you are done updating it.
5. And voila! You have now successfully imported a script.
9.2 How to add a script to the community library:
You can publish your script in the community library by clicking on the Publish in Community option on the top right corner of the page.
Your scripts can be rejected for multiple reasons and will only be published in the community library after being subjected to many evaluations.
3. Once you have published your script in the community library, every time you make any changes to the script, you need to save and sync it to the community by clicking on "Sync to the community."
4. The users who have already imported the script will be shown an update notification so that they can reimport the script.
📝 Note:
Any scripts imported from the community script library are done at your own risk. SuperOps.ai cannot be held responsible. SuperOps.ai is not responsible for the scripts published by the community. You import these scripts entirely at your own risk.
9.3 Limitations in uploading scripts to the Community Library:
There are a couple of limitations that you’ll need to keep in mind when you upload your scripts to the Community Library.
The files that have been attached to your script will not be uploaded to the Community Library.
If custom field values are used in the Placeholder variable, they will not be uploaded to the Community as well.