Author: bradsdavis Date: 2009-04-09 20:07:30 -0400 (Thu, 09 Apr 2009) New Revision: 4533 Modified: jbpm4/branches/email/modules/userguide/src/main/docbook/en/modules/ch09-Emails.xml Log: Updated with templating starts. Modified: jbpm4/branches/email/modules/userguide/src/main/docbook/en/modules/ch09-Emails.xml =================================================================== --- jbpm4/branches/email/modules/userguide/src/main/docbook/en/modules/ch09-Emails.xml 2009-04-09 22:45:20 UTC (rev 4532) +++ jbpm4/branches/email/modules/userguide/src/main/docbook/en/modules/ch09-Emails.xml 2009-04-10 00:07:30 UTC (rev 4533) @@ -10,26 +10,107 @@ </section> <section id="scriptableemails"> <title>Producers</title> + <para>Producers are responsible for creating emails within jBPM. All mail producers implement the <literal>MailProducer</literal> interface. + Several out-of-the-box implementations have been created to address simple email needs.</para> + <para>For complex emails or custom generation of attachments, see: <link linkend="customemails">Extension Points: Custom Emails</link>.</para> <section id="standardemailformat"> <title>Standard</title> + <para>Used to send non-scripted text emails.</para> + <table><title>Standard Email</title> + <tgroup cols="2" rowsep="1" colsep="1"> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>subject</literal></entry> + <entry>Email subject.</entry> + </row> + <row> + <entry><literal>text</literal></entry> + <entry>The textual body of the email.</entry> + </row> + </tbody> + </tgroup> + </table> </section> <section id="scriptedemailformat"> <title>Scriptable Standard</title> + <para>Used to send scripted text emails for the subject and/or text.</para> + <table><title>Scriptable Email</title> + <tgroup cols="2" rowsep="1" colsep="1"> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>language</literal></entry> + <entry>The scripting language used to resolve properties within the subject and textual body.</entry> + </row> + <row> + <entry><literal>subject</literal></entry> + <entry>Email subject.</entry> + </row> + <row> + <entry><literal>text</literal></entry> + <entry>The textual body of the email.</entry> + </row> + </tbody> + </tgroup> + </table> </section> <section id="htmlemailformat"> <title>Scriptable HTML</title> + <para>Used to send scripted HTML formatted emails for the subject, text, and html.</para> </section> + <table><title>Scriptable HTML Email</title> + <tgroup cols="2" rowsep="1" colsep="1"> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>language</literal></entry> + <entry>The scripting language used to resolve properties within the subject, textual body, and HTML body.</entry> + </row> + <row> + <entry><literal>subject</literal></entry> + <entry>Email subject.</entry> + </row> + <row> + <entry><literal>text</literal></entry> + <entry>The textual body of the email.</entry> + </row> + <row> + <entry><literal>html</literal></entry> + <entry>The HTML formatted body of the email.</entry> + </row> + </tbody> + </tgroup> + </table> </section> <section id="emailtemplates"> <title>Templates</title> + <para>Templates are available to externalize commonly used messages from jPDL definitions. In jBPM 4, templates can produce either standard or HTML message; also, templates + can support any scripting language supported by the jBPM Script Manager. As you will see, any <literal>MailProducer</literal> implementation available to jPDL is also available to be templated. + </para> </section> - <section id="serverconfiguration"> + <section id="emailserverconfiguration"> <title>Server Configuration</title> - <para>Mail Server configuration is provided within jbpm.cfg.xml The <emphasis role="bold">mail-server</emphasis> tag describes an SMTP mail server capable of sending email messages. - Because jBPM uses JavaMail to send mail, all properties supported by JavaMail are also exposed to jBPM. Within the <emphasis role="bold">session-properties</emphasis> - subtag of <emphasis role="bold">mail-server</emphasis>, the SMTP properties must be provided as described in the example below.</para> + <para>Mail Server configuration is provided within jbpm.cfg.xml The <literal>mail-server</literal> tag describes an SMTP mail server capable of sending email messages. + Because jBPM uses JavaMail to send mail, all properties supported by JavaMail are also exposed to jBPM. Within the <literal>session-properties</literal> + subtag of <literal>mail-server</literal>, the SMTP properties must be provided as described in the example below.</para> <para> - See the Sun JavaMail API for more information on supported properties. <ulink url="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smt... SMTP Properties</ulink> + See the Sun JavaMail API for more information on supported properties: <ulink url="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smt... SMTP Properties</ulink>. </para> <programlisting>&lt;objects&gt; &lt;mail-session&gt; @@ -48,10 +129,10 @@ <para> To setup multiple SMTP mail servers, provide multiple mail servers within the jBPM configuration, as described below. - Note that the tag <emphasis role="bold">address-filter</emphasis> has been added to filter which domains are serviced by each mail server. + Note that the tag <literal>address-filter</literal> has been added to filter which domains are serviced by each mail server. The mail filter accepts regular expressions to determine if an address is to be sent by a given server. </para> - <para>See the Sun Pattern API for more information on supported RegEx expressions. <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern... Pattern JavaDoc</ulink> + <para>See the Sun Pattern API for more information on supported RegEx expressions: <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern... Regex Patterns</ulink>. </para> <programlisting>&lt;objects&gt; &lt;mail-session&gt; @@ -123,6 +204,13 @@ </section> <section id="customemails"> <title>Custom Emails</title> + <para>jBPM 4 allows the creation of your own Email Producers to address an organization's specific email needs. + To do so, users must implement the <literal>MailProducer</literal> interface. The method produce will return one or more Email objects, which jBPM will then send using the jBPM MailSession. + <para>Apache Commons Email was choosen to simplify the email interface for jBPM. All emails returned by the MailProducer implementation must extend the base <literal>org.apache.commons.mail.Email</literal>.</para> + <para>See the Apache Commons for more information on supported <literal>Email</literal> types: + <ulink url="http://commons.apache.org/email/">Apache Commons Email</ulink>.</para> + </para> + <section id="generatedemailattachments"> <title>Attachments</title> </section>