Anthony’s Mac Labs Blog

Posted 2018 September 16

This article is archival. For more recent information, refer to my May 2019 post on the state of Microsoft AutoPkg recipes.

It’s been quite a week for those who deploy Microsoft Office, what with its bifurcation into Office 365/2019 and Office 2016 (perpetual). The Mac Admin community, as always, has been collaborating to determine what we need to do to make certain the people we support have the right version of this product for our licensing scheme. (Special thanks go to Paul Bowden of Microsoft for being very active in the #microsoft-office channel in the MacAdmins Slack to help us understand and manage this.) For AutoPkg users/recipe authors, that has meant determining what still works in our recipes and what needs tweaking to accomodate this new situation. I learned a lot about the variety of Office AutoPkg recipes that people use this week. This post is a first attempt at describing the recipes available and how they differ so that you might select the best recipe group for your immediate needs. I will not be discussing the Office 2011 recipes, as that product is no longer supported by Microsoft. As well, I am going to limit my scope to the .download and .pkg recipes available and will not try to dissect the type of Office installers that Microsoft offers—that would be a blog post on its own.^[1] If you are in a panic and/or don’t want to read the whole article, skip down to the What Do I Do? section.

Finding All The Recipes

Determining where all the recipes are for Office 365/2016/2019 and its component parts is non-trivial. For example, if you search for “Office” or “2016” in AutoPkg, your results are truncated because the GitHub API limits the list to 100 (as I mentioned in my previous blog post). You can search for individual Office components like Excel and get a manageable list, which then narrows down which repos might have the rest of the recipes you need. You’ll find three pools of recipes that act as parent recipes:

• The core AutoPkg recipes, found at github.com/autopkg/recipes in the MSOfficeUpdates folder;
• Rich Trouton’s recipes, found at github.com/autopkg/rtrouton-recipes in product-specific folders whose name starts with “Microsoft” or “Office”;
• Allister Banks’ recipes, found at github.com/autopkg/arubdesu-recipes in the 2016SuiteSKUless folder.

What you won’t find through a search (deliberately so, it seems) is this repo:

• github.com/arubdesu/office-recipes

As much as there are over 100 recipe repos included in the AutoPkg project, a number of people/institutions/enterprises still have private and/or public repos. Allister Banks chose to host early work on Office 2016 recipes in his own GitHub repos, and as I was an early adopter (and eventual small contributor), I added his repo to my AutoPkg workflow so that I could use the recipes therein. Until this week, these recipes worked perfectly well for my needs, so that is what I have been using. Because the autopkg/arubdesu-recipes and the arubdesu/office-recipes came from the same efforts originally, they use the same method (including the same custom processor) to download what you require. Thus, from here on in, I will treat them as a single method with two related implementations.^[2] That boils us down to three groups: the Core AutoPkg recipes, the arubdesu-recipes, and the rtrouton-recipes.

Default Behaviour

One of the reasons the conversations online have been so confusing is because people are having different problems depending on which set of recipes they are using. As a point of analysis, here is what you get today when you run the respective download recipes for PowerPoint using the recipe’s default Input key values:

So immediately we see a potential problem. The 16.16.2 version is the release for Office 2016 volume license customers and 16.17 is the Office 365 release. Without going into too much detail, volume and perpetual license customers who try to run 16.17 will find that the app goes into “Read Only” mode, with the only fix (before the new volume serializer is released on 2018-09-24) being to uninstall and reinstall 16.16.x. Conversely, Office 365 clients want 16.17, but that is not what the Core AutoPkg recipes generate.

Because both the arubdesu and rtrouton recipes use Microsoft's FWLink to determine what to download, you can change the override value to specify whether you want Office 365 (the default, regardless of what the recipe name is) or Office 2016 streams—the appropriate values are most easily found at macadmins.software. So here are the results when we ask explicitly for PowerPoint 2016:

We’ve now identified two more potential problems. The arubdesu recipes download the correct package, but the method the custom processor uses to determine the version number (that it appends to the filename) does not anticipate this new bifurcated feed, so it uses the number of the latest Office 365 version.

You may also note that there is a size difference between what the Core AutoPkg recipes download and what the other two do. That’s because they download two different things: the Core AutoPkg recipes download a full updater (what I would compare to a macOS Combo Updater in concept), the other two download a standalone installer. The Core AutoPkg recipes suggest that you should be able to download that standalone installer by setting the VERSION key in your override to "latest-standalone". When I tried this, AutoPkg reported a 404 Not Found error when trying to download the link that the recipe thought would be correct. I’ve filed this as an issue for now, since my research is showing that the recipe isn’t able to download any Office 365/2019 products, so I will leave it to the authors to decide the best course of action, which may involve a new set of recipes for Office 2019.

Finally, you’ll notice that the rtrouton download recipes don’t append the version number to the filename of the installer. Instead, they choose to do that in the .pkg recipe. There is actually a lot of interesting learning to be had from looking at these three sets of recipes and how they are constructed; I am planning a second post to do just that. But for now, let’s just assess what people can do to get AutoPkg working for their Office needs without waiting for any changes to existing recipes.

What Do I Do?

For those who want/need an immediate fix, the easiest path might be to manually download what you need from Microsoft — macadmins.software is a simple way to find the downloads you need. If you want the post-processing that AutoPkg provides, just run your recipe at the command line using the -p or --pkg option (e.g., autopkg run -p ~/Downloads/Microsoft_PowerPoint_16.16.18091001_Installer.pkg RecipeOfYourChoice.recipetype). I suspect all the recipes will work properly with the --pkg option, but I have not tested all the possibilities.

Nevertheless, since we are expecting Office version 16.18 in concert with Mojave, perhaps you want to avoid the manual work you’ll need to do in a week and are looking to make AutoPkg do your bidding again. Here are the main options, as I can determine them, for the different types of Office customers:

I want the standalone installer for Office 365 or its component apps

• The arubdesu-recipes and rtrouton-recipes can both do this now using default override settings.
• If you want versioning as part of the installer filename, use .download recipes for arbudesu-recipes or .pkg recipes for rtrouton-recipes.

I want the standalone installer for Office 2019 or its component apps

• The Office 365 installers and the Office 2019 installers are one and the same, so you would use the arubdesu-recipes or rtrouton-recipes using default override settings.
• If you are a volume license customer, make certain you are licensed for 2019 and that you do not upgrade from 2016 until the new volume license installer is released (2018 September 24).

I want installers for Office 2016 (perpetual or volume license) or its component apps

• The Core AutoPkg recipes appear to retrieve update installers just fine (you may encounter a problem with standalone installers).
• The rtrouton-recipes will retrieve the full installer and name the installer with the installer version if you change your override based on the FWLink values you can find on macadmins.software (e.g., set PRODUCTID to 871743 for the full Suite, 871751 for PowerPoint).
• The arubdesu-recipes will retrieve the full installer if you change your override based on the FWLink values you can find on macadmins.software (e.g., set REGION to 871743 for the full Suite, 871751 for PowerPoint). There is currently a bug where the filename of the installer will use the Office 365 version number (currently 16.17.0) instead of the actual version number of the installer downloaded (currently 16.16.2). If you want to manually fix this bug (assuming you don’t need Office 365 installers as well), you can open the OfficeSuiteSKULessVersionProvider.py custom processor in the same folder as the repo recipes (e.g., 2016SuiteSKUless folder) and replace 'o365' with 'vl2016' on Line 48. (If you do need both, you’ll probably just want to manually rename the file to match the actual payload.)

I want to update an already-installed version of an Office app

• Right now, the most reliable (and safest) method is to use Microsoft AutoUpdate (MAU). You may need to update either MAU or the app or both to get access to the very latest release, but it should not upgrade you to an incorrect track. (More discussion on this is available in the #microsoft-office channel in the MacAdmins Slack.)
• The Core AutoPkg recipes should work for Office 2016 perpetual/volume customers.
• Any full installer can also function as an updater (see above for instructions on full installers).

Caveat Lector

I developed this post because I saw a need and thought I could help. However, my scope is limited. I am very open to corrections, clarifications, and other suggestions. Contact me through the MacAdmins Slack (@jazzace) or on Twitter (@AnthonyReimer). I hope this helped some Admins navigate their Office AutoPkg situation better.

[1] The detailed article by Clayton Burlison from 2016 and the follow-up post from 2017 still have some very relevant information in this regard. You should also refer to the macadmins.software page to get information on all the current Suite and Standalone downloads. [Return to main text]

[2] It is completely possible to override the autopkg/arubdesu-recipes SKU-less recipes one or more times to download individual products, not just the entire suite, if you use macadmins.software to determine what the correct value for REGION should be (FWLink). Using the arubdesu/office-recipes just takes a little of the labour out of that for you, and adds access to some other management systems (.jss, .ds, .lanrev) without you having to write a child recipe. [Return to main text]