1 /** 2 * @fileOverview 3 * @author <a href="https://www.labkey.org">LabKey</a> (<a href="mailto:info@labkey.com">info@labkey.com</a>) 4 * @license Copyright (c) 2009-2017 LabKey Corporation 5 * <p/> 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * <p/> 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * <p/> 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * <p/> 18 */ 19 20 /** 21 * @namespace <font color="black">LabKey Email Notification Helper class. 22 * This class provides static methods to generate an email notification message that gets sent from the 23 * LabKey SMTP server.</font> 24 * <p>Additional documentation on SMTP setup for LabKey Server: 25 * <ul> 26 * <li><a href="https://www.labkey.org/Documentation/wiki-page.view?name=configWindows">Install LabKey via the Installer</a></li> 27 * <li><a href="https://www.labkey.org/Documentation/wiki-page.view?name=cpasxml">Modify the Configuration File -- Includes SMTP Settings</a></li> 28 * </ul> 29 * </p> 30 */ 31 LABKEY.Message = new function() 32 { 33 /*-- public methods --*/ 34 /** @scope LABKEY.Message */ 35 return { 36 /** 37 * A map of the email recipient types. The values in 38 * this map are as follows: 39 * <ul> 40 * <li>to</li> 41 * <li>cc</li> 42 * <li>bcc</li> 43 * </ul> 44 * For example, to refer to the cc type, the syntax would be:<br/> 45 * <pre><code>LABKEY.Message.recipientType.cc</code></pre> 46 */ 47 recipientType : { 48 to : 'TO', 49 cc : 'CC', 50 bcc : 'BCC' 51 }, 52 /** 53 * A map of the email message body types. Email messages can contain multiple content types allowing a 54 * client application the option to display the content it is best suited to handle. A common practice is to 55 * include both plain and html body types to allow applications which cannot render html content to display 56 * a plain text version. The values in 57 * this map are as follows: 58 * <ul> 59 * <li>plain</li> 60 * <li>html</li> 61 * </ul> 62 * For example, to refer to the html type, the syntax would be:<br/> 63 * <pre><code>LABKEY.Message.msgType.html</code></pre> 64 */ 65 msgType : { 66 plain : 'text/plain', 67 html : 'text/html' 68 }, 69 70 /** 71 * Sends an email notification message through the LabKey Server. Message recipients and the sender 72 * must exist as valid accounts, or the current user account must have permission to send to addresses 73 * not associated with a LabKey Server account at the site-level, or an error will be thrown. 74 * @param config A configuration object containing the following properties 75 * @param {String} config.msgFrom The email address that appears on the email from line. 76 * @param {String} [config.msgSubject] The value that appears on the email subject line. 77 * @param {Object[]} config.msgRecipients An array of recipient objects which have the following properties: 78 * <ul> 79 * <li>type: the recipient type, must be one of the values from: LABKEY.Message.recipientType.</li> 80 * <li>address: the email address of the recipient.</li> 81 * </ul> 82 * The utility function LABKEY.Message.createRecipient can be used to help create these objects. 83 * @param {Object[]} config.msgContent An array of content objects which have the following properties: 84 * <ul> 85 * <li>type: the message content type, must be one of the values from: LABKEY.Message.msgType.</li> 86 * <li>content: the email message body for this content type.</li> 87 * </ul> 88 * The utility function LABKEY.Message.createMsgContent can be used to help create these objects. 89 * @param {function} [config.success] A reference to a function to call if the action succeeds. This 90 * function will be passed the following parameters: 91 * <ul> 92 * <li><b>result:</b> an object containing a boolean property: success.. 93 * <li><b>response:</b> The XMLHttpResponse object</li> 94 * </ul> 95 * @param {function} [config.failure] A reference to a function to call when an error occurs. This 96 * function will be passed the following parameters: 97 * <ul> 98 * <li><b>errorInfo:</b> an object containing detailed error information (may be null)</li> 99 * <li><b>response:</b> The XMLHttpResponse object</li> 100 * </ul> 101 * @param {object} [config.scope] A scoping object for the success and error callback functions (default to this). 102 * @returns {Mixed} In client-side scripts, this method will return a transaction id 103 * for the async request that can be used to cancel the request. 104 * In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.) 105 * @example Example: 106 <pre name="code" class="xml"> 107 <script type="text/javascript"> 108 109 function errorHandler(errorInfo, responseObj) 110 { 111 LABKEY.Utils.displayAjaxErrorResponse(responseObj, errorInfo); 112 } 113 114 function onSuccess(result) 115 { 116 alert('Message sent successfully.'); 117 } 118 119 LABKEY.Message.sendMessage({ 120 msgFrom: 'admin@test.com', 121 msgSubject: 'Testing email API...', 122 msgRecipients: [ 123 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.to, 'user1@test.com'), 124 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.cc, 'user2@test.com'), 125 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.cc, 'user3@test.com'), 126 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.bcc, 'user4@test.com') 127 ], 128 msgContent: [ 129 LABKEY.Message.createMsgContent(LABKEY.Message.msgType.html, '<h2>This is a test message</h2>'), 130 LABKEY.Message.createMsgContent(LABKEY.Message.msgType.plain, 'This is a test message') 131 ], 132 success: onSuccess, 133 failure: errorHandler, 134 }); 135 </script> 136 </pre> 137 */ 138 sendMessage : function(config) 139 { 140 var dataObject = {}; 141 142 if (config.msgFrom != undefined) 143 dataObject.msgFrom = config.msgFrom; 144 if (config.msgRecipients != undefined) 145 dataObject.msgRecipients = config.msgRecipients; 146 if (config.msgContent != undefined) 147 dataObject.msgContent = config.msgContent; 148 if (config.msgSubject != undefined) 149 dataObject.msgSubject = config.msgSubject; 150 151 return LABKEY.Ajax.request({ 152 url: LABKEY.ActionURL.buildURL("announcements", "sendMessage"), 153 method : 'POST', 154 success: LABKEY.Utils.getCallbackWrapper(LABKEY.Utils.getOnSuccess(config), config.scope), 155 failure: LABKEY.Utils.getCallbackWrapper(LABKEY.Utils.getOnFailure(config), config.scope, true), 156 jsonData : dataObject, 157 headers : { 158 'Content-Type' : 'application/json' 159 } 160 }); 161 }, 162 /** 163 * A utility function to create a message content object used in LABKEY.Message.sendMessage. 164 * @param {LABKEY.Message.msgType} type The content type of this message part. 165 * @param {String} content The message part content. 166 */ 167 createMsgContent : function(type, content) 168 { 169 return { 170 type : type, 171 content : content 172 }; 173 }, 174 /** 175 * A utility function to create a recipient object used in LABKEY.Message.sendMessage. 176 * @param {LABKEY.Message.recipientType} type Determines where the recipient email address will appear in the message. 177 * @param {String} email The email address of the recipient. 178 */ 179 createRecipient : function(type, email) 180 { 181 return { 182 type : type, 183 address : email 184 } 185 }, 186 187 /** 188 * A utility function to create a recipient object (based on a user ID or group ID) used in LABKEY.Message.sendMessage. 189 * Note: only server side validation or transformation scripts can specify a user or group ID. 190 * @param {LABKEY.Message.recipientType} type Determines where the recipient email address will appear in the message. 191 * @param {Integer} id The user or group id of the recipient. 192 */ 193 createPrincipalIdRecipient : function(type, id) 194 { 195 return { 196 type : type, 197 principalId : id 198 } 199 } 200 }; 201 }; 202