Power Manager Terminology

Standard Suite #

Common classes and commands for all applications.

Classes

application #

The application's top-level scripting object.

Contents

connection / read and write

Connection to this computer.

Properties
  • name (text / read-only) The name of the application.
  • frontmost (boolean / read-only) Is this the active application?
  • version (text / read-only) The version number of the application.
Elements
Responds To

open

print

quit

document #

A document.

Properties
  • name (text / read-only) Its name.
  • modified (boolean / read-only) Has it been modified since the last save?
  • file (file / read-only) Its location on disk, if it has one.
Responds To

close

print

save

window #

A window.

Properties
  • name (text / read-only) The title of the window.
  • id (integer / read-only) The unique identifier of the window.
  • index (integer / read and write) The index of the window, ordered front to back.
  • bounds (rectangle / read and write) The bounding rectangle of the window.
  • closeable (boolean / read-only) Does the window have a close button?
  • miniaturizable (boolean / read-only) Does the window have a minimize button?
  • miniaturized (boolean / read and write) Is the window minimized right now?
  • resizable (boolean / read-only) Can the window be resized?
  • visible (boolean / read and write) Is the window visible right now?
  • zoomable (boolean / read-only) Does the window have a zoom button?
  • zoomed (boolean / read and write) Is the window zoomed right now?
  • document (document / read-only) The document whose contents are displayed in the window.
Responds To

close

print

save

Commands

open #

Open a document.

Direct Parameter

list of file / read and write (Required)

The file(s) to be opened.

Result

The opened document(s).

close #

Close a document.

Direct Parameter

specifier / read-only (Required)

the document(s) or window(s) to close.

Parameters
  • saving: save options / read and write (Optional)

    Should changes be saved before closing?

  • saving in: file / read and write (Optional)

    The file in which to save the document, if so.

save #

Save a document.

Direct Parameter

specifier / read-only (Required)

The document(s) or window(s) to save.

Parameters
  • in: file / read and write (Optional)

    The file in which to save the document.

print #

Print a document.

Direct Parameter

list of specifier / read and write (Required)

The file(s), document(s), or window(s) to be printed.

Parameters
  • with properties: print settings / read and write (Optional)

    The print settings to use.

  • print dialog: boolean / read and write (Optional)

    Should the application show the print dialog?

quit #

Quit the application.

Parameters
  • saving: save options / read and write (Optional)

    Should changes be saved before quitting?

count #

Return the number of elements of a particular class within an object.

Direct Parameter

specifier / read-only (Required)

The objects to be counted.

Parameters
Result
  • integer

The count.

delete #

Delete an object.

Direct Parameter

specifier / read and write (Required)

The object(s) to delete.

duplicate #

Copy an object.

Direct Parameter

specifier / read-only (Required)

The object(s) to copy.

Parameters
  • to: location specifier / read and write (Optional)

    The location for the new copy or copies.

  • with properties: record / read and write (Optional)

    Properties to set in the new copy or copies right away.

exists #

Verify that an object exists.

Direct Parameter

any / read-only (Required)

The object(s) to check.

Result
  • boolean

Did the object(s) exist?

make #

Create a new object.

Parameters
  • new: type / read and write (Required)

    The class of the new object.

  • at: location specifier / read and write (Optional)

    The location at which to insert the object.

  • with data: any / read and write (Optional)

    The initial contents of the object.

  • with properties: record / read and write (Optional)

    The initial values for properties of the object.

Result
  • specifier

The new object.

move #

Move an object to a new location.

Direct Parameter

specifier / read-only (Required)

The object(s) to move.

Parameters
  • to: location specifier / read and write (Required)

    The new location for the object(s).

Enumerations

save options #

  • yes Save the file.

  • no Do not save the file.

  • ask Ask the user whether or not to save the file.

printing error handling #

  • standard Standard PostScript error handling

  • detailed print a detailed report of PostScript errors

Records

print settings #

Properties
  • copies (integer / read and write) the number of copies of a document to be printed
  • collating (boolean / read and write) Should printed copies be collated?
  • starting page (integer / read and write) the first page of the document to be printed
  • ending page (integer / read and write) the last page of the document to be printed
  • pages across (integer / read and write) number of logical pages laid across a physical page
  • pages down (integer / read and write) number of logical pages laid out down a physical page
  • requested print time (date / read and write) the time at which the desktop printer should print the document
  • error handling (printing error handling / read and write) how errors are handled
  • fax number (text / read and write) for fax number
  • target printer (text / read and write) for target printer

Connection Suite #

Connection class for communicating with a Power Manager installation.

Classes

connection #

A connection.

Properties
  • name (text / read-only)
  • authenticated (boolean / read-only)
  • client (Client API / read-only) Host device details.

    The Scheduler provides a selection of host details to help identify and group clients.

  • time zone (Time Zone API / read-only) Local time zone details

    The time zone of the client is useful to know in order to present dates and times in an appropriate format for remote users.

  • power (Power API / read-only) Power source details.

    Power details the host computer’s power sources and each of those sources’ state. If the computer only supports AC/mains, there may not be any power sources.

  • authorisation (Authorisation API / read-only) Authorisation control for requests and functionality.

    Authorisation determines who can and can not access specific requests and functionality within the engine. By default, authorisation is tightly associated with the calling user’s role within the operating system.

  • astronomic (Astronomic API / read-only) Astronomical calculator.

    Calculations are performed using the Astronomic Algorithms Plus (AA+) library by PJ Naughter.

  • audio (Audio API / read-only) Device audio settings.

    Audio provides access to both the system default audio output device and the default audio device. Often these two devices will be the same.

  • event store (Event Store API / read-only) Stores, organises, and tracks events.

    Event Store is the storage of the Scheduler. All events are stored in Event Store.

    Use the Event Store to add and remove events. Event history is available for recently triggered or performed events.

    Changes to the contents of the Event Store will be reflected in the Scheduler and other Scheduler objects.

  • scheduler (Scheduler API / read-only) Coordinates the events, triggers, conditions, and actions.

    The Scheduler object is the core of Power Manager’s Schedule. All events, triggers, conditions, and actions are managed through the Scheduler.

    Use the Scheduler to add and remove events. The Scheduler provides requests to atomically set multiple events, and a request to disable all events from being triggered.

  • on demand (On Demand API / read-only) On demand events can be performed immediately.

    On Demand manages events that can be performed immediately. Determining events that can be performed immediately is not trivial, and this object exists to help isolate you from that task.

  • notifications (Notifications API / read-only) All pending events and their notifications.

    Notifications provides ordered lists of current, pending, and warning events and their triggers or actions.

    Notifications also provides requests to adjust events with time and date triggers. These triggers can be adjusted and cancelled through Notifications.

  • build (Build API / read-only) Scheduler meta-data.

    Build provides build details and control.

  • legal (Legal API / read-only) Legal and licensing details.
  • listen (Listen API / read-only) Configures and controls incoming network connections.

    Listen manages the push behaviour of the Scheduler.

    In a push environment, schedules are sent to the Scheduler from the server. The connection from server to Scheduler is instigated by the server as needed.

    Listen provides a means for configuring the Scheduler remotely.

Responds To

authenticate

Commands

authenticate #

Authenticate a connection.

Direct Parameter

connection / read and write (Required)

The connection to authenticate.

Result
  • boolean

Did the connection authenticate successfully?

Power Manager Suite #

Classes common to all Power Manager installations.

Classes

local workshop #

A workshop for creating, editing, and storing objects.

Elements
  • environment variable

    Environment variable.

  • resource limits

    Constraints for external processes.

    The engine can constrain the resources used by external processes. These resources are described in detail in the link below:

    http://www.opengroup.org/onlinepubs/009695399/functions/setrlimit.html

    Avoid setting constraints for external executables. macOS will provide adequate defaults.

  • external

    Description for executing an external process.

    external describes all the detail needed to execute an external process. The structure provides fine grain control over how an external process should be configured.

  • external executable

    Execute the external executable.

  • external inline

    Execute the inline content.

  • sample criterion

    Criterion for concluding a sample.

    sample criterion provide a set of constraints used to judge a sample. The criterion is applied to the sample’s window of collected data once the window is full; no evaluation occurs until enough samples have been collected to fill the window.

  • sample criterion equal

    Judge the samples looking for a positive match.

  • sample criterion not equal

    Judge the samples looking for a negative match.

  • external criterion

    Criterion for judging an external executable sample.

    When an external executable exits, a criterion is needed to judge what the executable’s result means. The best practice is to determine the result entirely on the exit code. This is fast and reliable.

    Alternatively, the last few kilobytes of the executable’s stdout or stderr can be interpreted or parsed for a numeric result.

    Where possible avoid using stdout or stderr, because the interpretation requires reading from disk. This will slow down sampling times.

  • external criterion interpret

    Interpret the output as a number.

    The output will be first intrepretted as a UTF8 string. The number should be composed of numeric values only.

    A decimal value is acceptable but be aware of assumptions regarding internationalisation. Not every locality uses spaces, commas, and decimal places 7in the same way.

    If both multiple sources are provided, the first valid numeric value is used. The sources are ordered: stdout, stderr. Thus if stdout and stderr both contains numeric values, the numeric value from stdout is used. Only if stdout does not contain a numeric value, is stderr intrepretted.

    Where possible avoid interpretting as criteria. It is better practice to return a boolean response using the exit code, or contains, criterion types.

  • external criterion contains

    Output contains a value.

    The output is interpreted as a UTF8 string.

    If both multiple sources are provided, every source is searched for the value. Only one source needs to contain the value.

    If the output contains the value, the sample is returned as 0 (zero) If the output contains the value, the sample is returned as 1 (one).

    Zero is used to indicate a successful match because zero equates to success for exit codes. The default sample criterion also uses zero as success.

  • sample

    Description for sampling.

    sample describes the constraints and criteria for sampling the environment and determining a result. sample provides a generic solution to a class of common situations that require near constant monitoring of external events.

  • sample execute external

    Sample from an external executable.

  • application description

    Description for launching an external process.

    external describes all the detail needed to launch an external process. The structure provides fine grain control over how an external process should be configured.

  • power source

    A power source.

    A power source is typically an internal or external battery or specialised power supply. Specialised power supplies include uninterruptible power supply (UPS) devices.

  • power source serial

    Power source connected via a serial cable.

  • power source USB

    Power source connected via a USB cable.

  • power source network

    Power source connected via a network connection.

  • power source internal

    Internal power source such as a fitted or removable battery.

  • power source unknown

    Unknown power source.

  • power source filter

    A profile for filtering power source changes.

    A computer can have multiple power sources. Power sources can be responsible for a wide range of properties changes and events. The ability to filter these changes is important to allow triggers and conditions to support specific situations involving specific power sources.

  • geolocation

    Geospatial location.

  • notification context value

    Notification context value.

  • process signature

    Process signature provides a robust means of identifying a running process.

  • process signature bundle identifier

    Match a process's bundle identifier.

  • process signature name

    Match a process's bundle or executable name.

  • process signature localised name

    Match a process's localised name.

  • trigger

    Description of an external event or potential change in state to watch.

    trigger describes an external event, such as a notification, or potential change in state, such as the Mac going to sleep, to watch.

    The engine uses triggers to trigger events.

  • trigger once

    Trigger once on a given time and date.

  • trigger daily

    Trigger at a given time on given days of the week.

    daily trigger will trigger when the time reaches seconds from midnight on the days provided.

  • trigger after inactivity

    Trigger after a given period of user inactivity.

    Trigger the event after the user has been inactive.

    Activity is a measure of user activity and not computer, process, or device activity. Inactivity is a measure of time since the user last interacted with an input device.

    This is not idle time but rather a more specific metric. If the mouse, keyboard, or other input device is in use, the user is not inactive.

  • trigger notification

    Trigger on receiving a notification.

    Notifications are messages sent by processes on a host. A notification can be sent by any process. That process can be owned by any user.

    The notification mechanism is built upon Apple’s CoreFoundation CFNotificationCenter implementation, and mirrored in Objective-C by NSNotificationCenter.

    Notification triggers are an easy way to trigger the engine and recommended for use by others looking to integration their solutions.

  • trigger power on

    Trigger when the computer powers on.

    The trigger will fire shortly after the computer has powered on from power off. Power off includes sleep and hibernate modes.

    The delay between powering on and the trigger firing will vary. The delay’s duration depends on how soon the engine is executed and is able to evaluate the runtime environment.

  • trigger start up

    Trigger when the computer starts up.

    The trigger will fire shortly after the host has started up. The start up trigger is fired shortly after the engine is executed. The engine compares the last start up trigger date with the last start up date. If the trigger date is more distant than the start up date, the trigger fires.

    The delay between starting up and the trigger firing will vary. The delay’s duration depends on how soon the engine is executed and is able to evaluate the runtime environment.

    Be careful when running executables that require the network or hardware resources. During start up many resources are being set up in parallel and may not yet be available.

    You should not expect network or hardware resources to be available immediately; check the environment. Consider using an alternative trigger in these situations.

  • trigger log in

    Trigger when a user logs in.

    The trigger will fire shortly after a user logs in. The trigger only responds to a user logging into the graphical interface as the primary console user.

  • trigger log out

    Trigger when a user logs out.

    The trigger will fire shortly after a user logs out. The trigger only responds to the primary console user logging out from the graphical interface.

  • trigger user session time

    Trigger when a user session reaches a specific age.

    The trigger will fire when a user session has existed for a specific time. The trigger begins counting when the user session begins and automatically stops when the user session ends.

  • trigger sleep

    Trigger when the computer is about to sleep.

    The trigger will fire when the operating system notifies processes that sleep is about to occur. This notification is an opportunity for hardware to idle and software to pause nicely.

    Avoid starting long running processes or tasks. Any process that lasts more than a second or two, may interrupt sleep or be interrupted by the sleep process.

    You should avoid using the sleep trigger.

  • trigger sample

    Trigger when a sample successfully concludes.

    The trigger will fire shortly after sample successfully concludes. Sample triggers provide a means of polling external executables for trigger situations.

  • trigger power state

    Trigger when the source of power changes.

    The trigger will fire when a power source’s state changes. This change will occur when one of the power source’s switches to AC/mains supply, to battery, goes off-line, or is disconnected.

    There may be multiple power sources. The trigger can filter which power source’s can trigger using the name field as a filter. By providing a previous and now state, the trigger can further filter the power source changes that initiate the trigger.

    A trigger without either a before or now state, will trigger whenever the power source state changes. A trigger with one or both the before and now state, will trigger only when those values are matched by the changing power source’s state.

  • trigger power remaining

    Trigger when the power remaining changes.

    The trigger will fire each time a power source’s current capacity or seconds remaining changes. The trigger’s fields provide a means of filtering the changes to specify specific conditions. These conditions might be to trigger only when a charging battery reaches 95% capacity, or when an internal battery is about to empty.

    An empty trigger will cause the trigger to fire every time a power source’s current capacity or seconds remaining changes.

  • trigger battery health

    Trigger when a power source's battery health changes.

    The trigger will fire when a power source’s battery health changes. This change will occur when one of the power source’s detects that its battery health has changed. Typically the health of a battery will decline in quality over time. As the health declines, so the live span of the battery is reduced.

    There may be multiple power sources. The trigger can filter which power source’s can trigger using the name field as a filter. By providing a previous and now state, the trigger can further filter the power source changes that initiate the trigger.

    A trigger without either a before or now state, will trigger whenever the power source state changes. A trigger with one or both the before and now state, will trigger only when those values are matched by the changing power source’s state.

  • trigger sun

    Trigger at a given angle of the Sun.

    sun trigger will trigger when the Sun reaches a specific angle on the days provided.

  • trigger external assistant

    Trigger when an external assistant changes.

    The trigger will fire each time a new external assistant checks-in with the scheduling engine. Typically this will happen shortly after a user log-in when the new user’s graphical session is available. Deprecated in v5.1.0; use log-in trigger.

  • trigger application

    Trigger when an application launches or quits.

    The trigger will fire when an application is detected as having launched or terminated. Detection occurs through OS X’s Launch Services and is limited to graphical applications.

    Applications launched from the command line, through forking, or other non-Launch Service pathways will not be detected.

  • trigger audio mute

    Trigger when an audio device mute state changes.

    audio mute triggers when an audio devices mute state changes to either muted or unmuted. Omitting a value for mute results in the trigger triggering each time the mute state changes.

  • trigger audio volume

    Trigger when an audio device's volume level changes.

    audio volume triggers when an audio device’s volume changes and the comparison is met. Omitting a value for the volume level results in the trigger triggering each time the volume changes.

  • condition

    Description of a testable condition that resolves to a boolean.

    Conditions are designed to be positive where a specific situation can be tested. A condition can more easily test for the existence of a running process or power assertion, than for the lack of these states.

  • condition boolean

    A constant condition.

    Used for testing compound conditions.

  • condition delayed boolean

    A delayed constant condition.

    Used for testing compound conditions. There is no reason to use this condition in deployed events. Where a constant condition is required, use the immediate edition of this condition, condition boolean.

    A delayed condition is one that does not respond immediately. The engine performs conditions in an optimised order to avoid testing expensive conditions; a delayed condition is expensive.

  • condition days

    Conditional on the day of the week.

    days tests the current day of the week is contained in days.

  • condition date range

    Conditional on the date falling within a specific period.

    date range provides a flexible means of testing if the current date falls within or without a specific period.

    Both not before and not after fields are optional. Inclusion of either, or both, allow the condition to represent the following tests:

    • now is before a specific date;
    • now is after a specific date;
    • now is within a specific date range;
    • now is not within a specific date range.
  • condition time range

    Conditional on the time now falling within a specific period.

    time range tests if the time now, falls between two provided times.

    The time range may cover two periods; spans between the two times within one day and spans between two times over two days. The period is determined by the order of the times.

    • 9am - 5pm = one day
    • 5pm - 9am = two days
  • condition execute external

    Conditional on the external executable's exit status.

    execute external launches an external process and waits for the process to exit. The exit status is used as the condition’s outcome.

    If the process exits successfully, by returning EXIT_SUCCESS, the condition is true. If the process exits with an error, or crashes, the condition is false.

    Try and avoid using condition execute external, the condition is expensive to run.

    Do not rely on a condition execute external to be tested. The engine will avoid calling expensive conditions where possible. The engine may test conditions at any time. Use an action if you need to launch an external process in a predictable manner.

  • condition sample

    Conditional on a sample's successful conclusion.

    Try and avoid using condition sample, the condition is expensive to run.

  • condition running processes

    Conditional on whether specific processes are running.

  • condition power assertions

    Conditional on whether other processes have power assertions set.

    Processes can request that the computer does not dim the display or sleep. These requests take the form of assertions.

    The power assertions ‘do not display sleep’ and ‘do not sleep’ are checked. If either assertion is set, the condition will be true.

  • condition power state

    Conditional on the computer's power source state.

    A power source may be using the mains power, battery power, be off-line, or be in an unknown state. This condition tests the current power sources and can be used to determine if the computer is connected to the mains power, or to a battery.

    Be aware that a computer can have multiple sources of power. Use the filter to restrict the power sources to test.

    Only one power source needs to match this condition in order to return true.

  • condition battery health

    Conditional on the battery health.

    The health of a battery backed power source can diminish over time. As the health declines, many power sources can provide a guide as to the battery’s current state. This condition allows you to create events that conditionally perform only if the battery’s health matches a given comparison.

    Consider using this condition to check the battery’s health when a user logs in, or before beginning a long running critical task.

    Not every battery will have corresponding health information. This information is provided by the battery itself and thus the existence of the health information is dependent on the manufacturer.

    Only one power source needs to match this condition in order to return true.

  • condition power remaining

    Conditional on the power remaining.

    Where both a current capacity and seconds remaining value are provided, both must be true for the condition to be evaluated as true.

    Where neither current capacity or seconds remaining are provided, no power sources will be matched, and the condition will always evaulate to false.

    Only one power source needs to match this condition in order to return true.

  • condition sun

    Conditional on the Sun's position being between two events.

    sun position tests if the Sun’s position, observed from given location on Earth, is between two astronomic events. Typically this condition is used to test if the date and time is during the day or night.

  • condition user inactivity

    Conditional on the period of user inactivity.

    inactive tests if the user has been inactive for a period of time. User inactivity is considered the time since any user last interacted with an input device. Input devices include mice, keyboard, and trackpads.

  • condition console user

    Conditional on a user being logged in.

    console user tests if a user is logged into the primary console. The primary console is typically the graphical interface for OS X.

  • condition start up

    Conditional on time since start up.

    start up tests if enough time has passed since the computer started up.

  • condition audio mute

    Conditional on an audio device being muted.

    audio mute tests if an audio device has been muted. Invert the condition to check if the device is not muted.

  • condition audio volume

    Conditional on an audio device's volume level.

    audio volume tests if an audio device has a given volume level.

  • criteria

    Group of conditions to test.

    Determine how conditions are evaluated.

    criteria groups conditions with a pass requirement. Through criteria the host’s environment can be tested.

    While the order of the conditions is maintained by the engine, the order does not affect the order in which conditions are tested. The engine may reorder the conditions at runtime to reduce the computation or time needed to reach the final outcome.

    Do not reply on conditions be tested at the time of triggering. The engine may perform conditions at any time.

  • action

    Task to perform.

    action describes a process or task to perform.

  • action sleep

    Put the computer to sleep.

    If the computer is powered on and awake, puts the computer into sleep mode. The next action will not be performed until the computer next wakes up or powers on.

    No running process can block sleep. This action mimics the user selecting sleep from macOS’s Apple menu.

  • action shut down

    Shut down the computer.

    If the computer is powered on and awake, shuts down the computer. The next action will not be performed until the computer next wakes up or powers on.

    The shut down process will quit all running applications and processes. Any logged in users will be logged out as part of the shut down process.

    An action warn must be performed before shutting down. This action may cause data loss where open documents contain unsaved changes.

  • action restart

    Restart the computer.

    The restart process will quit all running applications and processes. Any logged in users will be logged out as part of the restart.

    An action warn must be performed before restart. This action may cause data loss where open documents contain unsaved changes.

  • action log out

    Log out all users.

    Log out all active and fast switched users. User applications and processes with be automatically quit.

    An action warn must be performed before log out. This action may cause data loss where open documents contain unsaved changes.

  • action fast user switch

    Switch to the Login Window.

    Fast User Switch to the Login Window. The primary console user’s applications and processes will continue to run.

  • action notification

    Post a notification.

    Posts a notification to either the engine or the host. Notifications can be used to easily integrate the engine into other solutions.

  • action execute external

    Execute an external process.

    Executes an external process. By default the next action is performed immediately. Use the optional fields to alter the action’s behaviour after executing the process.

  • action launch application

    Launch an application.

    Launches an application. The next action is performed immediately after launching. The application description can be used to open and print documents.

  • action warn

    Warn users of imminent host affecting action.

    Notify active users of the host that an action is about to perform that will affect the host.

    warn inserts an entry in the Notifications’s warn queue. Interested clients observe this queue and display a prominent warning to users current active on the host.

    This action must be included before shut down, log out, restart, and other significant actions.

  • action await once

    Wait for a specific time and date to occur.

    The next action will not be performed until the specified time and date is reached.

  • action await daily

    Wait for a specific time and day to occur.

    The next action will not be performed until the specified time and day is reached.

  • action await relative date

    Wait for a period of time.

    The next action will not be performed until the specified period of time has passed.

  • action await user inactivity

    Wait for a period of user inactivity.

    The next action will not be performed until the specified period of user inactivity is reached.

  • action await notification

    Wait for a notification.

    The next action will not be performed until the specified notification is observed.

  • action await power on

    Wait for the computer to power on.

    The next action will not be performed until the computer next powers on.

  • action await start up

    Wait for the computer to start up.

    The next action will not be performed until the computer next starts up.

  • action await sleep

    Wait for the computer to sleep.

    The next action will not be performed until the computer is about to sleep.

  • action await sample

    Wait for a sample to conclude.

    The next action will not be performed if and until the sample concludes successfully.

  • action await log in

    Wait for a user to log in.

    The next action will not be performed until a user next logs in.

  • action await log out

    Wait for a user to log out.

    The next action will not be performed until a user next logs out.

  • action await user session time

    Wait for a user session to age.

    The next action will not be performed until a user session reaches a specific age.

  • action await battery health

    Wait for battery health to reach specific state.

    The next action will not be performed until the specified time and date is reached.

  • action await power state

    Wait for the source of power to change.

    The next action will not be performed until the power source changes.

  • action await power remaining

    Wait for the power remaining to change.

    The next action will not be performed until the power remaining changes.

  • action await sun

    Wait for a specific sun observation to occur.

    The next action will not be performed until a predicted sun observation occurs.

  • action await external assistant

    Wait for a change in the external assistants.

    The next action will not be performed until an external assistant changes.

  • action await application

    Wait for an application to launch or quit.

    The next action will not be performed until an application changes.

  • action audio volume

    Set the volume of an output audio device.

    Set the audio device’s volume. Typically, this is the master volume of the computer.

  • action audio mute

    Mute or unmute an output audio device.

    Set the audio device’s mute state.

  • event

    Event containing triggers to observe, conditions to test, and actions to perform.

    event is the core unit of the engine. events are self contained.

    event describes of a set of triggers to observe. When any one of these triggers fires, the criteria is tested. If the criteria is met at the time of triggering, the actions are performed in sequence.

    The unique ID of event is the structure’s key. When manipulating or tracking individual events, use this value.

  • queued trigger

    Queued trigger instance.

    queued trigger represents a specific instance of a trigger. Each queued trigger is derived from a trigger; the trigger is expanded were needed. Relative time triggers are queued as absolute date and time triggers.

  • queued warning

    Host wide warning.

    queued warning describes an imminent action that will affect the host and all active users.

    queued warning is generated by an action warning within an event’s actions.

  • event history

    Event history.

    A history of each event is kept. The history represents the behaviour of the event with a given unique ID. The history is maintained for as long as the event exists.

  • active event

    Active event instance.

    active event represents a specific instance of an event. The instance is being performed or is in the process of evaluating its criteria.

  • SSL

    A description of a SSL configuration.

  • socket

    A description of a TCP/IP socket.

  • URL options

    URL options.

    Options and settings to control how a URL is fetched.

  • source

    A description of a source.

  • authorisation right

    An authorisation right.

    An authorisation right sets out rules for access a request or function.

  • licence

    Active licence details for the Scheduler.

    Use state to determine if name and organisation contain useful details. Demonstration and expired licences rarely have useful name and organisation details.

Responds To

empty

environment variable #

Environment variable.

Properties
  • name (text / read and write) Name of the environment variable.
  • value (text / read and write) Value of the named variable.

resource limits #

Constraints for external processes.

The engine can constrain the resources used by external processes. These resources are described in detail in the link below:

http://www.opengroup.org/onlinepubs/009695399/functions/setrlimit.html

Avoid setting constraints for external executables. macOS will provide adequate defaults.

Properties
  • core size (integer / read and write) Largest size core file that may be created.

    In BSD’s setrlimit call this field maps to RLIMIT_CORE. core size is measured in bytes.

  • CPU time (integer / read and write) Maximum amount of CPU time to be used.

    In BSD’s setrlimit call this field maps to RLIMIT_CPU. CPU time is measured in seconds.

  • data segment (integer / read and write) Maximum size of the data segment.

    In BSD’s setrlimit call this field maps to RLIMIT_DATA. data segment is measured in bytes.

  • file size (integer / read and write) Largest size file that may be created.

    In BSD’s setrlimit call this field maps to RLIMIT_FSIZE. file size is measured in bytes.

  • memory lock (integer / read and write) Maximum size of memory that may be locked using mlock.

    The mlock function is used to lock physical pages of memory. This means those pages can not be swapped to disk by virtual memory.

    In BSD’s setrlimit call this field maps to RLIMIT_MEMLOCK. memory lock is measured in bytes.

  • number of files (integer / read and write) Maximum number of open files.

    Be careful limiting the number of open files an external process can open. Processes often need more files than even the developer expects. Open files include the three standard files:

    • standard in;
    • standard out;
    • standard error.

    Open files are also needed to make use of macOS frameworks and other linked-at-runtime resources. Use the command line tool lsof to examine what processes have what files open.

    In BSD’s setrlimit call this field maps to RLIMIT_NOFILE.

  • number of processes (integer / read and write) Maximum number of simultaneous processes for this user id.

    In BSD’s setrlimit call this field maps to RLIMIT_NPROC.

  • resident set size (integer / read and write) Maximum amount of physical memory.

    The maximum size to which a process’s resident set size may grow. This limits the physical memory provided to the external process but it does not restrict the virtual memory.

    In BSD’s setrlimit call this field maps to RLIMIT_AS / RLIMIT_RSS. resident set size is measured in bytes.

  • stack size (integer / read and write) Maximum size of the stack segment.

    In BSD’s setrlimit call this field maps to RLIMIT_STACK. stack size is measured in bytes.

external #

Description for executing an external process.

external describes all the detail needed to execute an external process. The structure provides fine grain control over how an external process should be configured.

Properties
  • type (external type / read and write) Type of external being described.
  • arguments (list of text / read and write) Arguments to pass to the executable.
  • user (text / read and write) User to execute process as.

    Short user name.

  • group (text / read and write) Group to execute process as.

    Short group name. If no group is provided, the primary group of the user is used.

  • root directory (text / read and write) Set the executable's root directory (chroot).
  • working directory (text / read and write) Set the executable's working directory (chdir).

    Relative paths are resolved with respect to any root directory.

  • redirect standard out (text / read and write) Redirect the executable's standard output (stdout) to a file.

    An absolute path to which the executable’s output to appended. The file is created as needed. Removing the file while the executable is running will cause undefined behaviour.

  • redirect standard error (text / read and write) Redirect the executable's standard error (stderr) to a file.

    An absolute path to which the executable’s error to appended. The file is created as needed. Removing the file while the executable is running will cause undefined behaviour.

  • process scheduling priority (integer / read and write) Set the executable's scheduling priority (nice).
  • throttle disk reads (boolean / read and write) Throttle the executable's disk reads.
  • file creation mode mask (integer / read and write) Set the executable's file creation mode mask (umask).
  • soft resource limits (resource limits / read and write) Set the executable's soft resource limits.
  • hard resource limits (resource limits / read and write) Set the executable's hard resource limits.
Elements

external executable #

Execute the external executable.

Inherits from external

Properties
  • executable (text / read and write) Absolute path to the executable.

    Executable to be executed as an absolute path to an existing file. The file must be readable and executable.

external inline #

Execute the inline content.

Inherits from external

Properties
  • inline (text / read and write) Inline content to write to disk and execute.

    inline is typically a shell script or other language.

  • encoding (encoding / read and write) Encoding format used by inline.

    Encoding is typically ‘UTF-8 no BOM’ but may be provided in another format.

sample criterion #

Criterion for concluding a sample.

sample criterion provide a set of constraints used to judge a sample. The criterion is applied to the sample’s window of collected data once the window is full; no evaluation occurs until enough samples have been collected to fill the window.

Properties
  • type (sample criterion type / read and write) Type of criterion to apply.
  • value (integer / read and write) Value to compare samples with.
  • result (boolean / read and write) Result to publish, if criterion is met.

sample criterion equal #

Judge the samples looking for a positive match.

Inherits from sample criterion

Properties

sample criterion not equal #

Judge the samples looking for a negative match.

Inherits from sample criterion

Properties

external criterion #

Criterion for judging an external executable sample.

When an external executable exits, a criterion is needed to judge what the executable’s result means. The best practice is to determine the result entirely on the exit code. This is fast and reliable.

Alternatively, the last few kilobytes of the executable’s stdout or stderr can be interpreted or parsed for a numeric result.

Where possible avoid using stdout or stderr, because the interpretation requires reading from disk. This will slow down sampling times.

Properties

external criterion interpret #

Interpret the output as a number.

Inherits from external criterion

The output will be first intrepretted as a UTF8 string. The number should be composed of numeric values only.

A decimal value is acceptable but be aware of assumptions regarding internationalisation. Not every locality uses spaces, commas, and decimal places 7in the same way.

If both multiple sources are provided, the first valid numeric value is used. The sources are ordered: stdout, stderr. Thus if stdout and stderr both contains numeric values, the numeric value from stdout is used. Only if stdout does not contain a numeric value, is stderr intrepretted.

Where possible avoid interpretting as criteria. It is better practice to return a boolean response using the exit code, or contains, criterion types.

Properties
  • source (external files / read and write) Sources to interpret.

    Output sources to interpret. Up to 16KB of content is retained from the external’s stdout and stderr stream. The content is taken from the final bytes output; much like the tail command line tool.

external criterion contains #

Output contains a value.

Inherits from external criterion

The output is interpreted as a UTF8 string.

If both multiple sources are provided, every source is searched for the value. Only one source needs to contain the value.

If the output contains the value, the sample is returned as 0 (zero) If the output contains the value, the sample is returned as 1 (one).

Zero is used to indicate a successful match because zero equates to success for exit codes. The default sample criterion also uses zero as success.

Properties
  • source (external files / read and write) Sources to search.

    Output sources to search. Up to 16KB of content is retained from the external’s stdout and stderr stream. The content is taken from the final bytes output; much like the tail command line tool.

  • value (text / read and write) Value to search for.

sample #

Description for sampling.

sample describes the constraints and criteria for sampling the environment and determining a result. sample provides a generic solution to a class of common situations that require near constant monitoring of external events.

Properties
  • source (source type / read and write) Source of samples.
  • initial delay (integer / read and write) Delay before sampling begins in seconds.
  • frequency (integer / read and write) Frequency of sampling in seconds.

    Duration between samples.

  • window (integer / read and write) Sample window to evaluate.

    The number of historic samples to use when determining if the criteria has been met. The window represents a collection of the latest samples gathered. As samples leave the window they are released and will not be used in any future evaluations.

    No evaluation will occur until enough samples have been collected to fill the window.

  • limit (integer / read and write) Seconds after sampling begins that it is stopped.

    Maximum duration of sample process.

    If the sampling has not reached a result and limit’s duration has passed since sampling begun, stop the sampling. Limit provides a time constraint on the sampling process.

Elements

sample execute external #

Sample from an external executable.

Inherits from sample

Properties
  • external (external / read and write) external to launch.

    Details of the external executable to launch.

  • external criterion (external criterion / read and write) Criterion to judge external executable by on exit.

application description #

Description for launching an external process.

external describes all the detail needed to launch an external process. The structure provides fine grain control over how an external process should be configured.

Properties
  • path (text / read and write) Absolute path to the application.

    If the application is a bundle, the path must refer to the top level of the bundle.

  • open (list of text / read and write) Absolute file paths to open.

    If the application path is omitted, each file is opened with the appropriate application.

  • arguments (list of text / read and write) Arguments to pass to the application.
  • user (text / read and write) User to execute process as.

    Short user name.

  • visibility (application visibility / read and write) Is the application visible after launch.
  • behaviours (list of application behaviour / read and write) Application behaviours.

    Behaviours affecting how the application is launched.

Elements

power source #

A power source.

A power source is typically an internal or external battery or specialised power supply. Specialised power supplies include uninterruptible power supply (UPS) devices.

Properties
  • type (power source type / read and write) Connection type of power source.
  • name (text / read and write) Name of the power source.
  • state (power state / read and write) Is the power source available and in use.
  • present (boolean / read and write) Is the power source present.
  • health (power health / read and write) Is the power source is good health.

    Power sources such as batteries degrade with age and use. Some power sources are able to detect this process and provide a guide as to the health of the battery.

  • confidence (power confidence / read and write) Is the health field accurate.
  • current capacity (integer / read and write) Current percentage capacity.
  • charging (boolean / read and write) Is the power source being charged.
  • seconds remaining (integer / read and write) Estimated seconds remaining until fully charged or empty.

    If the power source is being charged, the seconds remaining refer to the time remaining until fully charged.

    If the power source is being used, the seconds remaining refer to the time remaining until the power source is empty.

    This value may not be present for all power sources.

power source serial #

Power source connected via a serial cable.

Inherits from power source

Properties

power source USB #

Power source connected via a USB cable.

Inherits from power source

Properties

power source network #

Power source connected via a network connection.

Inherits from power source

Properties

power source internal #

Internal power source such as a fitted or removable battery.

Inherits from power source

Properties

power source unknown #

Unknown power source.

Inherits from power source

Properties

power source filter #

A profile for filtering power source changes.

A computer can have multiple power sources. Power sources can be responsible for a wide range of properties changes and events. The ability to filter these changes is important to allow triggers and conditions to support specific situations involving specific power sources.

Properties
  • transport type (power source type / read and write) Trigger only if the power source's type matches.

    Use this field to filter power sources by their connection to the host computer. By specifying a transport type of network, only changes to network connected power sources will trigger the trigger.

  • name (text / read and write) Trigger only if the power source's name matches.
  • comparison (comparison / read and write) How should the name be compared to the power source name.
  • options (list of comparison option / read and write) Comparison options allowing fine control over the comparison method.
  • charging (boolean / read and write) Trigger only if the power source's charging matches.

geolocation #

Geospatial location.

Properties
  • latitude (real / read and write) Latitude to calculate sun position from.

    Calculate sun position relative to this location on the planet.

  • longitude (real / read and write) Longitude to calculate sun position from.

    Calculate sun position relative to this location on the planet.

notification context value #

Notification context value.

Properties
  • name (text / read and write) Name of the value.
  • value (text / read and write) Value of the named variable.

process signature #

Process signature provides a robust means of identifying a running process.

Properties
  • type (process signature type / read and write) Type of process signature.

    A process can be identified using a range of methods. The type determines which method is used.

  • comparison (comparison / read and write) How should the process signature be compared.
  • options (list of comparison option / read and write) Comparison options allowing fine control over the comparison method.

process signature bundle identifier #

Match a process's bundle identifier.

Inherits from process signature

Properties
  • bundle identifier (text / read and write) Bundle identifier to compare to the process.

process signature name #

Match a process's bundle or executable name.

Inherits from process signature

Properties
  • name (text / read and write) Bundle or executable name to compare to the process.

    Name to compare against the process’s bundle name. If the process is not bundled, the name is compared to the process’s executable name.

process signature localised name #

Match a process's localised name.

Inherits from process signature

Properties
  • localised name (text / read and write) Localised name to compare to the process.

trigger #

Description of an external event or potential change in state to watch.

trigger describes an external event, such as a notification, or potential change in state, such as the Mac going to sleep, to watch.

The engine uses triggers to trigger events.

Properties
  • type (trigger type / read and write) Type of trigger being described.

trigger once #

Trigger once on a given time and date.

Inherits from trigger

Properties
  • date (date / read and write) Date and time to trigger.

    date can be any time and date in the past or future. Dates in the past are not useful but not invalid as values.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

trigger daily #

Trigger at a given time on given days of the week.

Inherits from trigger

daily trigger will trigger when the time reaches seconds from midnight on the days provided.

Properties
  • seconds from midnight (integer / read and write) Seconds past midnight to trigger.

    Trigger at this time each selected day.

    The trigger’s time is measured in seconds from midnight. Where 0 seconds equals midnight.

    Calculate seconds from midnight using the following formula:

    • seconds from midnight = (hours x (60 x 60)) + (minutes x 60)
    • 5:30 am = (5 x (60 x 60)) + (30 x 60) = 19800 seconds from midnight
    • 2:23 pm = (14 x (60 x 60)) + (23 x 60) = 51780 seconds from midnight
  • days (list of day / read and write) Days of the week to trigger.

    Trigger on these days of the week.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

trigger after inactivity #

Trigger after a given period of user inactivity.

Inherits from trigger

Trigger the event after the user has been inactive.

Activity is a measure of user activity and not computer, process, or device activity. Inactivity is a measure of time since the user last interacted with an input device.

This is not idle time but rather a more specific metric. If the mouse, keyboard, or other input device is in use, the user is not inactive.

Properties
  • seconds of inactivity (integer / read and write) Period of inactivity needed before triggering.

    seconds of inactivity is measured in seconds.

  • trigger limit (integer / read and write) Limit the frequency of repeating triggers.

    An inactivity trigger will fire whenever the inactivity timer is greater than the required seconds of inactivity field. If the event’s conditions postpone the event’s performance, the inactivity trigger is rescheduled and would to fire again immediately. The trigger limit provides a minimum number of seconds between inactivity triggers. Each trigger limit is applied per trigger instance.

    If the inactivity trigger has a value of 15 minutes, and a trigger limit value of 5 minutes, the event will triggered once after 15 minutes of inactivity and then every 5 minutes until activity occurs.

    If the trigger’s event is removed and added, or reset, the trigger limit’s behaviour is reset.

    If activity occurs, the trigger’s trigger limit behaviour is reset. If the inactivity trigger has a value of 15 minutes, and a trigger limit value of 30 minutes, the event will triggered once after 15 minutes of inactivity and then every 30 minutes. When activity occurs, the trigger limit will reset and the trigger will next fire after 15 minutes.

    The trigger limit is optional. If a value is not provided, the seconds of inactivity field is used instead. This behaviour provides the most commonly expected outcome.

    If a value of zero seconds is set, the inactivity trigger will not repeat until the inactivity timer has been reset.

trigger notification #

Trigger on receiving a notification.

Inherits from trigger

Notifications are messages sent by processes on a host. A notification can be sent by any process. That process can be owned by any user.

The notification mechanism is built upon Apple’s CoreFoundation CFNotificationCenter implementation, and mirrored in Objective-C by NSNotificationCenter.

Notification triggers are an easy way to trigger the engine and recommended for use by others looking to integration their solutions.

Properties
  • scope (scope / read and write) Observe notifications within this scope.

    Only notifications posted with the observed scope will cause the action to continue.

  • notification (text / read and write) Notification to observe.

    Process wide notifications are posted as strings. Notifications should follow a reverse domain name format to avoid namespace collisions.

Elements
  • notification context value

    Continue if notification's context contains this context.

    A notification can be accompanied by a context dictionary. If the action includes a context, only notifications matching the notification and containing the context will cause the action to continue.

trigger power on #

Trigger when the computer powers on.

Inherits from trigger

The trigger will fire shortly after the computer has powered on from power off. Power off includes sleep and hibernate modes.

The delay between powering on and the trigger firing will vary. The delay’s duration depends on how soon the engine is executed and is able to evaluate the runtime environment.

Properties

trigger start up #

Trigger when the computer starts up.

Inherits from trigger

The trigger will fire shortly after the host has started up. The start up trigger is fired shortly after the engine is executed. The engine compares the last start up trigger date with the last start up date. If the trigger date is more distant than the start up date, the trigger fires.

The delay between starting up and the trigger firing will vary. The delay’s duration depends on how soon the engine is executed and is able to evaluate the runtime environment.

Be careful when running executables that require the network or hardware resources. During start up many resources are being set up in parallel and may not yet be available.

You should not expect network or hardware resources to be available immediately; check the environment. Consider using an alternative trigger in these situations.

Properties

trigger log in #

Trigger when a user logs in.

Inherits from trigger

The trigger will fire shortly after a user logs in. The trigger only responds to a user logging into the graphical interface as the primary console user.

Properties
  • session type (user session type / read and write) Limit to user sessions of this type.
  • session age (integer / read and write) Ignore sessions older that this duration.

    Avoid triggering for user sessions that are older this a given age.

    This cut off exists to deal with slow log in times and restarting of the Scheduler
    mid-session.
    
    The default is appropriate for most situations and the session age should be left empty.
    

trigger log out #

Trigger when a user logs out.

Inherits from trigger

The trigger will fire shortly after a user logs out. The trigger only responds to the primary console user logging out from the graphical interface.

Properties

trigger user session time #

Trigger when a user session reaches a specific age.

Inherits from trigger

The trigger will fire when a user session has existed for a specific time. The trigger begins counting when the user session begins and automatically stops when the user session ends.

Properties
  • session age (integer / read and write) Trigger when the user session reaches this age.
  • session type (user session type / read and write) Limit to user sessions of this type.
  • wake up (boolean / read and write) Wake up the computer from sleep when the session time is due.
  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

trigger sleep #

Trigger when the computer is about to sleep.

Inherits from trigger

The trigger will fire when the operating system notifies processes that sleep is about to occur. This notification is an opportunity for hardware to idle and software to pause nicely.

Avoid starting long running processes or tasks. Any process that lasts more than a second or two, may interrupt sleep or be interrupted by the sleep process.

You should avoid using the sleep trigger.

Properties

trigger sample #

Trigger when a sample successfully concludes.

Inherits from trigger

The trigger will fire shortly after sample successfully concludes. Sample triggers provide a means of polling external executables for trigger situations.

Properties
  • sample (sample / read and write) Sample to run to evaluate the environment.

trigger power state #

Trigger when the source of power changes.

Inherits from trigger

The trigger will fire when a power source’s state changes. This change will occur when one of the power source’s switches to AC/mains supply, to battery, goes off-line, or is disconnected.

There may be multiple power sources. The trigger can filter which power source’s can trigger using the name field as a filter. By providing a previous and now state, the trigger can further filter the power source changes that initiate the trigger.

A trigger without either a before or now state, will trigger whenever the power source state changes. A trigger with one or both the before and now state, will trigger only when those values are matched by the changing power source’s state.

Properties
  • now (power state / read and write) New state of the power source.
  • before (power state / read and write) Previous state of the power source.
  • filter (power source filter / read and write) Power sources to monitor.

trigger power remaining #

Trigger when the power remaining changes.

Inherits from trigger

The trigger will fire each time a power source’s current capacity or seconds remaining changes. The trigger’s fields provide a means of filtering the changes to specify specific conditions. These conditions might be to trigger only when a charging battery reaches 95% capacity, or when an internal battery is about to empty.

An empty trigger will cause the trigger to fire every time a power source’s current capacity or seconds remaining changes.

Properties
  • capacity (integer / read and write) Trigger when a power source reaches or passes this capacity.

    Capacity reaches or passes this percentage.

    A power source’s capacity may not increase and decrease in single units. The current capacity value may jump a few percentage points at a time. The trigger will fire when the current capacity equals or passes this capacity value.

    If the power source is being charged, the trigger will fire if the capacity equals or is greater than this capacity.

    If the power source is being used, the trigger will fire if the capacity equals or is less than this capacity.

    The trigger will only fire when the power source reaches or passes this capacity value.

  • seconds remaining (integer / read and write) Trigger when a power source reaches or passes this duration remaining.

    Time remaining reaches or passes this duration.

  • filter (power source filter / read and write) Power sources to monitor.

trigger battery health #

Trigger when a power source's battery health changes.

Inherits from trigger

The trigger will fire when a power source’s battery health changes. This change will occur when one of the power source’s detects that its battery health has changed. Typically the health of a battery will decline in quality over time. As the health declines, so the live span of the battery is reduced.

There may be multiple power sources. The trigger can filter which power source’s can trigger using the name field as a filter. By providing a previous and now state, the trigger can further filter the power source changes that initiate the trigger.

A trigger without either a before or now state, will trigger whenever the power source state changes. A trigger with one or both the before and now state, will trigger only when those values are matched by the changing power source’s state.

Properties
  • now (power health / read and write) New health of the power source.
  • before (power health / read and write) Previous health of the power source.
  • filter (power source filter / read and write) Power sources to monitor.

trigger sun #

Trigger at a given angle of the Sun.

Inherits from trigger

sun trigger will trigger when the Sun reaches a specific angle on the days provided.

Properties
  • moment (astronomical sun event / read and write) Astronomical Sun event to calculate.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.

    Calculate Sun position relative to this location on Earth.

  • offset (integer / read and write) Offset from the calculated astronomical event.

    Offset the calculated time.

    Useful for creating triggers to occur some time before an astronomical event.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

trigger external assistant #

Trigger when an external assistant changes.

Inherits from trigger

The trigger will fire each time a new external assistant checks-in with the scheduling engine. Typically this will happen shortly after a user log-in when the new user’s graphical session is available. Deprecated in v5.1.0; use log-in trigger.

Properties

trigger application #

Trigger when an application launches or quits.

Inherits from trigger

The trigger will fire when an application is detected as having launched or terminated. Detection occurs through OS X’s Launch Services and is limited to graphical applications.

Applications launched from the command line, through forking, or other non-Launch Service pathways will not be detected.

Properties
  • process (process signature / read and write) Application to match.
  • change (application change / read and write) Change in application to detect.

trigger audio mute #

Trigger when an audio device mute state changes.

Inherits from trigger

audio mute triggers when an audio devices mute state changes to either muted or unmuted. Omitting a value for mute results in the trigger triggering each time the mute state changes.

Properties
  • mute (boolean / read and write) Trigger when mute matches this value.
  • audio device (audio device / read and write) Audio device to observe.

trigger audio volume #

Trigger when an audio device's volume level changes.

Inherits from trigger

audio volume triggers when an audio device’s volume changes and the comparison is met. Omitting a value for the volume level results in the trigger triggering each time the volume changes.

Properties
  • level (integer / read and write) Comparison master volume level to compare against.
  • comparison (numeric comparison / read and write) Method to compare the current volume with.

    How to compare the volume.

  • audio device (audio device / read and write) Audio device to observe.

condition #

Description of a testable condition that resolves to a boolean.

Conditions are designed to be positive where a specific situation can be tested. A condition can more easily test for the existence of a running process or power assertion, than for the lack of these states.

Properties
  • type (condition type / read and write) Type of condition to test.
  • invert (boolean / read and write) Invert the condition's conclusion.

    Conditions are designed to positively identify specific states. Many events will want a condition to confirm that a specific state is not occuring. To reverse the role of a positive condition, use the invert field.

    If a condition is true, and the invert field is set, the condition will invert the true and return false.

    If a condition is false, and the invert field is set, the condition will invert the false and return true.

condition boolean #

A constant condition.

Inherits from condition

Used for testing compound conditions.

Properties
  • can perform (boolean / read and write) Condition immediately resolves to this value.

    If can perform is true, the condition immediately resolves to true.

    If can perform is false, the condition immediately resolves to false.

condition delayed boolean #

A delayed constant condition.

Inherits from condition

Used for testing compound conditions. There is no reason to use this condition in deployed events. Where a constant condition is required, use the immediate edition of this condition, condition boolean.

A delayed condition is one that does not respond immediately. The engine performs conditions in an optimised order to avoid testing expensive conditions; a delayed condition is expensive.

Properties
  • can perform (boolean / read and write) Condition immediately resolves to this value.

    If can perform is true, the condition immediately resolves to true.

    If can perform is false, the condition immediately resolves to false.

condition days #

Conditional on the day of the week.

Inherits from condition

days tests the current day of the week is contained in days.

Properties
  • days (list of day / read and write) The day of week is one of the following.

    days is an unordered list of week days.

    If days contains Monday and Friday, only if the current day of the week is Monday or Friday will the condition resolve to true. If the current day of the week is Tuesday, Wednesday, Thursday, Saturday, or Sunday, the condition will resolve to false.

condition date range #

Conditional on the date falling within a specific period.

Inherits from condition

date range provides a flexible means of testing if the current date falls within or without a specific period.

Both not before and not after fields are optional. Inclusion of either, or both, allow the condition to represent the following tests:

  • now is before a specific date;
  • now is after a specific date;
  • now is within a specific date range;
  • now is not within a specific date range.
Properties
  • not before (date / read and write) The date is not before this date.
  • not after (date / read and write) The date is not after this date.

condition time range #

Conditional on the time now falling within a specific period.

Inherits from condition

time range tests if the time now, falls between two provided times.

The time range may cover two periods; spans between the two times within one day and spans between two times over two days. The period is determined by the order of the times.

  • 9am - 5pm = one day
  • 5pm - 9am = two days
Properties
  • not before (integer / read and write) The time is not before this time.
  • not after (integer / read and write) The time is not after this time.

condition execute external #

Conditional on the external executable's exit status.

Inherits from condition

execute external launches an external process and waits for the process to exit. The exit status is used as the condition’s outcome.

If the process exits successfully, by returning EXIT_SUCCESS, the condition is true. If the process exits with an error, or crashes, the condition is false.

Try and avoid using condition execute external, the condition is expensive to run.

Do not rely on a condition execute external to be tested. The engine will avoid calling expensive conditions where possible. The engine may test conditions at any time. Use an action if you need to launch an external process in a predictable manner.

Properties
  • external (external / read and write) External executable to run.

condition sample #

Conditional on a sample's successful conclusion.

Inherits from condition

Try and avoid using condition sample, the condition is expensive to run.

Properties
  • sample (sample / read and write) Sample to run.

condition running processes #

Conditional on whether specific processes are running.

Inherits from condition

Properties
Elements

condition power assertions #

Conditional on whether other processes have power assertions set.

Inherits from condition

Processes can request that the computer does not dim the display or sleep. These requests take the form of assertions.

The power assertions ‘do not display sleep’ and ‘do not sleep’ are checked. If either assertion is set, the condition will be true.

Properties

condition power state #

Conditional on the computer's power source state.

Inherits from condition

A power source may be using the mains power, battery power, be off-line, or be in an unknown state. This condition tests the current power sources and can be used to determine if the computer is connected to the mains power, or to a battery.

Be aware that a computer can have multiple sources of power. Use the filter to restrict the power sources to test.

Only one power source needs to match this condition in order to return true.

Properties
  • state (power state / read and write) Current state of at least one power source.
  • filter (power source filter / read and write) Power sources to monitor.

condition battery health #

Conditional on the battery health.

Inherits from condition

The health of a battery backed power source can diminish over time. As the health declines, many power sources can provide a guide as to the battery’s current state. This condition allows you to create events that conditionally perform only if the battery’s health matches a given comparison.

Consider using this condition to check the battery’s health when a user logs in, or before beginning a long running critical task.

Not every battery will have corresponding health information. This information is provided by the battery itself and thus the existence of the health information is dependent on the manufacturer.

Only one power source needs to match this condition in order to return true.

Properties
  • health (power health / read and write) Current health of at least one power source.
  • comparison (numeric comparison / read and write) Method to compare the battery health with.

    The health values are ordered from good (high) to failure (low). The unknown state always returns false.

  • filter (power source filter / read and write) Power sources to monitor.

condition power remaining #

Conditional on the power remaining.

Inherits from condition

Where both a current capacity and seconds remaining value are provided, both must be true for the condition to be evaluated as true.

Where neither current capacity or seconds remaining are provided, no power sources will be matched, and the condition will always evaulate to false.

Only one power source needs to match this condition in order to return true.

Properties
  • current capacity (integer / read and write) Current percentage capacity.
  • seconds remaining (integer / read and write) Estimated time remaining until fully charged or empty.

    Combine seconds remaining with a filter containing a charging value. A positive charging value indicates the power source’s seconds remaining are expected to increase. A negative charging value indicates the power source’s seconds remaining are expected to decline.

  • comparison (numeric comparison / read and write) Method to compare the current capacity and seconds remaining with.

    How to compare the capacity and time remaining.

  • filter (power source filter / read and write) Power sources to monitor.

condition sun #

Conditional on the Sun's position being between two events.

Inherits from condition

sun position tests if the Sun’s position, observed from given location on Earth, is between two astronomic events. Typically this condition is used to test if the date and time is during the day or night.

Properties
  • not before (astronomical sun event / read and write) The date is not before this Sun event.
  • not after (astronomical sun event / read and write) The date is not after this Sun event.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.

    Calculate Sun position relative to this location on Earth.

  • date (date / read and write) Date to calculate Sun position on.

    Optional date to use in Sun calculations. If omitted the current date will be used.

condition user inactivity #

Conditional on the period of user inactivity.

Inherits from condition

inactive tests if the user has been inactive for a period of time. User inactivity is considered the time since any user last interacted with an input device. Input devices include mice, keyboard, and trackpads.

Properties
  • seconds of inactivity (integer / read and write) Period of inactivity needed.

    seconds of inactivity is measured in seconds.

condition console user #

Conditional on a user being logged in.

Inherits from condition

console user tests if a user is logged into the primary console. The primary console is typically the graphical interface for OS X.

Properties

condition start up #

Conditional on time since start up.

Inherits from condition

start up tests if enough time has passed since the computer started up.

Properties
  • seconds (integer / read and write) Seconds elapsed since start up.

condition audio mute #

Conditional on an audio device being muted.

Inherits from condition

audio mute tests if an audio device has been muted. Invert the condition to check if the device is not muted.

Properties
  • audio device (audio device / read and write) Audio device to test.

condition audio volume #

Conditional on an audio device's volume level.

Inherits from condition

audio volume tests if an audio device has a given volume level.

Properties
  • level (integer / read and write) Comparison master volume level to compare against.
  • comparison (numeric comparison / read and write) Method to compare the current volume with.

    How to compare the volume.

  • audio device (audio device / read and write) Audio device to test.

criteria #

Group of conditions to test.

Determine how conditions are evaluated.

criteria groups conditions with a pass requirement. Through criteria the host’s environment can be tested.

While the order of the conditions is maintained by the engine, the order does not affect the order in which conditions are tested. The engine may reorder the conditions at runtime to reduce the computation or time needed to reach the final outcome.

Do not reply on conditions be tested at the time of triggering. The engine may perform conditions at any time.

Properties
  • requires (requires / read and write) Combination of required conditions.

    The combination of conditions that must pass or fail for the criteria to be met. conditions is manipulated as an unordered set.

    An empty conditions combined with requires resolves to the following:

    • empty conditions + requires all = criteria passes;
    • empty conditions + requires at least one = criteria fails;
    • empty conditions + requires none = criteria passes.

    conditions will be sorted by expense before being tested. The engine performs the lowest number of conditions possible to determine the criteria.

    If requires is all, the first condition that fails will cause any remaining conditions to be skipped; the criteria has not been met.

    If requires is at least one, the first condition that passes will cause any remaining conditions to be skipped; the criteria has been met.

    If requires is none, the first condition that passes will cause any remaining conditions to be skipped; the criteria has not been met.

Elements
  • condition

    Conditions to test.

    The engine will maintain the order of conditions.

action #

Task to perform.

action describes a process or task to perform.

Properties
  • type (action type / read and write) Type of action to perform.

action sleep #

Put the computer to sleep.

Inherits from action

If the computer is powered on and awake, puts the computer into sleep mode. The next action will not be performed until the computer next wakes up or powers on.

No running process can block sleep. This action mimics the user selecting sleep from macOS’s Apple menu.

Properties
  • seconds (integer / read and write) seconds to sleep before waking up.

    Time to sleep before waking up.

action shut down #

Shut down the computer.

Inherits from action

If the computer is powered on and awake, shuts down the computer. The next action will not be performed until the computer next wakes up or powers on.

The shut down process will quit all running applications and processes. Any logged in users will be logged out as part of the shut down process.

An action warn must be performed before shutting down. This action may cause data loss where open documents contain unsaved changes.

Properties

action restart #

Restart the computer.

Inherits from action

The restart process will quit all running applications and processes. Any logged in users will be logged out as part of the restart.

An action warn must be performed before restart. This action may cause data loss where open documents contain unsaved changes.

Properties

action log out #

Log out all users.

Inherits from action

Log out all active and fast switched users. User applications and processes with be automatically quit.

An action warn must be performed before log out. This action may cause data loss where open documents contain unsaved changes.

Properties

action fast user switch #

Switch to the Login Window.

Inherits from action

Fast User Switch to the Login Window. The primary console user’s applications and processes will continue to run.

Properties

action notification #

Post a notification.

Inherits from action

Posts a notification to either the engine or the host. Notifications can be used to easily integrate the engine into other solutions.

Properties
  • scope (scope / read and write) Who can observe the notification.

    A notification can be posted within a scope. The scope determines what processes can observe it. If the scope is engine wide, only the posting instance of the engine can observe the notification. This is particularly useful for chaining triggers to performing actions.

    If the scope is host wide, every process on the host can observe the notification.

  • notification (text / read and write) The notification to post.

    The notification should be formatted in reverse domain name format to avoid namespace collisions.

Elements

action execute external #

Execute an external process.

Inherits from action

Executes an external process. By default the next action is performed immediately. Use the optional fields to alter the action’s behaviour after executing the process.

Properties
  • external (external / read and write) external to execute.

    Details of the external executable to launch.

  • proceed (external continues / read and write) When to continue performing any remaining actions.

    When should any remaining actions be performed.

action launch application #

Launch an application.

Inherits from action

Launches an application. The next action is performed immediately after launching. The application description can be used to open and print documents.

Properties
  • application description (application description / read and write) application to launch.

    Details of the application to launch.

action warn #

Warn users of imminent host affecting action.

Inherits from action

Notify active users of the host that an action is about to perform that will affect the host.

warn inserts an entry in the Notifications’s warn queue. Interested clients observe this queue and display a prominent warning to users current active on the host.

This action must be included before shut down, log out, restart, and other significant actions.

Properties
  • seconds (integer / read and write) Seconds to display the warning.

    The warning will be active for this many seconds. While active the warning will appear in Notifications’s warning queue.

    Avoid including this value. A global default is used when this value is omitted. Administrators and users prefer consistent warning periods.

  • image (text / read and write) A Universal Image Identifer.

    image is a Universal Image Identifer (UII). The image may be used in association with the warning for any user interface.

  • message (text / read and write) Warning message.
Elements

action await once #

Wait for a specific time and date to occur.

Inherits from action

The next action will not be performed until the specified time and date is reached.

Properties
  • date (date / read and write) Date and time to trigger.

    date can be any time and date in the past or future. Dates in the past are not useful but not invalid as values.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

action await daily #

Wait for a specific time and day to occur.

Inherits from action

The next action will not be performed until the specified time and day is reached.

Properties
  • seconds from midnight (integer / read and write) Seconds past midnight to trigger.

    Trigger at this time each selected day.

    The trigger’s time is measured in seconds from midnight. Where 0 seconds equals midnight.

    Calculate seconds from midnight using the following formula:

    • seconds from midnight = (hours x (60 x 60)) + (minutes x 60)
    • 5:30 am = (5 x (60 x 60)) + (30 x 60) = 19800 seconds from midnight
    • 2:23 pm = (14 x (60 x 60)) + (23 x 60) = 51780 seconds from midnight
  • days (list of day / read and write) Days of the week to trigger.

    Trigger on these days of the week.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

action await relative date #

Wait for a period of time.

Inherits from action

The next action will not be performed until the specified period of time has passed.

Properties
  • seconds (integer / read and write) seconds to wait before continuing.

    Period of time to wait before continuing.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

action await user inactivity #

Wait for a period of user inactivity.

Inherits from action

The next action will not be performed until the specified period of user inactivity is reached.

Properties
  • seconds of inactivity (integer / read and write) Period of inactivity needed before triggering.

    seconds of inactivity is measured in seconds.

  • trigger limit (integer / read and write) Limit the frequency of repeating triggers.

    An inactivity trigger will fire whenever the inactivity timer is greater than the required seconds of inactivity field. If the event’s conditions postpone the event’s performance, the inactivity trigger is rescheduled and would to fire again immediately. The trigger limit provides a minimum number of seconds between inactivity triggers. Each trigger limit is applied per trigger instance.

    If the inactivity trigger has a value of 15 minutes, and a trigger limit value of 5 minutes, the event will triggered once after 15 minutes of inactivity and then every 5 minutes until activity occurs.

    If the trigger’s event is removed and added, or reset, the trigger limit’s behaviour is reset.

    If activity occurs, the trigger’s trigger limit behaviour is reset. If the inactivity trigger has a value of 15 minutes, and a trigger limit value of 30 minutes, the event will triggered once after 15 minutes of inactivity and then every 30 minutes. When activity occurs, the trigger limit will reset and the trigger will next fire after 15 minutes.

    The trigger limit is optional. If a value is not provided, the seconds of inactivity field is used instead. This behaviour provides the most commonly expected outcome.

    If a value of zero seconds is set, the inactivity trigger will not repeat until the inactivity timer has been reset.

action await notification #

Wait for a notification.

Inherits from action

The next action will not be performed until the specified notification is observed.

Properties
  • scope (scope / read and write) Observe notifications within this scope.

    Only notifications posted with the observed scope will cause the action to continue.

  • notification (text / read and write) Notification to observe.

    Process wide notifications are posted as strings. Notifications should follow a reverse domain name format to avoid namespace collisions.

Elements
  • notification context value

    Continue if notification's context contains this context.

    A notification can be accompanied by a context dictionary. If the action includes a context, only notifications matching the notification and containing the context will cause the action to continue.

action await power on #

Wait for the computer to power on.

Inherits from action

The next action will not be performed until the computer next powers on.

Properties

action await start up #

Wait for the computer to start up.

Inherits from action

The next action will not be performed until the computer next starts up.

Properties

action await sleep #

Wait for the computer to sleep.

Inherits from action

The next action will not be performed until the computer is about to sleep.

Properties

action await sample #

Wait for a sample to conclude.

Inherits from action

The next action will not be performed if and until the sample concludes successfully.

Properties
  • sample (sample / read and write) Sample to run to evaluate the environment.

action await log in #

Wait for a user to log in.

Inherits from action

The next action will not be performed until a user next logs in.

Properties
  • session type (user session type / read and write) Limit to user sessions of this type.
  • session age (integer / read and write) Ignore sessions older that this duration.

    Avoid triggering for user sessions that are older this a given age.

    This cut off exists to deal with slow log in times and restarting of the Scheduler
    mid-session.
    
    The default is appropriate for most situations and the session age should be left empty.
    

action await log out #

Wait for a user to log out.

Inherits from action

The next action will not be performed until a user next logs out.

Properties

action await user session time #

Wait for a user session to age.

Inherits from action

The next action will not be performed until a user session reaches a specific age.

Properties
  • session age (integer / read and write) Trigger when the user session reaches this age.
  • session type (user session type / read and write) Limit to user sessions of this type.
  • wake up (boolean / read and write) Wake up the computer from sleep when the session time is due.
  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

action await battery health #

Wait for battery health to reach specific state.

Inherits from action

The next action will not be performed until the specified time and date is reached.

Properties
  • now (power health / read and write) New health of the power source.
  • before (power health / read and write) Previous health of the power source.
  • filter (power source filter / read and write) Power sources to monitor.

action await power state #

Wait for the source of power to change.

Inherits from action

The next action will not be performed until the power source changes.

Properties
  • now (power state / read and write) New state of the power source.
  • before (power state / read and write) Previous state of the power source.
  • filter (power source filter / read and write) Power sources to monitor.

action await power remaining #

Wait for the power remaining to change.

Inherits from action

The next action will not be performed until the power remaining changes.

Properties
  • capacity (integer / read and write) Trigger when a power source reaches or passes this capacity.

    Capacity reaches or passes this percentage.

    A power source’s capacity may not increase and decrease in single units. The current capacity value may jump a few percentage points at a time. The trigger will fire when the current capacity equals or passes this capacity value.

    If the power source is being charged, the trigger will fire if the capacity equals or is greater than this capacity.

    If the power source is being used, the trigger will fire if the capacity equals or is less than this capacity.

    The trigger will only fire when the power source reaches or passes this capacity value.

  • seconds remaining (integer / read and write) Trigger when a power source reaches or passes this duration remaining.

    Time remaining reaches or passes this duration.

  • filter (power source filter / read and write) Power sources to monitor.

action await sun #

Wait for a specific sun observation to occur.

Inherits from action

The next action will not be performed until a predicted sun observation occurs.

Properties
  • moment (astronomical sun event / read and write) Astronomical Sun event to calculate.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.

    Calculate Sun position relative to this location on Earth.

  • offset (integer / read and write) Offset from the calculated astronomical event.

    Offset the calculated time.

    Useful for creating triggers to occur some time before an astronomical event.

  • availability (power / read and write) Should the host be made available for this trigger.

    Ensure the computer is powered on.

  • scatter (integer / read and write) Scatter the date.

    Randomly distribute trigger time.

  • quiet (boolean / read and write) Minimise the notifications.

    Reduce the notifications before the trigger occurs.

  • drift (integer / read and write) Acceptable drift.

    Additional time for the computer to be ready.

action await external assistant #

Wait for a change in the external assistants.

Inherits from action

The next action will not be performed until an external assistant changes.

Properties

action await application #

Wait for an application to launch or quit.

Inherits from action

The next action will not be performed until an application changes.

Properties
  • process (process signature / read and write) Application to match.
  • change (application change / read and write) Change in application to detect.

action audio volume #

Set the volume of an output audio device.

Inherits from action

Set the audio device’s volume. Typically, this is the master volume of the computer.

Properties
  • level (integer / read and write) Desired master volume level.
  • audio device (audio device / read and write) Audio device to set.

action audio mute #

Mute or unmute an output audio device.

Inherits from action

Set the audio device’s mute state.

Properties
  • mute (boolean / read and write) Desired mute state.
  • audio device (audio device / read and write) Audio device to set.

event #

Event containing triggers to observe, conditions to test, and actions to perform.

event is the core unit of the engine. events are self contained.

event describes of a set of triggers to observe. When any one of these triggers fires, the criteria is tested. If the criteria is met at the time of triggering, the actions are performed in sequence.

The unique ID of event is the structure’s key. When manipulating or tracking individual events, use this value.

Properties
  • unique ID (text / read and write) Unique identifier.

    A unique identifier for the event.

    We recommend the unique ID is set to a CoreFoundation UUID using its UTF8 string representation. This ensures the event’s unique ID is truely unique.

    The engine indexes events by unique ID.

  • domain (text / read and write) Domain unique identifier.

    Associated domain unique identifier.

    Every event is associated with a domain. The domain is identified using a unique identifier. This is called the domain ID is present in events returned by the engine. domain is read only. Any domain passed into the engine will be ignored.

  • enabled (boolean / read and write) Is the event available to be scheduled and performed.

    Setting enabled to true allows the engine to enqueue the event’s triggers.

    Setting enabled to false stops the engine from acting upon the event, even if the appropriate triggers fire.

  • name (text / read and write) Presentation name.

    Name of the event.

    name need not be unique, but we recommend it is. The name should convay the purpose of the event. Try to suggest or pick names that touch upon the cause or outcome of the event.

  • notes (text / read and write) Notes about this event's purpose.

    notes is provided to hold information about the event’s purpose, intent, creator, and any other miscellaneous details that may be useful to other users. No specific format should be expected.

  • image (text / read and write) A Universal Image Identifer respresenting the event.

    image is a Universal Image Identifer (UII). The image will be used is association with the event throughout the user interface.

  • tool (text / read and write) Owning tool in reverse domain name format.

    tool is the reverse domain named formatted identifier of the tool that created or last manipulated this event. Used to help tools identify which events they claim responsibility for. A tool with limited functionality might restrict itself to attempting to edit or show only events with a tool entry matching their own identifier.

  • behaviours (list of behaviour / read and write) Non-standard event behaviour.

    Behaviours affect how the event is performed and allow the event to take on non-standard responses to situations such as requests to idle sleep, and parallel triggers.

  • criteria (criteria / read and write) A criteria determining if the event performs.

    The criteria is tested after a trigger fires. Only if the criteria is met, will the actions be performed.

  • access rights (list of right / read and write) Caller rights for the event.

    Access rights lists what the caller can do to this event. The rights are specific to the caller. access rights is read only. Any access rights passed into the Scheduler will be ignored.

Elements
  • trigger

    Triggers determining when the event performs.

  • action

    Actions performed when the event is successfully triggered.

    List of actions performed in sequence after one of the’s event triggers has fired, and the criteria has been met.

queued trigger #

Queued trigger instance.

queued trigger represents a specific instance of a trigger. Each queued trigger is derived from a trigger; the trigger is expanded were needed. Relative time triggers are queued as absolute date and time triggers.

Properties
  • trigger ID (text / read and write) Unique trigger ID of the queued trigger.

    Each queued trigger instance is provided with a unique trigger ID. This identifier should be used to track and refer to the queued trigger.

    trigger ID has not related to any other unique ID values.

  • trigger (trigger / read and write) Derived trigger.

    The queued trigger may not match any trigger provided with the event. event triggers are transformed before being queued.

  • event (event / read and write) event associated with trigger.

    event to perform when the trigger fires.

queued warning #

Host wide warning.

queued warning describes an imminent action that will affect the host and all active users.

queued warning is generated by an action warning within an event’s actions.

Properties
  • date (date / read and write) date the action will perform.

    date will be a few seconds away. Interested clients should respond quickly the new queued warning instances.

  • action ID (text / read and write) Unique ID for this warning.
  • action (action / read and write) Action that will be performed.

    Warning clients should use action as the basis of any user facing message. message and context are provided by the event’s creator and may not be accurate.

    If action is missing, the action warning that generated this instance is the final action in the event’s actions.

  • event (event / read and write) event containing this action warning.
  • message (text / read and write) Warning message.
Elements

event history #

Event history.

A history of each event is kept. The history represents the behaviour of the event with a given unique ID. The history is maintained for as long as the event exists.

Properties
  • event ID (text / read and write) Unique identifier of the represented event.

    The event ID is included to help clients issuing multiple event history requests track responses.

  • last triggered (date / read and write) Date the event was last triggered.

    The most recent date the event was triggered. If an event has multiple triggers, this date refers to the most recent trigger.

    If last triggered is not present, the event has not been triggered.

  • last started (date / read and write) Date the event was last performed.

    The most recent date the event started performing. The event will perform if triggered, and then only if all the conditions are met. last started represents the date the trigger and conditions were successfully met.

    If last started is not present, the event has not been performed.

  • last finished (date / read and write) Date the event last finished performing.

    The most recent date the event finished performing.

    last started may be more recent than last finished. This can happen when an event may be performed concurrently; one instance finished while a second started slightly later and is still running.

    If last finished is not present, the event has not finished being performed.

  • trigger count (integer / read and write) Number of times the event has been triggered.

    An event may be triggered may times before its conditions are met. This value is incremented each time an event’s trigger is fired, regardless of whether any conditions are met.

  • perform count (integer / read and write) Number of times the event has been performed.

    Count of the number of times an event has been triggered, and any conditions are met.

    The count is incremented when the event’s performance begins.

active event #

Active event instance.

active event represents a specific instance of an event. The instance is being performed or is in the process of evaluating its criteria.

Properties
  • active ID (text / read and write) Unique ID of the active event.

    Each active event instance is provided with a unique ID. This identifier should be used to track and refer to the active event.

    active ID has no relation to any other unique ID values.

  • activity (event activity / read and write) Type of activity event is undergoing.
  • event (event / read and write) The event being performed or evaluated.

SSL #

A description of a SSL configuration.

Properties
  • keychain (text / read and write) Absolute path to Keychain containing a certificate and a signing key.

    SSL is an absolute path to a Keychain containing a suitable certificate and signing key for the socket.

    It is best practice to create a separate Keychain.

    To use the System keychain: /Library/Keychain/System.keychain

  • peer name (text / read and write) Override the name used for certificate verification.

    Provide an empty string to disable name verification.

  • allow (list of SSL allowances / read and write) Lessen the requirements of the SSL certificate.
  • level (SSL level / read and write) Level of SSL security to use.

socket #

A description of a TCP/IP socket.

Properties
  • unique ID (text / read and write) Unique identifier.

    unique ID must be unique within the immediate set of sockets. unique ID is used to identify a specific socket within a set and for reporting.

  • interface (text / read and write) Bind to which interface (hostname).

    interface is the hostname or IP address the socket binds to. An IP address is preferred as it avoids a domain name lookup. interface format must correspond to the protocol family.

    • To bind to the localhost with IPv4 use: ‘127.0.0.1’
    • To bind to the localhost with IPv6 use: ‘::1’

    Sockets can bind to all available interfaces by setting Interface to an empty string.

  • port (integer / read and write) port to accept incoming connections on.
  • protocol family (protocol family / read and write) Network protocol to use.

    To listen to both IPv4 and IPv6, create two sockets with a common port but listening to different protocols.

  • time out (integer / read and write) Seconds of silence before a connection times out.

    time out is the number of seconds a silent connection should wait before automatically disconnecting. A period of silence occurs when no information is being sent or received.

  • service (text / read and write) PAM service.
  • SSL (SSL / read and write) SSL configuration.
  • Bonjour domains (list of text / read and write) Bonjour domains.

    Bonjour domains enumerates the domains in which services are published. A socket may be published in multiple domains. Where no domains are listed, the default domains are used. Where an empty list is used, Bonjour is disabled. Bonjour is also known as ZeroConf.

  • options (list of socket options / read and write) Socket options.
  • URLs (list of text / read and write) URL to connect to this socket.
  • state (socket state / read and write) State of the socket.

URL options #

URL options.

Options and settings to control how a URL is fetched.

source #

A description of a source.

Properties
  • unique ID (text / read and write) Unique identifier.

    unique ID must be unique within the immediate set of source. unique ID is used to identify a specific source within a set and for reporting.

  • URL (text / read and write) URL of source.

    Absolute URL to source. URL is used to fetch the source’s configuration.

  • notes (text / read and write) Notes about this source.

    notes is provided to hold information about the source. notes should be used to describe why the source is listed, who manages it, and how to contact that person in case of problems.

  • options (URL options / read and write) Source URL specific options.
  • state (source state / read and write) State of the source.
  • fetched (date / read and write) Date of last successful fetch.

    Date and time of the last successful fetch of this source. If the source has not been successfully fetched, fetched will be excluded.

  • next (date / read and write) Date of next fetch attempt.

    Earliest date and time of the next fetch attempt. The source should be enqueued for fetching at this date, but fetching can occur later. next will not be included if the source has been suspended or has encountered problems during previous attempts.

authorisation right #

An authorisation right.

An authorisation right sets out rules for access a request or function.

Properties
  • signature (text / read and write) Unique signature of the right.

    The signature maps the authorisation right to the internal request or function being authorised. Typically the signature is a combination of the lowercase object name, a period, and the lower case request name.

  • rule (authorisation rule / read and write) Rule to enforce for right.

    The rule is applied when an attempt to access this right occurs.

  • default rule (authorisation rule / read and write) Default rule for right.

    The rule associated with a right may be changed. Being able to identify if the right has been changed and what the original right was is useful for debugging and restoring engines to their default state.

licence #

Active licence details for the Scheduler.

Use state to determine if name and organisation contain useful details. Demonstration and expired licences rarely have useful name and organisation details.

Properties
  • name (text / read and write) Name of the licenced contact.
  • organisation (text / read and write) Organisation licenced to use the Scheduler.
  • state (licence state / read and write) Licence state for the Scheduler.
  • expires (date / read and write) Date the Scheduler's demonstration period or licence expires.

    If state is licenced or expired, expires may be omitted.

Client API #

Host device details.

The Scheduler provides a selection of host details to help identify and group clients.

Properties
  • local host name (text / read-only) Computer's local host name.

    local host name is derived from the device name. The derived name is suitable for use as a URL and within the Domain Name System (DNS).

  • ethernet address (text / read-only) Primary ethernet address.

    A single ethernet address. Most likely to be the MAC address from the built-in ethernet card.

    The address is formatted as six groups of two digits in lowercase.

    • xx:xx:xx:xx:xx:xx
  • ethernet addresses (list of text / read-only) All ethernet addresses.

    A complete list of ethernet MAC addresses and wireless station IDs available.

    The list’s order is not specified and may change with each request.

    Each address is formatted as six groups of two digits in lowercase.

    • xx:xx:xx:xx:xx:xx
  • machine model (text / read-only) Machine's model type.

    The machine model is a unique identifer per device model type.

Time Zone API #

Local time zone details

The time zone of the client is useful to know in order to present dates and times in an appropriate format for remote users.

Properties
  • name (text / read-only) name

    Full name of the system time zone.

  • UTC offset (integer / read-only) UTC offset in seconds

    Seconds from UTC of the current system time.

Power API #

Power source details.

Power details the host computer’s power sources and each of those sources’ state. If the computer only supports AC/mains, there may not be any power sources.

Elements
  • power source

    Known sources of power.

    A computer may have multiple sources of power. Not all need be connected at any one time.

    Only major changes to power source state will trigger an observable update. This is a deliberate decision in order to reduce network traffic and avoid battery drain.

Authorisation API #

Authorisation control for requests and functionality.

Authorisation determines who can and can not access specific requests and functionality within the engine. By default, authorisation is tightly associated with the calling user’s role within the operating system.

Elements
  • authorisation right

    Defined rights.

    rights returns every authorisation right. The rights are used to control access to requests and functionality.

Responds To

apply right

Astronomic API #

Astronomical calculator.

Calculations are performed using the Astronomic Algorithms Plus (AA+) library by PJ Naughter.

Responds To

sun observation

Audio API #

Device audio settings.

Audio provides access to both the system default audio output device and the default audio device. Often these two devices will be the same.

Properties
  • system master volume (integer / read and write) Master volume of the default system output device.
  • system mute (boolean / read and write) Muted state of the default system output device.
  • volume (integer / read and write) Master volume of the default output device.
  • mute (boolean / read and write) Muted state of the default output device.

Event Store API #

Stores, organises, and tracks events.

Event Store is the storage of the Scheduler. All events are stored in Event Store.

Use the Event Store to add and remove events. Event history is available for recently triggered or performed events.

Changes to the contents of the Event Store will be reflected in the Scheduler and other Scheduler objects.

Elements
  • event

    Available events that can be triggered or performed.

    events contains a list of scheduled events. The list has no specific order, and the order may change with each request.

    When dealing with events, refer to specific events using the event’s unique ID.

Responds To

store

remove

history

Scheduler API #

Coordinates the events, triggers, conditions, and actions.

The Scheduler object is the core of Power Manager’s Schedule. All events, triggers, conditions, and actions are managed through the Scheduler.

Use the Scheduler to add and remove events. The Scheduler provides requests to atomically set multiple events, and a request to disable all events from being triggered.

Properties
  • enabled (boolean / read and write) Can events be triggered.

    If true, events can be triggered by their respective triggers. If false, no event will be triggered, regardless of triggers firing.

    Use enabled to effectively enable and disable the Power Manager Scheduler.

    When enabled is set to false, the Scheduler will continue to respond to requests and return information to clients. enabled only affects the triggering of events.

Elements
  • queued trigger

    Date and time based triggers with events.

    pending queued triggers include all triggers for which a time can be calculated. To appear in pending a trigger must belong to an active event, and the trigger’s date and time must be absolute.

    pending can include a single event multiple times, if that event has multiple time based triggers.

    pending is ordered by trigger time. The next event to be triggered is the first item in the list.

    pending can be altered using the adjust, cancel, and reset requests.

  • active event

    Active events.

    events whose criteria are being evaluated, or whose actions are being performed.

Responds To

cancel

adjust

reset

On Demand API #

On demand events can be performed immediately.

On Demand manages events that can be performed immediately. Determining events that can be performed immediately is not trivial, and this object exists to help isolate you from that task.

Elements
  • event

    Available on demand events.

    events supporting the on demand behaviour and are available to perform.

    To appear in this list an event must support on demand. The event must be immediately available to perform. The scheduler must be enabled; thus able to actually perform.

Responds To

perform

Notifications API #

All pending events and their notifications.

Notifications provides ordered lists of current, pending, and warning events and their triggers or actions.

Notifications also provides requests to adjust events with time and date triggers. These triggers can be adjusted and cancelled through Notifications.

Properties
  • warning period (integer / read and write) Seconds to display warnings.

    Seconds before a host affecting action that a warning should be presented.

    The warning is designed to provide the user with a reason for the shut down, sleep, or log out action that is taking place. It is not designed to replace the pending notification.

  • notify period (integer / read and write) Seconds to display notifications.

    Seconds before a queued trigger that a notification should be presented.

    Changing the notify period does not affect notifications issued for currently queued triggers.

Elements
  • queued trigger

    Notifying date and time based triggers with events.

    current queued triggers include all triggers for which can appear in pending, and have entered the notification period.

    current queued triggers should be presented to the user immediately upon appearing in the list. These triggers and their events are going to trigger soon, and the user needs to be kept informed. Typically the notification takes the form of a discrete dialog box or menu bar item update.

    current handles the work of calculating the notification period for each trigger and event. It is possible individual triggers and events can have differing notification periods. You should not attempt to calculate when specific triggers need notifying. Instead observe current and present notifications as queued triggers appear.

    A separate notification should be displayed to each user. If a user logs in within a notification period, and they have not previously seen the notification, immediately notify the user.

  • queued warning

    Warnings of host affecting actions.

    warning provides a list of critical queued warnings. warnings are used to notify the user to actions that will affect the host’s availability.

    Typically a warning will appear a few seconds before an event. You should immediately present a clear and vivid warning to the user. Remove the warning once the warning has been removed from this list.

Build API #

Scheduler meta-data.

Build provides build details and control.

Properties
  • version (text / read-only) Scheduler's release version.

    version is provided as a URI and three part release number. The Scheduler release number follows the traditional major, minor, and bug fix format.

    • The major value denotes significant changes, such as architectural modifications.
    • The minor value denotes new features or improvements.
    • The bug fix value denotes bug fixes only.

    Before presenting version, we recommend removing all but the final component of the URI. The URI is a reverse domain name styled string.

    • (product URI) v(major).(minor).(bug fix)
    • uk.co.dssw.powermanager.pmd v4.0.0
    • uk.co.dssw.powermanager.pnmd v4.0.0
  • revision (text / read-only) Scheduler's revision number.

    revision is the internal version used by the developers. The higher the revision value, the more recent the version of the Scheduler. revision is used to compare Scheduler versions.

    revision should rarely be displayed in the user interface. Where version information is being presented, use the value returned by version.

    The revision value may include a mix of numbers, letters, and punctuation.

Responds To

restart

Legal API #

Legal and licensing details.

Properties
  • licence (licence / read-only) Scheduler's licence details.

    licence details the state of the Scheduler and who, if anyone, holds a licence to use the Scheduler.

    Note licence does not include any private licence codes. Licence codes can not be retrieved once they are set; that is, licence codes are write only values.

Responds To

license

revoke

Listen API #

Configures and controls incoming network connections.

Listen manages the push behaviour of the Scheduler.

In a push environment, schedules are sent to the Scheduler from the server. The connection from server to Scheduler is instigated by the server as needed.

Listen provides a means for configuring the Scheduler remotely.

Elements
  • socket

    Sockets the Scheduler accepts incoming connections on.

    sockets contains a list of listening sockets. The list has no specific order, and the order may change with each request.

    When dealing with sockets, refer to a specific socket using that socket’s unique ID.

    The Scheduler can listen on multiple sockets for incoming connections. The Scheduler supports multiple simultaneous connections; requests are atomic. Each socket is independent of all other listening sockets.

Responds To

apply socket

remove socket

Class Extensions

application #

Power Manager's top-level scripting object.

Properties
Elements

Commands

empty #

Delete all objects from the workshop.

Direct Parameter

local workshop / read and write (Required)

The workshop to empty.

apply right #

Set a rule for a right.

apply right modifies a single right. Rights are indexed by their signature with one right per signature.

Direct Parameter

Authorisation API / read and write (Required)

Parameters
  • signature: text / read and write (Required)

  • rule: authorisation rule / read and write (Optional)

sun observation #

Calculate the time and date for an astronomical sun event.

Returns a date for the given event. An empty response will be returned when the event does not occur on the date at the location.

Direct Parameter

Astronomic API / read and write (Required)

Parameters
  • at: astronomical sun event / read and write (Required)

  • latitude: real / read and write (Optional)

  • longitude: real / read and write (Optional)

  • date: date / read and write (Optional)

Result
  • date

store #

Store zero or more events.

store adds an event to Scheduler’s events. If the event’s unique ID is unique, the provided event is added. If the event’s unique ID matches an existing event’s unique ID, the existing event is replaced by the provided event.

Use store to add and modify the Event Store’s events.

Calling store with an existing event’s unique ID, may cause the existing event to be removed and added, even if the provided event matches the existing event. The removal and addition can interrupt performing instances of the event.

Direct Parameter

Event Store API / read and write (Required)

Parameters
  • events: list of event / read and write (Optional)

  • replace existing: boolean / read and write (Optional)

remove #

Remove an event.

remove removes an event from the Scheduler’s events. Any performing instances of the event are stopped.

If the provided unique ID does not match an existing event’s unique ID, events is not affected.

Direct Parameter

Event Store API / read and write (Required)

Parameters
  • unique ID: text / read and write (Optional)

history #

Event history.

Get an event’s history.

Direct Parameter

Event Store API / read and write (Required)

Parameters
  • unique ID: text / read and write (Optional)

Result

cancel #

Cancel a pending queued trigger.

cancel cancels a pending queued trigger. Cancelling a queued trigger affects an instance of a trigger, not the trigger. If the date and time trigger can repeat, that is it calculates a relative date such as once-a-day, the next trigger date will be calculated and a new queued triggered will shortly appear in pending.

If the trigger repeats, providing an until date offers the ability to cancel more than one trigger instance. If no until parameter is provided, only the next instance of the trigger is cancelled.

To cancel a trigger for three days, you can provide cancel with an until date three days in the future, or you can call cancel on the appropriate queued trigger ID three times; note the queued trigger ID changes after each adjust, cancel, or reset request.

If the provided trigger ID does not match an existing queued trigger ID, no change occurs.

Direct Parameter

Scheduler API / read and write (Required)

Parameters
  • trigger ID: text / read and write (Optional)

  • until: date / read and write (Optional)

adjust #

Adjust a pending trigger date.

adjust replaces a pending trigger’s date and time.

adjust provides the ability to move a queued trigger’s date and time forward or backward in time. Use adjust to offer flexible schedules.

The provided date must be in the future.

If the provided trigger ID does not match an existing queued trigger ID, no change occurs.

Direct Parameter

Scheduler API / read and write (Required)

Parameters
  • trigger ID: text / read and write (Optional)

  • date: date / read and write (Required)

reset #

Reset a pending trigger.

reset removes any previous cancel or adjust requests applied to the pending trigger.

Resetting a previously cancelled repeating trigger will cause the trigger to immediately calculate the next trigger date. The date and time calculated will be relative to now, rather than when the cancel request was received.

If the provided trigger ID does not match an existing queued trigger ID, no change occurs.

If no trigger ID is provided, all modifications are reset and the associated triggers are requeued.

Direct Parameter

Scheduler API / read and write (Required)

Parameters
  • trigger ID: text / read and write (Optional)

perform #

Perform an event's actions.

perform immediately performs an event’s actions. The event must support the on demand behaviour, and not be constrained. Constraints include a single instance only event that is already running. The event must appear in the on demand variable’s contents.

Direct Parameter

On Demand API / read and write (Required)

Parameters
  • unique ID: text / read and write (Optional)

  • apply criteria: boolean / read and write (Optional)

restart #

Restart the Scheduler and associated processes.

Issues termination signals to the Scheduler’s associated processes in all user sessions. After the signals are sent, the Scheduler is stopped. launchd is responsible for relaunching.

Direct Parameter

Build API / read and write (Required)

license #

Append a licence to the Scheduler.

license appends the provided licence certificate to Scheduler.

The Scheduler can work with multiple licence certificates. A single licence may encapsulate a single feature or user right.

Direct Parameter

Legal API / read and write (Required)

Parameters
  • pem: text / read and write (Required)

revoke #

Remove all licence information.

Revokes the licence information stored by the Scheduler. Once revoked, the expiry and demonstration behaviour of the Scheduler will return. The stored revoked licences are unaffected and may be used again.

Direct Parameter

Legal API / read and write (Required)

apply socket #

Set a socket to listen for incoming connections on.

apply socket adds or modifies a single socket. Sockets are indexed by their unique ID. If the socket’s unique ID is unique, the provided socket is added. If the socket’s unique ID matches an existing socket’s unique ID, the existing socket is replaced by the provided socket.

Direct Parameter

Listen API / read and write (Required)

Parameters
  • unique ID: text / read and write (Required)

  • interface: text / read and write (Optional)

  • port: integer / read and write (Optional)

  • protocol family: protocol family / read and write (Required)

  • SSL: SSL / read and write (Optional)

  • Bonjour domains: list of text / read and write (Optional)

  • options: list of socket options / read and write (Optional)

remove socket #

Remove a socket.

Remove a socket listening for incoming connections. Action connections accepted through the removed socket will be immediately closed.

No further connections will be accepted through the removed socket. The socket’s port may be used again.

Passing an unknown unique ID has no effect.

Direct Parameter

Listen API / read and write (Required)

Parameters
  • unique ID: text / read and write (Optional)

Enumerations

external type #

Types of externals.

  • external Executable exists and is external to the structure.

  • inline Executable content is inline.

encoding #

Encoding formats.

  • UTF-8 Unicode, UTF-8.

  • UTF-8 no BOM Unicode, UTF-8 without a BOM.

  • UTF-16 Unicode, UTF-16.

  • UTF-16 no BOM Unicode, UTF-16 without a BOM.

external user types #

Types of special case users.

  • PME:logged in

  • PME:active user

external continues #

When to continue performing remaining actions.

  • immediately perform remaining actions without waiting for the application to exit.

  • on exit perform remaining actions after process has exit.

sample criterion type #

Types of sample criterion.

  • equal All sampled data equals a value.

  • not equal No item of sampled data equals a value.

external criterion type #

Types of external criterion.

  • exit code Return true, if exit code is EXIT_SUCCESS (0).

  • interpret Return numeric interpretation of stdout or stderr.

  • contains Return true, if stdout or stderr contain a substring.

external files #

Special case external files.

  • pme:stdout Use the external's standard output.

  • pme:stderr Use the external's standard error.

  • pme:stdout+stderr Use the external's standard output and error.

source type #

Types of sample sources.

  • execute external Launch and interpret external executable's response.

application visibility #

Application visibility.

  • visible Application is visible on launch.

  • hidden Application is hidden as soon as the launch sequence completes.

  • hides others Other applications are hidden as soon as the launch sequence completes.

application behaviour #

Application launch behaviours.

  • print Print the documents being opened.

  • exclude from Recent Items Do not include the application in the Finder's Recent Items menu.

  • in background Launch the application in the background.

  • new instance Always launch a new instance of the application.

  • untrusted Note the application and documents as untrusted.

  • visual errors Display launch errors in the user interface.

application change #

Application change.

  • launched The application has launched.

  • terminated The application has terminated.

comparison #

Value comparison methods.

  • equal to True if value is equivalent.

  • not equal to True if value is not equivalent.

  • starts with True if value starts with comparison value.

  • ends with True if value ends with comparison value.

  • contains True if value contains the comparison value.

  • does not contain True if value does not contain the comparison value.

numeric comparison #

Numeric value comparison methods.

  • equal to True if value is equivalent.

  • not equal to True if value is not equivalent.

  • greater than True if value is greater than the comparison value.

  • less than True if value is less than the comparison value.

  • greater than or equal to

  • less than or equal to

comparison option #

Comparison options.

  • case sensitive Compare case.

power state #

The power source state.

  • off line Source is unavailable or not connected.

  • ac power Source is external and battery is not being drained.

  • battery Source is a battery and it is being drained.

  • unknown Source state is unavailable or unknown.

power health #

The power source health.

  • good The power source is in good condition.

  • fair The power source is in an acceptable condition.

  • poor The power source needs attention.

  • check The power source needs immediate attention.

  • failure The power source has a permanent failure.

  • unknown Unable to determine the health of the power source.

power confidence #

The power source confidence.

  • good The health field is accurate.

  • fair The health field is reasonably certain.

  • poor The health field is not reliable.

  • unknown Unable to determine the confidence of the health field.

power source type #

The power source type.

The power source type is based on the power source’s transport characteristics.

  • serial An uninterruptible power supply attached via a serial cable.

  • USB An uninterruptible power supply attached via a USB cable.

  • network An uninterruptible power supply attached over a network.

  • internal An internal power source such as a battery.

  • unknown Unable to determine the power source type.

day #

Days of the week.

  • Saturday

  • Sunday

  • Monday

  • Tuesday

  • Wednesday

  • Thursday

  • Friday

astronomical sun event #

Astronomical Sun event.

  • night end Night ends; -18.0:set.

  • nautical dawn Nautical dawn begins; -12.0:rise

  • dawn Civil dawn begins; -6.0:rise

  • sunrise Sunrise; -0.833:rise

  • sunrise limit Sunrise ends; -0.3:rise

  • sunset limit Sunset begins; -0.3:set

  • sunset Sunset; -0.833:set

  • dusk Civil dusk begins; -6.0:set

  • nautical dusk Nautical dusk begins; -12.0:set

  • night begin Night begins; -18.0:rise.

audio device #

Audio devices.

  • default output The default audio output device.

  • default input The default audio input device.

  • default system output The default system audio output device.

trigger type #

Types of trigger.

  • once Trigger the Event once on a specific date and time.

  • daily Trigger the Event at given time once on each specified day.

  • inactive Trigger the Event after a given period of user inactivity has past.

  • notification

  • power on

  • start up Trigger the event shortly after the host starts up.

  • log in Trigger the event when a user logs into the console.

  • log out Trigger the event when a user logs out of the console.

  • user session time Trigger the event when a user sessions reaches a specific age.

  • sample Trigger the event when a sample successfully concludes.

  • power state Trigger the event when the source of power changes.

  • battery health Trigger the event a power source's battery health changes.

  • power remaining Trigger the event when a power source capacity changes.

  • sun Trigger the event when the sun reaches a specific angle.

  • external assistant Trigger the event when an external assistant changes.

  • sleep Trigger the event when the computer is about to sleep.

  • application Trigger the event when an application change occurs.

  • audio mute Trigger the event when an audio device mute changes.

  • audio volume Trigger the event when an audio device volume changes.

scope #

Scope of notification.

  • engine Notification Centre's reach is restricted to the engine.

  • host Notification Centre's reach is host wide.

power #

Power event.

macOS supports two power events:

  • wake up from sleep;
  • power on from power off.

Mac hardware can be configured to wake from sleep, or power on from a powered off state. A third option to wake or power on, as appropriate, is available.

Power events require hardware support.

  • wake up Wake up from sleep.

  • power on Power on from power off.

  • power on or wake up Wake from sleep, or power on from power off.

process signature type #

Types of process signature.

  • bundle identifier Compare the application's process identifier.

  • name Compare the application's bundle name or, if not bundled, executable name.

  • localised name Compare the process's localised name.

user session type #

Types of user session.

  • graphical Graphical user session with external assistant.

  • terminal Text input/output session (ttys).

  • all All types of user sessions.

condition type #

Types of condition.

  • boolean Continue if the boolean value is true.

  • delayed boolean Continue if the bool value is true; delayed.

  • days Continue if the current day of the week is listed.

  • date range Continue if today is within the given range of dates.

  • time range Continue if time now is within given range.

  • execute external Continue if the executable returns successfully.

  • full screen Continue if the a display is captured for full screen use.

  • sample Continue if the sample concludes successfully.

  • running processes

  • power assertions Continue if power assertions are set.

  • power state Continue if power state is matched.

  • battery health Continue if the battery health is matched.

  • power remaining Continue if the power remaining is matched.

  • sun Continue if the position of the Sun is matched.

  • inactive Continue if user inactivity is matched.

  • console user Continue if the primary console has a user.

  • start up Continue if seconds elapsed since start up is matched.

  • audio mute

  • audio volume

requires #

How many must resolve to true.

  • all All items must be true.

  • at least one Only one item must be true.

  • none All items must be false.

action type #

Types of action.

  • audio volume

  • audio mute

  • await battery health

  • await daily

  • await inactivity

  • await log in

  • await log out

  • await user session time

  • await notification

  • await once

  • await power on

  • await power state

  • await power remaining

  • await relative date

  • await sample

  • await start up

  • await sun

  • await external assistant

  • await sleep

  • await application

  • execute external

  • fast user switch

  • launch application

  • log out

  • notification

  • restart

  • shut down

  • sleep

  • warn

behaviour #

Event wide behaviours.

  • can perform in parallel Allow the event to be performed in parallel.

  • can perform on demand Allow the event to be performed on demand.

image #

Built-in image identifiers.

These images are provided for use only within a specific context. Do not use these images for any other purpose than for their original purpose. Do not rely on the image’s content remaining unchanged between releases; the meaning will however remaining constant.

  • action cog

  • alarm clock

  • fast user switch Switch to the Login Window.

  • log out Log out all users.

  • none No pending events.

  • missing No scheduler.

  • stopped Scheduler is not active.

  • restart Restart the computer.

  • shut down Shut down the computer.

  • sleep Put the computer to sleep.

  • wake up Wake the computer up.

  • locked Settings are locked.

  • restricted Settings require authorization.

  • application Run an application.

  • sun Sunrise or sunset.

  • executable Executable command line tool.

  • audio Audio device.

  • await Await an event.

event activity #

Active event state.

  • evaluating criteria Event is waiting for conditions to complete.

  • performing actions Event is performing actions.

SSL allowances #

SSL allow.

  • invalid certificate chain Certificate chains are not validated.

SSL level #

SSL level.

  • TLSv1 Use TLSv1 security.

  • negotiated Negotiate the security level; using TLS with fallback to lower versions.

socket state #

Socket states.

  • preparing Socket is being prepared.

  • listening Socket is listening for connections.

  • error Socket is closed due to an error.

protocol family #

Supported network protocols.

The engine supports both IPv4 and IPv6 networking protocols.

  • IPv4 Internet Protocol version 4.

  • IPv6 Internet Protocol version 6.

socket options #

Socket options.

  • use computer name

message level #

Levels of log messages.

  • emergency

  • alert

  • critical

  • error

  • warning

  • notice

  • information

  • debug

source state #

Source states.

  • waiting Source is waiting for next update.

  • fetching Source is checking for an update.

  • error Source encountered an error and is inactive.

domain type #

Types of domain.

  • engine Engine managed domain.

  • device Locally managed domain.

  • server Server managed domain.

right #

Known rights.

  • can read Read the contents of the containing item.

  • can update Update the containing item.

  • can remove Remove the containing item.

authorisation rule #

Rules available to rights.

  • universal Right is available to all.

  • administrator Right is available only to administrators.

licence state #

Available licence states.

  • demonstration A demonstration licence is active.

  • expired No valid licence exists. Expect limited functionality.

  • licensed A valid licence has been provided.