Admin Scripts

Functionality of KeyConfigure and the Web UI can be extended using add on scripts.

Manage Scripts Window

In KeyConfigure you load scripts into the server using the Manage Scripts Window found under the File menu.

     KeyConfigure Manage Scripts Window

To add scripts, simply drag them from the Library section (scripts created by Sassafras Software) to the Server section. You can also drag script bundles into the list of available scripts if you are making your own. JavaScript bundles are described in the Scripting Reference. Once a script is in the list you can move it from one location to another to control the availability of the script. The Web UI has some advanced features for scripts like an update button for any Sassafras Software supplied scripts, and the ability to configure defaults and set the script to run on a Schedule. See the Web section below for details.

If you need a script for an offline server, you can download them from the Scripts for KeyConfigure 7.8 page.

Scripts can be located in one of three places to control who will see the script when running KeyConfigure.

On Server for all admins
These scripts are stored on the KeyServer computer and available to all administrators who log in with KeyConfigure. There is no per-script access control, although scripts that operate on individual items (computers, policies, etc.) will be subject to the same access controls and permissions of the connected administrator. If a script must not be available to all administrators, place it in one of the local locations below.

Local for all accounts on this computer (Windows only)
These scripts are stored on the local computer in a directory that is accessible to all users who log onto the computer. They will not be available when connecting from other computers unless installed on those computers as well. Note that this location might not be listed if the account under which KeyConfigure is running does not have permission to modify the shared directory in which scripts are stored.

Local for this account on this computer
These scripts are stored on the local computer in a directory that is private to the account under which KeyConfigure is running. They will not be available when connecting from other computers unless installed on those computers as well. They will not be available to other users on the same computer unless separately installed for those accounts. This location is the best choice when testing a custom script, or when installing a script that should only be used by one administrators.

Using Scripts in KeyConfigure

All available scripts are listed in the Tasks menu. This will be the only way to access certain system level scripts like Sync with TeamDynamix. Scripts that operate on items of a particular type will be dimmed unless there is an applicable selection in the frontmost window. Such scripts are also available from the contextual menu when right clicking on a selection of the relevant item type. That is, right click on a Computer and you'll see any Computer scripts listed. Right click on a Product and you'll find scripts only applicable to products. This is often the easiest method of running scripts in KeyConfigure.

Web UI

To activate and manage scripts in the Web, navigate to Settings -> Scripts.

     Web UI Script Management

Scripts are listed by Name with a brief description. Simply checking the box to the left of a script will load it into the server for use by all admins. Any script that can only be used in KeyConfigure will state that next to the name. Scripts that can be used in the Web will usually have a Gear ⚙ icon to configure their settings. In those settings there may be a lock 🔒 on many options so you can restrict those from being changed on Run without unlocking them. This offers a way to try to prevent accidental changes of certain attributes. Some scripts have a Play ▷ button to run them on demand (presuming configuration) as they are system level functions. Such items will also have, a Clock 🕓 icon to set schedules for them to run on, like updating Dell Warranty date information or exporting data to TeamDynamix. If there is a new version of the script available from the one on your server, there will be an Update button on the right side. This is not something that is seen in KeyConfigure, so using the Web UI to verify your scripts are up to date is recommended.

Using Scripts in the Web

Using scripts in the Web is often done from the pull down menu in the upper right of the Ribbon on the Computers, Devices, or Purchases screens. Select one or more object in the list and click the menu to choose a script to run. A modal will pop up with the options for the script action. If this does not happen, you may need to return to the Settings - Scripts and set the defaults with the gear button first. This is the equivalent of the "right click" use in KeyConfigure. Other scripts that are system level (like Sync with TeamDynamix) must be configured and run from in the Scripts page itself as noted above.

     Web UI Run Script

Script Library

This section details various scripts that are available by default. Note that additional scripts can be created by Sassafras Software Support or your organization and added to your KeyServer instance. If you have a request please contact us.

Add Tag to Listed Items...

     Add Tag to Listed Items Web      Add Tag to Listed Items KeyConfigure

Using this script you can leverage an input file to add a Tag to all of the designated records. The input file needs to be plain text with one entry per line (computer, user, etc as appropriate). This allows you to bulk tag selected computers, devices, users, etc. using an input source rather than hand selecting objects. Simply pick the input file and put in the tag you wish to add to the objects. For some objects like Users, you will need to use KeyConfigure as not all object types have a dedicated screen in the Web UI.

Add Tags...

          

Very simple script to add a specified Tag to the selected objects. Just choose multiple computers, users, etc. and run the script. Do this with normal shift/control/command clicks pending platform. You can add multiple tags at one time by typing each one (and clicking off of it to complete the tag creation in KeyConfigure). In the Web UI, the number of selected items which will be tagged is shown in the lower left. There is also an option to replace all existing tag(s) on the selected objects with the new one(s). See also Remove Tags...

Change Lifecycle Stage...

If you use the Lifecycle management features it may be useful to bulk change several computers from Deployed to Salvaged at the same time for example. Note that this script is hard coded with options and therefore will not show any Custom Values you have added. Contact Sassafras Software Support if you need a custom script with custom values. As with other scripts, simply select the computers or devices you want to alter, run the script, and make your selection.

Change Map Visibility...

Simple script to set if selected Products are visible in the "public" areas of the Web UI. That is, the Software page, and clicking on Computers on Maps to see their installed applications. This script is only usable in KeyConfigure. In the Web UI you can use the checkmarks instead in the Manage screen.

Change Policy Expiration...

Basic script to change when selected policies expire. Uncommon use case, but manage policies can have an expiration date and bulk change may be needed in some instances. KeyConfigure use only.

Computers Without Product

KeyConfigure only. A no option script that is extremely useful. It simply opens another window that contains a list of all Computers that do not contain the selected Product. Note you should only right click on a single selected product or results could be confusing to say the least.

Create Okta Apps...

     Okta Script

This script is used when implementing Okta authentication. It generates several unique keys needed for that integration. See our documentation on this module for full details.

Export Detail URLs...

Used to generate URLs that can then be uploaded to Avery.com to print out QR codes for Devices and Computers. The resulting codes will open the URLs for those unique items. This allows easy scan of code labels to then edit and update device records when servicing in person. When running the script ensure the base url properly matches the Web Service URL (so there are no cert issue). It will then create an output file you can upload to the Avery site. See our Blog Post on this for steps on the Avery site.

Gather Dell Dates...

     Dell Warranty Date Script

This script will query all computers based on OEM Serial with Dell using your Dell API key (required input) and populate the Warranty fields with the relevant purchase and expiry information. Obtain your API key and Secret from your Dell rep. You can then choose to populate the Purchase and/or Replacement dates with the query results, replace or keep any values currently in the local records, and record the output if needed for troubleshooting.

Gather Lenovo Warranty Dates

Similar to the Dell script but no API needed, and Lenovo does not supply purchase dates only expiry dates.

Gather Microsoft Warranty Dates

Similar to the Dell script but no API needed.

Geolocate via ipstack...

A robust script that Tags each Computer with a location based on the ipstack open database. Accuracy is of course no promise. You can sign up to get a free API key which is then the only input to the script. Execution will add tags to every computer record based on IP lookup. You can then create a Tag based Map Set and view computers by reported physical location of the IP. Because the maps are value tag based, re-running the script and therefore updating their location will update the map sets.

Import Computers from Intune...

     Import Computers from Intune Script

This script can be used to import, synchronize, or both. If computers do not exist in KeyServer that are in Intune, they can be created in the Imported state. A client that then connects and matches will move the record to Dedicated. Additional information like warranty status can be pulled in as well.

Import Computers from Jamf...

     Import Comptuers from Jamf Script

This script can be used to import, synchronize, or both. If computers do not exist in KeyServer that are in Jamf, they can be created in the Imported state. A client that then connects and matches will move the record to Dedicated. Additional information like warranty status can be pulled in as well.

Import Devices from Google...

This script will import computer records from your Google management console for ChromeOS devices. It can be used to supplement the ChromeOS KeyAccess agent in that it pulls some additional fields not available from the client, and will pull all devices on demand instead of waiting for a client checkin.

Import Devices from Intune...

Nearly identical to the above import computers script except this operates on the non computer devices (i.e. Android tablets). Therefore, it only imports as there are no records for these non Windows based devices due to lack of an agent. These records go to the Imported state of Computers and do not use a license seat.

Import Devices from Jamf...

Nearly identical to the above import computers script except this operates on the non computer devices (i.e. iPads). Therefore, it only imports as there are no records for these non MacOS based devices due to lack of an agent. These records go to the Imported state of Computers and do not use a license seat.

Import Time Sets...

It is possible to create and update schedules on Maps by importing time set information from CSV. The format needs to be very precise so it is readable, so your source data may need to be adjusted to fit our format. See Time Sets for more details.

Import User Information from AD...

     Import Users from AD Script

User records in KeyServer are created by the login names reported by the OS. This means you could have more than one record for the same person because of platform differences or even local vs domain accounts. There may also be additional data fields in your Active Directory records which we would have no knowledge of at the desktop level that you would like to have in the KeyServer record. This script is designed to help manage these concerns.

There are several operational notes for this script.

The List Users in AD Group script below may be a useful companion in some cases.

List Computers...

KeyConfigure only. Given an input file with a list of computer names, open a new window with matching computer records. Used for an add hoc search based on arbitrary input from another source. A similar script can be provided that works on Serial numbers if needed. Contact Support for that script.

List Users in AD Group...

KeyConfigure only. Utility script to list all local users that exist in a given AD group. Useful when setting up User based polices to ensure AD query is working and user attributes are matching. May be useful in conjunction with the Import User Information from AD script above.

Merge Imported with Discovered Computers

     Move Computers Script

This script is useful in some instances when imported records didn't line up with records created by KeyAccess checkins. This can happen due to using an ID type other than Serial as the primary and importing records prior to client creation. Using this script you can choose how to merge the Import records with the Discovered records.

Move Computers...

     Move Computers Script

A more robust script that incorporates options available in many of the other simple scripts, like setting Division, Lifecycle, Auto Logout, Map Visibility, and more. You can select multiple Computers and change multiple attributes quickly in bulk.

Move Devices...

     Move Devices Script

Similar to Move Computers but with many fewer options. Allows bulk change of Lifecycle stage, Division, and Anchor state of selected Devices.

Move Purchases...

Much like the Move Computers and Move Devices scripts, this allows bulk change of a few attributes of Purchase records: Status, Entitlement, and Section.

Remove Tags...

Very simple script for bulk removal of Tags from items. Simply enter the tag or tags you want to remove.

Reset Station ID

This is for troubleshooting and generally only used by Sassafras Software Support or at their direction. It resets a data field used to identify computers on maps that can become scrambled in some rare cases causing computers to not show as expected.

Set Auto-logout

If you are using our web font end as a method of finding and connecting to computers over RDP, this script can be useful. If a user drops their connection without logging out, this option being enabled on a computer will cause it to auto log out after 3 minutes. Use this script to quickly set this option on all selected computers.

Set Map Availability...

In addition to all other settings for Maps, you can select in each computer record if the computer will be shown on Floorplans. Use this script to quickly hide or show a number of computers at once by setting this flag.

Set PVU

Only useful for datacenter license managers. Allows setting the PVU value of several computers at once.

Show Package Audit

     Package Audit Script     Package Audit Window

Useful to show all Packages on a selected computer, or all Computers that have a selected Package. Similar to the Show Installs function that is built in to KeyConfigure Computers. You can choose one type of package or all types. Results will vary by Operating System.

Show Tagless Items

Opens a new window showing all selected items that contain no tags. Useful if you use Tags extensively and are looking for object that have not been tagged yet.

Sync with TeamDynamix...

This script drives our integration with TeamDynamix. For more information see our Blog post on this integration and the Documentation for setting it up.