How to Configure Mail Notifications from Forms in Ideagen Smartforms

  Who is this article for?  

  Ideagen Smartforms users connecting for the first time.

  Connection information is required.

There are two methods of configuring email notifications:

1. The Results Tab
2. Custom Email Notifications

This article outlines how to configure both options.

Important Note: Custom email notifications are only available when running Mi-Enterprise Middleware Server 11.1 or higher.

1. The Results Tab

Navigate to the Results tab for the form currently being worked on in the Ideagen Smartforms 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. 

2. Custom Email Notifications

The steps below outline how to configure custom script-drive email notifications. If your email notification needs are satisfied by the Results tab then you do not need to perform these steps.

Reminder: These steps are only available when running Mi-Enterprise Middleware Server 11.1 or higher.

Custom email notifications allow 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.

There are two main objects that you will be interacting with when creating mail notifications from forms as described below.

1. 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.
2. 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.

3. 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 = "An inspection was completed"

  ' 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

4. 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 <<>> and <<>> designations. These will be used as places where each mail detail replaces content
  m.Body = "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 <<>> 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 = "<<>>"
  md.SubstitutionValue = "
  
  ' 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 <<>> appears in the registered body
  If _Defects.Value = "Yes" Then
    md = New MiCo.MiApp.Server.MailDetail()
    md.SessionID = _form.SessionData(0).SessionID
    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 <<>> 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