Email Notification via Results Tab
Navigate to the Results tab for the form currently being worked on in the NextGen Designer. The completed report can be sent as a CSV, XML, or PDF to a specified email. Additional recipients may also be entered as well as the content of the email being sent. For details on how to send a custom email notification via scripting, continue reading below.
Custom Email Notifications
The instructions below refer to custom script-drive email notifications. If your email notification needs are satisfied by the Results tab (see above), you do not need to perform these steps.Overview
Starting in v11.1 of the Mi-Enterprise Middleware Server it is possible for a form to instruct the server to send a mail notification at a given time. It is also possible for multiple submitted form sessions to create a single mail message that contains data from all of the sessions. This can be useful if there's a desire to send a single report-style email per day based upon form submission. The mail notification API does not require the form's designer to know anything about the configuration of a mail server in order for the notifications to be sent. The rest of this article will walk you through the concept of mail notifications and provide examples for using them.
Concepts
There are two main objects that you will be interacting with when creating mail notifications from forms as described below.
Mail Notification
A single mail notification corresponds to a single emailed message. This message may have multiple recipients (separated by ;), but will have a single subject. Multiple submitted form sessions may combine to send a single mail notification.Mail Detail
A mail detail corresponds to data from a single submitted form session that provides content (body or attachments) to a single mail notification. These are used to provide form session specific data to a single email message.Example of Sending an Immediate Mail Notification
The following example shows how to send a mail notification immediately upon the form being submitted. It has a subject that contains the value of a field in the form and will attach a PDF export to the message. The code is within the form's AfterDataPathsRun .NET event:
<MiCode(FormScriptEventType.AfterDataPathsRun)> _
Public Sub Form_AfterDataPathsRun(ByVal e As AfterDataPathsRunEventArgs)
Try
' Create a new mail notification object
Dim m As New MiCo.MiApp.Server.MailNotification()
m.FormID = _form.FormID
' Set the subject to whatever we want the email message's subject to be. Note the use of a form field within the subject.
m.Subject = "Inspection for " & _repStateNumber.Value
' In this case our body will simplistically be this one line of text. Note that the body can use HTML markup as
m.Body = "<font face=""Arial"">An inspection was completed</font>"
' This indicates when the mail should be sent. Since we want it immediately, DateTime.Now is appropriate.
m.TargetDate = DateTime.Now
' Setting the sending user is optional. If left unset then the default user the server connects with to the mail server will be used. However, if set the specified user's real name is used as the sender.
m.SendingUser = "administrator"
' This will send the user to the current submitting user
m.To = _form.CurrentCredentials.Email
' This will also send the mail to every member of the Reviewers group
m.Groups = New String(0) {"Reviewers"}
' Register the mail notification with the server
Dim sr As MiCo.MiApp.Server.ServerResponse = _server.RegisterMail(m)
If (sr.Success = False) Then
Me.RecordExportResult("Mail-Notification", False, sr.Error.Exception.Message, sr.Error.Exception.Message, sr.Error.Exception.Message)
Return
End If
' Now create a mail detail. Even though we're sending this mail immediately rather than batching it up with other form sessions, we need this detail in order to do things like add attachments to the message
Dim md As New MiCo.MiApp.Server.MailDetail()
md.SessionID = _form.SessionData(0).SessionID
' We want the message to attach the output of the PDF datapath to the message
md.Exports = New String(0) {"PDF"}
' Register the mail detail with the server
sr = _server.RegisterMailDetail(sr.IntegerData, md)
If (sr.Success = False) Then
Me.RecordExportResult("Mail-Detail", False, sr.Error.Exception.Message, sr.Error.Exception.Message, sr.Error.Exception.Message)
Return
End If
Catch ex As Exception
RecordExportResult("Mail", False, ex.Message, ex.Message, ex.Message)
End Try
End Sub
Example of Sending A Report Once a Day
The following example shows how to send a mail notification once a day that combines information from all sessions submitted for a given form. It has a simple subject, but its body contains details from each submitted session as well as attachments for exports created from each session. The code is run within the form's AfterDataPathsRun .NET event:
<MiCode(FormScriptEventType.AfterDataPathsRun)> _
Public Sub Form_AfterDataPathsRun(ByVal e As AfterDataPathsRunEventArgs)
Try
Dim m As New MiCo.MiApp.Server.MailNotification()
m.FormID = _form.FormID
m.Subject = "Inspection Report"
' Note that the body has <<<TARGET>>> and <<<TARGET2>>> designations. These will be used as places where each mail detail replaces content
m.Body = "<font face=""Arial"">Inspections have been performed for the following equipment today<br><<<TARGET>>><p>Here are the defects:<<<TARGET2>>></font>"
m.Groups = New String(0){"Managers"}
m.SendingUser = "administrator"
' This indicates that the mail message should be sent tomorrow at midnight. Note that messages are considered unique by form ID and target date so if another form session has already registered this mail notification, this will not add a second notification, it instead will find the already registered one.
m.TargetDate = MiCo.MiApp.Server.ServerInterface.FormAPI.FormInterface.ToISO8601(New DateTime(DateTime.Today.AddDays(1))
Dim sr As MiCo.MiApp.Server.ServerResponse = _server.RegisterMail(m)
If (sr.Success = False) Then
Me.RecordExportResult("Mail-Notification", False, sr.Error.Exception.Message, sr.Error.Exception.Message, sr.Error.Exception.Message)
Return
End If
dim mailID as Integer = sr.IntegerData
Dim md As New MiCo.MiApp.Server.MailDetail()
md.SessionID = _form.SessionData(0).SessionID
' This is going to substitute in equipment and defect information where the <<<TARGET>>> appears in the notification registered above. Note that each session will add this substitution so the message will have the cumulative data from all sessions.
md.SubstitutionTarget = "<<<TARGET>>>"
md.SubstitutionValue = "<li>" & _Equipment.Value & " (" & _Defects.Value & ")"
' Add multiple attachments to the message per session
md.Exports = New String(2){"XML", "CSV", "PDF"}
sr = _Server.RegisterMailDetail(mailID, md)
If (sr.Success = False) Then
Me.RecordExportResult("Mail-Export-Details-1", False, sr.Error.Exception.Message, sr.Error.Exception.Message, sr.Error.Exception.Message)
Return
End If
' If the form has defects recorded, we're going to add those as well where the <<<TARGET2>>> appears in the registered body
If _Defects.Value = "Yes" Then
md = New MiCo.MiApp.Server.MailDetail()
md.SessionID = _form.SessionData(0).SessionID
md.SubstitutionTarget = "<<<TARGET2>>>"
md.SubstitutionValue = "<li>" & _Equipment.Value & " -- " & _DefectDetails.Value
_Server.RegisterMailDetail(mailID, md)
If (sr.Success = False) Then
Me.RecordExportResult("Mail-Export-Details-2", False, sr.Error.Exception.Message, sr.Error.Exception.Message, sr.Error.Exception.Message)
Return
End If
End If
Catch ex As Exception
RecordExportResult("Mail", False, ex.Message, ex.Message, ex.Message)
End Try
End Sub
Assuming 2 inspection form sessions were submitted 1 with defects, and 1 without, the resulting message body would look similar to the following:
Inspections have been performed for the following equipment today
- Equipment 1 (No)
- Equipment 2 (Yes)
Here are the defects:
- Equipment 2 -- Broken propeller blade