Sending SQL notifications with CDOSYS

Desiree Harris
July 27, 2004

While SQL Server has a very mature set of tools, one thing that is lacking is the ability to send a simple email alert based
on a pre-defined set of rules. At first glace, it appears that email notifications exist but what becomes a problem to many
people is the requirement for a MAPI subsystem to be present on the server. This means that Outlook or an equivalent
program has to be installed on the server. Not only that, to properly configure it, the administrator will need to log into the
server as the user that the SQL Server service is running under. I have always found this inconvenient so I set out to
create a stable, free, easy to configure means of accomplishing the same thing without installing anything special on the
server. I've included steps below to complete this task successfully.

Before we start, a SMTP server needs to be available. This can be setup on the server itself, on another server within the
local network, or outside the network. To install an SMTP service on the SQL Server, ensure that IIS SMTP Services are
installed. You can do so from Add/Remove programs in the Control panel. Once it is installed, '127.0.0.1' will need to be
added to 'relay' on the 'access' tab in the SMTP Properties. Alternately a SMTP server of another mail server can be used
instead. This information will need to be added to the 'sp_send_cdosys' stored procedure we'll create later.

First we need to create the stored procedure to send the e-mail. This can be done with Enterprise Manager and Query
Analyzer. For our example, we'll implement the job with Enterprise manager using the Northwind database.

In Enterprise Manager, expand the Northwind database, select and right-click on 'stored procedures', and then select 'New
Stored Procedure… '. Note: This can also be added to the Master database so that it is available for all databases.

Delete the contents in the box, and copy and paste the contents below in the stored procedure box (everything between ' -
-- ').

Note: The sp_send_cdosysmail stored procedure uses ‘sp_OACreate' and ‘sp_OASetProperty' stored procedures; this will
require the user account running it to have SA permissions.

-------------------------------------

CREATE PROCEDURE [dbo].[sp_send_cdosysmail] @From varchar(100) , @To varchar(100) , @Subject

varchar(100)=" ", @Body varchar(4000) =" " /******************************************
This stored procedure takes the parameters and sends an e-mail. All the mail configurations are hard-coded in the
stored procedure. Comments are added to the stored procedure where necessary. References to the CDOSYS
objects are at the following MSDN Web site: http://msdn.microsoft.com/library/default.asp?url=/ library/en-
us/cdosys/html/_cdosys_messaging.asp

*******************************************/

AS Declare @iMsg int Declare @hr int Declare @source varchar(255) Declare @description varchar(500) Declare
@output varchar(1000)

--***** Create the CDO.Message Object *****

EXEC @hr = sp_OACreate 'CDO.Message', @iMsg OUT

--*****Configuring the Message Object *****

-- This is to configure a remote SMTP server.

-- http://msdn.microsoft.com/library/default.asp?url=/library/en-
us/cdosys/html/_cdosys_schema_configuration_sendusing.asp
EXEC @hr = sp_OASetProperty @iMsg, 'Configuration.fields
("http://schemas.microsoft.com/cdo/configuration/sendusing").Value','2'

-- This is to configure the Server Name or IP address.

-- Replace MailServerName by the name or IP of your SMTP Server.

EXEC @hr = sp_OASetProperty @iMsg, 'Configuration.fields("http://schemas.
microsoft.com/cdo/configuration/smtpserver").Value', 'MailServerName'

-- Save the configurations to the message object.

EXEC @hr = sp_OAMethod @iMsg, 'Configuration.Fields.Update', null

-- Set the e-mail parameters.

EXEC @hr = sp_OASetProperty @iMsg, 'To', @To
EXEC @hr = sp_OASetProperty @iMsg, 'From', @From
EXEC @hr = sp_OASetProperty @iMsg, 'Subject', @Subject

-- If you are using HTML e-mail, use 'HTMLBody' instead of 'TextBody'.

EXEC @hr = sp_OASetProperty @iMsg, 'TextBody', @Body
EXEC @hr = sp_OAMethod @iMsg, 'Send', NULL

-- Sample error handling.

IF @hr <>0
select @hr
BEGIN
EXEC @hr = sp_OAGetErrorInfo NULL, @source OUT, @description OUT
IF @hr = 0
BEGIN
SELECT @output = ' Source: ' + @source
PRINT @output
SELECT @output = ' Description: ' + @description
 PRINT @output
END
ELSE
BEGIN
PRINT ' sp_OAGetErrorInfo failed.'
RETURN
END
END

-- Do some error handling after each step if you have to.

-- Clean up the objects created.
EXEC @hr = sp_OADestroy @iMsg
GO

-----------------------

Once you have copied the stored procedure into the box, find the line below within the code.

EXEC @hr = sp_OASetProperty @iMsg,

'Configuration.fields("http://schemas.microsoft.com/cdo/configuration/smtpserver").Value', 'MailServerName'

Replace 'MailServerName' with either 'localhost' or your 'SMTPMailServer'.

Be careful of word wrapping. When pasting from my example you may find that some lines wrap. You may need to double
check the lines to make sure nothing wrapped that shouldn't have.

Next, as an example we will create a job that will backup the Northwind database, then send a notification via e-mail when
it completes successfully.

In Enterprise Manager, open 'Management' > 'SQL Server Agent', and then select and right-click on 'Jobs', and select 'New
Job… '.

On the 'General' tab name the job 'Backup Northwind'.

On the 'Steps' tab, click on 'New', enter the information below, and then click OK. (The path should be a path that exists
on the SQL Server.)
This is what you should see after you click 'OK'. Notice that the 'On Success' column says 'Goto next step' (this is ok,
because we are about to create another step) and the 'On Failure' column says 'Quit with failure' (this is ok, because if the
job fails, we don't want it to go to the next step).

Now we'll add the job step that will notify us that the job has completed.

Click 'New…' and add the information below (everything between ' --- ').

----------------------------------------

Name: SendNotification
Database: Northwind
Command: EXEC sp_send_cdosysmail
'[email protected]*',
'[email protected]*',
'subject*',
'I've added an example message for you*
Team,

The Northwind database has been backed up successfully.

Thank you,
ORCS Web '

----------------------------------------

*fill in the fields with the desired information.

Click on the 'Advanced' tab and change the 'On Success' box to 'Quit the job reporting success' and then click 'OK'.

This is what the job should look like now.

For our purposes, the 'Schedules' and 'Notifications' tabs default settings are fine; we will not need to make any changes.
Click 'OK' and your job should appear in the job window.

Now, right-click on the job we just created and click 'Start Job'.
Make sure that the Job step named 'Backup' is selected then click start. When the job complete, you will be sent an email
notification that looks like this.

Now, even though email notifications can be setup as a 'job step' you can also setup an alert based on a SQL Server event
that will send an email and include details of the event. Next we will setup an alert that will send an email notification with
details.

In Enterprise Manager, open 'Management' > 'SQL Server Agent', and then select and right-click on 'Jobs', and select 'New
Job… '.
On the 'General' tab name the job 'SQL Server Severity Alert Notification'.

On the 'Steps' tab, click on 'New', name it 'SendEmail' and enter the script below (everything between '--').On the
'Advanced' tab, change the 'on success action' to 'Quit the job reporting success' and click 'OK'.

---------
DECLARE @msg nvarchar(4000)
Set @msg = REPLACE("Error: [A-ERR]
Severity: [A-SEV]
Date: [STRTDT]
Time: [STRTTM]
Database: [A-DBN]
Message: [A-MSG] ", "'", "") --'

EXEC sp_send_cdosysmail '[email protected]*',

'[email protected]*',
'subject*',
@msg
----------

*fill in fields with desired information

I guess you're wondering what the script does. The script takes advantage of the power of agent tokens, which will be
automatically filled in at runtime. You can get more information about agent tokens
here:http://www.sqldev.net/sqlagent/SQLAgentStepTokens.htm

The 'Schedules' and 'Notifications' tab don't need any changes at this time; let's click 'OK' again to complete the job.

Next we'll create the alert that will run the job we just created when an event occurs. In Enterprise Manager, open
'Management' > 'SQL Server Agent', and then select and right-click on 'Alerts', and select 'New Alert… '.

On the 'General' tab name the job 'SQL Server Severity Alert'. We'll leave the severity level at 010 as it will return
information and isn't specific to an error and we'll let this alert fire for all databases.

On the 'Response' tab, put a check in the box for 'Execute job', select the job we just created, 'SQL Server Severity
Notification', and then click 'OK'.

Now, we are ready to test. Let's backup the Northwind database in Query Analyzer with the script below:

Use master
BACKUP DATABASE Northwind TO DISK = 'c:\temp\northwind.bak*'

*ensure the path exists on the SQL Server

This task will execute the alert. At this point, an email should appear in the inbox of the email address you specified in the
script. I've included an example below.