Message API - quandis/qbo3-Documentation GitHub Wiki

The Message module provides for:

• Adding messages to any object within QBO
• Outbound email processing (SMTP integration)
• Outbound texting (SMS)
• Inbound email processing (POP3 and IMAP)
• Inheritance-based inboxes
• Templates (canned messages)

Message Templates allow you to create "canned" or "mail merged" messages. For example:

-- Create a template ('canned message') that applies to a Contact; form elements have newlines for readability
POST MessageTemplate/Save
MessageTemplate=Welcome Email
&Subject=Welcome {FirstName}!
&Object=Contact
&BodyHTML=<p>We're glad you're interested in our products!</p>

-- Create a new Contact
POST Contact/Save
FirstName=Alice&LastName=Anderson&[email protected]

-- Send Alice a welcome email
POST Message/Save
Object=Contact&ObjectID=1&Template=Welcome Email

Note: The Subject and Body may use "mail merge" fields by using curly braces around a field name (e.g. {FirstName} The fields available are determined by the object the message applies to (in this case, a Contact).

You may also pre-determine the To, Cc and Bcc recipients:

Three examples of recipients:

QBO sends outbound email via one or more providers, such as SMTP or Amazon's SES.

In the example below, we configure QBO to send email via Gmail by creating:

1. A MailOutbound.config entry referencing QBO's qbo.Message.Providers.Smtp provider, and
2. A Credential entry providing QBO the Gmail credentials to use when sending email.

<ConfigurationEntryCollection>
  <ConfigurationEntryItem>
    <ConfigurationEntry>MailOutbound.config/Google</ConfigurationEntry>
    <Source>MailOutbound.config</Source>
    <ConfigurationType>qbo.Message.Configuration.MailOutboundCollection</ConfigurationType>
    <ConfigurationKey>Google</ConfigurationKey>
    <ConfigurationXml>
      <MailOutbound Name="Google" Host="smtp.gmail.com" Port="587" EnableSsl="true" Type="qbo.Message.Providers.Smtp, qbo.Message"/>
    </ConfigurationXml>
  </ConfigurationEntryItem>
  <ConfigurationEntryItem>
    <ConfigurationEntry>Google SMTP</ConfigurationEntry>
    <Source>Credential.config</Source>
    <ConfigurationType>qbo.Application.Configuration.CredentialCollection</ConfigurationType>
    <ConfigurationKey>Google SMTP</ConfigurationKey>
    <ConfigurationXml>
      <Credential Name="GoogleSMTP" UriPrefix="smtp://smtp.gmail.com" AuthType="Basic" Username="{your user name}" Password="{your password}" />
    </ConfigurationXml>
  </ConfigurationEntryItem>
</ConfigurationEntryCollection>

The Message module can be configured to monitor email accounts, and import emails sent to these accounts as messages and attachments. Configuration includes:

• Creating MailInbound configuration entries to identify email accounts to monitor, and define how to deal with emails found in these accounts.
• Create statements used to bind a Message created from an email to a parent object, usually based on the email subject.
• Leverage an IMailInbound plugin (current qbo.Message.Rebex) to handle processing of emails over using POP3 or IMAP.

Once configured, the Message/Receive method signature will iterates through each configured email account, and calls the underlying code to process the email inbox.

The key to effective email processing is figuring out what object to attach the Messages or Attachments to. This is done by leveraging either standard or custom statements. Typically, a SmartSearch is performed based on the email subject line, and the highest weighted match is chosen as the Object/ID for the message. If no match is found, the Message can be attached to a "default" object to act as a global inbox.

Assume a client named Acme Loan Servicing uses is loan-centric QBO installation (that is, most users spend their day working from Loan/Summary). They may set up an email address [email protected], and provide Quandis with the credentials to access that email account. The standard Message/BindBySubject statement can be used to bind an email to a Loan by scanning the subject line for either a Loan number or a Property Address.

If Acme starts doing a lot of title work (that is, some of their users start working from Title/Summary in addition to Loan/Summary), they have two options to determine whether messages get routed to a Loan vs. a Title:

• They can extend the BindBySubject statement to Smart Search on Title rows as well as Loan rows, or
• They can create another email account ([email protected]), and configure that account to use a different statement (BindTitleBySubject)

The later method is preferred, as it is easier to resolve conflicts between matching identifiers.

The configuration for inbound mail for the above scenario might look like this:

<MailInbound>
 <Accounts>
   <Account Name="Loans" MessageStatement="BindBySubject" Host="pop.gmail.com" Port="995" Account="[email protected]" Password="myLoanPassword" Type="qbo.Message.Rebex.Pop, qbo.Message.Rebex"/>
   <Account Name="Titles" MessageStatement="BindTitleBySubject" Host="pop.gmail.com" Port="995" Account="[email protected]" Password="myTitlePassword" Type="qbo.Message.Rebex.Pop, qbo.Message.Rebex" />
 </Accounts>
</MailInbound>

Specific properties of an Account include:

One can create a MessageRecipient, with the ReadRequired bit set to true. This will cause a message to appear in the individual's inbox, with a visual indication that they must read the message. When the user views the message, the system will mark the MessageRecipient.ReadDate, providing an audit trail proving the user read the message.

QBO systems are used to coordinate work across multiple organizations. Frequently, a client requires that someone within a vendor's organization acknowledges receipt of a message, but they do not care who. In this case, a MessageRecipient targeting a Group can be created, and any member of the group can mark the message as read. After one member of the group acknowledges the message as read, it is considered read by the entire group; other users reading it makes no technical difference.

-- Require anyone from a specific company (OrganizationID 15) to acknowledge MessageID 13
MessageRecipient/Save?MessageID=13&RecipientObject=Organization&RecipientObjectID=15

-- Require anyone from a department (CollectionID 3) to acknowledge MessageID 13
MessageRecipient/Save?MessageID=13&RecipientObject=Collection&RecipientObjectID=3

-- Require anyone from a brokerage (BrokerID 2) to acknowledge MessageID 13
MessageRecipient/Save?MessageID=13&RecipientObject=Broker&RecipientObjectID=2

In some cases, one wishes every single member of a group to explicitly acknowledge receipt of a message. In this case, one would add a MessageRecipient row for each user that is a member of the group. For example, one may require all Brokers to acknowledge a change to terms of service. If there are 12000 brokers in the system, this implies the creation of 12000 MessageRecipient rows, each tracking it's own Read date, rather than a single MessageRecipient row targeting the Broker role.

Standard QBO installations include a plugin that implements the IMailOutbound around Twilio to provide two-way SMS.

This can be invoked via:

Message/Send?Subject=Hello World!&[email protected]&Provider=SMS

Note: that the Message module requires that From, To, Cc, and Bcc address be formatted as email addresses. The Twilio plugin simply strips the phone from from the front of the email address.

Similarly, you can SMS any Twilio number that posts messages to Message/Twilio.ashx/ReceiveSMS, and a Message will be added to the Message table containing the SMS message.

To SMS-enable a QBO 3 system via Twilio:

• Create an account on Twilio
  • Configure at least one number to post messages to Message/Twilio.ashx/ReceiveSMS
• From the QBO 3 system:
  • create a MailOutbound configuration entry pointing to Twilio (example below)
  • create a Credential using the Twilio AccountSid and AuthToken

Sample MailOutbound.config entry:

-- Sample MailOutbound configuration entry
<MailOutbound Name="SMS" Host="https://api.twilio.com/2010-04-01/+14242171014" EnableSsl="true" Type="qbo.Message.Twilio.SMS, qbo.Message.Twilio"/>

-- Sample Credential configuration entry
<Credential UriPrefix="https://api.twilio.com/2010-04-01" AuthType="Basic" Username="AC7612***" Password="732***"/>

Note: The Twilio phone number should appear to the right of the main API Url in the Twilio interface. The main API Url will change if Twilio rolls out updates; this is data-driven in qbo.Message.Twilio.Settings.APIUrl.

Use cases for SMS integration include:

• Two-factor authentication with the qbo.Security module
• Sending an SMS to real estate brokers when a BPO is available for acceptance
• Notifying a borrower that a Loan Modification or Short Sale status has changed
• Notifying a client's IT resources when an import routine has been completed

Application settings are standard settings built into a class that can be overridden by a configuration file.

These settings can be maintained from Design > Configuration > Installed Modules > Message > Settings.