Manage Scripts
Table of Contents
Scripting is one of the core RMM features in Syncro. We designed our Scripting module to have maximum flexibility and interoperability with tools you already use, including:
- PowerShell: Microsoft's scripting language for Windows administration. This is Syncro's primary and most supported file type because of its power and relative ease of readability for technicians.
- Batch: You probably have some .bat files; these are common and do work, but leave aren't as good for automations.
- VBScript: Powerful, but difficult to write if you're not a programmer. Syncro can't help you with these.
- Mac Bash: A UNIX shell and command language available for sending commands to Mac assets.
Prerequisites
Syncro's scripting engine requires PowerShell version 4.0 to run.
Devices such as Win 7 / Server 2008 have PowerShell 3.0 by default, which uses .NET Framework 2.0. Install Windows Management Framework 5.1 to update these assets.
Our scripting engine also supports Bash scripting for MacOS. When creating a new script or editing an existing one, just select Mac Script for the File Type.
About the Scripts Table
When you navigate to the Scripts tab/module, you'll see the Scripts table:
The Scripts table displays:
- Name: The name of the script.
- Favorite: If the script is marked as a favorite, displays a yellow star.
- Category: If available, the script categories associated with the script.
- Description: A more detailed description of what the script will do when run.
- Created: The date/timestamp for when the script was created. If you imported the script from the Community Script Library, this is the date of your import.
- Scheduled Runs: The number of scripts currently in the queue. This number does NOT include scripts that are scheduled on a Policy or an Asset. See also Run a Script.
From this page you can:
- Search: Enter some text in the Search box, then click Search. Syncro filters the table to display matching scripts only. Remove your text and click the button again to return to the full list.
- Filter: By default, the filter is set to “All Categories,” but you can choose to display only specific ones. Syncro has four default categories (Batch, Mac Script, PowerShell, and VBScript) but you can also create your own custom ones. See Use Script Categories.
- Bulk Edit Script Categories
- Create a New Script
- Add a Required File
- View: The Community Script Library, any custom Script Categories, or previously uploaded Script Files.
Create a Script
To create a new script, follow these steps:
- Navigate to the Scripts tab/module.
- Click +New Script.
- Enter a Name to help you identify the script later.
- Optionally, complete the other fields:
- Description: Enter a more detailed description of your script's purpose, what it does, etc.
- Category: Select one or more custom Categories you can use to locate the script. See Use Script Categories.
- Mark as Favorite: Check the box to find the script in your list of Favorites later. See Favorite or Unfavorite a Script.
- Available on Every Customer Portal: Check this box to allow End Users to run the script directly from the End User Portal. End Users see the script in their Assets section. You can choose to do this later; use the horizontal ellipsis menu in the Script list to select “Make Available on Customer Portal.” Note that scripts using runtime variables are can't be used in the Portal.
-
Add Script Variable: Click this button to display a new row for the Name and Type of each variable you want to add. (Note that variables are PowerShell-based only.) Make sure to add your variables in the text editor for your Script (e.g., echo “$runtime”). Type options include:
- Dropdown: Allows you to build a set of predefined values to select from at runtime. Click Edit Dropdown Values to add/edit/delete each value, and select one as the default value to be prefilled when running the script.
- Password: Variables that mask their characters from view within Syncro.
- Platform: Standard and custom properties stored in Syncro, including tags and custom fields. Select the one you want from the Value dropdown menu.
- Runtime: Like command line arguments; you'll be prompted to enter values when you schedule the script.
- +Add A Required File: Click this button to upload/attach a file to your script. See Add a Required File.
- File Type: TBD
-
Run As: Select to run your script as "System" (like in a background service with system-level access) or as “Logged In User.”
Note: Logged In User only works if a user is currently logged in. For most system maintenance and alerting, you'll want to choose System. Only use Logged In User if you need to know something about a logged in user or you want to alert them. - Max Script Run Time (minutes):
-
Enable Maintenance Mode Options: You won't be notified/alerted for assets in maintenance mode, so when you check this box you'll have a few choices:
- Enable Maintenance Mode: The default, which allows you to choose a time-based Duration.
- Disable Maintenance Mode: Useful for follow up scripts that may be used during your work on the asset. Maintenance Mode will turn off at the completion of the script with this selected.
-
Enable for the Duration of the Script: Starts Maintenance Mode at the beginning of the script and turns it off at the end of the script run.
Note: Enabling maintenance mode for a script that's also creating alerts that trigger automated remediations is not recommended. While Maintenance Mode is enabled, any created Alerts from the script will be closed automatically and the automated remediation will not trigger.
- Script: A numbered-line text/editor area for your actual script. (Quick Help for PowerShell is available at the bottom of the page.)
- Click Create Script.
Edit a Script
To edit an existing script, follow these steps:
- Navigate to the Scripts tab/module.
- Click on the row for the script you want to modify. (Alternatively, click the horizontal ellipsis at the end of the row, then select Edit.)
- Click Update Script.
See also: Bulk Edit Script Categories.
Clone a Script
To clone (duplicate) an existing script, follow these steps:
- Navigate to the Scripts tab/module.
- Click on the row for the script you want to clone. Then click Clone. (Alternatively, click the horizontal ellipsis at the end of the row, then select Clone.) Syncro displays the Editing Script page with “Copy” appended to the Name.
- Revise the Name and any other values you'd like.
- Click Update Script.
Delete a Script
To delete a script you no longer want, follow these steps:
- Navigate to the Scripts tab/module.
- Click the horizontal ellipsis at the end of the row, then select Delete.
- Click OK.
Favorite or Unfavorite a Script
When you mark a script as a Favorite, a yellow star appears in the Script's table's star column, so you can easily see it.
To mark a script as a favorite, follow these steps:
- Navigate to the Scripts tab/module.
- Click on the row for the script you want to favorite. Then check the “Mark as Favorite” box. (Alternatively, click the horizontal ellipsis at the end of the row, then select "Add Favorite.")
- Click Update Script.
To unfavorite a script, follow the same steps but uncheck the box or select “Remove Favorite.”
Add a Required File
You can upload files and use these files inside your scripts. The attached file will download in the location you specify before the script runs on an asset. This enables downloading of functions, libraries, or executables that are needed to execute your scripts.
Note: The maximum size of a script file is 200MB.
To upload/attach a file, follow these steps:
- Navigate to the Scripts tab/module.
- In the upper right, click Add New File.
- In the pop-up window that opens, select that file, then click Upload. Click OK. This file will be available whenever you create or edit a script.
Tip: To view, download, or delete previously uploaded files, select Script Files from the View button menu.
To use the file within a script, follow these steps:
- Navigate to the Scripts tab/module.
- Locate the script in the list, then click it to display its edit page.
- Click +Add Required File, then enter the full path in the Destination File Name field and select the File:
Notes:- Be sure to enter the FULL PATH for the Destination File Name field, including the file name itself. For example, if the name is script.bat, the path might be: C:\Users\syncro\script.bat. Entering only C:\Users\syncro will result in errors.
- On Windows, you can use Environment Variables here.
- Click Update Script.
Environment Variables
Environment variables (Windows only) listed below include options that allow you to specify any file location on the asset. This is useful for placing a Required File in directory other than the app path. However, placing the file in the default location is advised for most cases.
Variable | Example / Description |
---|---|
%ALLUSERSPROFILE% | C:\ProgramData |
%APPDATA% | C:\Users\{username}\AppData\Roaming |
%CD% | The current directory (string). |
%ClientName% | Terminal servers only; the ComputerName of a remote host. |
%CMDEXTVERSION% | The current Command Processor Extensions version number. (NT = "1", %Win2000%+ = "2".) |
%CMDCMDLINE% | The original command line that invoked the Command Processor. |
%CommonProgramFiles% | C:\Program Files\Common Files |
%COMMONPROGRAMFILES%(x86) | C:\Program Files (x86)\Common Files |
%COMPUTERNAME% | The name of the computer. |
%COMSPEC% | C:\Windows\System32\cmd.exe or if running a 32 bit WOW - C:\Windows\SysWOW64\cmd.exe |
%DATE% | The current date using same region specific format as DATE. |
%ERRORLEVEL% | The current ERRORLEVEL value, automatically set when a program exits. |
%HighestNumaNodeNumber% | The highest NUMA node number on this computer. |
%HOMEDRIVE% | Returns the drive letter where the user profile is stored, followed by a colon (e.g., C:). |
%HOMEPATH% | \Users\{username} |
%LOCALAPPDATA% | C:\Users\{username}\AppData\Local |
%LOGONSERVER% | \\{domain_logon_server} |
%NUMBER_OF_PROCESSORS% | The number of processors running on the machine. |
%OS% | Operating system on the End User's workstation. |
%PATH% | Returns a list of folder locations the system will search through when you type a command, without giving its full path. |
%PATHEXT% | .COM; .EXE; .BAT; .CMD; .VBS; .VBE; .JS; .JSE ; .WSF; .WSH; .MSC |
%PROCESSOR_ARCHITECTURE% | Returns the architecture of the currently running progress (e.g. 'AMD64' or 'x86'). |
%PROCESSOR_ARCHITEW6432% | Returns the underlying architecture when a 32-bit process is running on a 64-bit Windows system. |
%PROCESSOR_IDENTIFIER% | Processor ID of the End User's workstation. |
%PROCESSOR_LEVEL% | Processor level of the End User's workstation. |
%PROCESSOR_REVISION% | Processor version of the End User's workstation. |
%ProgramData% | C:\ProgramData |
%ProgramFiles% | C:\Program Files |
%ProgramFiles%(x86) | C:\Program Files (x86) |
%ProgramW6432% | Returns the Program Files folder for 64-bit applications (e.g. 'C:\Program Files"). |
%PROMPT% | Code for current command prompt format, usually $P$G%C%:> |
%PSModulePath% | %SystemRoot%\system32\WindowsPowerShell\v1.0\Modules\ |
%Public% | C:\Users\Public |
%RANDOM% | A random integer number, anything from 0 to 32,767 (inclusive). |
%SessionName% | Terminal servers only - for a terminal server session, SessionName is a combination of the connection name, followed by #SessionNumber. For a console %session%, SessionName returns "Console". |
%SYSTEMDRIVE% | Returns the drive letter of the system's boot drive followed by a colon (e.g. "C:"). |
%SYSTEMROOT% | By default, Windows is installed to C:\Windows but there's no guarantee of that; Windows can be installed to a different folder, or a different drive letter. %systemroot% is a read-only system variable that will resolve to the correct location. NT 4.0, Windows 2000 and Windows NT 3.1 default to C:\WINNT. |
%TEMP% and %TMP% | C:\Users\{Username}\AppData\Local\Temp. Under XP this is \{username}\Local Settings\Temp. |
%TIME% | The current time using same format as TIME. |
%UserDnsDomain% | If an End User is a logged into a domain, returns the DNS name of the domain (i.e., corp.example.com). |
%USERDOMAIN% | {userdomain} |
%USERDOMAIN_roamingprofile% | The user domain for RDS or standard roaming profile paths. Windows 8/10/2012 (or Windows 7/2008 with Q2664408). |
%USERNAME% | Returns the currently logged-in user's account name. In the event that no user is logged in, this will either be unset (empty) or return the system account name (depending on the context). |
%USERPROFILE% |
%SystemDrive%\Users\{username} This is equivalent to the $HOME environment variable in UNIX/Linux. |
%WINDIR% | %WinDir% pre-dates Windows NT and seems to be superseded by %SystemRoot%. Set by default as windir=%SystemRoot%. |
Use Script Categories
Script Categories help you to manage your ever-growing list of scripts for quick and easy access to the ones you want.
The Script Categories you create here appear in the Scripts Table's Filter option and are also available when you Run a Script.
- Navigate to the Scripts tab/module.
- From the View menu, select “Script Categories.” Syncro displays any existing custom categories.
- To create a new one, click +New Category.
- In the pop-up window, enter a Name and Description for your new category. Then click Save Script Category. Syncro displays this in the Script Categories table, which also shows you how many scripts are in your category, and allows you to edit/delete the category.
- Add scripts to appear in your new category. Either:
- Edit a script, select your Category from the Category dropdown menu, and click Update Script, or
- Bulk Edit Script Categories.
Note: You can add as many categories as you want to a script.
Bulk Edit Script Categories
To bulk edit script categories, follow these steps:
- Navigate to the Scripts tab/module.
- Click the checkboxes to select the script(s) you want to modify. (Check the box in the header row to select all.)
- Click Bulk Edit Categories.
- In the pop-up window, select the Category name(s) by checking the box(es).
- Select the appropriate Action:
- “Add Categories to Selected Scripts,” then click Assign.
- "Remove Categories from Selected Scripts," then click Remove.
Disable Scripts for Organizations in One Click
You can easily disable all scheduled scripts for a specific Organization with the click of a button.
- Navigate to the Organizations tab, then click one to display their Details Page.
- On the Overview subtab, at the bottom of the Overview section, you'll see whether scripting is currently enabled or disabled:
- Click Enabled. The button will change to Disabled, and Syncro will skip all upcoming scheduled scripts until you flip this switch again.
Notes:
- The Asset's Script History shows any date(s) the script was skipped.
- If you need to run a one-off script for an Organization that's been set to Disabled, you will be prompted to override the disabled scripting status.
- These options require that a Syncro User has the "Customers - Disable Scripting" and “Customers - Manually Run Scripts When Disabled” security permissions.
Troubleshooting Scripts
Scripts from the Community Script Library come with specific instructions and variable requirements. If you have one that's failing, verify that you've accounted for all variables and prerequisites. You can always find script-specific instructions in the Community Script Library.
If Syncro cmdlets are failing, check that you've:
- Imported Syncro's module at the top of the script,
- Accounted for variables (such as for subdomain, email with your account subdomain, and email of a user on your account), and
- Not made any changes to the cmdlets, since all variables are required.
If you're still having trouble scripting with any of Syncro module cmdlets or commands, let Support know:
- The name of the script on your account,
- An example asset that you've run the script on, and
- The expected behavior compared to the actual outcome.
Notes:
- There's a PowerShell Quick Help at the bottom of all script New/Edit pages that provides examples, including how to use our cmdlets.
- Unfortunately, Syncro Support is unable to help you troubleshoot any Community Scripts or Custom Scripts.