Automation

Created: Modified: Documentation

Introduction

GroundControl includes a powerful system to automatically select and deploy Workflows to devices based on pre-defined criteria. It works like this:

  1. You plug an iOS device into a GroundControl Launchpad.
  2. The Launchpad reads basic device information, including serial number, UDID, and model, and sends this information to the GroundControl server.
  3. The server uses the Automation Rules to determine which workflow(s) to deploy, if any.
  4. The server tells the Launchpad to deploy the specified workflow(s) sequentially.

For example, you can set up one workflow to deploy when an iPod is connected, and a different workflow for iPad.

Automation Indicator

When at least one automation rule is enabled, the navigation bar will display a check next to the Automation tab. This means a workflow may begin automatically when you connect a device.

Terminology

It’s helpful to understand several terms:

  • Rule: A set of one or more conditions to check, plus a set of one or more workflows to run. There’s a control so you can enable or disable each rule. You can give your rules names, like “Erase patient iPads.”
  • Condition: A single comparison that evaluates to true or false. For example, Device Name starts with “Nursing iPad”.
  • Built-in Attribute: Details for a device or launchpad that are maintained by GroundControl. For example, Device Serial, Device Erase State, Launchpad Name.
  • Custom Attribute: These are attributes you may create and maintain yourself. See Attributes.
  • Comparison: A way of comparing one value to another, for example Is, Is Not, Starts With, Contains.
Creating A Rule

1. Click on the Automation tab then on the “New Rule” button.

2. Enter a name for the Rule in the “Rule Name” field.

3. Click “Add condition” to select from the built-in attributes and custom attributesNote: each rule must have at least one condition.

4. Add a Comparison to the attribute, and fill in the right-hand side of the comparison when needed.

5. If desired, add additional conditions. Important: When you add multiple conditions, ALL MUST BE TRUE for the workflows to run.

6. Click “Choose Workflow…” and select a workflow to run when all conditions are true. Note: Each rule must have at least one workflow. 

7. Add additional workflows if you like. Unlike conditions, the order of workflows are important. You may arrange the workflows to execute in the desired order by dragging on the three-lined “ hamburger” icon.

To remove conditions and workflows, simply click the grey “Remove” button.

8. Finally, click the Save button.

Enabling and Disabling Rules

Rules are disabled by default. You can enable them by toggling the Enabled button to ON. This works in both the rule list and the rule editor.

Multiple Rules, Conditions, and Workflows

There are well-defined behaviors for handling multiple rules, conditions and workflows. GroundControl administrators should be familiar with the following.

Multiple Rules

  • Rules are examined one at a time, from top bottom. In other words, rules at the top of the list have a higher priority than rules at the bottom of the list.
  • If a rule does not match, GroundControl looks at the next rule down the list.
  • GroundControl never executes more than one rule for a single device. If a rule at the top of the list matches all conditions, then GroundControl stops evaluating.
  • The special rule All Other Devices is executed only if no other rules match.
  • If All Other Devices is disabled, and no rules match a device, GroundControl performs no action.
  • Since the order of rules is important, you can rearrange rules by dragging the “ hamburger” icon.

Multiple Conditions

  • When a rule has multiple conditions all conditions must evaluate true for the rule to match. There is an implicit AND between each rule.
  • New GroundControl users often long for a way to specify OR. For example, you may want both the Launchpad “Blue Surface” and the Launchpad “Red Surface” as conditions. Here’s the wrong way to do that:

This will never work because there’s no such thing as OR. GroundControl adds the word AND to these conditions. In other words, GroundControl interprets this as “Launchpad name is Blue Surface AND Red Surface.” Of course Launchpads can’t have two names.

As an alternative, you can create two rules. Better yet, use a custom attribute to “tag” these Launchpads, and begin unlocking the true power of GroundControl.

Multiple Workflows

  • In general, multiple workflows are not necessary. Keep all the actions in a single workflow, and GroundControl will execute them in the best order for dependable device operation.
  • Multiple workflows may be required when you wish to override GroundControl’s default behavior.
  • If you do use multiple workflows, the order of workflows are important. GroundControl will execute the listed workflows in order. You may arrange the workflows to execute in the desired order by dragging on the three-lined “ hamburger” icon.
  • If the first workflow fails, GroundControl will halt and not execute other workflows in the rule.
When are Rules Evaluated?

GroundControl typically evaluates rules when devices are plugged into a running Launchpad. But there are a few exceptions to this.

Launchpad is running, and device is plugged inRules are evaluated
Launchpad starts with devices attached, and Launchpad Monitoring is enabledRules are evaluated
Launchpad starts with Recovery devices attachedRules are evaluated
Launchpad starts with devices attachedRules are NOT evaluated
Launchpad restarts due to an updateRules are NOT evaluated
Built-In Conditions

ConditionExample
Device Battery LevelAny whole number from 1 to 100
Device Erased StateErased / Not Erased
Device Recovery ModeOn / Off
Device iOS9.3.5 / 10.3.1 / etc.
Device MAC Address00:00:00:00:00:00
Device ModeliPad / iPhone / iPod
Device Model (Detailed)iPad4,1 / etc.
Device NameAny text
Device SerialAAAA11A1A1AA / etc.
Device UDID111a1a111a11a1111111aa11a1aa111111a111aa / etc.
Launchpad NameAny text

Special Conditions

Most conditions accept free text in the right-hand side of the comparison. For advanced applications, it is also possible to use an attribute in that field. This is similar to how attributes can be used in workflows.

This technique is useful when tracking devices that may wander from one Launchpad to another, for example.

Please keep some limits in mind when using attributes in this way:

  • Only Launchpad attributes may be used on the right side
  • Enclose the attribute name within [square brackets]
  • The names are case sensitive.