There are four sections of List Item Emailer web part properties:
(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.
(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.
• 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.
(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.
(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*>
(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.
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>>/ |
* 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.
(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.
(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.
(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.
(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.
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.
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.
(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.
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.
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.
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.
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.
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.
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.
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.
NOTE: If you make any changes to user access to an email-enabled list, it is important that you consider how those modifications might interact with this particular property. For example, if you restrict user rights to a list so that the user can only create (not edit) an item, the List Item Emailer will not be able to reset the Send Email field when a list item is created because that is a type of edit. As a result, it will not be able to send the email notification.
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.
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.
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.
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.
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.
(Required) The name of the field that controls the process (email) to be used.
(Required) The value in the above field that triggers the email to be sent.
(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.
(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.
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.
(Optional) The subject for the message to be sent. This cannot be set to a field value.
(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.
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.”