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-2016 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/wiki/home/Documentation/page.view?name=configWindows">Install LabKey via the Installer</a></li>
 27  *                  <li><a href="https://www.labkey.org/wiki/home/Documentation/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 fuction 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 fuction 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 fuction 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