TaskCentre Exchange Agent – How to create a subscription to monitor a mailbox

Introduction #

This knowledge base article will outline how an inbox for a specified mailbox can be monitored. This is achieved by calling the stored procedure Subscribe located within the MSEventAgent database. This will supply the event agent database with a subscription which will then be automatically maintained in Exchange. Any events that occur within Exchange for the mailbox will be written back into the event agent database.

Global Configuration – Creating a Call Procedure Database Connection #

A Call Stored Procedure (OLEDB) connection to the event agent database must first be configured. This will allow the tool to call stored procedures from the database. Please follow the below link for instructions on configuring database connections: Global Configuration – ODBC /OLEDB connections

Creating a New Subscription #

Before beginning make sure the account/email address you wish to monitor has access permissions from the account you setup the agent with.

1. 1. Within the TaskCentre client create a task using the tool Call Stored Procedure (OLEDB).
   2. Select the Main tab and using the Connection Used drop down list, select the event agent database connection.
   3. Using the Browse button select the stored procedure Subscribe.

Parameters Overview #

Once the stored procedure has been called the Parameters table will become populated with parameters which will be used to map information to the database table RequestedSubscriptions. The parameters are as follows: @EmailAddress – The email address of the mailbox to be subscribed to @IsGroup – This parameter is a Boolean property, therefore a 1 or a 0. IsGroup is designed to specify whether the inbox you’re subscribing to is a group inbox. For example, if you’re subscribing to your personal inbox this would be set to 0. It would be set to 1 for a group inbox. @ObjectOrFolder – The part of the mailbox to be monitored, for example the Inbox or Calendar. Either a WellKnownFolderName or an Exchange Folder ID is entered here. Well known folder names are items such as Inbox, Calendar, Contacts, DeletedItems etc. A list of valid items can be found here.

Exchange folder IDs are the internal reference used by Exchange and have a long format such as:

AQMkADU4ZWYwZjdjLWJiADlmLTQwMWUtYjkyMy04MzRkOWFlMWU3NTEALgAAAxJopBjvmAJNvGHhmqaZ3DQBABU2zOrHroBJqBr5EBjL108AAAISGwAAAA===

@Created – Event required when an object or folder is created in the mailbox. @Deleted – Event required when an object or folder is deleted in the mailbox. @Modified – Event required when an object or folder is modified in the mailbox @Copied – Event required when an object or folder is copied in the mailbox @Moved – Event required when an object or folder is moved in the mailbox @ StatusFrequency – This field is an integer (in minutes) between 1 and 1440. This is the interval between attempts for Exchange to send a notification to the URL specified in the Agent configuration. @ID – Represents the ID that the Agent will use to manage this subscription. The ID is the output of the subscription that is to be processed and is created upon successful completion of the stored procedure. @Succeeded – Represents whether the stored procedure executed successfully or not. @ErrorMessage – If succeeded = False then this return field will be populated with the SQL Server error message associated with the problem encountered.

• Within the Value column, set the parameter @Emailaddress to the mailbox account you wish to monitor.
• Set the parameter @IsGroup to 0 as the account is not a group.
• Set the parameter @ObjectOrFolder to Inbox, if you want to monitor a subfolder then you will need to know the folder ID and not the folder name.
• Using values of 0 and 1 where 1 = yes/true and 0 = no/false, set any of the following parameters to trigger events:@Created @Deleted @Modified @Copied @Moved
• The last option you need to set is the parameter @StatusFrequency. For an idea of what to set, it is best to wait at least twice the time of the expected time out before re-issuing the PUSH request. Push subscription notifications will be sent until the maximum number of minutes is reached (specified by the StatusFrequency element).The way it works is that the initial notification should be tried right away, if that fails then the next try is in 30 seconds.
  After that, the next retry is double the prior one… 30, 60, 120, 240 seconds… Each retry is basically the “frequency” of retries. The retries are done until the frequency you specified is reached. Note that the actual time of when the PUSH occurs may be delayed by other load sever, so the expected PUSH time is not exact. The default retry with the Exchange Web Service is 30 seconds. The Exchange managed API has a default of 30 minutes – that’s six retries.

• Once the required parameter fields have been completed. Close and run the task.

This will now create a subscription in the table RequestedSubscriptions within the event agent database. Any events that now occur within Exchange for the specified mailbox will be written to the Notifications table by the event agent.

Example #

When a new email is created it will insert a row into the table similar to the following: AgentNotificationID row 36:

What this row tells you is that RequestedSubsciptionId = 19, this links to the Subscription in the ExchangeSubscription table. The ItemID is the key for the email itself. You will need this to complete a Get on the message using the exchange connector. You can also see that the Processed and ProcessedOn columns are set to NULL. This is set when the item is created. After the item has been processed you can update the 2 fields by calling the stored procedure UpdateNotifications

You will need to pass the AgentNotificationID which in this case is 36. The @ProcessedValue is a value for your reference only. By calling this stored procedure it also sets ProcessedOn with the date and time. It should then look like the following: