OS4X plugin os4xplugin prowl

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.

With Prowl, you can send up to 1000 notifications per hour for free.

Screenshots

Prowl on an Apple Watch (WatchOS 3):

Prowl on an iPhone (iOS 10):

Requirements

• File /etc/os4x.conf or the configuration file which points to the 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.
  • The following key words exist:
    • internalUserApiKey: extract the API key from the person which is configured at the job:
      • Send job: sender of the job
      • Receive job: recipient of the job
    • externalUserApiKey: extract the API key from the person which is configured at the job:
      • Send job: recipient of the job
      • Receive job: sender of the job
  • An empty API key will let the plugin exit without error.
• (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).

Example configuration

As an example, the following configuration can be used as a good basis for notification executin for both aborted jobs (which will be reported to a specific API key) and default job processing (using the API key of the internal user):

The textual description information (for copy&paste) of both configs are:

• Plugin mode: $/OS4X_job/job_information/job_direction OS4X job $/OS4X_job/job_information/job_number successfully transfered!
• Event handler mode: $/OS4X_job/job_information/job_direction OS4X job $/OS4X_job/job_information/job_number aborted!

Clients

• iOS (with Apple Watch support): https://itunes.apple.com/de/app/prowl-easy-push-notifications/id320876271?mt=8#
• Mac OS X: http://growl.info/
• Windows: http://www.growlforwindows.com/gfw/

Not tested:

• Android: http://www.notifymyandroid.com/

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