dockutil – St. Ignatius College Prep Tech Blog

Use docklib to manage macOS docks

docklib instead of dockutil

I have a few posts about using dockutil to manage the macOS dock. dockutil is still a valid and working project, but I'm starting to migrate my scripts to docklib instead.

Installing docklib

The installation instructions for docklib say you can put the docklib.py file in the same directory as the scripts that invoke it or you can put it "in your Python path." I'd recommend just grabbing the docklib .pkg from the releases page or using the AutoPkg docklib recipes to download it. The .pkg puts docklib.py in /Library/Python/2.7/site-packages/docklib.py.

Using docklib with Outset

docklib can be used in an Outset login-once or login-every script. There is no need to explicitly put in a delay to wait for the initial dock to appear before running your script. There is also no need, if you're specifying a dock (rather than modifying an existing one) to remove the default applications Apple puts on the dock. If you're specifying a dock, just say what you want to add. Use this suggested template:

import os
from docklib import Dock
tech_dock = [
   '/Applications/Google Chrome.app',
   '/Applications/App Store.app',
   '/Applications/Managed Software Center.app',
   '/Applications/System Preferences.app',
   '/Applications/Utilities/Activity Monitor.app',
   '/Applications/Utilities/Console.app',
   '/Applications/Utilities/Disk Utility.app',
   '/Applications/Utilities/Migration Assistant.app',
   '/Applications/Utilities/Terminal.app',
]
dock = Dock()
dock.items['persistent-apps'] = []
for item in tech_dock:
   if os.path.exists(item):
      item = dock.makeDockAppEntry(item)
      dock.items['persistent-apps'].append(item)
dock.save()

Checking if an item exists before removing/adding via docklib?

Here's an example of checking for something's existence on the right side of the dock before adding it. To check on the left side, it's a very similar process, except you just replace

section='persistent-others'

with

section='persistent-apps'

For example, this will add Microsoft Word only if it's not in the dock already:

from docklib import Dock
dock = Dock()
if dock.findExistingLabel('Microsoft Word', section='persistent-apps') == -1:
   item = dock.makeDockAppEntry('/Applications/Microsoft Word.app')
   dock.items['persistent-apps'].append(item)
   dock.save()

If you add an item using docklib that already exists in the dock, a second instance of it will be added to the dock, so you definitely should check for the existence of the item first.

However, if you want to remove an item, just use the standard removal procedure:

from docklib import Dock
dock = Dock()
dock.removeDockEntry('Microsoft Word')
dock.save()

If the item isn't in the dock when you try to remove it, docklib won't give any error or warning.

Updating MS Office dock icons from 2011 to 2016 using dockutil

Managing client machines while also giving your users freedom to customize their machines as they want can be a bit tricky. On the one hand, you want to automate things as much as possible so users don't have to be bothered with too many update prompts and other maintenance nuisances. On the other hand, you don't want to automate things in a way that will confuse your users.

Jamie (our Dir. of IT) and I had a discussion about moving people from Microsoft Office 2011 to Microsoft Office 2016 and what that would look like. We didn't want to just uninstall Office 2011 right away, especially since it's the only thing MathType will reliably work with (in February, 2016, Design Science announced compatibility with Office 2016 for Windows, with a note that compatibility with Office 2016 for Mac would be coming "soon"—still hasn't come over a year later, as of this writing). And, even though installing Office 2016 side by side with Office 2011 makes 2016 the default for Office files, we wanted to update the Dock icons, so people would launch Office 2016 applications instead of Office 2011 ones.

These were the situations we thought we'd encounter:

User has MathType installed. If that's the case, we don't want to touch the Dock icons. We have only a handful of MathType users, and most of them have already installed Office 2016 (previously an optional install through Munki's Managed Software Center). Only one user asked about how to change the default application to be Office 2011's instead of Office 2016's.
User has only Office 2016 icons in the Dock. Nothing to do in this scenario, because everything's cool already.
User has a mix of Office 2016 and Office 2011 icons in the Dock. If both Word 2011 and Word 2016 are in the Dock, we're going to assume the user wants it that way, and we aren't going to mess with it. But if Excel 2011 and Excel 2016 are in the Dock but only Word 2011 is in the Dock, we want to switch that up to be Word 2016.
User has only Office 2011 icons in the Dock. If this isn't a MathType user, let's switch these all up for Office 2016.
User has no Office icons in the Dock. Leave it alone. If the user doesn't want shortcuts to Office, don't put any in there.

The tricky thing about changing up Office icons in the Dock is that dockutil goes by name or bundleid to add, and both the name and the bundleid is the same for Office 2011 and Office 2016 applications.

So I wrote up a script that checks based on the dockutil --list output to see if the Dock icon is for 2011 or not. It may not work exactly for your organization, but you can see the logic in there, and it's easily tweakable.

Putting Dockutil add/removes in arrays in Bash

Most of the time when you see scripts using Dockutil to add and/or remove items from the Dock in Mac OS X, they look like this:

/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP1.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP2.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP3.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP4.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP5.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP6.app' --no-restart
/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP7.app' --no-restart

That's totally fine to do, but I figured putting the additions and removals into arrays may be a cleaner way to manage things, so I wrote up a sample script for that.

There is an array of Dock items to remove and then an array of Dock items to add. Then it loops through all the removal items, makes sure each item already exists (no point in removing something that doesn't exist), and then removes it. Then the script loops through all the addition items, makes sure each item isn't already there (otherwise, Dockutil warns that you should using the --replacing option) and that the source item exists (otherwise, the non-existent item gets added as a question mark), and then adds it.

Using Dockutil with Outset to set user Docks on a Mac

Many people will find Dock Master a good tool to distributing docks to users. If you would prefer to use Dockutil with Outset and a login-once (or login-every) script, you may run into this issue:
Items are added but not always removed

Workaround #1

kcrawford (developer of Dockutil) has a workaround for this:

# Wait for a default dock
while ! /usr/local/bin/dockutil --list | grep Messages
do
/bin/sleep 1
done
# actual dockutil dock modifications here
# /usr/local/bin/dockutil --add ...

I've found that (at least in El Capitan), you can do fractions of seconds in sleep, so

/bin/sleep .25

works, and I'd recommend it. Either way, you may still have to wait a little bit before the Dock refreshes.

Workaround #2

I did quite a bit of experimenting (with the latest Dockutil and the latest El Capitan), and the way I got a login script with Dockutil to work is to

/usr/local/bin/dockutil --remove all

remove everything on the Dock, and then do individual additions

/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP.app' --no-restart

until you get to the last item and then do

/usr/local/bin/dockutil --add '/Applications/NAMEOFAPP.app' --no-restart

This will refresh the Dock twice, but that seems to be what works. If you do a --no-restart after the first command, you may not get everything actually removed.