Notifications are a fundamental component of the IssueNet platform. Understanding how notifications are processed can aid in the planning and troubleshooting of notification service configurations. The scope of this article is to describe the mechanics of how a Notification Action results in an actual email item. The construction of Notification Actions and their execution rules is outside the scope of this article.

In this article we will discuss;

• Notifications Overview
• What is MSMQ
• Creating and Managing Notification Queues
• Administrating MSMQ Queues
• Configuring Notification Actions
• Troubleshooting

All notifications are a result of a Notification Action. There are many operations such as an item update or workflow transition that might result in the execution of a Notification Action. Notification Actions generate an MSMQ message with the proper information such as;

• Who the recipients are
• Who the message is from
• What notification template to use
• What priority the message should be sent as
• What IssueNet item the notification was in regards to
• What Notification Action triggered the event

The process by which a Notification Action becomes an actual email follows these steps;

1. A Notification Action generates a properly formatted MSMQ message.
2. The IssueNet platform inserts the MSMQ message into the MSMQ queue.
3. The IssueNet Notification Service reads the incoming MSMQ message.
4. The IssueNet Notification Service transforms the MSMQ message into a properly formatted email message.
5. The IssueNet Notification Service sends the email message to the SMTP server.
6. The IssueNet Notification Service clears the MSMQ message from the MSMQ queue.

At the core of the notification process is the Microsoft Message Queuing service (MSMQ). MSMQ is a component of all supported Microsoft operating systems and does not have a separate license requirement. If you are using a web service connection for communication to the IssueNet database the machine running the web service must have MSMQ installed, be able to address the MSMQ queue, and have privileges to insert MSMQ messages. If you are using a direct connection for communication to the IssueNet database, then your client machine must have MSMQ installed, be able to address the MSMQ queue, and have privileges to insert MSMQ messages.

To install MSMQ on a machine, open Add/Remove Programs under Control Panel. Click the Add/Remove Windows Components button then check the Message Queuing option in the Windows Component Wizard. Click the Next button and MSMQ will be installed.

MSMQ privileges are administrated using the Computer Management console. Open Computer Management through Control Panel | Administrative Tools then open the Services and Applications node. If MSMQ is installed, you will see the Message Queueing node. Navigate under this node to locate and select the MSMQ queue created from the IssueNet Service Manager. Select menu option Actions | Properties and then select the Security tab. At this point you can add the user or groups that will be using the MSMQ queue for IssueNet. In the case of the web service connection, it will be the user name that is being used for authentication of the web service itself.

Before Notification Actions can be succesfully processed, an IssueNet Notification Queue must be created where the Notification Actions can insert MSMQ messages. To do this, open the IssueNet Service Manager on the machine that will host the MSMQ queue. Navigate to the Queues node under the Notification node in the Service Browser window. Select the File | New | Queue menu option. Rename the queue so that it has some meaning to your environment.

Note: The name you give the Message Queue in the IssueNet Service Manager is a logical name only and has no bearing on either the actual MSMQ queue name or the Notification Action queue name.

Open the IssueNet Notification Queue by right mouse clicking on the node and selecting the Properties... menu option. The Queue Path property points to the actual MSMQ queue the local IssueNet Notification Service will use to listen for and process incoming MSMQ messages.

Note: A fully qualifed path would typically follow a format FormatName:DIRECT=OS:[MachineName]\Private$\IssueNet. Please refer to the online documentation for complete information regarding Notification Queue Property values and fully qualified path names.

Note: The notification service queue path value may differ from the queue path given in the Administrator settings for Notification Actions. The reason for this is the queue path is relative to the process communicating to MSMQ. Typically the notification service is running on the same machine as the MSMQ queue and can address the MSMQ using a local queue path notation such as .\Private$\IssueNet. It is a good idea to fully qualify MSMQ queue paths in both the IssueNet Service Manager and in the IssueNet Administrator to avoid confusion.

Typically, creating the Notification Queue through the IssueNet Service Manager is sufficient for getting notifications working. It may be necessary though to administrate the MSMQ security settings to allow MSMQ messages to be inserted.

To administrate the security settings of the MSMQ queue, open the Computer Management Console in Control Panel. Navigate to the Services and Applications | Message Queuing node. Look for the MSMQ queue created in this area. Typically this will be under the Private Queues subfolder. Select the MSMQ queue and select the Action | Properties menu option. Select the Security tab and ensure that access has been given to the users or groups that will be using IssueNet.

Note: If you are using a web service connection, the required permissions will be governed by the web service security context.

Once the IssueNet Notification Service is configured and running using the IssueNet Service Manager the users must be configured to send their Notification Action messages to these MSMQ queues. This is centrally managed through the IssueNet Administrator.

Notification Actions specify a logical queue name that they wish to use when the Notification Action is triggered. The logical name is used so that if an MSMQ path is changed, only the logical Notification Action queue path needs to be updated as opposed to updating each Notification Action.

To specify the correct Notification Queue Path for your environment logon to your IssueNet database using the IssueNet Administrator and select the Notification Queues section under the Tools|Options... menu option. Typically only one notification queue need be created, but IssueNet supports multiple queues for the same database for situations where different MSMQ queues are utilized for different types of notifications.

Select the Notification Queue of interest and select the Configure... button. The notification queue name property must match the Notification Action queue property. By default this value is name Default. You should not rename this unless you plan to rename all the relavent Notification Actions Queue property as well. The MSMQ path should be the fully qualified path to the MSMQ queue. This queue path value is used by the web service connection or direct connection when the Notification Action is processed.

Please refer to the online documentation for information regarding fully qualified MSMQ path formats.

There are several working parts to the notification process. If notifications are not being generated as expected it is best to test the steps of the notification process from the triggering of the Notification Action to the actual email item being sent.

1. Determine if the Notification Queue has been suspended.
   1. Open the Event Viewer on the machine running the notification service and select the Application events node.
   2. Look for warnings or errors from the Elsinore Notification Service. They will provide descriptions on what caused the warning or error. There will be several events describing a successful startup or shutdown of the Notification Service.
   3. Rectify the problem described by the events and restart the service.
2. Determine if the MSMQ is configured correctly.
   1. Open the IssueNet Service Manager.
   2. Open any notification template.
   3. Select the Tools | Send Test Notification... menu option.
   4. Select the queue to be tested and enter a valid email address to send the test notification to then click OK.
   5. If an email does not get delivered to that address make sure the Elsinore Notification Service is running and examine the security privileges on the MSMQ queue.
3. Determine if the Notification Action definition has invalid values.
   1. Open the IssueNet Service Manager.
   2. Select the Notification Queue in the Service Browser window.
   3. Right mouse click and select the Properties... menu option.
   4. Enable Logging on the General tab and click OK.
   5. Select the Tools | Restart Service menu option.
   6. Examine the log output located in the Document and Settings\All Users\Elsinore Technologies directory. The name of the log file will be in the form of issueNetYYYYMMDD.log.
   7. Rectify any problems documented in the log file and restart the service.
4. Determine if the Notification Action is actually triggered.
   1. Logon to the IssueNet client
   2. Open the output window by selecting the View | Output menu option.
   3. Perform the action that you would expect a Notification to be generated from.
   4. Examine the output window for the notification action output.
   5. If there is no output regarding a notification action then the Notification Action definition is incorrect and should be rectified through the IssueNet Administrator.
5. Determine if the Notification Action is able to insert the MSMQ message in the queue.
   1. Open the IssueNet Service Manager
   2. Selecting the Tools | Stop Service menu option. MSMQ messages can still be inserted in the queue but they will not be processed until the notification service is started.
   3. Open the Computer Management Console from Control Panel and navigate to Message Queuing | Private Queues | | Queue messages. Count the number of messages currently in this queue on the right.
   4. Force the Notification Action as specified above.
   5. Right mouse click in the MSMQ queue messages list in Computer Management Console and select Refresh.
   6. Examine the number of MSMQ messages now in the queue. If there are no new messages then either the client did not have privileges to insert the MSMQ message or the Administrator configuration is pointing to the wrong queue path.
   7. Rectify the problem and restart the service.

Web Service Security Configuration
MSMQ: Frequently Asked Questions