Posted on 28th January 2016 by Darren Wallace

Imagr 101: Workflows and Content

Hi All, and welcome back to our series on configuring Imagr.

Last time, we ran through the setup of the NetBoot image to use with Imagr.

This ‘part 4’ looks to cover populating the Imagr repo with content and building a workflow. ‘Part 5’ will look at some possible use cases for Imagr with the current popular management tools.

Key Facts

OS Used:                              OS X El Capitan (10.11.1)

Server App Used:                 5.0.15

Imagr Used:                           0.0.4

Recommended knowledge (but not required):

  • Apple NetBoot server configuration
  • AutoDMG
  • Auto[X]NBI (such as AutoCasperNBI or AutoImagrNBI)
  • Editing XML files (or OS X plist files)

I will often be using “Repo” as shorthand for “Repository” throughout this series.

UPDATE 28 January 2106:

Between writing this blog and publishing it, there have been a lot of updates to Imagr.

The current version is 1.0.1 and so I’d highly recommend using the latest version.

 

Step-By-Step: Adding Items into the Repo

Before we can configure a workflow with items, we need to add those items to the Repo.

1. On your Repo server, open up Finder and navigate to the location of your Imagr folder. In the example, this is located at /Volumes/Data HD/Imagr.

 

2. For the example, I will be using the following items:

a) “osx_updated_151022-10.11.1-15B42.hfs.dmg” – An AutoDMG created, unbooted OS image.b) “Enabled-Automatic-SUS.sh” – A shell script to enabled all the auto-update options in the ‘App Store’ section of System Preferences.

c) “Enable_VNC.sh” – Another shell script to enable VNC with some basic settings.

d) “001-outset-1.0.2.pkg” – An installation package to install the basic components of the Outset solution (see here for more information on Outset)

e) “002-Ouset-setupAssistant-1.0.pkg” – Another installation package that uses Outset to setup a profile on every boot to skip the iCloud setup request (see here for more information on SetupAssistantProfiler).

Please Note: In my screenshots, these installer packages are shown with spaces in the filenames. In practice these caused issues when trying to be retrieved from the web server Repo. I would strongly recommend removing all spaces in the filenames for disk images, installers and scripts you use with Imagr. To be honest, I’d recommended this as general good practice (as I’ve done in the past and forgotten when running through this screenshots)!

 

3. Drag these items into the relevant folders, within the Imagr directory, e.g. OS images into ‘images’, installers into ‘packages’ and scripts into ‘scripts’.

Imagr 101 blog - part 4 - blog pic 1

 

4. Next we need to move the imagr_config.plist file into the ‘workflow’ folder. You can create this from scratch, or grab the template version from the Imagr GitHub page. I have also put up a template configuration file in our GitHub here . This guide will be assuming you are using the Amsys template version, only as it contains all the relevant sections we’ll work through as part of this blog.

 

5. However you get your copy of “imagr_config.plist”, drag a copy into the ‘workflow’ folder in the Imagr directory.

Imagr 101 blog - part 4 - blog pic 3

 

Imagr 101 blog - part 4 - blog pic 3a

 

6. Right, once we’ve got this in place, we’re going to need to edit this using a plain text editor. Personally, I’d recommend TextWrangler but feel free to use your own favourite. Please do not use Microsoft Word, or TextEdit as these will do funny things to the file and break its functionality.

 

7. I’d suggest, once you’ve got your chosen editor installed, use the ‘right click’ > “Open With” menu item to open the file in this application.

Imagr 101 blog - part 4 - blog pic 4

 

8. You should see the contents of the file open and ripe for editing!

Imagr 101 blog - part 4 - blog pic 5

 

Step-By-Step: Configuring the imagr_config.plist

Still with me? Good, as this next section is going to have us hand-editing XML files and so might get a little heavy!

 

9. The first bit we need to change / add is the password key and value. This is the password that the technician would need to enter before the can view the Imagr workflows. To quote the wiki (here ):

“…designed to stop customers from accidentally imaging their computers, not to keep the crown jewels safe!”

 

This section needs to be within the initial dictionary (“<dict>”) tags, but outside any others (such as the ‘workflows’ keys). This is stored as a SHA hash within the plist. The example below was for ‘apple’ as the password so we need to change this!

Imagr 101 blog - part 4 - blog pic 6

 

10. Launch your Terminal application (located in /Application/Utilities/).

Imagr 101 blog - part 4 - blog pic 7

 

11. Run the below command, substituting the words “YOURPASSWORDHERE” with…well, your chosen password! I’ve used “apple123” in these examples.

python -c 'import hashlib; print hashlib.sha512("YOURPASSWORDHERE").hexdigest()'

Imagr 101 blog - part 4 - blog pic 8

 

12. You will get back the SHA hash of your password. This is on one line, but may wrap onto a second line in the GUI due to its length.

Imagr 101 blog - part 4 - blog pic 9

 

13. Highlight this and copy it.

Imagr 101 blog - part 4 - blog pic 10

 

14. Switch back to your imagr_config.plist, and highlight the hash that is already present. Ensure to not also select the two “string” tags on the same line (shown as “<string>” and “</string>”).

Imagr 101 blog - part 4 - blog pic 11

 

15. Now paste your SHA hash you copied from step 13, ensuring there are no spaces at the end of it. This will overwrite the old password with your new one.

Imagr 101 blog - part 4 - blog pic 11a

 

16. The next section we’ll move onto is ‘workflows’. This is an array of dictionary items, with each dictionary item a separate workflow. To keep things simple, we’ll stick with one workflow for this example.

Imagr 101 blog - part 4 - blog pic 12

 

17. Let’s start with the ‘name’ key. This is the name of the workflow as shown to the end user. As each workflow is its own dictionary item, there will be a ‘name’ key for each dictionary item. In the Amsys template, this has the value “Rename and image the Mac”. Find this in the template plist.

Please Note: Some XML editors will format keys within dictionaries and arrays in alphabetical order. As you can probably see with the Amsys template, this puts the ‘name’ key towards the bottom of the XML.

Imagr 101 blog - part 4 - blog pic 13

 

18. Edit this value to the chosen name for your workflow. This is the first thing your technician will see when picking a workflow to run. As with step 14, ensure to not remove the ‘string’ tags. In the example screenshots, I have changed this to “Rename, image with 10.11.1 and install outset”

Imagr 101 blog - part 4 - blog pic 14

 

19. Next is the ‘description’ key. As you can imagine, this is the description of the workflow. As per the ‘name’ key, this is unique to each workflow. In the Amsys template, this has the value “Deploys a 10.10.1 image and renames the device” and is above the ‘name’ value.

Imagr 101 blog - part 4 - blog pic 15

 

20. Edit this value to the chosen description for this workflow. This is the second thing your technician will see when picking a workflow to run, as it’s shown when the relevant workflow is selected (put not started). This is a similar behaviour to DeployStudio. As with steps 14 and 18, ensure to not remove the ‘string’ tags. In the example screenshots, I have changed this to “Deploys a 10.10.1 image, renames the device, installs Outset and sets up a boot script to disable the iCloud…”

Imagr 101 blog - part 4 - blog pic 16

 

21. Next is the (optional) restart_action key (more information) . This key tells the workflow what to do once its finished its other tasks. Options are ‘none’ (do nothing), ‘restart’ (set the target volume as the start-up disk and restart) and ‘shutdown’ (set the target volume as the start-up disk and shutdown). As per the ‘name’ and ‘description’ keys, this is a ‘per-workflow’ option. In the Amsys template, this has the value “restart” and is at the bottom of the XML file.

Imagr 101 blog - part 4 - blog pic 17

 

22. Change this as required. In the example screenshots, I have changed this to “shutdown”. If this key is missing, Imagr will use the default behaviour of ‘none’.

Imagr 101 blog - part 4 - blog pic 18

 

23. Next is the (also optional) bless_target key (more information). This key tells the workflow if it should set the target volume as the system boot disk. Options are ‘true’ (set the target volume as the start-up disk), and ‘false (don’t set the target volume as the start-up disk). As per the ‘name’ and ‘description’ keys, this is a ‘per-workflow’ option. In the Amsys template, this has the value “true” and is at the bottom of the XML file.

Imagr 101 blog - part 4 - blog pic 19

 

24. Change this as required (if you need to). In the example screenshots, I have left this as “true”. If this key is missing, Imagr will use the default behaviour of ‘true’.

Imagr 101 blog - part 4 - blog pic 20

 

25. So that’s the key options of the workflow as a whole configured and set. Don’t forget to save the file as you go! Next, we’ll look at the workflow ‘tasks’ that can be used to deploy our items we copied into the Repo, back in step 3. These are added into each workflow dictionary item, into another array under the ‘components’ key. This array, much in the same way as the ‘workflow’ array, is made up of dictionary items for each task. Told you this was going to get a little heavy!

Please Note: These will be run in the order specified so I would suggest an order something along the lines of:

  • ‘image’
  • ‘Computer Naming’
  • Any scripts and / or installers

See Component Ordering for more information.

Imagr 101 blog - part 4 - blog pic 21

 

26. First up, deploying an Image (more information ). This dictionary item will mount the disk image over HTTP / HTTPS and restore the data using ASR (Apple Software Restore).

imagr pic 1

 

27. This needs a full URL to the item, of the format:

“[HTTP or HTTPS]://[server address]/[path to item].dmg”

 

In the example, our disk image lives in the Imagr directory, in an ‘images’ folder:

Imagr 101 blog - part 4 - blog pic 23

 

28. As a result, in this example, the URL for this image will be:

 

Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.

imagr pic 2

 

29. Next one, computer name (more information). This dictionary item, left as-is and with no additional keys, will prompt the technician for the desired device name. If the technician doesn’t supply one, Imagr will try to pull the name from the current target volume and use this. If this doesn’t work, or is not possible (such as its blank or not set on the target volume) then it will set the name to blank.

imagr pic 3

 

30. You can add further options for using the device serial number, and preventing the technician from providing a name (and overriding other options), details of which can be found on the Imagr wiki. For this example, we’ll let the technician set the name.

 

 

31. Next, is the package task (more information). This dictionary item will grab a copy of the specified package, and either copy it locally to the target volume for installation on first boot (default behaviour), or will run it whilst booted to the NetBoot image.

Imagr 101 blog - part 4 - blog pic 25

 

32. In the same way as for the image task (step 29), this needs the URL path to the item in question. In our example, the first package we want to install lives in the Imagr directory, within the ‘packages’ folder:

Imagr 101 blog - part 4 - blog pic 26

 

33. As a result, in this example, the URL for this image will be:

 

Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.

Imagr 101 blog - part 4 - blog pic 27

 

34. By default, this will install the package on first boot. But what if you don’t want that behaviour? You can use the (optional) ‘first_boot’ key in your package task.

Imagr 101 blog - part 4 - blog pic 28

 

35. Change the value from ‘true’ to ‘false’ to have this specific installer package run within the NetBoot Image, onto the ‘target volume’.

Please Note: To use this option, any scripts within the specific installer package must work on a non-boot volume.

Imagr 101 blog - part 4 - blog pic 29

 

36. Package task fully configured! But my example had two installer package items and you may have even more. How do we get these to run too?

 

37. Firstly, I’d recommend keeping the items installed and configured by Imagr to a minimum, and instead use it to ‘boot strap’ a device into your management solution (more on that, in part 5).

 

38. However, taking off the Grinch hat, it can be done. Highlight the entire ‘package’ section, including it’s opening and closing ‘dict’ tags.

Imagr 101 blog - part 4 - blog pic 30

 

39. Add a line under the close ‘dict’ tag, and paste the copied ‘package’ task, thereby duplicating the full dictionary item.

Imagr 101 blog - part 4 - blog pic 30a

 

40. Repeat steps 32 to 35 for this new, second package task. In this example, I have added the “002-Outset-SetupAssistant-1.0.pkg” installer.

Imagr 101 blog - part 4 - blog pic 31

 

41. If you don’t have any installers you wish to run as part of this workflow, simply highlight the task as per step 38, and remove it, instead of copying it.

 

42. Next up, running scripts (more information ). Imagr can run scripts in one of two ways, embedded or from a URL. With an embedded script, the contents of the script live within the imagr_config.plist itself, and any ‘non-xml safe characters’ would need to be escaped. In my opinion, this is more work, with more potential to go wrong, and can make your imagr_config.plist file a little messy.

 

43. The second method works in pretty much the same way as the image and package tasks, and will pull the script from the Repo and run it.

Imagr 101 blog - part 4 - blog pic 32

 

44. In the same way as for the image task (step 29), this needs the URL path to the item in question. In our example, the first script we want to install lives in the Imagr directory, within the ‘scripts’ folder:

Imagr 101 blog - part 4 - blog pic 33

 

45. As a result, in this example, the URL for this image will be:

 

Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.

Imagr 101 blog - part 4 - blog pic 34

 

46. In the same way as the package task, by default, the script task will run the scripts on first boot. To override this behaviour, use the same “first_boot” key we used for the package task, in exactly the same way (steps 34 and 35).

Imagr 101 blog - part 4 - blog pic 35

 

47. Script task fully configured! But again, my example had two to run and you may have even more. How do we get these to run too? The same way as we did for the package tasks.

 

48. Highlight the entire ‘script section, including it’s opening and closing ‘dict’ tags.

Imagr 101 blog - part 4 - blog pic 36

 

49. Add a line under the close ‘dict’ tag, and paste the copied ‘package’ task, thereby duplicating the full dictionary item.

Imagr 101 blog - part 4 - blog pic 37

 

50. Repeat steps 44 to 46 for this new, second script task. In this example, I have added the “Enable-Automatic-SUS.sh” script.

Imagr 101 blog - part 4 - blog pic 38

 

51. If you don’t have any scripts you wish to run as part of this workflow, simply highlight the task as per step 48, and remove it, instead of copying it.

 

52. Quit your text editor and save the edited file.

Imagr 101 blog - part 4 - blog pic 39

 

53. That completes the configuration of the imagr_config.plist.

 

Step-By-Step: Validating the plist and testing the URLs

So we’ve got your workflow plist file configured, but we’ve made a lot of manual changes. How can we test these changes are good? The Imagr GitHub has you covered using the ‘validateplist’ tool.

 

54. Download the latest releases DMG, or clone the GitHub repo to your local machine, or navigate to the GitHub page in a web browser (https://github.com/grahamgilbert/imagr) and download a Zip of the repo.

Imagr 101 blog - part 4 - blog pic 40

 

55. Un-zip the download so you can access the files. Find the ‘validateplist’ tool in the Finder.

Imagr 101 blog - part 4 - blog pic 41

 

56. Launch the Terminal application (/Applications/Utilities/) and drag the ‘validateplist’ tool into the Terminal window. This will complete the full path to the tool.

Imagr 101 blog - part 4 - blog pic 42

 

57. Find your imagr_config.plist in the Finder, and drag this in after the ‘validateplist’ tool, leaving a single space in between. Hit enter to run the tool.

Imagr 101 blog - part 4 - blog pic 43

 

Imagr 101 blog - part 4 - blog pic 44

 

58. You should get a message to say “SUCCESS: [path to plist] looks like a valid Imagr configuration plist.”

Imagr 101 blog - part 4 - blog pic 45

 

59. If you see any errors or failures, the tool will tell you what part of the configuration file it doesn’t like. The tool will check for items such as:

a) Is the plist a valid XML file?

b) Is it using options that are known to Imagr?

c) Does each built in task have all the required keys?

It will not check if the URLs you have provided are valid and correct, but it’s a good and fast initial check of your configuration plist file.

 

60. If your Repo is live and accessible, you can also swap out the file path we grabbed in step 57 with the full URL to the imagr_config.plist, like so:

Imagr 101 blog - part 4 - blog pic 46

 

61. So your plist file is good, but what about all those URLs you specified in each task? Simply copy each URL out of the workflow task (without the tags) and paste into a web browser. If successful, the browser should be able to download the files.

Imagr 101 blog - part 4 - blog pic 47

 

Imagr 101 blog - part 4 - blog pic 48

 

Pre-testing complete. Now it’s time to run a full test!

 

Step-By-Step: Full Testing!

The final section, full testing!

 

62. Grab a spare Mac, or a VM and NetBoot it to your Imagr NetBoot Image we created last time.

 

63. As before, eventually the Imagr local application will launch. This time it will ask you for the password, the same one we configured in steps 9 to 15. Enter this and click “Login”.

Imagr 101 blog - part 4 - blog pic 49

 

64. You will be greeted with the main workflow ‘chooser’ menu.

Imagr 101 blog - part 4 - blog pic 50

 

65. Use the “Choose Target” dropdown menu to select the storage volume you wish to run the workflow on. By default this will target the first non-booted volume, which typically would be the internal Hard Drive.

Imagr 101 blog - part 4 - blog pic 51

 

66. Use the “Choose Workflow” dropdown menu to select the workflow you wish to run. The name/s listed here are the ones we’ve set in step 18 above.

Imagr 101 blog - part 4 - blog pic 52

 

67. When you pick the workflow in step 66, the box below will show the description. This is what we set in step 19 above.

Imagr 101 blog - part 4 - blog pic 53

 

68. Once you’ve got your workflow and target selected, click “Run Workflow” to start things off.

Imagr 101 blog - part 4 - blog pic 54

 

69. The first task will ask you to specify a name for the computer (as we configured in step 26). Fill this in and click “Set Computer Name”.

Imagr 101 blog - part 4 - blog pic 55

 

70. The Imagr application will now work through the remaining steps. Restoring the OS image, installing packages and running scripts.

Imagr 101 blog - part 4 - blog pic 56

 

Imagr 101 blog - part 4 - blog pic 57

 

71. Once complete, the device will reboot (as per what we configured in step 21).

Imagr 101 blog - part 4 - blog pic 58

 

If your workflow reaches this far, then Congratulations! You’ve successfully got an Imagr lab configured and running! Go forth and play!

 

Summary

Congratulations you now have your Imagr solution lab image up and running and deploying Macs!

Next time, I’ll offer some specific use cases that I’ve come across for Imagr, as well as touching on some more advanced features and next steps.

As always, if you have any questions, queries or comments, let us know below and I’ll try to respond to and delve into as many as I can. I’m especially eager to hear any feedback on this new series.

The usual Disclaimer:

While the author has taken care to provide our readers with accurate information, please use your discretion before acting upon information based on the blog post. Amsys will not compensate you in any way whatsoever if you ever happen to suffer a loss/inconvenience/damage because of/while making use of information in this blog.