
= Notification Commands
:description: Default notification commands in {page-component-title} and how to create custom commands.

A notification command is a named, reusable execution profile for a Java class or external program command used to convey notices to targets.
{page-component-title} includes several default notification commands.
You can also create custom commands to send notifications to a platform of your choice.

== Default notification commands

[caption=]
.Default {page-component-title} notification commands
[cols="1,3"]
|===
| Command       | Description

| callHomePhone
| Calls the home phone number configured in the user's contact information. +
Uses the in-process Asterisk notification strategy.

| callMobilePhone
| Calls the mobile phone number configured in the user's contact information. +
Uses the in-process Asterisk notification strategy.

| callWorkPhone
| Calls the work phone number configured in the user's contact information. +
Uses the in-process Asterisk notification strategy.

| ircCat
| Conveys a notice to an instance of the IRCcat Internet Relay Chat bot. +
Uses the in-process IRCcat notification strategy.

| javaEmail
| Delivers a notice to the email address listed in the user's `email` contact field. +
Uses the in-process JavaMail notification strategy.

| javaPagerEmail
| Delivers a notice to the email address listed in the user's `pagerEmail` contact field.
By configuring `pagerEmail` to target an email-to-SMS gateway, you can easily configure SMS notifications. +
Uses the in-process JavaMail notification strategy.

| microblogDM
| Sends a notice to a user as a direct message via a microblog service with a Twitter v1-compatible API.

| microblogReply
| Sends a notice to a user as an at-reply via a microblog service with a Twitter v1-compatible API.

| microblogUpdate
| Sends a notice to everyone as an update via a microblog service with a Twitter v1-compatible API.

| numericPage
| Sends a notice to a user's numeric pager. +
Implemented as an external command using the `qpage` utility.

| textPage
| Sends a notice to a user's alphanumeric pager. +
Implemented as an external command using the `qpage` utility.

| xmppGroupMessage
| Sends a message to an XMPP group. +
Uses the in-process XMPP notification strategy.

| xmppMessage
| Sends a message to an XMPP user. +
Uses the in-process XMPP notification strategy.
|===

== Custom notification commands

You can edit `$\{OPENNMS_HOME}/etc/notificationCommands.xml` to customize and extend notification commands.

IMPORTANT: Use external binary notification commands sparingly, as they spawn additional process threads on your core {page-component-title} system.

=== Custom command configuration

The `streamed` attribute dictates whether the substitution text or switch text (or both) will be placed in the command line or in the input stream when the command starts to run.

.Place boilerplate arguments
[source, xml]
----
   <argument streamed="false">
      <substitution>-D</substitution>
   </argument>
----

.Place dynamic values
[source, xml]
----
   <argument streamed="false">
      <switch>-tm</switch>
   </argument>
----

When you combine the two (substitution and switch), each is written as a separate argument in the command line.
For example:

[source, xml]
----
   <argument streamed="false">
      <substitution>-Dnodeid=</substitution>
      <switch>-nodeid</switch>
   </argument>
Translates to:
   -Dnodeid= 8
and not:
   -Dnodeid=8
----

=== Valid switches from NotificationManager

The `NotificationManager` class defines some special switches, providing data for the class or command that is run:

[options="autowidth"]
|===
| Internal Name | Switch Name   | Source

| PARAM_DESTINATION
| -d
| From notification definition

| PARAM_EMAIL
| -email
| From user profile

| PARAM_HOME_PHONE
| -hphone
| From user profile

| PARAM_INTERFACE
| -interface
| From original event

| PARAM_MICROBLOG_USERNAME
| -ublog
| From user profile

| PARAM_MOBILE_PHONE
| -mphone
| From user profile

| PARAM_NODE
| -nodeid
| From original event

| PARAM_NUM_MSG
| -nm
| From notification definition

| PARAM_NUM_PAGER_PIN
| -np
| From user profile

| PARAM_PAGER_EMAIL
| -pemail
| From user profile

| PARAM_RESPONSE
| -r
| From notification definition

| PARAM_SERVICE
| -service
| From original event

| PARAM_SUBJECT
| -subject
| From notification definition

| PARAM_TEXT_MSG
| -tm
| From notification definition

| PARAM_TEXT_PAGER_PIN
| -tp
| From user profile

| PARAM_TUI_PIN
| -tuipin
| From user profile

| PARAM_TYPE
| -t
| Binary yes or no

| PARAM_TUI_PIN
| -tuipin
| From user profile

| PARAM_WORK_PHONE
| -wphone
| From user profile

| PARAM_XMPP_ADDRESS
| -xmpp
| From user profile
|===

=== Extended dynamic values

You can pass arbitrary parameters from the notification to the `notificationCommand` via the `<parameter>` tag.

== Examples

=== SnmpTrapNotificationStrategy

This configuration sends a {page-component-title} trap to an external system with the `nodelabel` in the varbind:

[source, xml]
----
    <notification name="snmpTrap" status="on">
        <uei>uei.opennms.org/nodes/nodeDown</uei>
        <rule>IPADDR IPLIKE *.*.*.*</rule>
        <destinationPath>trapNotifier</destinationPath>
        <text-message>
                All services are down on node %nodeid%.
        </text-message>
        <subject>node %nodeid% down.</subject>
        <numeric-message>111-%noticeid%</numeric-message>
        <parameter name="trapVersion" value="v1" />
        <parameter name="trapTransport" value="UDP" />
        <parameter name="trapHost" value="my-trap-host.mydomain.org" />
        <parameter name="trapPort" value="162" />
        <parameter name="trapCommunity" value="public" />
        <parameter name="trapEnterprise" value=".1.3.6.1.4.1.5813" />
        <parameter name="trapGeneric" value="6" />
        <parameter name="trapSpecific" value="1" />
        <parameter name="trapVarbind" value="Node: %nodelabel%" />
    </notification>
----

The parameters defined here are passed to the notification command as switches.
You can see these in the `notificationCommands.xml` file:

[source, xml]
----
    <command binary="false">
        <name>snmpTrap</name>
        <execute>org.opennms.netmgt.notifd.SnmpTrapNotificationStrategy</execute>
        <comment>Class for sending notifications as SNMP Traps</comment>
        <argument streamed="false">
                <switch>trapVersion</switch>
        </argument>
        <argument streamed="false">
                <switch>trapTransport</switch>
        </argument>
        <argument streamed="false">
                <switch>trapHost</switch>
        </argument>
        <argument streamed="false">
                <switch>trapPort</switch>
        </argument>
        <argument streamed="false">
                <switch>trapCommunity</switch>
        </argument>
        <argument streamed="false">
                <switch>trapEnterprise</switch>
        </argument>
        <argument streamed="false">
                <switch>trapGeneric</switch>
        </argument>
        <argument streamed="false">
                <switch>trapSpecific</switch>
        </argument>
        <argument streamed="false">
                <switch>trapVarbind</switch>
        </argument>
    </command>
----

You can define any or none of these parameters and switches.
If you define a parameter in the notification, however, you must define a corresponding switch in the notification command.
The defaults are as follows:

[source, properties]
----
trapVersion="v1" ("v1 or "v2c")
trapTransport="UDP" (only UDP for now)
trapHost="127.0.0.1" (any valid hostname or ip address)
trapPort="162" (any valid IP port)
trapCommunity="public" (any valid community string)
trapEnterprise=".1.3.6.1.4.1.5813" (any valid OID)
trapGeneric="6" (any valid generic ID)
trapSpecific="1" (any valid trapSpecific ID)
trapVarbind="OpenNMS Trap Notification" (any string or one or more valid %<event field>% such as "%eventUEI%" in the string)
----

The one allowed trap varbind will be sent with the object ID `.1.3.6.1.4.1.5813.20.1` and the `DisplayString` object type.
