Component Example 4: Sending an email

This example shows how travel guides are automatically notified by email whenever they are scheduled on a particular scheduled tour.

Technically, the email is sent when the record is stored (at record validation), since this is when the Rules Engine processes transitional multi-record constraints. If a rollback subsequently occurs, the mail action cannot be revoked. If you want to tie the mail action more closely to the commit event, you can present the user with a confirmation dialog at commit time, or you can flag the record and invoke the component later on the basis of the flag, or process mailing through a separate batch job in a separate transaction.

The example uses the Travel Agency case (Expanded Version).

Component

Query protocol association

Constraint

Set the SQL statement to:

INVOKE    usmail.send_mail    /* email address, subject, message-text */ WITH
SELECT    
p.email,
    'Tour guide',
    'Dear ' || p.first_name ||
',
With this mail we would like to inform you that we have scheduled you as a guide on a tour to ' || s.destination || '.
Please contact the office as soon as possible for details.
Kind regards,
The Travel Agency.
'
FROM    person    p,
    schedtour    s
WHERE    s.guide = p.person_id
AND    p.email is not null
AND    ( s.guide != old(s.guide)
      or old(s.guide) is null
    )

Code of invoked subprogram

The component sends an email message to a Microsoft Exchange account using Microsoft's standard MAPI component. The recipient account depends on the input parameters of the INVOKE. The component then returns 0 (no violation) if the operation concludes normally, or -1 if an error occurs.

Visual Basic code of subprogram directly invoked by USoft:

Const USOFT_STATUS_VIOLATION = 1
Const USOFT_STATUS_NO_VIOLATION = 0
Const USOFT_STATUS_ERROR = -1
Public Function send(address As String, _
                        Optional subject As String, _
                        Optional text As String, _
                        Optional password As String, _
                        Optional profile_name As String, _
                        Optional silent As Boolean) _
                        As Long
   ' Initialize this function to return a violation
   send = USOFT_STATUS_VIOLATION
   Dim objSession As Object
   Dim objMessage As Object
   On Error GoTo on_error
   ' Apply defaults for optional arguments
   If IsNull(silent) Then
      silent = False
   End If
   ' Create a objSession
   Set objSession = newSession(profile_name:=profile_name, _
                                 password:=password, _
                                 no_mail:=False)
   ' Create a new message
   Set objMessage = newMessage(objSession, address)
   If Not IsNull(subject) Then
      objMessage.subject = subject
   End If
   If Not IsNull(text) Then
      objMessage.text = text
   End If
   objMessage.Recipients.Resolve
   objMessage.send
   If Not silent Then
      MsgBox "Email successfully sent to " & address & "."
   End If
   cleanUp objSession, objMessage
   send = USOFT_STATUS_NO_VIOLATION
   Exit Function
on_error:
   If Not ignoreError() Then
      showError "send"
      send = USOFT_STATUS_ERROR
   End If
   cleanUp objSession, objMessage
End Function