Chapter 4. Creating an Event

There are many ways to create events. The best way to start, and the recommended way, is to use the Schedule Assistant.

Schedule Assistant

Power Manager includes a Schedule Assistant to help create task-based events. The Schedule Assistant provides a selection of task-orientated templates for you to choose from.

The Schedule Assistant is located in the Power Manager application. You begin using the Schedule Assistant by clicking the Add button () in the application, or by double-clicking on an existing editable event:

Power Manager > Add

Power Manager ready to create an event
Schedule Assistant tasks

Common Steps

Schedule Assistant's task templates are divided into steps. The Schedule Assistant walks you though each step gathering details about your desired task. At the end of the steps the Schedule Assistant creates the required events to schedule your task.

The Schedule Assistant typically separates the event into three sections:

  • What
  • When
  • Why

What Step

The What section details the actions that will occur if the event is performed. These actions might include shutting down, or running an application.

Schedule Assistant's What step determines the action

When Step

The When section details how the event is triggered. Most events created by the Schedule Assistant are triggered by a time and date, or after periods of inactivity.

Schedule Assistant's When step determines the trigger

Why Step

The Why section provides a opportunity to name and document your new event. Events can represent complex behaviours and the opportunity to include notes is essential to documenting your expectations. Notes can be useful when sharing events with others. The notes are stored within the event and will be visible to others using your event.

Schedule Assistant's Why step documents the purpose

Triggers

An event can be triggered in a range of ways. Let’s look at the most common methods used by the Schedule Assistant.

On a Specific Date and Time

The simplest trigger is on a specific date and time. An event can be created to trigger just once when a specific date and time occurs. Once that date and time has passed, the event will not be performed again by this trigger.

Regularly on a Specific Time

The daily trigger is a variation of the date and time trigger. Events can be triggered once a day on specific days. The specific days can be refined to include one or more days of the week.

If an event is set to trigger once a day, every day of the week, that event will appear only once in the pending trigger's list. Only once the event has been triggered, or the last trigger time has passed, will Power Manager calculate the next trigger date.

You can see this behaviour in action by cancelling a pending daily trigger. Notice that each time you cancel the trigger, the next day's trigger appears to replace it. Reset the trigger, and the original trigger date returns.

Only one trigger will appear in the pending list per event trigger.

After Inactivity

The inactivity trigger is used to allow events to occur based on the user's behaviour. Events can be triggered after periods of user inactivity. See the section called “A Better Inactivity Triggered Sleep”

An inactive computer is one where no user activity is taking place. User activity is the act of you, or someone else, actually interacting with the computer i.e. moving the mouse, typing on the keyboard, or using an input device such as a barcode scanner.

The inactivity counter starts accuring the second user activity stops.

Power Manager supports the creation of multiple inactivity triggered events. It is possible to have an event that an application or script after five minutes of inactivity, and a second event put the Mac to sleeps after 15 minutes of inactivity. As long an event's actions do not reset Mac OS X's inactivity counter, the following inactivity triggers will work as expected.

Some actions will reset Mac OS X's inactivity counter. These events include all the power events i.e. waking the computer from sleep. Scripts may also reset the inactivity counter if they simulate key presses or mouse movement.

The default behaviour of the inactivity trigger is to trigger, then wait for an equal period of inactivity before triggering again. This delayed repetition behaviour is important for events with constraints.

Consider an event that is triggered after five minutes of inactivity, and includes a constraint that stops the event if the screen is captured. If the event is triggered by inactivity and the screen is captured, then the next time the event will be triggered by inactivity will be in another five minutes i.e. at the intervals of five minutes, 10 minutes, 15 minutes, and so on until the screen is no long captured.

On Demand

The on demand behaviour is not a trigger but it is associated with how an event can be triggered. Many of the Schedule Assistant templates create events that support the on demand behaviour.

On demand is a behaviour of an event. Events supporting on demand behaviour can be triggered by the user at any time. On demand events appear in the status menu bar, and can be triggered through Power Manager's other interfaces such as AppleScript and the command line tool pmctl.

Criteria, Conditions, and Constraints

Event triggers are predictable, however they alone can not represent the broad range of situations where an event must, or must not, perform. To provide more flexibility events combine triggers with criteria.

When an event is triggered, the event's criteria is evaluated. Only if the criteria is met, will the event's actions be performed. This design allows for the use of lightweight predictable triggers in an event's creation. Once triggered an event can examine a range of conditions to determine if the actions should actually be performed.

The Schedule Assistant's constraints are combinatorial. All the constraints must be met before the event's actions can be performed.

Constraints

The Schedule Assistant creates an event's criteria based on your desired constraints. Constraints do not always map directly to event conditions and criteria; often the Schedule Assistant will perform a little translation to make the process of creating events easier.

Time Of Day

The time of day constraint restricts an event to performing within a given span of time each day. The range is provided as two times within a day's 24 hours. The times are inclusive.

If an event is triggered outside of the time range, then the event will not perform its events.

If an event is trigger within or on the boundary of the time range, then the event will perform its events.

The time range can be provided in two orders; the first order where the earlier time is provided before later time, and the second order where the later time is provided first.

If the times are provided earlier to later, for example 9:00 am - 5:00 pm, then the time period is understood as 9:00 am through until 5:00 pm on the same day.

However, if the times are provided later to earlier, for example 11:00 pm - 2:00 am, then the time period is understood to mean 11:00 pm through until 2:00 am, passing midnight and into the next day.

You can represent any range of times using this constraint.

Day of the Week

The day of the week constraint restricts an event to performing on specific days of the week. The constraint allows events to be restricted to one or more days each week.

Any combination of one or more days of the week is supported. The selected days of the week do not need to be contiguous, for example Monday, Wednesday, and Sunday is allowed.

Display is Captured in Full Screen

The display is captured in full screen constraint is useful for Macs used for playing movies, watching television, or showing presentations.

This constraint restricts an event from performing when an application has captured the main display for exclusive full screen use. The behaviour is call capturing because the capturing application gains exclusive use of the display.

This display capturing behaviour is common in media players such as QuickTime, Front Row, and iTunes when showing movies. The business applications, Keynote and PowerPoint both capture the main display when showing presentations.

Use this constraint to avoid your events putting your Mac to sleep or shutting down in the middle of a film or presentation.

Other Applications Requested Not to Sleep

Mac OS X applications can request that idle triggered sleep is denied. This behaviour is designed for applications that play movies or provide a service where no interaction is required, but where the Mac should be kept awake. If interaction is required, then the need to deny idle triggered sleep is not required.

Power Manager events can use this constraint to avoid putting the Mac to sleep while another application is asking for idle sleep to be denied. If some situations, ignoring the other application's request might be desirable.

The number of applications that support or use this behaviour are limited. We expect more applications to adopt this behaviour over the next few years as developers release updates to their products.

The ability for an application to affect idle triggered sleep in this corporative manner was introduced in Mac OS X 10.5, aka Leopard. This constraint has no effect on Mac OS X 10.4, aka Tiger.

Running Applications

Power Manager events can be constrained to performing only when specific applications are not running.

The running applications constraint allows an event to check if one or more listed applications are running. If any of these applications are running, then the event will not perform its actions.

This constraint is useful for limiting events to performing only when other critical applications are not running.

Where possible, try to use constraints and events that look for specific behaviours. The full screen being captured constraint is an example of a more specific constraint.

This constraint is useful but often too broadly applied to permit the best energy saving schedule. Be careful not to add applications that are always running to your event's constraints.

Actions and Tasks

The Schedule Assistant provides task templates to create events performing a range of actions. The actions and tasks available through the Schedule Assistant are discussed next.

These actions do not represent all the actions available to Power Manager; for a complete list see the Developer documentation. To create events using other actions, or events that chain together multiple actions together, learn more about Power Manager Professional.

Wake Up

The wake up action will wake a sleeping Mac. The Mac must be asleep for the wake up action to have any effect.

Power On

The power on action will power on a switched off Mac. The Mac must be switched off for the power on action to have any effect.

[Note] Hardware Limitations

Power Manager relies on the Mac's System Management Controller (SMC) to perform the wake up and power on actions. The SMC is a small piece of your Mac's circuitry that is always on. The SMC on modern Mac computers allows powering on at intervals of appropriately thirty seconds. Because of this interval, your Mac may wake up or power on slightly before or after the scheduled time.

If you are using a portable Mac, such as a laptop, your Mac must be connected to a power source to automatically power on. The behaviour and power limitations of recent MacBooks is reported to have changed, please check your hardware's capabilities before leaving your Power Manager schedule to run unattended.

If you are using a portable Mac, such as a laptop, your Mac must be open to automatically wake up and stay awake. Modern Mac's are not designed to wake automatically and stay awake while the lid is closed.

Sleep

The sleep action will put your Mac into a low power state called sleep.

This action will put your Mac into sleep mode regardless of other applications. Add constraints to your event to avoid interrupting critical tasks.

Power Manager's sleep action is equivalent to manually selecting Sleep from the Apple menu:

Apple Menu > Sleep

Log Out

The log out action will log out all logged in users. This includes Fast User Switched accounts.

Power Manager is designed to overcome applications that block log out requests. Applications block traditional log out requests by presenting dialogs and refusing to quit. This behaviour is not appropriate or desired when automating Macs.

Logging out is performed in three stages:

  1. Power Manager asks running applications to quit. This is done using a traditional AppleEvent; the Mac OS X equivalent of asking politely.

  2. After a short delay, if any applications are still running, the application is sent a more direct request to quit immediately. Well written applications rarely decline this second request.

  3. Only after these two stages is Mac OS X's Finder asked to perform a traditional log out. This is the equivalent to selecting Log Out… from the Apple menu:

    Apple Menu > Log Out…

Power Manager will not directly quit or affect applications or processes located within the Mac OS X /Library or /System folders. These applications are core to Mac OS X and assumed to be well behaved.

If an application located within /Library or /System blocks log out, this is a situation that needs your attention. Please see a Mac expert for help dealing with these applications.

Users connected remotely via ssh or other non-graphical sessions will not be logged out.

[Warning] Save Your Work

Whenever you leave your Mac unattended always save your documents and work.

Logging out will quit running applications that contain unsaved work. Unsaved work may be lost.

Power Manager provides notifications and warnings before performing actions that will discard unsaved work. If a pending event is going to interrupt a critical task, use the Power Manager status menu to adjust, delay, or cancel the pending event.

[Note] Automatically Saving

If you need to automate the process of saving work before logging out, consider creating a more sophisticated event using Power Manager Professional, or an alternative event creator.

A suitably written AppleScript inserted before the log out action could automatically save outstanding documents.

Fast User Switch

The Fast User Switch action will return to Mac to the Login Window. Any active user at the time of Fast User Switching will continue to be logged in, but no longer visible. To continue using the Mac, a logged in user will need to enter their log in details.

Any running applications will not be quit.

Power Manager's Fast User Switch action is equivalent to selecting Login Window… from the Fast User Switch status menu:

Fast User Switch > Login Window…

[Note] Securing an Inactive Mac

The Schedule Assistant includes a task template that offers an alternative to Mac OS X's Require a Password on Wake feature. Requiring a password on wake can cause problems and, while these problems are being addressed with each major Mac OS X update, it is still not suitable for all situations.

The Schedule Assistant's Secure Sleep template combines an inactivity trigger, with a Fast User Switch action and a sleep action. After a period of inactivity, the event will switch to the secure Login Window screen and put the Mac to sleep. When the Mac is later woken, a password is required.

Shut Down

The shut down action powers off the Mac.

Before powering off the Mac, this action will logged out all users. The shut down action uses the same process as the log out action to ensure a smooth shut down. This process ensures that running applications can not block the shut down sequence.

After logging out any users, the shut down action asks Mac OS X to shut down fully. Users logged in via ssh or remote non-graphical sessions are notified at this later stage.

Restart

The restart action powers off, and then immediately powers on the Mac.

The restart action matches the shut down action's behaviour. The restart action's behaviour only differs in the request to Mac OS X after logging out any users; Mac OS X is asked to restart immediately.

Launching Applications, Externals, and Documents

A Schedule Assistant task can launch an application, run an executable, or open a document.

Launch an Application

Applications are launched within the active user's session. The active user's session is the user who is logged in and visible on the display.

If no user is logged in and active, the application will not be launched.

If a user is logged in, but Fast User Switched, the application will not be launched.

Run an Executable

An executable is a file that has the UNIX executable flag set. You can use this action to run a wide range of command line tools and shell scripts.

Providing the Schedule Assistant with an UNIX executable (single file binary), will reveal additional options. These options allow you to control where the executable is executed.

An executable does not always require an active user. Thus Schedule Assistant provides the option to run the executable within a number of user environments, see the section called “Executable Environments”.

Open a Document

Providing the Schedule Assistant with a document changes the action's behaviour. When performed the provided document will be opened in the active user's session. The document will be opened as if it were double-clicked in the Finder.

You can provide a folder. If a folder is provided, the folder will be opened and displayed in the active user's Finder.

Run an Embedded Script

An event can include embedded scripts. When performed, the embedded script is written to disk, marked as executable, and executed. After executing the associated file is removed from the disk.

The embedded script can be executed with a number of environments with different credentials, see the section called “Executable Environments”.

The embedded script can be written in a wide range of languages. The language used to interpret the embedded script depends on the first line of script. This line must start with a hash-bang (#!) and absolute path to the interpreter.

The following interpreters are available on all recent distributions of Mac OS X:

  • /bin/bash
  • /bin/csh
  • /bin/ksh
  • /bin/sh
  • /bin/tcsh
  • /bin/zsh
  • /usr/bin/perl
  • /usr/bin/python
  • /usr/bin/ruby
  • /usr/bin/osascript

Your events can include embedded AppleScripts by using the osascript interpreter. See Example 4.1, “Embedding an AppleScript”.

Example 4.1. Embedding an AppleScript

When providing an AppleScript, always set your embedded script to run within the Active User's environment. AppleScript typically requires access to Mac OS X's windowing system to run successfully.

#!/usr/bin/osascript

say “Hello from Power Manager"

tell application “Finder"
    activate
    display dialog “This is an embedded AppleScript"
end tell

Embedding scripts within an event is preferred to running an external copy of the same script. An embedded script has the benefit of being less fragile than an event relying on the existence of external files. An event containing embedded scripts can also be deployed more easily.

Mirror Files

The Schedule Assistant includes a task to mirror files and folders. The mirror task is provided to offer a basic back up solution.

The mirror task requires a source file or folder, and a destination folder, hard disk drive, or device. When performed the task copies the source files and folders to the destination folder or device.

This task uses /usr/bin/rsync (remote synchronise) to perform the copying (mirror). rsync will only copy files and folders than have changed. Any files or folders than have been removed from the source, will be removed from the destination.

The mirror task is provided to compliment your existing back up solution. The task is ideal for regularly mirroring particularly important selections of files and folders to an external hard disk drive.

Executable Environments

A few actions and tasks run external scripts and executables. The Schedule Assistant provides the option to run these executables within a selection of user environments. The environment you choose will depend on which user you want the executable to run as, and if the executable needs access to the graphical interface/window server.

The Schedule Assistant supports the following environments:

  • Active User: Running an executable as the active user will place the executable into the active user's environment. The executable will have access to Mac OS X's windowing system. Access to the windowing system is important for AppleScripts.

  • Current User (you): Running an executable as you will place the executable in a non-graphical environment with your credentials. You do not need to be logged in for the executable to be performed.

  • Super User (root): Running an executable as super user (root) will place the executable in a non-graphical environment with super user credentials. Be careful when using this environment; as super user the executable has unrestricted access to your Mac.