List Item Emailer

Overview XE "Overview:List Item Emailer" XE "List Item Emailer:Overview"

When introduced into a list, the List Item Emailer™ (LIE) web part will send an email to a user that you specify in the list item. This web part is extremely customizable, allowing you to choose list item field names, the email body to be sent to the user, and the subject line. The server and email address that will handle the email request are also customizable.

Once email notification has been configured, an email can be sent to the identified individual(s) each time an item in the email-enabled list is added or modified. The person who adds or modifies the list item has the option to send an email, define the content of the message, and specify who to send it to.

To simplify the process of customizing email notification, CorasWorks introduced the List Item Emailer Wizard in the Winter 2006 release of the Workplace Suite. 0Click hereHelp_D2HPrivate(-9,1601)Overview0 to access the online help for the LIE Wizard.

The List Item Emailer utilizes a component called "ChilKat" to access and send email through your SMTP server. It has been tested and is deemed secure to function on your server. ChilKat is only utilized when sending via SMTP; if you choose to send through SharePoint, ChilKat will not be used.

Last Modified: DATE \@ "MMMM yy" October 06

How to Create and Use an Email-Enabled List from a Template XE "Email Notification:Create and Use an Email-Enabled List" XE "Create an Email-Enabled List"

These steps explain how to use these list templates to create an email-enabled list. If you are working with a different type of list or a custom list, the appendix of the Capabilities Guide includes procedures entitled “How To: Email-Enable a List or Library.” The Capabilities Guide is included in the zip file downloaded from CorasWorks, and it is also available in the Support section of CorasWorks Central.

(If you do not have an ID and password for CorasWorks Central, please contact our Support team at support@corasworks.net.)

To create an email-enabled list from a template:

1. Go to the site where you want to create the list.

2. Expand the Lists section of the Workplace View Advanced and select Create List. The Create Page is displayed, with the lists and library templates you can use.

3. Select Lists from the menu on the left side of the page, and then select the name of the appropriate template.

4. Type a name for your new list in the Name field.

5. Provide a description that makes it clear that this list is email-enabled and then click Create. The list is created in your SharePoint site and will be displayed on your screen.

You have added an email-enabled list to your SharePoint site that is ready for use.

NOTE: You can also email-enable your own lists and libraries; you do not have to rely solely on the email-enabled list templates provided by CorasWorks. Detailed procedures to email-enable a list are provided in the Appendix of the CorasWorks Workplace Suite Capabilities Guide, which is included in the Workplace Suite download and also available in the Support area of CorasWorks Central.

To use your new list:

This section explains how to send an email by creating an item and notifying someone about it.

1. Access the list and click New Item. Fill out the fields as usual and note the following email-related fields:

· Send Email: A Yes or No choice

· Message: The body of the message to be sent to the person to whom you assign the task

· Assigned To: Who the task is assigned to (and the email will be sent to)

· To use a cross-site group, the site must be set up with unique permissions and the cross-site group must be given rights to that site.

· CC: The person to be copied on the email

· History: Will contain the audit trail information, empty for now

· This field is NOT supported for document or picture libraries because SharePoint limits a multi-line field in libraries to 254 characters.

2. Select Yes from the Send Email field, if it is not already selected.

3. Type the content you want to include in the email in the Message field.

4. Select the Assigned To and the person to CC.

5. Click Save and Close. A pop-up box is displayed briefly, stating “Checking Email,” and then you are returned to the task list.

NOTE: If you do not see the pop-up box, it may be blocked by your browser settings. You can modify these settings via the browser’s Tools menu.

Audit logging is turned on by default, so you will see that an entry has been made in the History field of the task. The entry will state the person and date and time that it was modified. You can modify this to add any fields to include the message. (See Web Part Properties.)

A Sample Optional Email Process

One topic for which CorasWorks Support receives a number of calls is the Optional Email Process. As described in the 1Web Part PropertiesHelp_D2HPrivate(-9,726)Web Part Properties1, this allows you to define different emails to be sent based upon the value in a particular column of the email-enabled list. It directs the List Item Emailer web part to look at the value in the identified column and, based on that value, send the appropriate email message to the identified recipients.

NOTE: Emails will be sent only when the individual list item is opened and then closed. Emails will not be sent based on a filter (e.g., Due Date) if the item has not been opened, or if the item is opened and closed in Datasheet mode.

This topic provides the code for a series of messages to be sent based upon the values within the Status column of a task list. A different message will be sent to the appropriate audience for each possible value. The messages will be formatted using HTML, including code for using a table to format the data. Of course, you can customize this example to fit your needs and the steps in your processes.

There will be a total of five steps to the process, one for each Status type, as defined in the table below. This table shows the values and title of each message to be defined.

Status Value	Message Sent To	Title of Notification
Not Started	To: Assigned To CC: Person Creating Task	Task has been Assigned
In Progress	To: Assigned To CC: manager@abc.com	Task has been Started
Completed	To: Assigned To CC: Person Creating Task	Task has been Completed
Deferred	To: Person Creating Task CC: manager@abc.com	Warning – Task has been Deferred
Waiting on Someone Else	To: Person Creating Task CC: Assigned To	Warning – Task is Waiting on Someone Else

Start with the First Column Value

You can start with the code for the Not Started message:

Look at this code before you go any further to make sure you understand what it is doing. As is stated in the 2Web Part PropertiesHelp_D2HPrivate(-9,726)Web Part Properties2 topic, the format for each entry in the Optional Email Process is:

Field#;Value#;Email To#;CC#;Email From#;Subject#;Body

So, if you look at the sample code above, it can be broken down as described here:

Parameter	Usage	Value in Process
Field	Column name referenced by the process	Status
Value	Value within column	Not Started
Email To	Destination of the notification	Assigned To
CC	Another address	Created By
Email From	Source of email	Created By
Subject	Title of email message	Task has been Assigned
Body	Format of email body	HTML-encoded body with column values

This process looks at the Status column. When the Status is set to “Not Started,” a notification message will be sent with the following settings:

· It will be sent to the value within the Assigned To column

· A copy will be sent to the address found within the Created By column

· The “Created By” person will also be listed as the originator of the message

· The title of the message is “Task has been Assigned”

The body of the email is HTML-encoded, using a table with rows and cells. Within the cells are text and the values from the identified columns. So the body of the message includes:

· Line of Greeting: The following task has been assigned to you.

· Starting of an HTML table: <table border=”1” width=”100%”>

· Creating of Rows and Cells: <tr> <td width=”111”>…</td> </tr>

· Value Identifiers: Task Title

· Column Values: <*=Description*>

The message that is sent has the formatting of a table that includes the values of the columns. It is not required that the notification be formatted using HTML code, but the resulting notification is placed within a table and is easy to read.

Add the Remaining Steps in the Process

Now, you can easily add the code for the remaining steps in the process (the other possible status values) by copying, pasting, and modifying the sample code above.

If you want to start with the sample code provided above for the Not Started, you can copy and paste it for each step in the process. If you have your own code, copy and paste that. Make sure you type <NEW> at the end of each process. So you would copy the first set of code, type <NEW>, and then paste and make the necessary modifications to the status, destinations, title, and body. Then repeat.

For the example described above, the final code looks like this. As the task moves along through each status, a different message is sent.

Status#;Not Started#;Assigned To#;Created By#;Created By#;Task has been Assigned#;The following task has been assigned to you. 
<table border=”1” width=”100%”>
<tr> <td width=”111”>Task Title</td><td><*=Title*></td> </tr>
<tr> <td width=”111”>Assigned To</td><td><*=Assigned To*></td> </tr>
<tr> <td width=”111”>Description</td><td><*=Description*></td> </tr>
<tr> <td width=”111”>Due Date</td><td><*=Due Date*></td> </tr>
<tr> <td width=”111”>Task Link</td><td><a href=<*=ItemURL*>>Click Here</a></td> </tr>
</table>
<NEW>
Status#;In Progress#;Assigned To#;manager@abc.com#;Created By#;Task has been Started#;The following task has been started. 
<table border=”1” width=”100%”>
<tr> <td width=”111”>Task Title</td><td><*=Title*></td> </tr>
<tr> <td width=”111”>Assigned To</td><td><*=Assigned To*></td> </tr>
<tr> <td width=”111”>Description</td><td><*=Description*></td> </tr>
<tr> <td width=”111”>Due Date</td><td><*=Due Date*></td> </tr>
<tr> <td width=”111”>Task Link</td><td><a href=<*=ItemURL*>>Click Here</a></td> </tr>
</table>
<NEW>
Status#;Completed#;Assigned To#;Created By#;Created By#;Task has been Completed#;The following task has been completed. 
<table border=”1” width=”100%”>
<tr> <td width=”111”>Task Title</td><td><*=Title*></td> </tr>
<tr> <td width=”111”>Assigned To</td><td><*=Assigned To*></td> </tr>
<tr> <td width=”111”>Description</td><td><*=Description*></td> </tr>
<tr> <td width=”111”>Due Date</td><td><*=Due Date*></td> </tr>
<tr> <td width=”111”>Task Link</td><td><a href=<*=ItemURL*>>Click Here</a></td> </tr>
</table>
<NEW>
Status#;Deferred#;Created By#;manager@abc.com#;Created By#;Warning - Task has been Deferred#;The following task has been deferred. 
<table border=”1” width=”100%”>
<tr> <td width=”111”>Task Title</td><td><*=Title*></td> </tr>
<tr> <td width=”111”>Assigned To</td><td><*=Assigned To*></td> </tr>
<tr> <td width=”111”>Description</td><td><*=Description*></td> </tr>
<tr> <td width=”111”>Due Date</td><td><*=Due Date*></td> </tr>
<tr> <td width=”111”>Task Link</td><td><a href=<*=ItemURL*>>Click Here</a></td> </tr>
</table>
<NEW>
Status#;Waiting on Someone Else#;Created By#;Assigned To#;Created By#;Warning - Task is Waiting on Someone Else#;The following task is waiting on someone else. 
<table border=”1” width=”100%”>
<tr> <td width=”111”>Task Title</td><td><*=Title*></td> </tr>
<tr> <td width=”111”>Assigned To</td><td><*=Assigned To*></td> </tr>
<tr> <td width=”111”>Description</td><td><*=Description*></td> </tr>
<tr> <td width=”111”>Due Date</td><td><*=Due Date*></td> </tr>
<tr> <td width=”111”>Task Link</td><td><a href=<*=ItemURL*>>Click Here</a></td> </tr>
</table>

Web Part Properties XE "Web Part Properties:List Item Emailer"

There are four sections of List Item Emailer web part properties:

· 3Emailer PropertiesHelp_D2HPrivate(-9,1611)Emailer Properties3

· 4Audit PropertiesHelp_D2HPrivate(-9,1612)Audit Properties4

· 5Override PropertiesHelp_D2HPrivate(-9,1613)Override Properties5

· 6Optional Email ProcessHelp_D2HPrivate(-9,741)Optional - Email Process6

Emailer Properties XE "Emailer Properties" XE "Email Notification:Emailer Properties" XE "Email Notification:Subject and Body Definition"

Email Server/Name IP

(Optional) This is the Server Name or IP Address that handles all email SMTP requests. If you have Use SharePoint Email enabled (see below), leave this field blank. When this property is blank, the web part will default to the SMTP Service that resides on the same server on which SharePoint is installed. If you utilize this SMTP Service, make sure you permit "Relay" for this server.

If you do not use SharePoint email, this property must be filled in so the web part knows what email server to use when sending messages. This value can be an IP address (ex: 10.13.99.30) or a server name (ex: mailserver.coras.net). In either case, the address or name must point to your internal email server.

User Lookup Field

(Required) This property is used to name the field (column) in the list item that is used to determine the email address to send the email to (usually Assigned To).

Traditionally, this column corresponds to the "User Lookup" column within the list, and it is utilized to retrieve the user's email address. This requires that the user's email address is entered into the "View Information About Site Users" area of "Site Settings." To append an email address to a selection box from within your list, place the email address within brackets [ ]. Example: Approval Required [approver@company.com] The web part will parse out the email address when the notification is sent. You can also utilize a single or multi-line text field that allows users to enter email addresses manually.

Winter 2006 Updates

· If a user name is identified, the domain must also be supplied. This can be done via the Domain property (discussed below). The LIE will get the email address from SharePoint.

· Values can be entered or selected via a User Lookup, Multi Choice, List Lookup (pre-Winter 2006 only), Multi-Line, or Single Line field.

· Just as you can use this format to identify an email address: John Doe [jdoe@companxyz.com] you can do the same with the username. For example: John Doe [companyxyz\jdoe].

· Display names and Active Directory (groups) are not supported.

· To use multiple values, simply separate each with a semicolon (;).

· To use a cross-site group, the site must be set up with unique permissions and the cross-site group must be given rights to that site.

Sec. User Lookup Field

(Optional) This property is used to name the field (column) in the list item that is used to determine the secondary email address to send the email to (usually CC). The same rules, abilities, and updates for Winter 2006 apply here as to the User Lookup Field above.

NOTE: If you have Use SharePoint Email enabled, the To and CC selections will both be placed in the To field of the email.

Email Subject XE "Email Subject Definition"

(Required) This property is used to define the subject of the email that is sent to the user. This can be a static value or it can be driven by one or more list variables If you want this to include the list name, use this: <*=List*>

Email Body XE "Email Body Definition"

(Required) This field is used to define the body of the email to be sent to the user.

CorasWorks populates the Email Body field with a default message so you have something to start with, but it can be changed. If you enable the “Use SharePoint Email” option above, you can include HTML or plain text characters. Any fields in the list can be used.

As an example, the email body documenting recent updates to a project could read:

The summary for Project ID: <*Project ID*> has been updated by <*Modified By*> on <*Modified*><*Return*><*=Return*>

Please note the formatting of variable names.

· List fields should be encapsulated like this: <*=fieldname*>

· Carriage returns should be encapsulated like this: <*=Return*>

· Other key fields and syntax:

· The summary for Project ID: <*=Project ID*> has been updated by <*=Modified By*> on <*=Modified*><*=Return*><*=Return*>

· Message:<*=Return*><*=Message*><*=Return*>Links: <*=Return*>

· This returns the hyperlinked words Record, List, and Workspace:

· <a href="<*=ItemURL*>"> Record </a><*=Return*> <a href="
<*=SiteURL*>/<*=ListURL*>"> List </a><*=Return*> <a href="
<*=SiteURL*>"> Workspace </a><*=Return*><*=Return*>

· This returns the URL Strings:

· Item: <*=Return*><a href="<*=ItemURL*>"><*=ItemURL*></a>
<*=Return*><*=Return*>

· List: <*=Return*><a href="<*=SiteURL*>/<*=ListURL*>"><*=ListURL*>
</a><*=Return*><*=Return*>

· Workspace: <*=Return*><a href="<*=SiteURL*>"><*=SiteURL*></a>

Where:

· <*=Return*> = Carriage Return

· <*=Title*> = The List Item Title from the list item as set up in the List Item Title property

· <*=CreatedUser*> = The user who created/modified the list item

· <*=CurrentDate*> = The date/time when the list item was created/modified

· <*=List*> = The List Title for the list

· <*=ItemURL*> = The direct URL to the list Item

NOTE: If you have enabled either “Send SharePoint Email” or “Send Email As HTML,” you will need to modify the ItemURL to include an anchor tag. This allows you to hyperlink a field to the actual item. For example, to hyperlink the task title, add the following line to the email body:

Link: <a href="<*=ItemURL*>"><*=Title*></a> <*=Return*><*=Return*>

In this example, the <a href="<*=ItemURL*>"> handles the encoding of the hyperlink, while the second <*ItemURL*> tag places the actual URL for the link in the message. This helps in cases where the user’s email application does not support hyperlinks.

When sending the user directly to a document within a library, use the <*=Encoded Absolute URL*> code.

Another Way of Looking At This…

This table provides another way of looking at how to format the Email Body.

To Display This	Use This Coding	Appearance in Notification
Value from Column	<=fieldname**>	Same as item in list
Carriage Returns	<=Return>	Single line break
ID Number of Item	<= ID>	4
Site URL*	<=SiteURL>	http://<<domain>>/<<site structure>>
Name of List/Library	<=List>	Provides name of list (i.e. – Tasks)
URL of List Within Site URL	<=ListURL>	Lists/Tasks
Time/Date of Last Modification	<=Modified>	3/10/2006 12:52:27 PM
User Last Modifying Item	<=Modified By>	Bob Harris
Time/Date of Item was Created	<=Created >	3/10/2006 12:27:50 PM
User Creating Item	<=Created By>	Robert Jones
Time Notification was Sent	<=CurrentDate >	3/10/2006 12:52:27 PM
“From” Name of Sender	<=CreatedUser>	Frank Stephens
Link to the Item**	<=ItemURL>	http://<<domain>>/<<site structure>>/ List/<<list name>>dispform.asp?ID=4

* There is no way to get the name of the site into the notification message, short of typing it into the “Email Body” field.

** To go directly to the item for editing, change the value within the “Destination Page” field in the LIE Wizard web part (or the “Display Form Name” within the LIE web part properties) from dispform.aspx to editform.aspx.

Email From

(Optional) The value you define here is placed in the “From” line of the email message. The property is typically left blank, in which case it defaults to the currently logged in user.

Alternatively, it can be hard-coded (ex: support@corasworks.net). For example, you could specify a manager’s reply-to address for users to send immediate issues or concerns. If you choose to hard-code an email address, the Email Server Name/IP Address field must be completed and the "Use SharePoint Email" option must be disabled.

Issues sometimes arise when there is a mismatch between the server that sends the email and the return email address in the message, causing the email to be caught in the Spam filter.

List Name

(Optional) This property is used to identify the name of the email-enabled list. It is utilized by the web part to check the list for modified items that require an email to be sent. This should be the same name as the name of the folder that contains the checkemail.aspx file.

This property is typically left blank, in which case the web part will automatically detect the list name from the list URL. This alleviates the need to change this value repeatedly if you create a list template and give your new list a different name.

NOTE: If you leave this property blank and the list name has been changed since it was originally created, the list name will no longer match the URL and the auto list detect feature will not function. Also note that if your list name includes a colon or opening or closing parentheses, these characters will not make it into the URL and the web part will fail.

Display Form Name

(Required) This property defines the action to be taken when a hyperlink in the email is clicked. The default action is to go to dispform.aspx, which displays the list item’s information and does not allow editing. However, this value can be set to any form you want to use to display the list item. If you want the list item to be immediately sent into Edit Mode, type "editform.aspx" here.

List Item Title - 2.5 Only

(Optional) This property contains the title for the list item that is sent in the email body. It defaults to "Title," which is what the Tasks template utilizes as the Title field, but you can use any field in the list as the title. For instance, to enable this for Contacts, you can set this property to "Last Name" and the contents of the Last Name field will be included in the email message body.

Use SharePoint Email (Overrides Send Attachments) XE "SharePoint Email" XE "Email Notification:SharePoint Email"

Toggle this property on to utilize SharePoint to send email (version 3.5+ only). For most people, turning this on provides the most effective way of sending email. It allows the email to contain HTML elements.

The default is for this option to be turned on, which allows the web part to pull configuration information from SharePoint. It uses the internal mail settings that SharePoint uses when sending alerts. This is useful if you have utilized an SMTP server that is not on the same machine as SharePoint. It will not require you to enter the property hostname/IP for your email server.

If this option is enabled, it will send the email as HTML, so you will need to place an anchor tag around any URLs in the body of your message. For example:
Before: <*= ItemURL*>
After:<ahref="<*=ItemURL*>"><*=ItemURL*></a>

NOTE: This feature will be deactivated if you enter an email address in the Email From property or the server IP or hostname in the Email Server property.

Domain

This property is available in the Winter 2006 release only. It should be populated when a user name may be referenced in the User Lookup Field or Sec. User Lookup Field properties (above). When a user name is referenced, the domain for those users within the workplace must be identified. This property allows the administrator to identify the domain so the users do not have to each time they add or edit list items.

For example, rather than requiring the user to remember and type companyxyz\jdoe, you would enter companyxyz in the Domain property, and the user could simply type or select jdoe as a recipient.

Enable Error Event Log XE "Error Event Log:Email Notification" XE "Email Notification:Error Event Log"

(Optional) If this property is selected and an error occurs, the error will be sent to the Application Event Log on the server. The format will tell which list is causing the error and the error message. It will also provide trace information that can be used to resolve the error. This is disabled by default.

7Back To TopHelp_D2HPrivate(-9,726)Web Part Properties7

Audit Properties XE "Audit Properties:Email Notification" XE "Email Notification:Audit Properties"

Audit Field Title

This property is used to identify the name of the c that will be used to store the text for each entry of the audit history. The default is “History.” This must match a multi-line text field name in the list to allow more than 255 characters to be saved. If this option is left blank, no audit log will be saved.

Audit Field Body

This property is used to define the information to be written to the audit history field for each entry. It should be formatted in the same manner as the Email Body. You can use any text and variables from any of the fields in the list, just make sure the field names here match the ones in your list. The default format is:
Modified By: <*=Modified By*><*=Return*>Modified On: <*=Modified*><*=Return*><*=Return*>

If the audit field type does not support something you define here, you may see the code in the audit history instead of the value you were expecting.

If you set the History field to read-only, this field will be invisible to the edit/new item screens, but still visible in the All Items view.

NOTE: Audit History is NOT supported for document or picture libraries because SharePoint limits a multi-line field in libraries to 254 characters.

Log All Accesses and Changes Even If Email Is Not Sent

If this property is selected, an audit history will be written every time an item is accessed, regardless of whether an email was sent or an edit was saved. The default is for this option to be turned off.

Set History Field To Read Only – Cannot Be Reset

This property sets the History field to read-only, so it can only be edited by the List Item Emailer (LIE). If you enable this, the History field from that point on will only be visible in a view or a roll-up; the field will be locked and you will longer be able to see or edit it in a list (version 3.5+ only).

Use this property with caution. It cannot be turned off once it has been enabled.

8Back To TopHelp_D2HPrivate(-9,726)Web Part Properties8

Override Properties XE "Override Properties:Email Notification" XE "Email Notification:Override Properties"

Override Issue Catch

This property applies to Issues lists only. SharePoint uses the same ID for all responses to a particular issue. When this option is turned on, the web part looks at the type of list being used and if it is an Issues list, makes sure it behaves as expected. It makes sure that the item being looked at is the most recent entry for the issue.

Render Error To Output

Toggle this property on to render to the browser any errors that occur after the LIE has been activated. This means that errors will be displayed in the small notification window, so you need to make sure that "Ctrl A" - Select All and "Ctrl C" - Copy are ready to be handled because the window is only open for three seconds:

· As soon as the window opens, move your mouse to the window and click inside the window

· Type Ctrl-A to select all text

· Once all text is selected, type Ctrl-C to copy the selected text

· Open Notepad and paste the results

This can be used as an alternative to writing errors to the Application Event Log. It provides the same details, but does not require administrative access as the Event Log does and errors can usually be located faster.

Reset Send Email To No

By default, the List Item Emailer will set the Send Email field to Yes,when you leave the newform.aspx page or the editform.aspx page, unless you turn this option on. If this option is turned off and you type information on the page and then leave it without saving, it will still send an email to the person identified in the Assigned To field because Send Email will be set to “Yes.”

This is useful for Issues lists, as when Send Email is reset to Yes, it creates a new record for that Issue list item. With Issues lists, every change to a column is saved as a new line item. So whenever the LIE makes its changes and saved, it creates another new line item in the list.

Send Documents/Attachments As Attachments

This property allows you to send attachments stored within a list item as attachments in an email, instead of a link. If you are using the List Item Emailer within a document library, the document will be sent as an attachment within the email, negating the requirement to link back to the record in your message.

This only applies if you are utilizing the SMTP option of the List Item Emailer; it will not function with the Use SharePoint Email property.

Send Email As HTML – SMTP Server Only

Enable this property to allow emails to be sent as HTML instead of Mime. This can be used with any email program that supports SMTP; you do not have to use Microsoft Exchange^®. When this switch is turned off, emails are sent as text messages.

If you turn this property on or off, you may need to review the Email Body settings and edit them to include or exclude certain HTML properties. Specifically, if you enable this option and the “Use SharePoint Email” option, you will need to modify the item’s URL setting within the “Email Body,” setting it to be a hyperlink. If this is not done, the resulting notification may not have a link back to the item.

9Back To TopHelp_D2HPrivate(-9,726)Web Part Properties9

Optional - Email Process XE "Email Notification:Optional Email Process" XE "Optional Email Process"

The Email Process property allows you define a filtered value to be confirmed before sending and email to specific individuals with a specific message. This can be different for each filtered value you choose. This enables you to develop a process whereby information is validated and sent to users.

The message and recipients can be different for each possible column value. This enables you to develop a process whereby information is validated and sent to users.

NOTE: Any values entered here will replace the values found within the Emailer Properties section.

NOTE 2: See “A Sample Optional Email Process” for an example of how to define an optional email process.

A Note for Users Upgrading to Summer 2006

In past releases, if there were any situations where a process not identified in the Optional Email Process or the Subject and/or Body sections were left blank, an email would be sent that used the values from within the List Item Emailer’s Emailer Properties section. For example, if your organization utilizes five different task status values and the Optional Email Process identified four of them, an email would be sent for the fifth task status using the default settings.

This is no longer the case. If you choose to utilize the Optional Email Process, then all possible processes, along with the Email Subject and Body, must be identified. If part of the Optional Email Process is missed, an email will not be sent for that process.

Institute Email Process - Will Deactivate Assigned To and CC

This property allows you to enter the coded process that must be followed. The format for each entry in the Institute Email Process field is as follows:
Field#;Value#;Email To#;CC#;Email From#;Subject#;Body

The parameters for each entry are defined below. Each parameter must be separated by “#;” and a <NEW> tag must be placed between process entries. If you have multiple values in a parameter, they must be separated by a semicolon (;). If you choose to skip an optional field, just use #;

If you want to define an email message for more than one field value, use the <NEW> tag. This denotes the end of an individual email process and tells the LIE that a new process is beginning. Do not place a <NEW> tag before the first process. This element is case-sensitive.

NOTE: Do not use the + or ‘ characters within the Optional Email Process area. These characters are not compatible with the web part. The # character is only permitted as a parameter separation tool.

Field

(Required) The name of the field that controls the process (email) to be used.

Value

(Required) The value in the above field that triggers the email to be sent.

Email To

(Required) The field or email address to which the email should be sent. If you name a field, it will look up the email address in that field. Alternatively, you can hard-code an address here. If you choose to hard-code, you can identify multiple email addresses, separated by a semicolon (;).

NOTE: The ability to identify multiple email addresses is available only in the Optional Email Process, and only in the Winter 2006 and later releases.

CC

(Optional) The field or email address to which the email should be copied. The same rules apply here as to the Email To parameter.

NOTE: This parameter should be defined in the same manner as the Email To field above. That means that if you want to use a field name here, you must also use a field name for the Email To parameter. If you hard-code an email address here, you must also do so above.

Email From

This parameter is for future development. At this time, it will pull the value from the Email From web part property in the Emailer Properties. If that is empty, the email will come from the user saving the item.

Subject

(Optional) The subject for the message to be sent. This cannot be set to a field value.

Body

(Optional) The body for the message to be sent. If this is blank, the Email Body web part property (Emailer Properties) will be utilized. The same rules apply here as to the Email Body property.

Note that any field within the list can be used as part of the email message’s body, whether it is formatted as HTML or plain text.

Example:

Status#;Not Started#;Assigned To#;projectmanager@company.com
<NEW>
Status#;In Progress#;Assigned To#;projectmanager@company.com#;#;Task In Progress - <*=Title*>#;The following task has been started<*=Return*>Title: <*=Title*><*=Return*>By: <*=Modified By*><*=Return*>On: <*=Modified*>
<NEW>
Status#;Completed#;Assigned To#;projectmanager@company.com#;#;Task Completed - <*=Title*>#;The following task has been completed<*=Return*>Title: <*=Title*><*=Return*>By: <*=Modified By*><*=Return*>On: <*= Modified*>

In this example, the Email Subject and Email Body are stored in the corresponding properties in the Emailer Properties section of the web part properties.

This coding will cause the following to be done:

· If Status = Not Started, send an email to the assigned individual and cc it to the Project Manager from the person who created the task, with the subject and body that are stored in the web part’s Email Subject and Email Body properties.

· If Status = In Progress, send an email to the assigned individual and cc it to the Project Manager from the person who modified the task. The subject will be "Task In Progress - Task Title" and the body will be:
The following task has been started
Title: (Task Title)
By: (Person who modified Task)
On: (Time Task was changed)

· If Status = Completed, send an email to the assigned individual and cc it to the Project Manager from the person who modified the task. The subject will be "Task Completed - Task Title" and the body will be:
The following task has been completed
Title: (Task Title)
By: (Person who modified Task)
On: (Time Task was changed)

· If Status = Deferred, do nothing

· If Status = Waiting on Someone Else, do nothing

For more examples of the type of information you can use in a pre-configured email notification, see “Another Way of Looking at This,” above. Also see “A Sample Optional Email Process.”

10Back To TopHelp_D2HPrivate(-9,726)Web Part Properties10

Modifiable DWP Properties XE "DWP Properties: List Item Emailer"

CorasWorks web parts have a number of properties that can be modified by manually editing the DWP file associated with this web part. You can edit a DWP file by exporting the web part to a location of your choice, making the desired changes, and then uploading it back onto your site.

The properties described here allow you to change the function and display of the web part. Please keep in mind the XML namespace of the web part you are changing, or these properties will not be enabled within the web part. XML namespaces for all CorasWorks web parts are provided in the 11For DevelopersHelp_D2HPrivate(-9,656)Overview11 help topic.

Also note that some of these properties some may require the use of a "<", ">", or "&" symbol. If that is the case, you will need to replace these characters with their encoded equivalents of "<", ">", and "&" respectively.

These properties are only viewable in the DWP if the default settings have been changed.

ABody (String)

The body of the log that is stored in the list. Currently by default it implements "You have been assigned the following item; Title: <*=Title*><*=Return*>Modified By: <*=Modified By*> <*=Return*>Modified On: <*=Modified*> <*=Return*>------------------------<*=Return*>

<*=Return*> - Carriage Return

<*=Title*> - Title Field of List Item

<*=ModifiedBy*> - The user to Created/Modified the List Item

<*=Modified*> - The Date/Time when the List Item was Created/Modified

To alter this property change the text as you want it be presented in the Email. Place in the above tags to present information about the list item to the user. Place in the <*=Return*> to execute a Carriage Return in the body of the email message.

ALog (Boolean)

Log all accesses and/or changes to a list item even if an email is not sent to a user.

ATitle (String)

The list field that will be used to store the Audit Log. This should be a Multiple Line Text Field to allow more than 255 characters to be saved. This function is not available for Document Libraries as the max size of a Multiple Line Text field is 1000 characters. If this option is empty no audit log will be saved.

DFName (String)

The *.aspx page that displays the list item's information. By default this field will be filled in with "dispform.aspx" but can be set up to any form you want that will display the List Item. If you want the List Item to be sent immediately into Edit Mode, type "editform.aspx."

EBody (String)

The body of the email to be sent to the user. Currently by default it implements "You have been assigned the following item; <*=Return*>Title: <*=Title*> <*=Return*> Assigned By: <*=CreatedUser*> <*=Return*>Assigned On: <*=CurrentDate*> <*=Return*>List:<*=List*> <*=Return*>Item URL: <*=ItemURL*> <*=Return*><*=Return*>"

<*=Return*> - Carriage Return

<*=CreatedUser*> - The user to Created/Modified the List Item

<*=CurrentDate*> - The Date/Time when the List Item was Created/Modified

<*=List*> - The List Title for the List

<*=ItemURL*> - The direct URL to the List Item. This will include the "Display Form Name" that you specified in the "Display Form Name" property.

EField (String)

The Field that corresponds to the "User Lookup" field within the list that is utilized to retrieve the user's email address. This requires that the User's email address has been entered into "View Information About Site Users" area of "Site Settings" to send an email to this user.

If you want to append an email address to a choice select box from within you list you can do so by place the email address within a "[" and "]". Example (Approval Required [approver@company.com])

EField2 (String)

The Field that corresponds to the "User Lookup" field within the list that is utilized to retrieve the user’s email address. Utilize this property if you want to CC a user or assign responsibility to the list item to two individuals.

If you want to append an email address to a choice select box from within you list you can do so by place the email address within a "[" and "]". Example (Approval Required [approver@company.com])

EFrom (String)

The Email Address users will recognize as an email from the SharePoint Server. You can also specify a Manager reply-to address for users to immediately respond to for issues or concerns. If this entry is empty, this web part will default to the email address of the user who is currently logged-in and has created/modified a list item that has been emailed to a user.

ErrorEmail (Boolean)

Should errors occur, selecting this option will send an error to the Application Event Log on the server. The format will tell which list is causing the error and the error message and trace information that can be used to debug the error.

EServer (String)

The Server Name or IP Address which handles all email SMTP requests. If this entry is empty, this web part will default to the SMTP Service which resides on the same server with SharePoint installed. (If you decide to utilize this SMTP Service, please make sure you permit "Relay" for this server.)

ESubject (String)

The subject of the email sent to the user. By default, this implements "List Notification - <*=List*>".

<*=List*> - List Title

You can edit this property as necessary and, if you want the List Title to be presented in the Subject, implement the above tag to have it sent within the subject.

HistoryReadOnly (Boolean)

This setting allows you to change the history field to a read-only field that can only be edited by the List Item Emailer. Once you have enabled this, the history field from that point on only be visible in a view or a roll-up. After this has been changed, you can no longer edit this field and it will be locked.

LTitle (String) (2.5 Only)

The List Item Title field that is sent in the Email body. This is a required field and must be set as such in the List. By default, this is set to "Title," which is what the "Tasks" template utilizes as the Title field. But if you want to enable this for Contacts, you can set this to "Last Name" and the Last Name will be sent into the email message body.

Optional - Email Process

The Email Process Property allows you define a filtered value to be confirmed before sending an email to specific individuals with a specific message. This can be different for each filtered value you choose. This enables you to develop a process whereby information is validated and sent to users.

EmailProcess (String) - Will Deactivate Assigned To and CC

This property allows you to enter the coded process that must be followed.

Parameters

Email = Field#;Value#;Email To#;CC#;Email From#;Subject#;Body

New Entry = <NEW>

· Field (Required) = Name of the Field you want to filter on

· Value (Required) = The Value of the field that you want to filter on. Place """ around the value if you want to lock the value to what is stored there otherwise enter the value and it will execute if the value is found in the string. A quoted value will not function if your field is a choice, URL, or lookup

· Email To (Required) = The field or email address you want to send to. This functions in the same way as the User Lookup Field Property

· CC (Optional) = The field or email address you want to CC. This functions in the same way as the Sec. User Lookup Field Property

· Email From (Optional) = This parameter is for future development. At this time, it will pull the value from the Email From web part property in the Emailer Properties. If that is empty, the email will come from the user saving the item.

· Subject (Optional) = The subject for the message being sent. If this is blank then the Email Subject Property will be utilized. This functions in the same way as the Email Subject Property

· Body (Optional) = The body for the message being sent. If this is blank, the Email Body Property will be utilized. This functions in the same way as the Email Body Property.

<NEW> = If you have more than one filter to be used you can use this to separate each enabled email process. If you do not have more than one process this element is not required and should/must not be used.

In this example, the Email Subject and Email Body are stored in the corresponding properties in the Emailer Properties section of the web part properties.

This coding will cause the following to be done:

· If Status = Not Started, send an email to the assigned individual and cc it to the Project Manager, from the person who created the task, with the subject and body that are stored in the web part’s Email Subject and Email Body properties.

· If Status = In Progress, send an email to the assigned individual and cc it to the Project Manager, from the person who modified the task,. The subject will be "Task In Progress - Task Title" and the body will be:
The following task has been started
Title: (Task Title)
By: (Person who modified Task)
On: (Time Task was changed)

· If Status = Completed, send an email to the assigned individual and cc it to the Project Manager, from the person who modified the task. The subject will be "Task Completed - Task Title" and the body will be:
The following task has been completed
Title: (Task Title)
By: (Person who modified Task)
On: (Time Task was changed)

· If Status = Deferred, do nothing

· If Status = Waiting on Someone Else, do nothing

OverrideIssue (Boolean)

This toggle is designed to allow you to enforce the LIE to recognize this list as an Issues Type List. This is only useful if you have created a new List Definition from the Issues List list definition. Since the name of the original base template changes, this is the only way to indicate that the new list definition will be recognized as an Issues type list and will be handled accordingly.

RenderError (Boolean)

Toggle this property on to render any errors to the browser after the LIE has been activated. Since most of the time this error will be displayed in the small notification window, you will need to make sure that you have "Ctrl A" - Select All and "Ctrl C" - Copy ready to handled. As soon as the window opens, move your mouse to the window and click inside the window. After this, execute the first command to select all text. Once all text is selected, execute the second command to copy the selected text. Open Notepad and paste the results.

ResetSendEmail (Boolean)

By default, the List Item Emailer will reset the Send Email field from Yes to No when a list item is saved. If you do not want this default instance to occur, you can toggle this property off to not reset the Send Email field. This is useful for an Issues List, as when Send Email is reset to Yes, it will create a new record for that Issue List Item.

SendAsHTML (Boolean)

This property allows you to ensure that emails sent using the List Item Emailer will be sent as HTML instead of Mime. This is the same using SharePoint Email, but you are still able to send attachments.

SendAttachments (Boolean)

This property allows you to send attachments stored within a List Item as attachments in an email. If you are using the List Item Emailer within a document library, the document will be sent as attachment within the email negating the requirement for you to link back to the record in your message. This only applies if you are utilizing the SMTP option of the List Item Emailer. This will not function with the Use SharePoint Email property.

TLName (String)

This property is used to identify the list name you want to email-enable. This should be the same name as the folder that contains the "checkemail.aspx" file. This is utilized by the web part to check the list for modified list items that require an email to be sent. You can also leave this field blank to have the list name automatically detected from your list’s URL. This alleviates the need to change this constantly should you create a list template and give your new list a different name.

Use Complex Filter Process (String)

This property was introduced in the Winter 2006 release to allow you to activate filter use in the Optional Email Process.

NOTE: If you choose to use this property, be aware that you must alter the process you have in place in the Enable Optional Email Process property. The change that is required is the use of a filter instead of Field#;Value.

An example would be checking the current status of a task. In the standard Email Process, you would utilize “Status#;Not Started” to confirm the process if the task has not started. With the new process, you are required to use “Status=’Not Started’”. You will notice this filter looks identical to that used in the Calendar, Chart, and Data Publisher web parts.

Usage Example:

Send an email to the Project Manager if a task is assigned and not started. Send it from the person who assigned the item, to the Project Manager with a Subject of “Task Not Started”. In the body of the message, place a URL to the current item:

Status=’Not Started’#;pm@companyxyz.com#;#;#;Task Not Started#;Task <*=ItemURL*> Not Started

Send an email to the Assigned To and CC the Project Manager if a task is assigned and in progress. Send it from the person who modified the item, to the Assigned To and Project Manager with a Subject of “Task Started.” In the body of the message, place a URL to the current item:

Status=’In Progress’#;Assigned To#;pm@corasworks.net#;#;Task Started#;Task <*=ItemURL*> Has Started

UseSharePointEmail (Boolean)

Toggle this property on to utilize SharePoint to send emails. This is useful if you have utilized an SMTP server that doesn't exist on the same machine as SharePoint. It does not require you to enter the property hostname/IP for your email server. This will send the email as HTML, so you will need to modify anything in the body of your message for URLs with an anchor tag around them. Example:
Before: <*=ItemURL*>
After: <a href="<*=ItemURL*>"><*=ItemURL*></a>

Modifiable DWP Properties for Localization XE "Localization: List Item Emailer " XE "DWP Properties:Localization - List Item Emailer "

CorasWorks web parts have a number of properties that can only be modified by manually editing the DWP file associated with this web part. The properties described here relate specifically to localization. You can edit a DWP file by exporting the web part to a location of your choice, making the desired changes, and then uploading it back onto your site.

These properties allow you to change the function and display of the web part. Please keep in mind the XML namespace of the web part you are changing, or these properties will not be enabled within the web part. XML namespaces for all CorasWorks web parts are provided in the 12For DevelopersHelp_D2HPrivate(-9,656)Overview12 help topic.

Also note that some of these properties some may require the use of a "<", ">", or "&" symbol. With the exception of the LCIDXML property, you must replace these characters with their encoded equivalents of "<", ">", and "&" respectively.

These properties are only viewable in the DWP if the default settings have been changed.

Language (String)

This property allows the administrator to alter the default settings that the web part utilizes that are language-dependant. Each element must be separated by a ";"

Example: (Send Email;Modified;Modified By;Yes;No;Current)
Send Email = "Send Email"
Modified = "Modified"
Modified By = "Modified By"
Yes = "Yes"
No = "No"
Current = "Current" (Used with Issues lists to identify the most recent entry on a topic)

Use: <Language xmlns="webpart_namespace">Type Header Name</Language>

Example: <Language xmlns="EmailTestWebPart">Send Email;Modified;Modified By;Yes;No;Current</Language>

Troubleshooting XE "Troubleshooting:List Item Emailer " XE "FAQs: List Item Emailer " XE "Errors: List Item Emailer " XE "Email Notification:Troubleshooting"

If you have any questions that are not answered here, please refer to the Support area in CorasWorks Central.

How do I set up a group of individuals to send an email to?

You can do this in two ways:

· You can specify a distribution group email address which would be set up on your Exchange Server

· You can establish the Assigned to and/or CC column as a choice column, then identify email addresses (for either individuals or distribution groups) as the choices. Select the option to display the choices as checkboxes that allow multiple selections. Now you can select more than one email address, and the LIE will send the email to all of the selected addresses.

I didn't receive an email message.

This could be due several reasons:

· An error is occurring do to an incorrect setup of the web part. Please verify all properties correspond to the correct item in the List or Email server and try again. You will know if an error is occurring if the "Send Email" field does not change to "No" after you have saved the list item.

· Your email server is not permitting the email be sent through it. Please make sure you specified the correct email server and try again.

· You did not select "Yes" for the "Send Email" field.

· You did not select a User in the User Lookup field within the list item. (This references the primary User Lookup field only)

· You did not specify a Title within the list item that references the "Title" type field set up in the web part’s custom properties.

· The list item was added or edited in Datasheet mode. Email notifications are triggered when the checkemail.aspx is used and the pop-up is displayed. If the checkemail.aspx is not called, as is the case when Datasheet mode is used, the email will not be sent.

This can also occur if your email server is capturing Spam email message from your SharePoint Server. If you utilize an email address which does not correspond to the Domain (URL) of the server (e.g., yourdomainname.com), then your email server may not permit it since your DNS states that the email address domain you specified does not correspond to the IP Address of the domain from which you are sending.

Others are receiving email, but I am not.

This can occur if your Email Server is capturing SPAM email message from your SharePoint Server. If you utilize an email address which does not correspond to the Domain (URL) of the server (ex. corassolutions.com), then your Email Server may not permit it since your DNS states that the email address domain you specified does not the correspond the IP address of the domain you are sending from.

Notifications do not include a link back to the item.

If you enable both “Use SharePoint Email” and “Send Email as HTML,” you will need to modify the item’s URL setting within the “Email Body” field, setting it to be a hyperlink. If you do not do this, the resulting notification may not have a link back to the item.

Email Notification sends emails when items are closed without saving.

Emails are sent based upon the default behavior of the form pages. The CheckEmail.aspx page (the small window that is open whenever an item is saved) automatically runs whenever the NewForm.aspx or EditForm.aspx pages are exited. If that page has a value of "Send Email" equal to Yes, an email is sent. So, if the user does not want to send an email, they should set the “Send Email” value to No before exiting the page.

This can also occur for another reason. If you open a new item and then either close it or use your browser’s Back button, the LIE will look at the last item that was either edited or created and if the Send Email setting is set to Yes, it will send an email for that item. To prevent this from occurring, access the web part properties and locate the Reset Send Email to No property in the Override Properties section. This property is disabled by default. Place a check mark in the box to enable it.

I received the error "Value does not fall within the expected range."

If this error occurs before entering the list, it indicates that the list name located within the "List Name" text box is incorrect. Please correct it and try again.

If this error occurs after entering the list, it indicates that the Subject or Body values being used are incorrect. Please check to make sure that the values you are trying to collect exist within the list and try again.

I received the error "Access is denied."

This indicates that the user trying to send an email does not have permission to view the list shown in the email.

I received the error "User cannot be found."

This indicates that the user specified in the "Assigned To" is not a valid user for the site. This can be seen by trying to view the user within the "Manage Users" administration area.

I receive an error message which references the CDO Object.

This can occur if the email server settings are set incorrectly. You will need to confirm that the "Email Server" text box is correctly set and that the email server is able to send messages. This can also occur if the user who tried to send the email does not have an email address assigned to their account and the "Email From" text box is empty. Please also confirm that your email server permits relay from your current SharePoint Server.

How can I make email notification work with SPS?

Email notification does work in an SPS environment. However, as was stated earlier in this document, there is a SharePoint limitation that prevents list templates from working with SPS. The pre-enabled lists and libraries are for use with WSS or in WSS site collections under a portal. If you want to email-enable a list for use with SPS, you will need to add a few fields to the list. (If you are a PASM customer, see procedures in the How To: Email-Enable a List or Library document in the Premier section of the CorasWorks Central site.) Once that is done, you will need to use FrontPage to make the modifications described in the Capabilities Guide.

Tips and Tricks

Here are some hints and tips that CorasWorks Support has found valuable in troubleshooting email problems.

· Field Values – There are several default values in the List Item Emailer web part properties. Make sure the values correspond exactly to the field names in your list.

· Render Error To Output – The Render Error To Output option, from the Override Properties section of the web part properties, can be very useful as a troubleshooting tool. If you are experiencing errors and everything looks right, you can add the List Item Emailer web part to any page (default.aspx, for example) and configure it to point to the list you are working on. It will tell you if it has an error, but with more detail than the error log, every time you refresh the page. It will tell you if the error is before entering the list (which means that the list name is wrong) or after entering the list (which denotes an incorrect or empty field value). If it does not throw an error, after checking all the settings and correcting mistakes, copy the settings into the web part in the checkemail.aspx.

· Enable the ‘Use SharePoint Email’ option – For most people, the “Use SharePoint Email” web part property provides the most effective method of sending email. It allows the web part to query the SharePoint configuration and use the email information defined there. It will also allow the email to contain HTML elements.
There are three reasons why email will be sent as straight Mime rather than HTML:

· You have an email address specified in the From field.

· You have an IP address specified in the Server IP address line

· You have not checked the 'Use SharePoint Email' box

· Not Receiving Email Notifications – If some users receive the emails and others do not, make sure that the user has an email address assigned in the SharePoint system.

· If the user is signing in to WSS with an AD account rather than a SharePoint-created account, there will be no email address assigned, (Site Settings/Go to Site Administration/View User information). This is also an issue for SPS (Site Settings/Manage Security and Additional Settings/Show User Information).

Build Updates XE "Build Updates:List Item Emailer"

September 22, 2006

· The following issues were fixed regarding email notifications and documents in folders, as long as the site utilizes inherited permissions:

o Email notifications were not sent for documents uploaded into folders of an email-enabled library, but they were sent for documents loaded into the root folder

o If documents were uploaded into a folder and there were documents in the root, a notification would be sent for the last document placed in the library root by the same user

o If a folder was created in the root and the next action taken was to upload a file to a folder, you could see by rendering to output that the ID of the item the LIE was trying to send an email for was the ID of the newly created folder

· The LIE’s optional process logic no longer ignores the value supplied for the From field in the optional process definition. In the past, the LIE would only use the value specified as the Email From on the Checkemail.aspx page. This issue has been addressed. However, you need to make sure you are using an SMTP server in place of SharePoint Email for this to work.

· Support for emails sent to a cross-site group, as long as the sites do not use permission inheritance. To use cross-site groups, the site must be set up with unique permissions and the cross-site group must be given rights to that site.

March 17, 2006

· User name allowed in Assigned To and CC columns

· Added ability to customize web part response to user

· Updated Actions menu to include option to show web part version

December 1, 2004

· Added ability to auto detect current location of web part

· Added ability to SharePoint as mechanism for email

· Altered email component from CDO to ChilKat

· Added ability to send list attachments or documents as attachments

· Altered CC to no longer send via To field but as email CC

· Added ability to send email as HTML message

· Added support for Issues Type Lists

· Added ability to override reset of SendEmail

· Added ability to have email address within a choice field for Assigned To/CC

· Enabled ability to output errors to browser

· Added ability to set history field to read only

· Added ability to support email processes enabling the administer to send message based upon step in a process including;

· Field for Filter

· Filter Element (Field = choice)

· Assigned To

· CC

· Subject

· Message

October 1, 2004

· Added ability to force the recognition of a list as an Issue type list

· Added ability to added text and email address to a field within a list

· Added ability to render any errors out to the browser

· Added ability to send emails using SharePoint including HTML Email

· Added ability to automatically recognize list location not requiring the user to enter a list name

January 5, 2004

· Added ability to use text/multi-line/lookup field for Primary Email To Address

· Added ability to use text/multi-line/lookup field for Secondary Email To Address

· Added ability to use any field inside body of email that exists within the List

· Added Audit Logging

· Added support for Document Library Folders