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-2018 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 * Recipients whose accounts have been deactivated or have never been logged into will be silently dropped from 84 * the message. 85 * @param {Object[]} config.msgContent An array of content objects which have the following properties: 86 * <ul> 87 * <li>type: the message content type, must be one of the values from: LABKEY.Message.msgType.</li> 88 * <li>content: the email message body for this content type.</li> 89 * </ul> 90 * The utility function LABKEY.Message.createMsgContent can be used to help create these objects. 91 * @param {function} [config.success] A reference to a function to call if the action succeeds. This 92 * function will be passed the following parameters: 93 * <ul> 94 * <li><b>result:</b> an object containing a boolean property: success.. 95 * <li><b>response:</b> The XMLHttpResponse object</li> 96 * </ul> 97 * @param {function} [config.failure] A reference to a function to call when an error occurs. This 98 * function will be passed the following parameters: 99 * <ul> 100 * <li><b>errorInfo:</b> an object containing detailed error information (may be null)</li> 101 * <li><b>response:</b> The XMLHttpResponse object</li> 102 * </ul> 103 * @param {object} [config.scope] A scoping object for the success and error callback functions (default to this). 104 * @returns {Mixed} In client-side scripts, this method will return a transaction id 105 * for the async request that can be used to cancel the request. 106 * In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.) 107 * @example Example: 108 <pre name="code" class="xml"> 109 <script type="text/javascript"> 110 111 function errorHandler(errorInfo, responseObj) 112 { 113 LABKEY.Utils.displayAjaxErrorResponse(responseObj, errorInfo); 114 } 115 116 function onSuccess(result) 117 { 118 alert('Message sent successfully.'); 119 } 120 121 LABKEY.Message.sendMessage({ 122 msgFrom: 'admin@test.com', 123 msgSubject: 'Testing email API...', 124 msgRecipients: [ 125 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.to, 'user1@test.com'), 126 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.cc, 'user2@test.com'), 127 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.cc, 'user3@test.com'), 128 LABKEY.Message.createRecipient(LABKEY.Message.recipientType.bcc, 'user4@test.com') 129 ], 130 msgContent: [ 131 LABKEY.Message.createMsgContent(LABKEY.Message.msgType.html, '<h2>This is a test message</h2>'), 132 LABKEY.Message.createMsgContent(LABKEY.Message.msgType.plain, 'This is a test message') 133 ], 134 success: onSuccess, 135 failure: errorHandler, 136 }); 137 </script> 138 </pre> 139 */ 140 sendMessage : function(config) 141 { 142 var dataObject = {}; 143 144 if (config.msgFrom != undefined) 145 dataObject.msgFrom = config.msgFrom; 146 if (config.msgRecipients != undefined) 147 dataObject.msgRecipients = config.msgRecipients; 148 if (config.msgContent != undefined) 149 dataObject.msgContent = config.msgContent; 150 if (config.msgSubject != undefined) 151 dataObject.msgSubject = config.msgSubject; 152 153 return LABKEY.Ajax.request({ 154 url: LABKEY.ActionURL.buildURL("announcements", "sendMessage"), 155 method : 'POST', 156 success: LABKEY.Utils.getCallbackWrapper(LABKEY.Utils.getOnSuccess(config), config.scope), 157 failure: LABKEY.Utils.getCallbackWrapper(LABKEY.Utils.getOnFailure(config), config.scope, true), 158 jsonData : dataObject, 159 headers : { 160 'Content-Type' : 'application/json' 161 } 162 }); 163 }, 164 /** 165 * A utility function to create a message content object used in LABKEY.Message.sendMessage. 166 * @param {LABKEY.Message.msgType} type The content type of this message part. 167 * @param {String} content The message part content. 168 */ 169 createMsgContent : function(type, content) 170 { 171 return { 172 type : type, 173 content : content 174 }; 175 }, 176 /** 177 * A utility function to create a recipient object used in LABKEY.Message.sendMessage. 178 * @param {LABKEY.Message.recipientType} type Determines where the recipient email address will appear in the message. 179 * @param {String} email The email address of the recipient. 180 */ 181 createRecipient : function(type, email) 182 { 183 return { 184 type : type, 185 address : email 186 } 187 }, 188 189 /** 190 * A utility function to create a recipient object (based on a user ID or group ID) used in LABKEY.Message.sendMessage. 191 * Note: only server side validation or transformation scripts can specify a user or group ID. 192 * @param {LABKEY.Message.recipientType} type Determines where the recipient email address will appear in the message. 193 * @param {Integer} id The user or group id of the recipient. 194 */ 195 createPrincipalIdRecipient : function(type, id) 196 { 197 return { 198 type : type, 199 principalId : id 200 } 201 } 202 }; 203 }; 204