OS4X plugin os4xplugin prowl

From OS4X
Revision as of 09:59, 8 November 2016 by Admin (talk | contribs) (→‎Screenshots)
Jump to navigation Jump to search

Purpose

Send a notification to connected devices which use the Prowl service (compatible with Growl). Notifications can be displayed on mobile devices (such as mobile phones, smart watches, tablets) or even desktop systems.

The plugin is designed to run in two modes:

  • Default plugin mode: can be executed at any situation in a job processing
  • Event handler: the "OS4X Enterprise job abort event" can be configured to use the plugin executable directly.

Screenshots

Prowl on an Apple Watch (WatchOS 3):

Prowl-Apple Watch.png

Prowl on an iPhone (iOS 10):

Prowl-iPhone.png

Requirements

  • File /etc/os4x.conf or configuration file pointed to in environment variable $OS4X_CFGFILE. Via the used configuration file, the information are retrieved used by the plugin (such as default configuration etc.).
  • Either source file or renamed target file must exist. If none of these exist, the plugin stops execution.
  • Prowl account (API key): https://www.prowlapp.com/

Configuration

  • API key: when having registered for free at https://www.prowlapp.com, you can generate as many API keys you want in the "API key" section. You can use different API keys for different situations, with different notification situations depending on your device and program configuration.
  • (optional) API URL for message: If you want a different message API server than https://api.prowlapp.com/publicapi/add (i.e. if you plan to use your own messaging service), you can override the default value here.
  • (optional) Application name: You can override the default "OS4X" value with this config, which is also capable to interpret XPath expressions, indicated by a single dollar sign ("$"), based on the job XML (i.e. for dynamic parameter calculation).
  • Description: The text message which is being displayed at the connected devices. This configuration also supports XPath expressions, indicated by a single dollar sign ("$"), based on the job XML (i.e. for dynamic parameter calculation).
    • When configured globally in "Configuration" -> "OS4X Enterprise" -> "Plugins", this configuration is used for the event handler for aborted jobs. You may use a default value such as:
$/OS4X_job/job_information/job_direction OS4X job $/OS4X_job/job_information/job_number aborted!
  • (optional) Priority: numeric priority, with value from "-2" (very low) to "2" (emergency). Clients can be configured to display only priority messages of a given level or above.
  • (optional) Convert first character to uppercase: For a better readability, the calculated message description can be converted to a upper case message (useful when dealing with dynamic values, like XPath expressions).

Clients

Not tested:

Return values

0: everything OK

1: Configfile (/etc/os4x.conf or value of environment variable "OS4X_CFGFILE", read in as file) cannot be found or database unavailable.

2: License error

3: XML parameter file cannot be parsed