Chapter 133: Email Repository Overview

Purpose: You can use the Correspondence History file in CWDirect to store and review emails that you have received from or sent to your customers.

Email site: The email site in CWIntegrate enables you to translate emails you receive at your mail server into XML, and then forward them to CWDirect. Once the emails are received into CWDirect, the system assigns or “routes” the emails to the appropriate customer.

You need to purchase CWIntegrate and the email site in order to use them to forward emails into CWDirect. Contact your MICROS representative for more information. CWDirect will create correspondence history records as long as it receives correctly formatted XML messages, regardless of the source.

Outbound emails: You can also use the Correspondence History file to store outbound emails that you send to customers, such as backorder and soldout notices and shipment confirmations. However, because the text of each type of outbound email does not vary from customer to customer, the system does not save the text in the Correspondence History Detail file; no text is available for review at the screens where you can work with correspondence history, such as the Work with Email by Order Number Screen. The Write Outbound Email to Email Repository (H99) system control value specifies whether to save information on outbound emails.

If you use the Outbound Email API, the same type of information is also stored for the Outbound Email XML Message (CWEmailOut), based on the setting of the Write Outbound Email to Email Repository (H99) system control value. See the discussion of the Outbound Email API for more information.

Note: Purchase orders you email to vendors are not stored in the Correspondence History file.

In this chapter:

• Emails Repository Process Overview

• Typical Process

• Email Identifiers

• Alternate Email Processes

• How the Email Site Determines the Originating Email Address for a Forwarded Email

• Email Address Matching

• Reviewing and Working with Emails

• Summary of Emails Repository Setup

• Email XML Message (CWEmail)

• Email Message: Sample XML

Emails Repository Process Overview

The CWIntegrate email site:

• picks up an incoming email sent from your mail server

• converts the email to XML

• sends the XML message to CWDirect

Once the email is in CWDirect, the EMAIL process in Integration Layer Job Control:

• translates the XML message to a Correspondence History record

• assigns ("routes") the email to customers based on the message identifier(s) specified, or by searching for a customer with a matching email address

• flags the email as Unrouted if the email includes invalid, inconsistent, or insufficient identifying information.

Typical Process

Overview: In this sample process, a customer send an email to a customer service email address. A customer service representatives reviews the email; responds to the customer or takes whatever action is appropriate; then forwards the email to the email site, which converts the email and sends it to CWDirect. When forwarding the email, the customer service representative can indicate the customer number, order number, and other email identifiers, so that CWDirect can assign the email to the correct customer.

About email identifiers: The email site in CWIntegrate enables you to flag forwarded emails with identifiers such as order number, customer number, and so on. Once an email arrives in CWDirect, the system uses this information to assign it appropriately. If customer service representatives forward emails into CWDirect, they can use a Microsoft Outlook form provided with the email site to specify the email identifiers, as described below.

Identifying the originating email address: Regardless of whether an email arrives flagged with identifiers, the email site still attempts to identify the originating email address and passes the email message on to CWDirect for identification. If the email has been forwarded, the email site searches the text of the email for the originating email address; otherwise, the email site uses the “from” address as the originating email address. CWDirect can assign the email to a customer with a matching email address. See How the Email Site Determines the Originating Email Address for a Forwarded Email and Email Address Matching for more information.

Using the Outlook form: The email site includes a form that customer service representatives can install and use in Outlook to make forwarding and identifying emails easier. The form includes fields to specify key email identifiers, such as: order, drop ship purchase order, or order invoice number; sold-to and other customer numbers; and user-defined information. The “to” address on the form directs the email to the email site, which translates the email to XML and then forwards it into CWDirect.

Including email identifiers in the subject line: If you use the email site, you can also enter email identifiers in the subject line of an email. For example, by entering COMPANY=27;CUSTOMER=317 in the subject line, you indicate to the system that the email is related to customer # 317 in company 27. There are email identifiers that:

• you can enter using the form fields or the subject line (for example, customer number)

• you can enter only at the subject line

• that the system fills in for you on the subject line (for example, ATTACHMENT=N; or ATTACHMENT=Y;)

• that you need to enter only as an override to the default (company number)

See the CWIntegrate Emails Integration manual for more information on entering and using email identifiers when forwarding emails.

Note: Because any invalid or inconsistent identifier puts the incoming email into unrouted status, it is preferable to include only the identifiers needed to assign the email correctly and to verify that each identifier is accurate.

The email site builds an XML message for each inbound email, using the email message identifiers, the originating email address, the text of the email, and other information. See Email XML Message (CWEmail) for the layout of this message.

Email Identifiers

When attempting to assign an email, CWDirect looks for valid, consistent email identifiers as follows:

• Order-related information = Any provided information that connects the email to an order also indicates the sold-to customer, and potentially an individual, a bill-to customer, and a ship-to customer if they exist on the order. These identifiers are:

• Order number

• Order cross-reference number

• Drop ship purchase order number

• Invoice number

• Customer-related information = If there is not information related to the order, the system assigns the email at the customer level only. These identifiers are:

• Sold-to customer number

• Customer cross reference number (Alternate cust # or Alternate customer # cross reference; see Working with Alternate Customer Number Cross-References for an overview)

If any of the email identifiers is invalid or inconsistent, the system puts the email in unrouted status. You can work with unrouted emails through the Working with Email (WEML) menu option.

For more information: See Identifying an Unrouted Email for more information on how the system validates email identifiers.

Alternate Email Processes

Forwarding emails without specifying identifiers: It is not necessary for customer service representatives to include email identifiers; instead, they can forward emails and use Email Address Matching to have the system assign the email to the correct customer based on the originating email address. See How the Email Site Determines the Originating Email Address for a Forwarded Email.

Sending emails directly to CWDirect: It is possible to have emails sent directly to the email site for forwarding into CWDirect, rather than having them first arrive at a customer service email address, and use Email Address Matching to assign an incoming email if there is a match. In this situation, because the email assignment occurs automatically, you need a mechanism to identify and track incoming emails and make sure that you have responded to all customer inquiries and requests. One solution might be to configure your email systems so that a cc: of each email is also sent to a customer service representative. The customer service representative could also forward replies into CWDirect, so that both the original email from the customer and the reply would be available for review in correspondence history (as opposed to forwarding just the original email into CWDirect, as described under Typical Process.

Note: Configuring your web site or emails system to generate a cc: of each incoming email is outside the scope of CWDirect and the email site in CWIntegrate.

How the Email Site Determines the Originating Email Address for a Forwarded Email

If customer service representatives forward emails into CWDirect, it is important to distinguish their email addresses, which are irrelevant, from the addresses of customers. The email site determines whether the originating email is the “from” email address by checking whether the email was forwarded; if so, the email site searches the body of the message for the originating email address rather than just using the “from” address. If the email has been forwarded more than once, the email site uses the most recent “from” address in the email. CWDirect can use the originating email address to determine which customer sent the email; see Email Address Matching.

Can customer service representatives send a copy to CWDirect when they reply to an email? Unless the email is forwarded (indicated by text such as FW: in the subject line of the email), the email site does not know to search the text of the email for the originating address and uses the actual “from” address instead. To make sure that emails are still assigned correctly in CWDirect, you could use one of the following alternate methods:

• Select "forward" rather than "reply," but forward the email to both the email site address and the customer’s email address.

• After replying to the customer’s email, select the reply from the "sent" folder and forward it to the email site address.

Update customer email address: When an email is forwarded into CWDirect flagged with email identifiers, and the email address already exists in the Customer Sold To Email file, the system updates the Last used/customer date for the email address.

If the email site cannot find the original email address: If the email site cannot determine the originating email address in a forwarded email, it substitutes a standard email address in the Correspondence History record to indicate the originating address was not found. The default is forwardMissing@error.com, but can vary depending upon your setup.

See the CWIntegrate Emails Integration manual for more information on how the email site identifies the originating email address.

Email Address Matching

The Assign Unreferenced Email (H93) system control value indicates whether to compare the originating email address with the email addresses in your customer files in search of a match.

The system performs such a search in the following order:

• active individual customers

• ship-to customers

• sold-to customers

• bill-to customers

This system control value also specifies whether to search for and flag duplicates, or to use the first matching email address it finds.

For more information: See the Assign Unreferenced Email (H93) system control value for a description of the search and matching hierarchy.

If the email is not assigned: If the system cannot match the email to a customer or order, or if the email identifiers are inconsistent or invalid, you can use Working with Email (WEML) to review or work with the email. You can assign the email as appropriate, or delete it.

Reviewing and Working with Emails

Emails are stored in the Correspondence History file. You can review correspondence history related to a particular:

• order: Work with Email by Order Number Screen

• sold-to customer: Work with Email by Customer Sold To Number Screen

• ship-to customer: Work with Email by Customer Ship To Number Screen

• bill-to customer: Work with Email by Customer Bill To Number Screen

• individual customer: Work with Email by Customer Individual Screen

You can scan for and review emails related to a particular:

• order in order maintenance and order inquiry

• sold-to, ship-to, bill-to or individual customer: in order maintenance, order inquiry, or the appropriate customer maintenance screens

The Email Presentation (I01) system control value indicates whether to condense email messages in correspondence history by deleting blank lines or line breaks between paragraphs.

Purging emails: You can use Purging Correspondence History (MPCH) to purge Correspondence History records older than a specified date.

Summary of Emails Repository Setup

Purpose: The setup required within CWDirect for the email repository consists of:

System control values:

• Assign Unreferenced Email (H93): Specifies whether the system should attempt to assign an unreferenced email to a customer based on matching email address, and whether to leave an email unassigned if more than one customer has the matching address.

• Email Presentation (I01): Specifies whether to include all blank lines, include one line space between paragraphs, or wrap all text in emails coming into CWDirect.

• Write Outbound Email to Email Repository (H99): Specifies whether outbound emails such as soldout notices, backorder notices, and shipment notifications, or the Outbound Email XML Message (CWEmailOut), are saved in the email repository.

Secured feature: The Changed Routed Email (B08) secured feature controls the ability to change or delete previously routed emails through the Work with Routed Emails screens.

Working with Integration Layer Processes (IJCT): Set the EMAIL process to the queue manager and queues you have set up on the CWIntegrate server. See the CWIntegrate Emails Integration manual for more information.

This process has an inbound program only. The EMAIL_OUT process generates the Outbound Email XML Message (CWEmailOut), and other outbound email notifications are generated by different processes. See Working with E-Mail Notification Templates (WEMT) for an overview.

Working with Email Category (WEMC): Optionally, set up one or more email categories. If the Write Outbound Email to Email Repository (H99) system control value is set to Y, you will need an email category of NTF (notification); however, the system creates this category automatically the first time you use the Working with Email Category menu option.

Communication settings: You need to perform MQSeries setup for communication between CWIntegrate and the system. See the CWIntegrate Emails Integration manual for more information.

Email XML Message (CWEmail)

 

The CWEmail message is used to send emails to CWDirect from an external email system, such as Microsoft Outlook. When the system receives a CWEmail message from an external source, the system creates a Correspondence History record, matching the email to the related customer, order, or vendor based on the information provided in the message. If insufficient information is included in the email message, then the system attempts to match the email with a sold-to customer based on the email address in the message. Typically, the email site in CWIntegrate is used to convert emails into this XML file format, although it is possible to import an XML message from another source if the message is in the layout described below and is correctly formatted.

See the CWIntegrate Emails Integration manual for more information on how the email site populates the CWEmail message.

For more information: See:

• Email Message: Sample XML for a sample message..

• XML Messages for a table that provides links to the DTD, schema, and a sample XML layout for each XML message.

Attribute Name	Type	Length	Comments
Message
source	alpha	25	Identifies the source of the XML message. IDC indicates the XML message is from CWIntegrate.
target	alpha	25	Identifies the target of the XML message. RDC indicates the XML message is sent to CWDirect.
type	alpha	25	Identifies the type of information in the XML message. CWEmail indicates the message contains an inbound email.
Email
company	numeric	3	The company where the Correspondence History record will be created.
order	numeric	9	The order number related to the email. If the order number passed is valid, the Correspondence History record is assigned to the order, and each of the types of customers associated with the order. The sold-to customer is always associated, and the bill-to, ship-to, and individual customers are also associated with the email if they are on the order.
order_ship_to	numeric	3	The number representing the order ship-to address; requires that the order number be identified.
vendor	numeric	7	The number representing the vendor associated with the email. If order number and purchase order number are also passed, the vendor, order, and purchase order must represent a valid combination.
customer_sold_to	numeric	9	A number to identify the sold-to customer associated with the email. If the message does not include a sold-to customer number, the Assign Unreferenced Email (H93) controls whether the system can attempt to match the email with an existing sold-to customer based on the order number specified, or the email address included in the email. If the email has been forwarded, the system checks the body of the message for an originating email address. Not all emails are related to sold-to customers. For example, an email from a vendor might not be related to a sold-to, ship-to, bill-to, or individual customer, or to an order. If an order number is also specified, requires that the order number and customer number represent a valid combination.
customer_ship_to	numeric	3	A number to identify the ship-to customer associated with the email. Requires that the sold-to customer be identified, and that the sold-to number and order number represent a valid combination.
customer_bill_to	numeric	7	A number to identify the bill-to customer associated with the email. If an order number is also specified, requires that they represent a valid combination.
customer_individual	numeric	3	A number to identify the individual customer associated with the email. Requires that the sold-to customer be identified and that the individual must be in Active (A) status. Also, if an order number is specified, requires that the order number, sold-to number, and individual number represent a valid combination.
po	numeric	7	A number to identify the purchase order number related to the email. If the message includes both the order number and the purchase order number, or a vendor and a purchase order number, they must represent a valid combination. If the message includes just the purchase order number, but the purchase order references an order number, the Correspondence History record will be assigned to that order number and related sold-to customer.
email_category	alpha	3	A code used to group emails for reporting and analysis. Must be a valid email category.
invoice	numeric	7	A number to identify the Invoice Header related to the email. If an order number or customer sold-to number is also specified, they must represent a valid combination.
user_code_1	alpha	1	A user-defined field, available to pass a flag or status code for storage in the Correspondence History record.
user_code_2	alpha	10	A user-defined field, available to pass a code for storage in the Correspondence History record.
user_code_3	alpha	20	A user-defined field, available to pass a long code or other information for storage in the Correspondence History record.
user_number	numeric	13	A user-defined field, available to pass a long number for storage in the Correspondence History record.
user_date	numeric	7	A user-defined field, available to pass a date for storage in the Correspondence History record.
order_cross_reference	alpha	30	An alternate code to identify an order. If this cross reference matches the Alt ord for an order, the email is assigned to the order, and each of the types of customers associated with the order. If an order number or customer sold to is also specified, they must represent a valid combination.
customer_cross_reference	alpha	15	An alternate code to identify a sold-to customer. If this cross reference matches the Alt cust (Alternate customer number) for a sold-to customer, the email is assigned to the customer. If an order number or customer sold to is also specified, they must represent a valid combination.
from	alpha	50	The originating email address. The system can use this email address to search for a matching individual, sold-to, or ship-to customer, based on the setting of the Assign Unreferenced Email (H93) system control value. See How the Email Site Determines the Originating Email Address for a Forwarded Email for a discussion of how the email site determines this address.
to	alpha	50	The destination email address.
cc	alpha	50	The email address to receive a copy of the email.
subject	alpha	78	The contents of the Subject line for the email. Any email identifiers included in the subject line are deleted.
attachment	alpha	1	Indicates whether the email included an attachment. Valid values are: Y = there was an attachment N = there was no attachment The attachment is not included in the Correspondence History record.
display_name	alpha	50	The customer’s email alias, that is, the name that appears in place of the actual email address in some email applications.
email_date	numeric	7	The date the email was originally generated.
email_time	numeric	6	The time the email was originally generated.
body	alpha		The actual text of the email. Codes, images and formatting are deleted or replaced with plain text equivalents; see Symbol and Special Character Conversion in Emails for more information.

Email Message: Sample XML

A sample of the Email XML Message (CWEmail) is presented below.

<Message source="email" target="rdc" type="CWEMail">

<EMail company="555" customer_sold_to="6" from="kbottger@example.com" to="rdc@example.com" attachment="Y" display_name="Karen Bottger " email_date="12082004" email_time="093153" body="Hi Bernadette, Attached is the user reference you requested. I hope you find this documentation useful. If you have any questions, please let me know.~~ ~~Regards,~~Karen Bottger~~Technical Writer~~CommercialWare Inc.~~ ~~" />

</Message>