Scripting Overview

Table of Contents

 

Scripting Deep Dive Video

 

Minimum Requirements

Windows

Our Scripting engine currently requires Powershell version 4.0 in order to run. Devices such as Win 7 / Server 2008 have PowerShell 3.0 by default, which uses .NET Framework 2.0. These assets can be updated by installing Windows Management Framework 5.1.

For more instructions on updating your machine to Powershell 4.0 please follow this link:
https://www.microsoft.com/en-us/download/details.aspx?id=54616

MacOS

Our scripting engine also supports Bash scripting for macOS. When creating a new script or editing an existing one, set the File Type to Mac Script.

 

Overview

Check out the Community Script Library for ready-made scripts!

Running scripts on customer's assets is easy from Syncro. Once you've added a Syncro device, you can navigate to the Scripts tab:

Scripts tab

On this tab, you’ll see all the scripts that have been run previously as well as any that are coming up soon. Additionally, you’re able to both create a new script as well as run an existing one.

 

Running an existing script

Scripts can be run by clicking the Add to Queue button in the top right. This presents a dialog to pick the desired script along with scheduling when that script will run. In the below example, we have chosen the “Reboot with Prompt” script and then have the option to run that now or in the future.

Restart with Prompt

For some scripts, additional options are available such as the Scan Type and the checkboxes presented in the Run Antivirus script.

Run Antivirus

Note that, for scripts where you schedule a time, that time is based upon the Time Zone set in More > Admin > General Preferences. For example, if the Time Zone is set to (GMT-08:00) Pacific Time and you schedule the script to run at 3:00 am, then that script will fire off at 3:00 am Pacific Time, even if it is installed on an asset that is located halfway around the world in a completely different time zone.

 

Recurring scripts

You can also schedule a script to run repeatedly. You can choose the script to run every 15 minutes, every 30 minutes, hourly, daily, weekly, bi-weekly, and monthly.

Run repeatedly

 

Creating a new script

Scripts can be made by clicking the Create New button in the top-right, doing so leads to the new script editor page.

New Script

In the “Get Free Space” example above, we’ve provided a short description, adjusted the file type to “PowerShell” and copied our script code in.

 

Allow customers to run script in Portal

If you turn on the Available on Every Customer Portal checkbox, it will allow Customers to run the script directly from the Customer Portal. They can find this script by going to their Assets in the Customer Portal and then they will see an option to run it.

 

Required Files

Files can be attached and used inside of scripts. When the script is run on the asset the file will be downloaded to the location on the machine that was specified. This enables downloading functions, libraries, or executables that are needed to execute your scripts.

Before you can use a required file, it will first need to be uploaded to your Script Files on the main Scripts tab by clicking the Add New File button:

Add New File button

Existing script files can be viewed and managed by going to Scripts > View > Script Files:

Click View > Script Files

Once uploaded, the script file will be available when creating or editing a script. After clicking the Add A Required File button, it can be found in the File dropdown:

Add A Required File button

Note: When specifying the destination path, the full path will need to be entered including the file name. For Example, this is an example of a correct destination file path:

Destination path

Entering only C:\temp\ as a destination file path will result in errors when running the script.

The maximum size of a script file is 200MB. Note: Use of Environmental Variables is accepted here (Windows only):

Environmental Variables

 

Maintenance Mode

You can build Maintenance Mode in to your Scripts. This is great for when you are performing work that may cause an alert to fire off. This way no unnecessary alarms go off.

Please Note: Enabling Maintenance mode on a script that is also creating alerts meant to trigger Automated Remediation is not recommended. While Maintenance Mode is enabled, any created Alerts from the script will be closed automatically and Automated Remediation will not trigger.

 

Options

Enable Maintenance Mode: You will not be notified of alerts for this device while in Maintenance Mode.

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: This option starts Maintenance Mode at the beginning of the script and turns it off at the end of the script run.

Duration

When selecting Enable Maintenance Mode, you can choose the length of time that it will be active for. At the end of the chosen time, alert notifications will return normal operation.

 

Environment Variables

Environment variables (allowed on Windows only) allow you to specify any file location on the device. The main use of this feature will be for placing a “Required file” (see above) in directory other than the app path. That being said, for most use cases, placing the file in the default location is advised.

%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% - {computername}

%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.

%"FPS_BROWSER_APP_PROFILE_STRING%

%FPS_BROWSER_USER_PROFILE_STRING%" - "Internet Explorer

%HighestNumaNodeNumber% - The highest NUMA node number on this computer.

%HOMEDRIVE% - 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 user's workstation.

%PATH% - C:\Windows\System32\;C:\Windows\;C:\Windows\System32\Wbem;{plus program %paths%}

%PATHEXT% - ".COM; .EXE; .BAT; .CMD; .VBS; .VBE; .JS ; .WSF; .WSH; .MSC

PROCESSOR_ARCHITECTURE - AMD64/IA64/x86 This doesn't tell you the architecture of the processor but only of the current process, so it returns "x86" for a 32 bit WOW process
%running% on 64 bit Windows. See detecting OS 32/64 bit

%PROCESSOR_ARCHITEW6432% - =%ProgramFiles% (only available on 64 bit systems)

%PROCESSOR_IDENTIFIER% - Processor ID of the user's workstation.

%PROCESSOR_LEVEL% - Processor level of the user's workstation.

%PROCESSOR_REVISION% - Processor version of the user's workstation.

%ProgramW6432% =%PROCESSOR_ARCHITECTURE% (only available on 64 bit systems)

%ProgramData% - C:\ProgramData

%ProgramFiles% - C:\Program Files

%ProgramFiles%(x86) - C:\Program Files (x86)

%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% - 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 was \{username}\Local Settings\Temp"

%TIME% - The current time using same format as TIME.

%UserDnsDomain% - Set if a user is a logged on to a domain and returns the fully qualified DNS domain that the currently logged on user's account belongs to.

%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% - {username}

%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%. %windir% is a regular variable and can be changed, which makes it less robust than %%systemroot%%"

 

After clicking Save, head back to the desired Syncro Device and you’ll be able to run your newly created script.

 

Running a Script on Multiple Devices

If you want to run a script on multiple devices, there are three different ways to do that.

  1. Policies - You can add scheduled scripts to Policies if you want to regularly run scripts on every Device that has that Policy.
    Add scheduled scripts to Policies
  2. Selecting multiple Devices on the Assets & RMM page, clicking the Manage dropdown, and then clicking Run Script.
    Click Manage > Run Script
     
    If you have multiple pages of assets, you can also choose to run the script on all Syncro Devices:

     
  3. You can run scripts on all Syncro devices, only assets listed in a saved search, to all of a customer's assets, or to all assets on a policy. To do this, click Actions > Run Script from the Assets & RMM page:

 

Viewing Scheduled Scripts

If you want to see a list of all the Scripts that are scheduled to run, you can go to your Scripts page, and click the Scheduled Runs link for each Script.

Click dots > Scheduled Runs

 

This will bring you to a page showing all of the Assets that this Script is scheduled to run on:

All Scheduled Executions

 

Community Script Library

The Community Script Library is a place Users can go to find ready-made scripts that were created by Users (and vetted by us) to use on the devices. This is a great place to go and see if a script exists so you don't have to write it yourself! Or, if you have a super awesome script you think will help others, you can submit it to make it available to everyone!

First head to the Scripts page, then in the upper right, click View > Community Script Library.

This takes you to the Community Script Library where you are free to celebrate...quietly. This is a library, for Pete's sake.

You can get some details about the script from here as well. The name, a description of what it does, the author, when it was last updated, and number of times downloaded. Click a script name to view the actual script code.

When you find the Script that's just right for you, on the right hand side, click Import to My Scripts. Or if you clicked into a script, in the upper right, click Import Script. This will add it to your list of Scripts to use on your end points.

So at this point, you are saying to yourself, "Self, I have some awesome scripts I want to share with everyone. How do I do that?"

Head to a script you want to share and click the Edit button. At the bottom, click the Submit to Public Scripts Library button.

A pop up will appear letting you know that it will be submitted for review.

Important Notes

Please exercise caution when importing scripts from the Community Script Library into your Syncro instance. Syncro is not responsible for the code quality of these scripts, and these scripts are use at your own risk. Here are some additional guidelines for how the Community Script Library operates:

  • There is no guarantee scripts that are submitted to the library will be approved. Scripts may be rejected for any number of reasons, some of which may include file attachments, download URLs, personal information (subdomain or API keys), and broken functionality.
  • Users will not be notified if their script is approved or rejected
  • Syncro does not provide support for scripts in the library. We do have a category in our Community Forums named "Community Script Library" for users to discuss these scripts with one another

Scripting Variables

What is this? Scripting Variables add a powerful layer to the scripting system. Ever want to run a script but change the ticket number that the script is running for and not have to re-write the whole script? Now you can! Want to create a script that produces a pop-up that you want to use to alert Users of information pulled from their devices? Now you can! There is so much more you can do with Script Variables!

Important Note: Variables are PowerShell-based only.

 

First head to the Scripting section of Syncro and head to an existing Script or start creating a new one. There will be a button to add a Script Variable to the script.

When you click that button, four Variable Types will appear.

 

Variable Name: Give it a name. This is the variable that you will put into the script below.

Variable Type: Select one from the dropdown.

  • dropdown - Allows you to build a set of predefined values to select from at runtime. See Dropdown Variables below.
  • platform - This gives you the ability to leverage Customer/Asset/Account Tags from Syncro to grab specific info. This includes asset and customer custom fields as well! Click the Value dropdown and select the one you want.
    Platform Values
  • password - Mask their characters from view within the Syncro UI.
  • runtime - This option gives the ability to enter a value each time the script is run.

Add Variables to Script

Once you have named your Variable and chosen the type and value, make sure to add it to your script.

Add variable to script

 

Make sure to save the Script changes and you are ready to go!

When you go to run the script and have a Script Variable Runtime Type selected, you can enter the text that you want to go into the script before you run/schedule it.

Important Note: You cannot change the Runtime value after the Script has been scheduled or added to the queue. You must clear it from the queue before making changes to the value.

Also, scripts using runtime variables are unavailable to use in the customer portal.

Dropdown Variables

Dropdown Variables allow you to predefined variables that can be selected at runtime without having to type in that variable each time the script is run. To create a new dropdown list select 'Edit Dropdown Values' from the variable type:

You will then be able to add new values by clicking Add Value:

You can also delete any values as well as set a certain value as optionally the default value to be prefilled when running the script.

When running the script, the dropdown variable will show the default selected variable:

Or, you can use the dropdown to select a different variable to run the script.

 

One-Click Disable Scripts for Customers

One-click disable scripts allows you to easily disable all scheduled scripts for a particular customer with the click of a button. Navigating to the customer's detail page will show you whether scripting is enabled or disabled:

Then, if a customer has not paid or you need to easily turn off any upcoming, scheduled scripts, you can select the 'Disable' option and all scheduled scripts will be skipped.

Now, any scheduled scripts will show as disabled and show the date the script was skipped in the asset's script history.

Once scripting is set back to 'Enabled' they will be right back to where they were previously.

 

Scripting Overrides

If for any reason you need to run a one-off script for a customer who is set to disabled, you can override the disabled scripting status. Syncro will let you know that scripting is disabled for that customer and you can then proceed to run the script:

 

One-Click Disable Security Permissions

You can choose to give your technicians access to disable scripting for a customer and to manually run scripts when the customer is set to disabled. To give technicians these permissions, head to More > Admin > Security Groups, click Edit by the desired group and turn on the following permissions:

There is a PowerShell Quick Help at the bottom of any script page that provides examples, such as how to use our cmdlets. For any additional help, please contact us at help@syncromsp.com.

 

Script Categories

Script Categories allows you to manage your ever-growing list of scripts by various categories for easier viewing and access to finding your scripts.

You can create Script Categories by heading to the Scripts page and clicking View > Script Categories:

From the Script Categories page, you can add new categories, edit existing ones, and delete them. Each script category will get a name and a description.

Once your Script Categories have been created, you can assign them per script:

Or by selecting a group of scripts from the main scripting page and adding them in bulk:

You can add as many Script Categories to a script as you would like. You can sort your main scripts page by using the Categories filter at the top:

There will also be a categories dropdown when you go to run a script that will pre-filter the script list for you to avoid searching through a long list of scripts:

 

FAQ

Why is the script from the community Library failing?

These scripts usually come with specific instructions and variable requirements. Please verify that you have accounted for all variables and prerequisites. You can always head back to the page in the Community Script Library to view these instructions again.

 

Why are the Syncro cmdlets failing?

Have you imported our module at the top of the script? Have you accounted for variables such as for subdomain and email with your account subdomain and the email of a user on your account? Lastly, please do not change these cmdlets, as all variables are required

 

We are always here to help troubleshoot the scripts we have provided you, the Syncro module cmdlets, and Community Library scripts. If you are having trouble scripting with any of these, please write in with:

  • The name of the script on your account
  • An example asset that you have run this on
  • The name of the script from the Community Library (if imported and the name changed)
1 Like