Setup for opentaps email Handling

The Special opentaps Email Client

This section discusses special opentaps processing for email, which can be configured by a technical system administrator.

opentaps includes an email client with some special features that present your business email as a part of the context for teamwork and coordination.

With this processing, users can go to their Pending Emails Screen in CRMSFA > [My Home] and see all the business emails which have been assigned to them, including those sent to a standard email address. Users can view the emails, respond to them, assign them to someone else, mark them as completed, or delete the emails. If the emails are assigned to another user, it will show up on their Pending Emails Screen as well. Once an email is marked as completed, it will disappear from Pending Emails Screens and can no longer be assigned, modified, or deleted.

Each email is also associated with business processes your team is working on, and they will see these emails on the summary page of any Lead, Contact, Account, Case, Activity, Opportunity, Quote, or Order to which the email is relevant. The emails are made part of the context and history of the business processes.

Thus, it is well worth the effort to set up email in order that the user's email can appear in the activity information for all business transactions (Cases, Orders, Accounts, etc.) on the system.

opentaps email makes use of your existing outbound email service (SMTP) and your existing inbound email service (POP3, or IMAP) when the users email IDs are entered in opentaps by Setting User Profile, and the email server address and server authentication info are configured into the relevant opentaps system files. Also, a regular expression string is configured to provide for detecting the email addresses that are relevant to your opentaps business processing.

Some minor additional configuration of your inbound email server software is required to route email to the opentaps special address for inbound email reception.

When your outbound email is copied to this special address it is archived in context with the related opentaps transactions similar to the inbound email as we have discussed.

Finally, the teamwork context of opentaps can be enhanced further by enabling notification emails to your team members whenever certain things happen, which they should be made aware of, including:

  * When people are added or removed from activities or events
  * When people are assigned to leads and accounts
  * When catalog requests have been successfully fulfilled 
  * Optional -- When a catalog request is fulfilled an email can be sent to the customer who
      requested it.

From this description it is evident that configuring the email for opentaps processing is a task for the same technical administrator who has set up your regular email service, or someone who is familiar with system file configuration, email setup, and programming scripts that use regular expressions.

Configure User Email Addresses

Here we assume that you have set up your email Users with User addresses and passwords that are compatible with your outbound SMTP business mail server (or service), and your inbound IMAP (or POP3) business mail server (or service). Inbound IMAP is preferred. Before you set up opentaps email you should have completed the configuration of these two email services, and have a list of their email addresses for reference.

Configure each of your opentaps Users on the opentaps system as described in Create Users and User Profiles. When you enter their email information be sure to use the same email address for each User that you have configured on your company email servers.

Thus, the opentaps email client will be using the same email addresses as your Users have already been assigned.

If you want to use different email addresses for your Users now, then you need to set up different email addresses for them on your email services first, and then assign the same new email addresses to the Users on opentaps in their User Profile page.

Now, we can configure the opentaps email client to use these User addresses with your email services, providing the additional special functions to support teamwork coordination on business processes in opentaps.

Outbound Email Setup

To enable the opentaps email client to send outbound mail through your company SMTP mail server proceed as follows:

*  Open a terminal session on your opentaps server
*  Change directories on your opentaps server to the opentaps installation directory
*  Edit this file: framework/common/config/general.properties
*  Edit this line to read: mail.notifications.enabled=Y
*  Edit this line: mail.smtp.relay.host=yourmailserverurl
   (example - mail.yourcompany.com)
*  If your mail server requires an ID and password to authenticate then
   Edit: mail.smtp.auth.user=yourauthenticationname_goes_here
   Edit: mail.smtp.auth.password=yourauthenticationpassword_goes_here
   Leave these two blank if you don't use this authentication type
*  If you want to control the maximum upload size in bytes then
   Edit: http.upload.max.size=yourvalue_goes_here
*  Save your changes to this file.

This file contains special configuration options you can use for gmail compatibility as needed.

This completes the configuration for outbound email.

The Listener Function

To perform its additional special functions which associate emails with the business processes and the team members working on those processes, opentaps needs to receive all such emails on a special address that you configure. This address is refered to as the default CRM email listener.

Using this listener, the opentaps CRM application will store all incoming emails as a process Activity in the system. It will then look-up the parties, both internal and external, associated with the email addresses in the From, To, CC, and BCC sections and relate them to this Activity as participants.

The special processing will then look for keyword strings in the subject line to associate the email with Cases and Orders. By default, the strings are:

  [Case: DemoCase1]
  [Order: 10000]

Ownership of inbound emails is important if you want to make sure that each one is handled promptly and properly by your team members. To do this, you can (or already do) use a standard email address for inquiries, such as customerservice@mycompany.com. You can have all the emails coming into that address automatically owned by one of your users who is responsible for prompt assignment and handling. You can also let that address be your default CRM email listener. (You can also use another address for the listener if that works better.)

To implement this option, you can do the following:

*  Simply go to that user's profile, add the special email address to them, and add the purpose 
   "Owner of Received Emails".  This should only be assigned to one email address and one User ID.
*  Then, set the default CRM email listener on this email address, as described in the next section.

opentaps CRMSFA will automatically pull in all emails sent to this address and associate them with this user as the owner. If there are other recipients on the email, they will also be related to the email, but they will not be the owner. Only one user can be the "Owner of Received Emails" at any time.

This owner can then manage incoming mail to achieve the best customer response that you want to implement. This section describes what the system can do, if you want. In the next section, we will describe how to configure your inbound email.

Inbound Email Setup

To process inbound e-mails with opentaps, we recommend that you set up your mail server so that all your incoming e-mails are automatically forwarded to an e-mail address, your "default CRM email listener", with their original TO and CC intact. Opentaps can then be set up to listen to that e-mail address, your "default CRM email listener", and process all of the mail coming in for opentaps users.

Refer to your IMAP service software users guide and add another user address and password for the default CRM email listener. You can use the name "listener" if you like, or some other name such as "opentapsmail" for example.

Now, configure your IMAP service software to forward all incoming mail including the original addresses (TO:, CC:, etc) which must be preserved for processing by the special opentaps services. With this new address assigned and ready, we can configure the inbound mail service on opentaps, as follows:

*  Open a terminal session on your opentaps server
*  Change the directly to the opentaps installation directory
*  Open this file for editing: framework/base/config/ofbiz-containers.xml
*  Move down the file to this line: -- To use the mail listener just uncomment and go ...
*  Uncomment the listener by editing like this: 
                                    -- To use the mail listener just uncomment and go ...-->
   This will activate the listener
*  Move down the file to the line that begins <container name=javamail-container. . . 
*  Edit the following entries to these new values:
       <property name="mail.host" value="put_your_mailhost_name_here" 
         you must keep the quote marks, for example "mail.mycompany.com" 
         or you can use the IP address, for example "192.168.3.10"
         or if the mail server and opentaps are on the same host, then "localhost"
       <property name="mail.user" value="put_your_username_here"
         you must keep the quote marks, for example "listener"  or "opentapsmail"
       <property name="mail.pass" value="put_the_password_here"
*  Edit the following entry to prevent overly large email from coming into your system:
       <property name="maxSize" value="size_limit_in_bytes"
         for example "10000000" for a 10 megabyte limit on each email
*  Edit the following entry to control deletion of email after it is captured by this client:
       <property name="delete-mail" value="true" 
         if you want the mail deleted immediately after it is transfered to the client
         or use value="false" if you want to keep the mail on the server for a another client 
         to transfer and then delete.
*  Save your changes to this file.

This completes configuration of the inbound listener service.

In the next two sections we will configure the mail processing logic so that opentaps can recognize those incoming mail items that should be collected through the listener and processed for their value as business context. We refer to this as associating the selected email with the relevant processes to produce a stronger business context.

Archiving Outbound Email Via the Listener

With one simple step you can use the same facilities you configure for inbound email processing to select, associate, and archive your outbound business email. All that is required is that you copy your outbound email to the listener email address that you have set up. You can do this in either of these two ways:

• Blind Copy (bcc) your outbound email to the listener address, or
• Configure your outbound email service to copy all outbound messages to your listener address

Once this is done, the processing support applied to mail coming through the listener address will be applied equally to both inbound and the copied outbound mail.

This means that your teams working on business processes will find all of the relevant outbound and inbound email associated with any particular situation (such as an Account, a Case, an Opportunity, an Order, etc.) on the system screens that the teams share. Your coordinated support work for customers, partners, vendors and other parties should be enhanced by the immediate access to this relevant context added by your emails.

Associating Emails for Strong Context

Once you have set up your listener, you need to set up a processing service to select and then associate the desired listener emails. The listener may be receiving email forwarded from your service which should not be included in the business process activities. This can be set up by configuring a Mail-Condition-Action (MCA) in any of your applications such as CRMSFA or others. We will discuss CRMSFA MCA here.

By default, the opentaps CRMSFA application has an MCA configured to process emails coming through your listener email address, that we set up in the previous section. This includes inbound email, and outgoing emails which are being BCC'd to the listener address. The CRMSFA MCA is already configured by adding the following line to your ofbiz-component.xml file as follows:

*  Open a terminal session to your opentaps host computer
*  Change to the opentaps installation directory
*  Open this file for editing: hot-deploy/crmsfa/ofbiz-component.xml
*  Save a backup (renamed) copy of this file before editing it, if you like
*  This file contains the MCA entry pointing to the location of the regular expression sting used 
   to select the email coming through your listener, which we will process for business context
*  This is the entry:
      <service-resource type="mca" loader="main" location="servicedef/smcas.xml"/>
*  You do not need to change this entry to use this MCA.  
*  Close this file without changing it.

To configure the mail processing strings used to select the desired mail coming from your listener address, proceed as follows:

Refer to Using REGEX Validation Patterns

*  Next open this file for editing: hot-deploy/crmsfa/servicedef/smcas.xml
*  Move to the occurrence of this line: 
      <condition-field field-name="from" operator="matches" value=".*opentaps\.org>*"/>
*  Edit the regular string value (highlighted) to equal the value for your company outbound mail 
   from within CRMSFA that you bcc to your listener address for archiving 
*  Move down to the occurrence of the line:
      <condition-field field-name="to" operator="matches" value=".*opentaps\.org>*"/>
*  Edit the regular string value (highlighted) to equal the value for your company inbound mail 
   that you have forwarded to your listener address 
*  Save the modified file and exit.
*  This completes the setup for processing email in the CRMSFA application.

Now, this smcas.xml file has a definition of how to process the incoming email using these entries.

Note: A note about the regular expression string entry which follows:

 In this entry example, value="(?i).*@opentaps\.org>*"/> the (?i) makes the match case insensitive.

For more information about configuring email handling options refer to the page Managing Emails. Also, the page Handling Emails provides more information about default processing and associating with business processes and users.

Notification Emails for Team Coordination

What the Notifications Do

The notification emails keep internal team members up to date regarding coordinated activities. The CRM Notifications are only send to internal CRMSFA users, such as team members and customer service representatives, when certain status items change. Notification emails can be configured and sent when the following events take place:

  * When people are added or removed from activities or events
  * When people are assigned to leads and accounts
  * When catalog requests have been successfully fulfilled 
  * Optional -- When a catalog request is fulfilled an email can be sent to the customer who
      requested it.

In addition to CRM notifications, you can configure notification e-mails for order and shipment-related events in the order and product applications of opentaps.

Technical Administrators' Guide to Configuring the Notification Emails

You can configure CRM notifications for:

   * task and event assignments
   * account and lead assignment
   * catalog request notification 

To configure the CRM notifications, proceed as follows:

*  Open a terminal session into the opentaps installation directory on your server
*  Edit the file hot-deploy/crmsfa/config/notification.properties. 

*  The file includes a configuration section for these items:
 **   Common from address -- a common from address for all notification emails
 **   Password reminder
 **   Tasks and Events changes notification
 **   Leads changes notification
 **   Accounts changes notification
 **   Marketing catalog request fulfillment

*  Each changes notification section configures these parts: 
 **   the "from" email address (which is optional, the common address can be used) can be added
      to each section where a unique address is needed
 **   subject text of the emails based on the change event that has occurred 
 **   the screen (widget) template for each notification email version
 **   URL to access the CRMSFA application which you would not edit normally

*  For fulfilled catalog requests, an email can be sent to the customer who had originally 
   requested the catalog. This feature is turned on by default.
 **   To turn this feature off, set the email.marketing.catalog.sendCatalogRequestEmails property 
      to "false" in notification.properties. 
 **   The email subject, body and "from" email address are also configured here by the properties
      from.marketing.catalog, subject.marketing.catalog, screen.location.marketing.catalog. 
*  Save your file changes and exit.

The default notification emails are very simple but can be customized to your needs through modification of the XML files used to generate the messages.

Reference

• Many of the properties in framework/common/config/general.properties correspond to standard Java Mail properties

Section pages >> Credit Card Processing