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.

     

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

     

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.

     

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

           

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

Note the need for this script in the Web UI has been replaced by the Quick Edit functionality. 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 Software 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...

     

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

☑ Create PinIdentity Apps...

     

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

☑ Export Computers to Jira

Used by customers with Jira as a helpdesk ticketing tool, this script will export computer records to your Jira instance. This is useful for using AllSight as the source of ITAM while using Jira for ITSM.

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

☑ Find by Serial...

Simple script that takes an input plain text file with one serial per line and finds all matching computer records in the system.

☑ Gather Warranty Dates...

     

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. It will also pull Lenovo warranty expiration dates. 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. Note you can then use the Set Replacement Date script to build on this information automatically.

☑ 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 from Intune...

     

This script can be used to import, synchronize, or both, based on serial number, and will work for Windows, iOS and/or Android devices managed in Intune. 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 the Serial based ID will move the record to Dedicated and update with KeyAcces data. Additional information like warranty status can be pulled in as well.

The Azure App configuration for which you need the Tenant, App/Client ID, and Client Secret Credentials is very basic. The app needs permission to read the InTune devices and configuration, so at the simplest it needs DeviceManagementApps.Read.All and DeviceManagementManagedDevices.Read.All. Also ensure these are Application permissions and not Delegated as the latter will not work. You may alter as needed for the security or tenancy of your environment of course, but if the app can not read a device it will not be imported.

In the case of creating a record, the fields imported include:

computerOEMSerial
computerSystemSerial
computerBIOSSerial
computerUUID
computerLastAudit
computerName
computerModel
computerManufacturer
computerOSVersion
computerRAMSize
computerDiskSize
computerFreeSpace
computerMACAddress
computerWirelessAddress
computerUserName
computerOwner
computerServiceURL
computerPlatform
computerOSType
computerLastImport

In the case of an Update for an exiting record, the only fields that will be pulled are Owner and ServiceURL.

☑ Import from Jamf...

     

This script will import and/or sync data from Jamf for MacOS, iOS, and/or tvOS devices. For full information see our dedicated Tech Note on this item.

☑ 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. To get the JSON to add to this script, follow these steps:

In google cloud console, APIs & Services:

1. Create a new project (or use an existing one)
2. Enable the Admin SDK API for that project
3. Create a service account
4. In the service account, on the KEYS tab, ADD KEY ->Create new key
5. Choose the JSON key type

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

     

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.

• It will pull in Department, Phone, and eMail fields from AD for all matching user accounts.
• You can specify which user attribute to use as the Primary Name in KeyServer, and then Alias the others to that account.
• Additional Aliases is a coma delimited field that allows you to alias other user attributes from AD
• External ID from allows you to populate the external id field with a specified AD attribute. This is searchable in the Loaner Checkout Extra in newer versions.
• If you specify an OU or Filter it will import all user records from that resulting location even if we currently have no matching records locally. This allows you to create records not just sync them.
• There are also options to write the results to a file for logging to troubleshoot issues.

There are several operational notes for this script.

• It will only work through the Web UI if the host server is Windows (see below)
• It will only work in KeyConfigure on Windows if you are logged in to the OS with a Domain account (see below)
• In either case, the host computer account or local user account that is executing the script must be able to query the domain accounts
• IF your AD allows anonymous queries of user accounts and properties, then there are no operational restrictions, but this tends to be uncommon

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

☑ Import User Information from Azure AD...

Similar to the AD script of the same name, this seeks to import, sync, and alias user data from Azure. See the above script for relevant concepts. Ensure the credentials used in the script have the proper user and group read access in your tenant.

☑ 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

     

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

     

Note in the Web UI this script is generally replaced by the Quick Edit feature. 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...

     

Note in the Web UI this script is generally replaced by the Quick Edit feature. Similar to Move Computers but with many fewer options. Allows bulk change of Lifecycle stage, Division, and Anchor state of selected Devices.

☑ Move Purchases...

Note in the Web UI this script is generally replaced by the Quick Edit feature. 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 Asset Fields...

Note in the Web UI this script is generally replaced by the Quick Edit feature. Simple script to allow you to set values on multiple Asset pane fields of multiple Computer or Device records at once. The Quick Edit feature in the Web UI supplants the need for this script, but it can be useful in KeyConfigure.

☑ 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 Lifecycle Stage from AD...

If you Disable computer records in AD rather than delete them, this script can be used to automatically move those corresponding (by name) records to a Dormant login state in AllSight.

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

☑ Set Replacement Date...

Set the Replacement Date on all or select batches of computers based on various criteria. This can be useful when used in conjunction with the Gather Warranty Dates script. For example, if both are run on schedules, this one can set the replacement date to warranty date +1 year automatically.

☑ Show Package Audit

          

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.