Difference between revisions of "Java API:Email"

Revision as of 21:16, 25 June 2013

The Email and Document Management Java APIs are used to manage Email and generate documents.

sendEmail

Sends an email.

Syntax

Basic:

Functions.sendEmail(String objectName, String recordId,

         String to, String cc, String subject, String body, 
         String attachmentTemplateIdList, String attachmentIdList);

</syntaxhighlight>

with Bcc:

Functions.sendEmail(String objectName, String recordId,

         String to, String cc, String bcc, String subject, String body, 
         String attachmentTemplateIdList, String attachmentIdList);

</syntaxhighlight>

with TenantContext:

Functions.sendEmail(String objectName, String recordId,

         String to, String cc, String subject, String body, 
         String attachmentTemplateIdList, String attachmentIdList, 
         TenantContext context);

</syntaxhighlight>

with fromName and fromAddress:

Functions.sendEmail(String objectName, String recordid, String to, String cc, String bcc,

         String subject, String body, String attachmentTemplateId, 
         String attachmentIdList, String fromName, String fromAddress);

</syntaxhighlight>

Parameters

objectName

The name of the object the email relates to, or the objectId. This field is required, and must be a non-empty string.

recordId

The identifier of the record the message relates to. This field can be an empty string ("").

to

A list of comma-separated email addresses

cc

A list of comma separated email addresses to copy the message to. (Recipients see addresses in this list.)

bcc

Optional. List of comma separated email addresses for "blind copies" (Recipients do not see addresses in this list.)

subject

A descriptive text string

body

The contents of the email message (static text).

attachmentTemplateIdList

A list of comma-separated Document Template identifiers. The template variables are evaluated at run time, their values are substituted, and the resulting documents are then sent as attachments.

Note:
Do not choose a template based on a JSP page for use as an attachment.
Learn more: JSP Attachment Deprecation

attachmentIdList: A list of comma-separated document identifiers to send as attachments
context: An optional TenantContext Object used to send an email using a user-alias in another tenancy.
fromName and fromAddress: Provide fromName and fromAddress as parameter to send email if emails are bouncing as spam. See http://agileappscloud.info/wiki/Email_Bounce_Notification for more information.

Considerations

You can use this method to send attachments with data from the record using one or more Document Templates.

In order for the template variables to be populated, the document template ID passed to the API must be defined in the object that is specified in the first parameter - objectID

Successful execution of the call adds an entry in the 'Activity History' section of the record that is specified in the second parameter - recordID.

The values specified in the 'to' and 'cc' fields can be retrieved using requestParams object.

Direct email addresses can also be passed as a string in the API parameters.

In order to send email to multiple addresses with multiple attachments specify the various values in a comma-separated string.

Return: Result object

Example: This example calls sendMail for a contact.

<syntaxhighlight lang="java" enclose="div"> String contactID = ""; String attachmentIdList = ""; String attachmentTemplateIdList = "";

// Some code to populate contactID. // Some code to populate attachmentIdList. // Populate the attachmentTemplateIdList with template ID of the Document Template

Result sendEmailResult = Functions.sendEmail("CONTACT", contactID, "joe.smith@acme.com,mark.smith@acme.com",

   "cc.smith@xyz.com", "Some subject", 
   "Hello, This email was sent from the Java API",
   attachmentTemplateIdList, attachmentIdList);

</syntaxhighlight>

sendEmailUsingTemplate

Sends an Email message using the Template identified by the bodyTemplateId parameter. Generates one or more documents and includes them as attachments.

Prerequisites

Go to > Objects > {Object} > Email Templates

Define or find a template.

Get the ID of that template, for use in the bodyTemplateID parameter.

Syntax
Basic:

Result result = Functions.sendEmailUsingTemplate(String objectID, String recordID,

   String to, String cc, String subject, String bodyTemplateID, 
   String attachmentTemplateIdList, String attachmentIDList);

</syntaxhighlight>

with Bcc:

Result result = Functions.sendEmailUsingTemplate(String objectID, String recordID,

   String to, String cc, String Bcc, String subject, String bodyTemplateID, 
   String attachmentTemplateIdList, String attachmentIDList);

</syntaxhighlight>

with Bcc and from whom:

Result result = Functions.sendEmailUsingTemplate(String objectID, String recordID,

   String to, String cc, String Bcc, String subject, String bodyTemplateID, 
   String attachmentTemplateIdList, String attachmentIDList,
   String fromName, String fromAddress);

</syntaxhighlight>

Parameters

objectID

The identifier of the related object

recordID

The identifier of the related record

to

A list of comma-separated email addresses

cc

A list of comma separated email addresses

bcc

Optional. List of comma separated email addresses for "blind copies" (Recipients do not see addresses in this list.)

subject

A descriptive text string. If this value is an empty string, the subject specified in the template is used. Otherwise, the specified string is used.

bodyTemplateID

ID of the Email Template. It is evaluated at run time, template variables substituted, and then sent as the body of the message.

attachmentTemplateIdList

A list of comma-separated Document Template identifiers. The template variables are evaluated at run time, their values are substituted, and the resulting documents are then sent as attachments (in addition to any attachments defined by the Email Template).

Note:
Do not choose a template based on a JSP page for use as an attachment.
Learn more: JSP Attachment Deprecation

attachmentIdList: A list of comma-separated document identifiers to send as attachments

fromName

The name the email is coming from.
fromAddress: The address the email is coming from.

Return

Result object

Example: This example calls sendEmailUsingTemplate for a contact.

<syntaxhighlight lang="java" enclose="div"> String contactID = ""; String attachmentTemplateIdList = ""; String bodyTemplateID = ""; String attachmentID = "";

// Some code to populate contactID. // Populate attachmentTemplateIdList manually from the template Ids displayed in UI from Template object // Populate bodyTemplateID manually from the template Id displayed in the UI from Template object

Functions.sendEmailUsingTemplate("CONTACT", contactID, "joe.smith@acme.com,mark.smith@acme.com", "cc.smith@xyz.com", "Some subject", bodyTemplateID, attachmentTemplateIdList, attachmentID); </syntaxhighlight>

generateDocument

Generates a document based on an HTML Document Template.

Syntax

Result result; result = Functions.generateDocument(String object, String recordID,

                                   String templateID, String format);

</syntaxhighlight>

Parameters

object

The name or identifier of the object that contains the record of interest.

recordID

The identifier of the record to pass to the template.

printTemplate

The identifier of the Document Template.

To get the template ID:

Go to > Objects > {object} > Document Templates
Click the Wrench icon to edit the view or create a new one
Add the recordID field to the view
In the listing, find the ID of the Document Template you'll be using

format: CONSTANTS.DOCUMENT.HTML -or- CONSTANTS.DOCUMENT.PDF; This option applies to HTML and PDF templates. Word templates always produce Word files. PowerPoint templates produce PowerPoint files.

Return

Result object

Usage

Get the object name from the Object Properties
Get the template name from the Document Template
Get the record ID from the incoming parameters
Use result.getID() to retrieve the document ID
Pass it to the getDocument method to get a PlatformFileBean that contains the document

Example: This example calls generateDocument on a case to create an HTML document.

String printTemplate = ""; // Code this value String recordID = ""; // Get this value from incoming parameters

...

Result result = Functions.generateDocument("cases", recordID, printTemplate, CONSTANTS.DOCUMENT.HTML); int resultCode = result.getCode(); if(resultCode < 0) {

   String msg = "Some Message";
   Logger.info(msg + ":\n" + result.getMessage(), "Doc"); // Log details
   Functions.throwError(msg + ".");                       // Error message

} else {

   String doc_id = result.getID();
   PlatformFileBean file = Functions.getDocument(doc_id);

   // Additional business logic...

} </syntaxhighlight>

@@ Line 1: / Line 1: @@
 <categorytree mode=pages style="float:right; clear:right; margin-left:1ex; border:1px solid gray; padding:0.7ex; background-color:white;">Java API</categorytree>
-The Email and Document Management [[Java API]]s  manage [[Email]] and [[Documents]].
+The Email and Document Management [[Java API]]s  are used to manage [[Email]] and generate documents.
 == sendEmail ==

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

Difference between revisions of "Java API:Email"

Revision as of 21:16, 25 June 2013

Contents

sendEmail

sendEmailUsingTemplate

generateDocument