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.
  • workshop (local workshop / read-only) Workshop for objects.
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

Power Manager Suite #

Classes common to all Power Manager installations.

Classes

trigger application parameters #

Trigger application parameters.

Properties

resource limits #

Constraints for external processes.

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 Mac OS X 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.

trigger log in parameters #

Trigger log in parameters.

application description #

Description for launching an external process.

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.

    Arguments are passed to the application via argv. arguments are ignored on Mac OS X 10.4, aka Tiger.

  • user (text / read and write) User to execute process as.

    Short user name.

  • additional environment (record / read and write) Set additional environment variables for the executable.

    The dictionary's keys and values must be strings.

  • 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.

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.

trigger external assistant parameters #

Trigger external assistant parameters.

assistant #

Assistant details.

Properties
  • user (text / read and write) Name of the local user associated with the assistant.

trigger log out parameters #

Trigger log out parameters.

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.

trigger #

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

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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

trigger daily #

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

Inherits from trigger

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

    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.
  • availability (power / read and write) Should the host be made available for this trigger.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

trigger after inactivity #

Trigger after a given period of user inactivity.

Inherits from trigger

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

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.

  • context (record / read and write) Continue if notification's context matches this context.

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

trigger power on #

Trigger when the computer powers on.

Inherits from trigger

trigger start up #

Trigger when the computer starts up.

Inherits from trigger

trigger log in #

Trigger when a user logs in.

Inherits from trigger

trigger log out #

Trigger when a user logs out.

Inherits from trigger

trigger sleep #

Trigger when the computer is about to sleep.

Inherits from trigger

trigger sample #

Trigger when a sample successfully concludes.

Inherits from trigger

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

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

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

    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.
  • 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

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

Properties
  • at (astronomical sun event / read and write) Astronomical Sun event to calculate.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.
  • offset (integer / read and write) Offset from the calculated astronomical event.

    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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

trigger external assistant #

Trigger when an external assistant changes.

Inherits from trigger

trigger application #

Trigger when an application launches or quits.

Inherits from trigger

Properties

licence #

Licence details for this Power Manager Engine.

Properties
  • name (text / read and write) Name of the licenced contact.
  • organisation (text / read and write) Organisation licenced to use this engine.

    For individuals, organisation should be set to 'Personal'.

  • state (licence state / read and write) Licence state for the engine.
  • expires (date / read and write) Date this copy's demonstration period expires. If state is licenced or expired, expires may be omitted.

trigger sleep parameters #

Trigger sleep parameters.

external #

Description for executing an external process.

Properties
  • 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.

  • additional environment (record / read and write) Set additional environment variables for the executable.

    The dictionary's keys and values must be strings.

  • 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.

    Available on Mac OS X 10.5 (Leopard) and later.

  • 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.

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.

trigger daily parameters #

Trigger daily parameters.

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

    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.
  • availability (power / read and write) Should the host be made available for this trigger.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

trigger power state parameters #

Trigger power state parameters.

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.

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.

sample #

Description for sampling.

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.
  • 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.

    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.

trigger notification parameters #

Trigger notification parameters.

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.

  • context (record / read and write) Continue if notification's context matches this context.

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

event #

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

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

    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.

    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 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 engine will be ignored.

Elements
  • trigger

  • action

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

trigger battery health parameters #

Trigger battery health parameters.

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 once parameters #

Trigger once parameters.

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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

trigger power on parameters #

Trigger power on parameters.

sample criterion #

Criterion for concluding a sample.

Properties
  • 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

sample criterion not equal #

Judge the samples looking for a negative match.

Inherits from sample criterion

trigger power remaining parameters #

Trigger power remaining parameters.

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

    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.
  • filter (power source filter / read and write) Power sources to monitor.

queued warning #

Host wide warning.

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.
  • context (record / read and write) Additional context for warning clients.

trigger start up parameters #

Trigger start up parameters.

geolocation #

Geospatial location.

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

action #

Task to perform.

action sleep #

Put the computer to sleep.

Inherits from action

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

action shut down #

Shut down the computer.

Inherits from action

action restart #

Restart the computer.

Inherits from action

action log out #

Log out all users.

Inherits from action

action fast user switch #

Switch to the Login Window.

Inherits from action

action notification #

Post a notification.

Inherits from action

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.

  • context (record / read and write) Context to associate with notification.

    The context must contain string keys and and CFPropertyList valid values.

action execute external #

Execute an external process.

Inherits from action

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

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

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.
  • context (record / read and write) Additional context for warning clients.

    content must have string based keys and CFPropertyListRef valid values.

action await once #

Wait for a specific time and date to occur.

Inherits from action

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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

action await daily #

Wait for a specific time and day to occur.

Inherits from action

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

    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.
  • availability (power / read and write) Should the host be made available for this trigger.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

action await relative date #

Wait for a period of time.

Inherits from action

Properties
  • seconds (integer / read and write) seconds to wait before continuing.
  • availability (power / read and write) Should the host be made available for this trigger.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

action await user inactivity #

Wait for a period of user inactivity.

Inherits from action

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

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.

  • context (record / read and write) Continue if notification's context matches this context.

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

action await power on #

Wait for the computer to power on.

Inherits from action

action await start up #

Wait for the computer to start up.

Inherits from action

action await sleep #

Wait for the computer to sleep.

Inherits from action

action await sample #

Wait for a sample to conclude.

Inherits from action

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

action await log out #

Wait for a user to log out.

Inherits from action

action await battery health #

Wait for battery health to reach specific state.

Inherits from action

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

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

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

    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.
  • 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

Properties
  • at (astronomical sun event / read and write) Astronomical Sun event to calculate.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.
  • offset (integer / read and write) Offset from the calculated astronomical event.

    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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

action await external assistant #

Wait for a change in the external assistants.

Inherits from action

action await application #

Wait for an application to launch or quit.

Inherits from action

Properties

process signature #

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

Properties
  • 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.

condition #

Description of a testable condition that resolves to a boolean.

Properties
  • 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

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

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

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

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

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

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

condition sample #

Conditional on a sample's successful conclusion.

Inherits from condition

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

condition running processes #

Conditional on whether specific processes are running.

Inherits from condition

Elements

condition power assertions #

Conditional on whether other processes have power assertions set.

Inherits from condition

condition power state #

Conditional on the computer's power source state.

Inherits from condition

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

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

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.
  • 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

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.
  • date (date / read and write) Date to calculate Sun position on.

condition user inactivity #

Conditional on the period of user inactivity.

Inherits from condition

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

condition start up #

Conditional on time since start up.

Inherits from condition

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

trigger sun parameters #

Trigger sun parameters.

Properties
  • at (astronomical sun event / read and write) Astronomical Sun event to calculate.
  • geolocation (geolocation / read and write) Location to calculate Sun position from.
  • offset (integer / read and write) Offset from the calculated astronomical event.

    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.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

queued trigger #

Queued trigger instance.

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.

common power source #

Common fields shared by power source based triggers.

Properties

domain #

Description of a domain.

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

    unique ID must be unique within the domains. unique ID is used to identify a specific domain within a set and for reporting.

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

    name need not be unique, but we recommend it is. Use name to inform the user where the associated events came from, or why they are grouped. This might be the url for events fetched from a remote server.

  • content rights (list of right / read and write) Caller rights for the contents of the domain.

    content rights lists what the caller can do in this domain. The rights are specific to the caller. content rights is read only. Any content rights passed into the engine will be ignored.

domain engine #

Domain managed by the engine.

Inherits from domain

domain device #

Domain managed through the local device.

Inherits from domain

domain server #

Domain managed by a server.

Inherits from domain

Properties
  • source id (text / read and write) Identifier of the source providing the domain's events.

trigger after inactivity parameters #

Trigger after inactivity parameters.

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.

active event #

Active event instance.

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.

log message #

Properties
  • Facility (text / read and write)
  • Host (text / read and write)
  • Sender (text / read and write)
  • Level (message level / read and write)
  • Time (text / read and write)
  • Message (text / read and write)

power source filter #

A profile for filtering power source changes.

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.

authorisation right #

An authorisation right.

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.

trigger sample parameters #

Trigger sample parameters.

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

event history #

Event history.

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.

common date and time #

Common fields shared by date and time based triggers.

Properties
  • availability (power / read and write) Should the host be made available for this trigger.
  • scatter (integer / read and write) Scatter the date.
  • quiet (boolean / read and write) Minimise the notifications.
  • drift (integer / read and write) Acceptable drift.

URL options #

URL options.

criteria #

Group of conditions to test.

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

    The engine will maintain the order of conditions.

external criterion #

Criterion for judging an external executable sample.

external criterion interpret #

Interpret the output as a number.

Inherits from external criterion

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

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.

power source #

A power source.

Properties
  • 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

power source USB #

Power source connected via a USB cable.

Inherits from power source

power source network #

Power source connected via a network connection.

Inherits from power source

power source internal #

Internal power source such as a fitted or removable battery.

Inherits from power source

power source unknown #

Unknown power source.

Inherits from power source

Client API #

Host details.

The engine provides a selection of host details to assist servers and clients group engines.

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

    The computer name is set in the Sharing System Preferences panel.

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

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

    You can see the local host name in the Sharing System Preferences panel.

  • 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 AirPort 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 computer model type.

Build API #

Engine meta-data.

Build provides build details and control.

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

    version is provided as a URI and three part release number. The engine 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) Engine's revision number.

    revision is the internal version used by the developers. The higher the revision value, the more recent the version of the engine. revision is used to compare engine 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

Event Store API #

Stores, organises, and tracks events.

Event Store is the storage of the engine. 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 engine objects.

Elements
  • event

    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

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
Responds To

apply right

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

    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.

Legal API #

Legal and licensing details.

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

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

    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

Scheduler API #

Coordinates the events, triggers, conditions, and actions.

Scheduler is the core of the engine. 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 Engine.

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

Elements
  • queued trigger

    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

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

  • assistant

    available assistants helping the scheduler on the local host. Assistants provide the means to run executables within user sessions and perform user specific tasks, such as logging out.

Responds To

cancel

adjust

reset

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

    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

    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.

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.

Listen API #

Configures and controls incoming network connections.

Listen manages the push behaviour of the engine.

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

Listen provides a means for configuring the engine remotely.

Properties
  • source options (URL options / read and write) Options applied to all sources.

    Individual sources may have their own associated options; where this occurs options are merged with the individual source options taking precedence over global options.

Elements
  • socket

    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 engine can listen on multiple sockets for incoming connections. The engine supports multiple simultaneous connections; requests are atomic. Each socket is independent of all other listening sockets.

  • source

    sources contains a list of sources to poll. The order of the list is important as it controls the precedence of the associated content.

    When dealing with sources, refer to specific sources using the source's unique ID.

Responds To

apply socket

remove socket

Astronomic API #

Astronomical calculator.

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

Responds To

sun observation

Log API #

Audit logging.

The engine logs key tasks as they occur. The log provides an audit trail detailing the what and when of the engine's behaviour.

Properties
  • filter level (message level / read and write) Filtering out log messages with levels lower than this.
Elements
  • log message

    Recent log messages stored by Apple System Log (ASL). Messages are filtered according to the filter level, and any remote syslogd filter, settings.

    Logged messages are not guaranteed to appear in the recent list. Messages may be omitted if they occur too rapidly, or have identical time stamps.

    For a complete log, use ASL to retrieve the messages directly.

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

    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

local workshop #

A workshop for creating, editing, and storing objects.

Elements
Responds To

empty

Class Extensions

application #

Power Manager's top-level scripting object.

Contents

connection / read and write

Connection to this computer.

Properties
Elements

Commands

restart #

Restart the engine and associated processes.

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

Direct Parameter

Build API / read and write (Required)

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
  • these events: list of event / read and write (Optional)

    Passing an empty array empties the scheduler's pending events queue in one request.

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

    Replace existing events with provided events.

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
  • event with id: text / read and write (Required)

    Unique ID of an event.

history #

Event history.

Get an event's history.

Direct Parameter

Event Store API / read and write (Required)

Parameters
  • for event with id: text / read and write (Required)

    Unique ID of an event.

Result

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 (Optional)

    Signature of the right to modify.

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

    Rule to associate with right. If omitted, default right is set.

license #

Set the licence details.

license applies the provided licence details to engine.

All parameters are case sensitive and must be provided exactly as provided in the issued licence details.

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

Direct Parameter

Legal API / read and write (Required)

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

    Name provided in the licence details.

  • organisation: text / read and write (Optional)

    Organisation provided in the licence details.

  • code: text / read and write (Required)

    Code provided in the licence details.

revoke #

Remove all licence information.

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

Direct Parameter

Legal API / read and write (Required)

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 with id: text / read and write (Required)

    Trigger ID of a queued trigger.

  • until: date / read and write (Optional)

    Date before which the trigger can not trigger the event.

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 with id: text / read and write (Required)

    Trigger ID of a queued trigger.

  • to date: date / read and write (Required)

    Date to set the queued trigger to fire.

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 with id: text / read and write (Optional)

    Trigger ID of a queued trigger.

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 (Optional)

    Unique ID of the socket.

  • interface: text / read and write (Optional)

    Interface address, hostname or numeric IP.

  • port: integer / read and write (Optional)

    TCP/IP port number.

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

    Use IPv4 or IPv6 protocol.

  • SSL: SSL / read and write (Optional)

    Encoded SSL certificate path and options.

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

    Bonjour domains to publish within.

  • 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
  • socket with id: text / read and write (Required)

    Unique ID of the socket to remove.

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 (Optional)

  • latitude: real / read and write (Optional)

  • longitude: real / read and write (Optional)

  • date: date / read and write (Optional)

Result
  • date

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
  • event with id: text / read and write (Required)

    Unique ID of an event.

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

    Should the event's criteria be enforced.

empty #

Delete all objects from the workshop.

Direct Parameter

local workshop / read and write (Required)

The workshop to empty.

Enumerations

SSL level #

SSL level.

  • SSLv2 Use SSLv2 security.

  • SSLv3 Use SSLv3 security.

  • TLSv1 Use TLSv1 security.

  • negotiated Negotiate the security level; using TLS or SSL with fallback to lower versions.

external user types #

Types of special case users.

  • PME:logged in

  • PME:active user

comparison option #

Comparison options.

  • case sensitive Compare case.

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.

external type #

Types of externals.

  • external Executable exists and is external to the structure.

  • inline Executable content is inline.

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.

action type #

Types of action.

  • await battery health

  • await daily

  • await inactivity

  • await log in

  • await log out

  • 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

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.

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.

message level #

Levels of log messages.

  • emergency

  • alert

  • critical

  • error

  • warning

  • notice

  • information

  • debug

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.

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.

  • 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.

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.

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.

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.

SSL allowances #

SSL allow.

  • any root Any root certificate is allowed; deprecated since 4.3.3

  • expired certificates Expired certificates are allowed; deprecated since 4.3.3

  • expired root certificates Expired root certificates are allowed; deprecated since 4.3.3

  • invalid certificate chain Certificate chains are not validated.

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

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.

scope #

Scope of notification.

  • engine Notification Centre's reach is restricted to the engine.

  • host Notification Centre's reach is host wide.

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; deprecated since 4.6.5

  • visual errors Display launch errors in the user interface.

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.

event activity #

Active event state.

  • evaluating criteria Event is waiting for conditions to complete.

  • performing actions Event is performing actions.

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.

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.

sample criterion type #

Types of sample criterion.

  • equal All sampled data equals a value.

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

power source type #

The power source type.

  • 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.

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.

domain type #

Types of domain.

  • engine Engine managed domain.

  • device Locally managed domain.

  • server Server managed domain.

socket state #

Socket states.

  • preparing Socket is being prepared.

  • listening Socket is listening for connections.

  • error Socket is closed due to an error.

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.

authorisation rule #

Rules available to rights.

  • universal Right is available to all.

  • administrator Right is available only to administrators.

day #

Days of the week.

  • Saturday

  • Sunday

  • Monday

  • Tuesday

  • Wednesday

  • Thursday

  • Friday

application change #

Application change.

  • launched The application has launched.

  • terminated The application has terminated.

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 #

Power event.

  • 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.

image #

Built-in image identifiers.

  • 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.

right #

Known rights.

  • can read Read the contents of the containing item.

  • can update Update the containing item.

  • can remove Remove the containing item.

socket options #

Socket options.

  • use computer name

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.

protocol family #

Supported network protocols.

  • IPv4 Internet Protocol version 4.

  • IPv6 Internet Protocol version 6.

source type #

Types of sample sources.

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