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) 2012-2019 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