This plugin can display an alert message at the top of all pages for sites in a WordPress network. The alert consists of a message box which is inserted into the markup of the page during the WP init hook.
The alerts are stored and rendered from the wp_sitemeta table. Alerts can be started and ended through 2 interfaces:
- WP REST API
- WP-CLI
Stopping and starting alerts will also trigger a full cache flush using $wp_object_cache->flush( 0 ) to ensure the message is rendered immediately. It also includes an integration with the static homepage capture setup in r-editorial, so stopping and starting alerts will trigger new homepage renders through the page-capture lambda if it is setup in the r-editorial homepage admin.
In case of emergency, check the wiki for command recipies to start and stop alerts manually.
The wiki also contains some additional details about the Everbridge integration.
The plugin includes a custom REST API endpoint with start and stop commands that are secured by a custom token. This interface is designed primarily for the Everbridge incident integration, but can be used by anything that has the security token.
The REST API token is defined in the environment outside the plugin (through wp-config.php) and is called BU_ALERT_API_TOKEN. It is converted from the bu-wordpress.ini file.
To start an alert through the API, send a POST request to the endpoint /wp-json/bu-alert/v1/start/ with the json encoded body of the alert message in the POST body, and a ?token= url parameter for the secure token. The alert will be added for the domain that receives the API request, but additional domains can be activated by passing a comma delimited list through an optional additionalDomains= parameter. The structure of the start endpoint is determined mostly by the Everbridge Web Posting that it is designed to support.
There is an endpoint /wp-json/bu-alert/v1/stop/ that will remove the alert for the targeted domain. Because the Everbridge integration uses a separate mechanism to remove alerts (see incident expiration in the CLI), the /stop/ endpoint is much simpler and is mostly useful as an aid during development. It only accepts the security ?token= parameter.
The WP CLI interface provides commands to stop and start alerts, as well as commands to work with the Everbridge integration. Notably, removing expired Everbridge incidents is handled through the WP CLI interface (along with a dedicated cron task that invokes a WP CLI command).
There is online help available through:
wp help alertBelow is a description of the individual commands:
Manual alerts can be started for a targeted domain with the start-manual command. It takes the body of the message as a command line argument.
wp alert start-manual --url=http://www-test.bu.edu "<message body>"These manual alerts use a special hardcoded incident_id consisting of the string "manual", which tells the Everbridge integration to leave these alerts alone and not remove them.
Starting alerts in this way will also trigger an r-editorial homepage rebuild, if available.
All alerts for all domains in the network can be immediately removed with the stop-all command, which requires no arguments.
wp alert stop-allBecause it removes alerts from all domains in the multisite WP network, it does not matter which domain is targeted. Every alert will be removed.
Stopping alerts in this way will also trigger an r-editorial homepage rebuild, if available.
The list command will return a table containing all active alerts in a network.
wp alert listIt requires no arguments, and because it queries the entire network it doesn't matter which domain is targeted.
The list-everbridge command queries the Everbridge API to get all of the incidents that are currently active in Everbridge. It is primarly for troubleshooting the Everbridge integration.
wp alert list-everbridgeThe expire command handles removing alerts once they are no longer active in Everbridge. This is necessary because Everbridge does not provide an event when incidents are closed. To work around this limitation, expire gets the list of current active incidents from the Everbridge API and compares it to the list of currently active alerts in the WordPress network. Any alerts that are active in WordPress, but not present in Everbridge are removed.
There's no way to tell when an incident may be closed, so expire is designed to be run from a system cron task that regularly checks for expired incidents, currently every minute.
This should also have the side effect of guarding against stateless Everbridge 'notifications' from persisting. If a Web Posting is accidentally included with an Everbridge notification, the incident id should come through as blank. Running expire will remove alerts with empty incident ids. This is also the reason why manual alerts have a hardcoded incident id, in order to distinguish them from malformed Everbridge Web Postings.
This command can also be run manually and doesn't require any arguments.
wp alert expireAccessing the Everbridge API requires 4 environment variables from bu-wordpress.ini, which are parsed from wp-config.php.
EB_ENDPOINT: Generally 'https://api.everbridge.net/'EB_BU_ORG_ID: The Everbridge organization ID to useEB_KEY_ID: Key ID of the API access accountEB_SECRET_ACCESS_KEY: Secret key of the API access account
In order to remove closed Everbridge incidents, a cron task is required to run the wp alert expire command on a regular basis. This cron entry should live in the wpcms user crontab for each environment, and can be added with the following command:
sudo -u wpcms crontab -eBelow are examples for the TEST and PROD environment. Because DEVL consists of many independent sandboxes, a cron task there would probably only complicate matters. These definitions run every minute.
TEST (as installed):
# expire everbridge alerts every minute for www-test
* * * * * /fs/test/scratch/shared/bin/wp alert expire --url="http://www-test.bu.edu" --path="/var/www/cms-test/current/"PROD (to be installed):
# expire everbridge alerts every minute for www
* * * * * /fs/prod/scratch/shared/bin/wp alert expire --url="http://www.bu.edu" --path="/var/www/cms-prod/current/"