There are five sections of properties on the LIE Wizard interface:
When this property is enabled, SharePoint is used to send email. For most people, enabling this property provides the most effective way of sending email, and 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 property will be deactivated if you enter an email address in the Email From property or identify server IP or host name in the Server Name property.
This is the Server Name or IP Address that handles all email SMTP requests. If you have Use SharePoint Email enabled (see above), leave this field blank. When this field 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.
This property is populated when a user name may be referenced in the Primary or Secondary Recipient(s) Field properties (below). 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.
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 (see above). The LIE Wizard will get the email address from SharePoint.
• 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.
• To reference a cross-site group, type “xsg:” in front of the group name in the appropriate column when the list item is added or modified (e.g., xsg:Team1). A cross-site group can also be identified as a choice, as can an email address or user name. (e.g., Team1 [xsg:Team1]). This tells the LIE to look for the Team1 cross-site group in the current site and get the email addresses for all users within that group.
This property is used to name the field (column) in the list item that is used to determine the secondary email address(es) to send the email to (usually CC). The same rules and abilities apply here as to the Primary Recipient(s) Field above, including the ability to reference a user name or email address.
NOTE: If you have Use SharePoint Email enabled, the To and CC selections will both be placed in the To field of the email.
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*>
This property is used to define the body of the email to be sent to the user.
CorasWorks populates the Email Body property 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 columns in the list can be used, including custom columns you have created.
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: <*=columnname*>
• Carriage returns should be encapsulated like this: <*=Return*>
• Other key columns and syntax:
• 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.
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.
NOTE: As of the Winter 2007 release, if you have the Use SharePoint Email property enabled, anything entered as the Email From value is overridden by the value set as the From Address property in SharePoint’s Outgoing Email Settings. This is accessed via SharePoint Central Administration/ Operations.
This optional 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.
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.
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 column, but you can use any column in the list as the title. For instance, to enable this for Contacts, you can set this property to "Last Name" and the value in the Last Name column will be included in the email message body.
If this option 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 column 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 column 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 column in the list, just make sure the column
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 enable Set Audit Column 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 box 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 Audit column to read-only, so it can only be edited by the List Item Emailer (LIE). If you enable this, the Audit column from that point on will only be visible in a view or a roll-up; the column will be locked and you will longer be able to see or edit it in a list (version 3.5 only).
Use this option with caution. It cannot be turned off once it has been enabled.
TIP: Enabling the option to set the Audit column to read-only can help your organization comply with Sarbanes-Oxley regulations by providing a static record of notification activity.
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 option 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 Optional Email Process section 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.
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 1: Any values entered here will replace the values found within the Emailer Properties section of the List Item Emailer Wizard.
NOTE 2: With the Optional Email Process, emails will only be sent 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.
NOTE 3: See A Sample Optional Email Process for an example of how to define an optional email process.
This property is used to enter the coded process to 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 “#;” If you reference multiple email addresses within a parameter, they must be separated by a semicolon (;). If you choose to skip an optional field, 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 1: 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.
NOTE 2: The values identified in the settings below replace the values found within the corresponding fields in the Emailer Properties section. The definitions below detail which fields are replaced with each section of the process string. If any optional values are not defined in the Email Process section, they will default to the values in the Emailer Properties section.
(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.
(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.
This section contains one property, Language Translation. This property allows the administrator to alter the web part’s default settings that are language-dependent.
This property allows the administrator to alter the web part’s default settings that are language-dependent. It is comprised of the elements listed below. Each element must be separated by a semicolon (;).
• Send Email
• Modified
• Modified By
• Yes
• No
• Current (Used with Issues lists to identify the most recent entry on a topic)
Example: Send Email;Modified;Modified By;Yes;No;Current
The Response Properties section allows you to configure a customized web part response to the user. In past releases, each time an item in an email-enabled list was added or modified, a pop-up window would be displayed with a default response of “Checking Email.” This section allows you to change the message displayed in that window. As of the Winter 2007 release, the standard configuration of email-enabled lists no longer includes this pop-up window. However, the section titled “How To: Email-Enable a List or Library” in the Appendix of the Capabilities Guide (included in the Suite documentation) provides code to cause the pop-up window to continue to be displayed.
This property is used to modify the web part’s response to the user to utilize HTML or XML. If you utilize this property, it overrides any text defined in the CheckEmail.aspx page, and any other item displayed on the page such as web parts, text, and images.
If you want to take the response a step further and include the web part status messages, enable the Render Error in Output property, set the Response Type (described below) to HTML, and include the <%Output%> variable in your HTML. (The status message output is not XML-safe.)
Example:
To display the current output in HTML with “Checking Email”:
<html><body><br/><br/><font size=”3” face=”arial”><b>Checking Email</b></font><br/></body></html>
Property Setup:
<Response xmlns=”CorasWSC.List.Item”><![CDATA[HTML]]></Response>
This property allows you to change the type of response displayed by the web part to the user. Valid choices include:
• text/html (default)
• text/xml
• text/plain
Property Setup:
<ResponseType xmlns=”CorasWSC.List.Item”><![CDATA[text/html]]></ResponseType>