h2. HTTP Active Alert Endpoints
Alerts require configuration of endpoints, the destination for notifications that should be sent to users. These are defined in {{$LWE_HOME/app/rails/config/alerts.yml}} file and can be a mail server, a log file, an IM service, etc. An endpoint's job is to render the notification in a manner appropriate to the notification channel and then alert the user via that channel (an email, instant message, SMS, and so on). Alert notifiers can be written in any language and development environment that can respond to HTTP POST requests.
One notifier, a log file notifier, is enabled by default in the alert system. The log notifier appends the notification message to a file located in {{./data/logs}} directory of LucidWorks Enterprise called {{notification.log}}. The endpoint URL is {{[http://localhost:8989/alerts/notifiers/log/notification]}}.
If you are only using passive alerts, you do not need to define any endpoints, but you can define them, if you like. If you wish to use active alerts, at least one endpoint must be defined.
When new documents match an active alert query, a notification message is sent to each defined active alert URL endpoint. Each endpoint receives an HTTP POST request notifying it of the alert. The body of the POST request contains the alert and the query results in the same format as the response to the [alert check API request|lweug18:Alerts API].
h3. The Alerts Configuration File
The alerts configuration file is located at {{./app/rails/config/alerts.yml}} and defines the endpoints. On some Windows systems, You may need to [shut down|lweug18:Starting and Stopping LucidWorks Enterprise] LucidWorks Enterprise before editing configuration files.
{code:borderStyle=solid|borderColor=#666666}
production: {
endpoints: {
log: { url: <%=LWEConfig[:alerts][:address]%>/notifiers/log/notification }
}
}
{code}
h3. Available built-in alert notifiers
There are three notifiers in LucidWorks Enterprise, with only the log notifier enabled by default. The other two notifiers, jabber and mail, require local administrator configuration and commented out of the production configuration. The following table lists each of the built-in notifiers, the endpoint URL using the default install port, and an example configuration section.
|| Notifier Name || Default Notifier Endpoint URL || Example Notifier Configuration Section || Notes ||
| log | {nolink:http://localhost:8989/notifiers/log/notification} | {code:borderStyle=solid|borderColor=#666666}log: {url: <%=LWEConfig[:alerts][:address]%>/notifiers/log/notification}{code} | The last piece of the log notifier URL is the log file name, with "notification" being the default. |
| jabber | {nolink:http://localhost:8989/notifiers/jabber} | {code:borderStyle=solid|borderColor=#666666}jabber: {
url: <%=LWEConfig[:alerts][:address]%>/notifiers/jabber,
host: host,
port: 1234,
service_name: service name,
user_name: user name,
password: s3cr3t
} {code} | The jabber notifier requires that each active alert specify a jabber_id property (which can currently only be specified when creating alerts through the REST API, but not through the UI) |
| mail | {nolink:http://localhost:8989/notifiers/mail} | {code:borderStyle=solid|borderColor=#666666} mail: {
url: <%=LWEConfig[:alerts][:address]%>/notifiers/mail,
from: lwe@localhost,
base_search_url: <%=LWEConfig[:search][:address]%>,
delivery_method: smtp,
smtp_parameters: {
address: localhost,
port: 25,
domain: localhost.localdomain,
user_name: username,
password: password,
authentication: plain,
enable_starttls_auto: true
}
} {code} | See [Ruby's Mail API|http://api.rubyonrails.org/classes/ActionMailer/Base.html] for details on the delivery method available. The delivery method value is used as the prefix to the delivery method parameters section name (for example, "smtp" looks for parameters in the "smtp_parameters" section). See [Ruby's Net::SMTP|http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/smtp/rdoc/classes/Net/SMTP.html] for details on the smtp delivery method parameters. The base_search_url parameter is used as the base used in the e-mailed links to the search system. The mail notifier requires each alert specify an email property, which can be entered when an alert is saved through the search user interface. |
The alerts.yml file is first interpreted as a Ruby ERb template so that dynamic configuration information may be used, such as the {{<%=LWEConfig\[:alerts\]\[:address\]%>}} values used as the base URL for the built-in notifiers, and will include the port specified during installation.
Alerts require configuration of endpoints, the destination for notifications that should be sent to users. These are defined in {{$LWE_HOME/app/rails/config/alerts.yml}} file and can be a mail server, a log file, an IM service, etc. An endpoint's job is to render the notification in a manner appropriate to the notification channel and then alert the user via that channel (an email, instant message, SMS, and so on). Alert notifiers can be written in any language and development environment that can respond to HTTP POST requests.
One notifier, a log file notifier, is enabled by default in the alert system. The log notifier appends the notification message to a file located in {{./data/logs}} directory of LucidWorks Enterprise called {{notification.log}}. The endpoint URL is {{[http://localhost:8989/alerts/notifiers/log/notification]}}.
If you are only using passive alerts, you do not need to define any endpoints, but you can define them, if you like. If you wish to use active alerts, at least one endpoint must be defined.
When new documents match an active alert query, a notification message is sent to each defined active alert URL endpoint. Each endpoint receives an HTTP POST request notifying it of the alert. The body of the POST request contains the alert and the query results in the same format as the response to the [alert check API request|lweug18:Alerts API].
h3. The Alerts Configuration File
The alerts configuration file is located at {{./app/rails/config/alerts.yml}} and defines the endpoints. On some Windows systems, You may need to [shut down|lweug18:Starting and Stopping LucidWorks Enterprise] LucidWorks Enterprise before editing configuration files.
{code:borderStyle=solid|borderColor=#666666}
production: {
endpoints: {
log: { url: <%=LWEConfig[:alerts][:address]%>/notifiers/log/notification }
}
}
{code}
h3. Available built-in alert notifiers
There are three notifiers in LucidWorks Enterprise, with only the log notifier enabled by default. The other two notifiers, jabber and mail, require local administrator configuration and commented out of the production configuration. The following table lists each of the built-in notifiers, the endpoint URL using the default install port, and an example configuration section.
|| Notifier Name || Default Notifier Endpoint URL || Example Notifier Configuration Section || Notes ||
| log | {nolink:http://localhost:8989/notifiers/log/notification} | {code:borderStyle=solid|borderColor=#666666}log: {url: <%=LWEConfig[:alerts][:address]%>/notifiers/log/notification}{code} | The last piece of the log notifier URL is the log file name, with "notification" being the default. |
| jabber | {nolink:http://localhost:8989/notifiers/jabber} | {code:borderStyle=solid|borderColor=#666666}jabber: {
url: <%=LWEConfig[:alerts][:address]%>/notifiers/jabber,
host: host,
port: 1234,
service_name: service name,
user_name: user name,
password: s3cr3t
} {code} | The jabber notifier requires that each active alert specify a jabber_id property (which can currently only be specified when creating alerts through the REST API, but not through the UI) |
| mail | {nolink:http://localhost:8989/notifiers/mail} | {code:borderStyle=solid|borderColor=#666666} mail: {
url: <%=LWEConfig[:alerts][:address]%>/notifiers/mail,
from: lwe@localhost,
base_search_url: <%=LWEConfig[:search][:address]%>,
delivery_method: smtp,
smtp_parameters: {
address: localhost,
port: 25,
domain: localhost.localdomain,
user_name: username,
password: password,
authentication: plain,
enable_starttls_auto: true
}
} {code} | See [Ruby's Mail API|http://api.rubyonrails.org/classes/ActionMailer/Base.html] for details on the delivery method available. The delivery method value is used as the prefix to the delivery method parameters section name (for example, "smtp" looks for parameters in the "smtp_parameters" section). See [Ruby's Net::SMTP|http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/smtp/rdoc/classes/Net/SMTP.html] for details on the smtp delivery method parameters. The base_search_url parameter is used as the base used in the e-mailed links to the search system. The mail notifier requires each alert specify an email property, which can be entered when an alert is saved through the search user interface. |
The alerts.yml file is first interpreted as a Ruby ERb template so that dynamic configuration information may be used, such as the {{<%=LWEConfig\[:alerts\]\[:address\]%>}} values used as the base URL for the built-in notifiers, and will include the port specified during installation.