diff --git a/docs/illustrations/messaging_sms_billing_settings.png b/docs/illustrations/messaging_sms_billing_settings.png new file mode 100644 index 0000000000000000000000000000000000000000..1aa555c82dedd5a8ef6b59b67a953d0a5a94be13 Binary files /dev/null and b/docs/illustrations/messaging_sms_billing_settings.png differ diff --git a/docs/illustrations/messaging_user_preferences.png b/docs/illustrations/messaging_user_preferences.png new file mode 100644 index 0000000000000000000000000000000000000000..5c655508fd9aee47f200719353aa7c404c4f6ae1 Binary files /dev/null and b/docs/illustrations/messaging_user_preferences.png differ diff --git a/docs/index.md b/docs/index.md index 6c4a1e42028257b0eac3ee7f94465b5274699e66..546a81381cc5f33d14d20c27dfbc638c8ba9b3b5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ ### Recommended: Building with Docker #### First: the database -The docker container needs a database. Important parts of the data model [is described in the Data Model chapter](./data_model.md). +The docker container needs a database. Important parts of the data model [are described in the Data Model chapter](./data_model.md). So make sure you have PostgreSQL >= 10 and PostGIS >=2.4 installed. Then create a user called vipslogic. Make sure you enter the vipslogic username and password in the `standalone.xml` file of Wildfly (see chapter below). diff --git a/docs/messaging.md b/docs/messaging.md index 7991cc23ebe401d2e3faba171985593da46700b2..78464a0a1be78e103075e9e9c1205b8f746fe79e 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -1,15 +1,58 @@ -# VIPSLogic messaging +# VIPSLogic push notifications ("messaging") + +**Last update: 2022-08-11** + +VIPSLogic allows for push notifications for a few events: +* Publication of a news message tagged with a crop category and a message type selected by the user +* Publication of a field observation tagged with a crop category selected by the user +* A pest prediction forecast for a given crop category at a specified location changes from low to high risk (may happen during the daily update of the forecast) + +**The notification system is generic; it can be adapted to send other types of notifications.** + +The notifications may be sent as emails or tests (SMS), depending on the VIPSLogic server's available message gateways. See how to configure this below. + +The user can change their notification preferences on their personal settings page (see illustration below) + + + +On the personal settings main page, the user has to accept SMS billing - or be granted free SMSs by the super user (option only visible to super users). + + + +## Code +The code for the messaging system is found in the `no.nibio.vips.logic.messaging` package and subpackages. + +### Usage example + ## Configuration These system properties must be set in order for the messaging system to function: -```xml -<property name="no.nibio.vips.logic.messaging.dist.SIMULATE_MAIL_SENDING" value="true"/> -<property name="no.nibio.vips.logic.messaging.dist.MAIL_SENDER_ADDRESS" value="noreply@foobar.com"/> -<property name="no.nibio.vips.logic.messaging.dist.SMS_SERVER" value="smsgateway.foobar.com"/> -<property name="no.nibio.vips.logic.messaging.dist.SMS_USERNAME" value="foobar"/> -<property name="no.nibio.vips.logic.messaging.dist.SMS_PASSWORD" value="foobar"/> -<property name="no.nibio.vips.logic.messaging.dist.SMS_SENDER_SRC" value="foobar"/> -<property name="no.nibio.vips.logic.messaging.dist.TRAFFIC_LOG_DIRECTORY" value="/var/log/trafficLog/"/> +```bash +# Set to true if you want to dry run the email system +no.nibio.vips.logic.messaging.dist.SIMULATE_MAIL_SENDING=true +# This will be the email sender address displayed to the receiver +no.nibio.vips.logic.messaging.dist.MAIL_SENDER_ADDRESS=noreply@foobar.com +# The URL to the SMS provider's API +no.nibio.vips.logic.messaging.dist.SMS_SERVER=smsgateway.foobar.com +# Username for the SMS gateway API +no.nibio.vips.logic.messaging.dist.SMS_USERNAME=foobar +# Password for the SMS gateway API +no.nibio.vips.logic.messaging.dist.SMS_PASSWORD=foobar +# Where the messaging system stores its logs +no.nibio.vips.logic.messaging.dist.TRAFFIC_LOG_DIRECTORY=/var/log/trafficLog/ +``` + +How to configure these system properties may vary between application servers. The example below is from WildFly's `[...]/standalone/configuration/standalone.xml` configuration file. +```xml +<system-properties> + <property name="no.nibio.vips.logic.messaging.dist.SIMULATE_MAIL_SENDING" value="true"/> + <property name="no.nibio.vips.logic.messaging.dist.MAIL_SENDER_ADDRESS" value="noreply@foobar.com"/> + <property name="no.nibio.vips.logic.messaging.dist.SMS_SERVER" value="smsgateway.foobar.com"/> + <property name="no.nibio.vips.logic.messaging.dist.SMS_USERNAME" value="foobar"/> + <property name="no.nibio.vips.logic.messaging.dist.SMS_PASSWORD" value="foobar"/> + <property name="no.nibio.vips.logic.messaging.dist.SMS_SENDER_SRC" value="foobar"/> + <property name="no.nibio.vips.logic.messaging.dist.TRAFFIC_LOG_DIRECTORY" value="/var/log/trafficLog/"/> +</system-properties> ``` \ No newline at end of file