Chapter 4. Creating an Event
Table of Contents
There are many ways to create events. The best way to start with, and the recommended way, is to use the 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…
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: the What, the When, and the Why.
The What section details the actions that will occur if the event is performed. These actions might include shutting down, or running an application.
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.
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.
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.
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.
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.
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.
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.
The wake up action will wake a sleeping Mac. The Mac must be asleep for the wake up action to have any effect.
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.
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 selectingfrom the menu:
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:
Power Manager asks running applications to quit. This is done using a traditional AppleEvent; the Mac OS X equivalent of asking politely.
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.
Only after these two stages is Mac OS X's Finder asked to perform a traditional log out. This is the equivalent to selectingfrom the menu:
Power Manager will not directly quit or affect applications or processes located within the Mac OS X
/System folders. These applications are core to Mac OS X and assumed to be well behaved.
If an application located within
/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.
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 selectingfrom the status menu:
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.
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:
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.
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.
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.