Auto-run a workflow when devices are connected
A popular device management scenario is one in which the act of connecting an iOS device to a computer running device management software, will automatically trigger the restoration and formatting of the connected devices without requiring any user-interaction.
Such a scenario is possible using Apple Configurator 2, but requires some initial setup involving the Terminal application, the built-in “cfgutil” command-line utility, and a special set of Automator actions.
IMPORTANT: The attachment mechanism and tools provided here will work with both macOS Sierra, and macOS High Sierra. To use these tools with macOS High Sierra, install the provided attachment tools and actions after removing earlier versions of the Automator actions and command files that are incompatible with macOS High Sierra.
There are three elements of this automated scenario:
Here is how these elements are implemented to create an automated setup solution triggered when a device is connected to the host computer:
The “exec” Command
The Apple Configurator 2 built-in command-line utility “cfgutil” provides the “exec” command which will run an instance of a specified shell-script command whenever iOS devices are either attached or detached from the host computer.
The structure of the “exec” command, entered in a new Terminal window, follows a simple structure:
/usr/local/bin/cfgutil exec -a path/to/shell/script.command
The -a option is used to identify the shell command file to execute when a device is attached, and the -d option (not shown here) is used to run a specified shell command file when the device is detached from the computer.
The Shell-Script Command File
The Shell-Script Command File is basically a text file containing multiple lines of UNIX shell code that use the “automator” command to execute a specific workflow file.
The UNIX command file whose contents are shown below, auto-attachment.command, is placed in the Home > Library > Workflows folder when the installer is run.
In the command (line 7), the names and values of UNIX environment variables pertaining to the attached device are passed as input to the Begin Attach Workflow action, which then parses the passed string to retrieve the values, and write them to a property list file used to track the status of the attached device (line 10).
The default environment variables that are automatically set when a device is attached, are: $ECID, $PATH, $UDID, $attachPID, $deviceName, $deviceType, $buildVersion, $firmwareVersion, and $locationID.
You can compose a shell command file in any text editor such as BBEdit, TextWrangler, TextEdit, etc. and save it as a standard (non-RTF) text file with the “commmand” file extension. Once saved, you convert the text file into a executable command file by entering and running the following in a new Terminal window:
chmod +x path/to/shell/script.command
The Attachment Actions
During the process of being erased or restored, deices will often detach themselves from their host computer and reattach after completing a restoration or erasure.
On a computer running an “exec” attachment session in the Terminal, reattachment by a device will re-trigger the running of a desginated attachment workflow. In order to prevent a workflow from running repeatedly on the same device, use the Attachment Actions provided here, to track the status of devices and protect them from looping workflows.
To create a thread-safe workflow, simply begin the workflow with the “Begin Attached Workflow” action, and end the workflow with the “End Attached Workflow” action:
The “Begin Attached Workflow” action (v1.5)
Both of the attachment actions perform their functions by monitoring the contents of the “com.apple.configurator.AttachedDevices” folder located within the user’s Cache folder:
When a workflow beginning with the “Begin Attached Workflow” action is run, the action will first determine the ECID of the device that the workflow is targeting by reading the value of the $ECID environment variable. It then then checks the contents of the “com.apple.configurator.AttachedDevices” folder to see if it contains a property list file whose name matches the ECID of the attached device.
If the folder contains a matching property list file, the “Begin Attached Workflow” will stop the execution of its parent workflow, since it is assumed that the iOS device is still in mid-process and is re-attaching to the host computer thereby re-triggering its related workflow.
However, if there is no matching property list file, then the “Begin Attached Workflow” action will read the values for all of the environment variables and write the retrieved data into a new property file it creates within the “com.apple.configurator.AttachedDevices” folder. This created property list file is named using the ECID of the attached device.
The action view of the “Begin Attached Workflow” action contains three controls: (⬇ see below )
The “End Attached Workflow” action
Like the “Begin Attached Workflow” action, the “End Attached Workflow” action monitors the contents of the “com.apple.configurator.AttachedDevices” folder.
Since this action is placed at the end of a device-processing workflow, it is used to indicate that a device has completed processing. Therefore, it deletes the property list named for the ECID its receives as its input.
The action view of the “End Attached Workflow” action contains three controls: (⬇ see below )
NOTE: If no property list matching the passed ECID is found in the attached devices folder, this action will log an error message that will appear in the log displayed in the Terminal session window.
An archive is provided here for downloading that contains an installer applet for the two attachment actions and their related AppleScript scripts, as well as example command and workflow files.
DO THIS ► DOWNLOAD the installer for the attachment actions and related files, and then follow the these steps:
The “auto-attachment.command” and “auto-attachment.plist” files are provided in the Attachment Files folder in the installer folder. You can edit and install the “auto-attachment.plist” file to enable automatic attachment action whenever an iOS device is connected.
Auto-Launch Setup (Optional)
With Apple Configurator 2.2.1, you can now bypass the requirement for manually beginning a Terminal session for the cfgutil exec command, by creating and installing a Launch Services instruction file.
DO THIS ►In the provided Launch Services property list (auto-attachment.plist), change the placeholder to path to the Command File you are using (auto-attachment.command). After making the change, put the property list file in the LaunchAgents folder in the user Library folder. The process will load automatically at next login or can be toggled manually using the launchctl command
NEXT TOPIC: Workflow Recipes