Skip to content

Latest commit

 

History

History
270 lines (211 loc) · 6.71 KB

form-runner-email.md

File metadata and controls

270 lines (211 loc) · 6.71 KB

Email configuration properties

Connection to the SMTP server

The following properties control the connection to the SMTP server:

  • host: required SMTP host name
  • port: optional SMTP port override. If not specified, the defaults are:
    • plain SMTP: 25
    • TLS: 587
    • SSL: 465
  • encryption:
    • blank: none (plain SMTP)
    • tls: use TLS
    • ssl: use SSL
  • username: SMTP username (required if TLS or SSL is used, optional otherwise)
  • credentials: SMTP password
<property
    as="xs:string"
    name="oxf.fr.email.smtp.host.*.*"
    value="my.outgoing.smtp.server.org"/>

<property
    as="xs:string"
    name="oxf.fr.email.smtp.port.*.*"
    value="587"/>

<property
    as="xs:string"
    name="oxf.fr.email.smtp.encryption.*.*"
    value="tls"/>

<property
    as="xs:string"
    name="oxf.fr.email.smtp.username.*.*"
    value="jdoe"/>

<property
    as="xs:string"
    name="oxf.fr.email.smtp.credentials.*.*"
    value="secret"/>

Email addresses properties

  • from:
    • sender email address(es) appearing in the email sent
  • reply-to:
    • SINCE Orbeon Forms 2020.1
    • message Reply-To address(es)
  • to:
    • recipient email address(es) of the email sent
  • cc:
    • SINCE Orbeon Forms 2017.1
    • carbon copy recipient email address(es) of the email sent
  • bcc:
    • SINCE Orbeon Forms 2017.1
    • blind carbon copy email address(es) of the email sent

List of emails are space- or comma- separated.

<property
    as="xs:string"
    name="oxf.fr.email.from.*.*"
    value="[email protected]"/>

<property
    as="xs:string"
    name="oxf.fr.email.reply-to.*.*"
    value="[email protected]"/>

<property
    as="xs:string"
    name="oxf.fr.email.to.*.*"
    value="[email protected],[email protected]"/>
    
<property
    as="xs:string"
    name="oxf.fr.email.cc.*.*"
    value="[email protected],[email protected]"/>

<property
    as="xs:string"
    name="oxf.fr.email.bcc.*.*"
    value="[email protected],[email protected]"/>

Format of email addresses

In the examples above, only raw email addresses are shown. Multiple addresses must be separated by commas.

[SINCE Orbeon Forms 2021.4]

The configuration properties can now contain a name, following the standard syntax:

John Smith <[email protected]>

Or:

"John Smith" <[email protected]>

Keep in mind that if the addresses are stored in an XML attribute in your properties-local.xml, you need to escape some characters:

<property
    as="xs:string"
    name="oxf.fr.email.from.*.*"
    value="John Smith &lt;[email protected]&gt;"/>

Similarly, if you use quotes, you need to escape them:

<property
    as="xs:string"
    name="oxf.fr.email.from.*.*"
    value="&quot;John Smith&quot; &lt;[email protected]&gt;"/>

When more than one email is present, if you specify names, you must use commas exclusively as a separator (with whitespace allowed around commas):

<property
    as="xs:string"
    name="oxf.fr.email.from.*.*"
    value="&quot;John Smith&quot; &lt;[email protected]&gt;, Alice &lt;[email protected]&gt;"/>

Attachment properties

  • attach-pdf: whether the PDF representation is attached to the email
  • attach-tiff: whether the TIFF representation is attached to the email
  • attach-xml: whether the XML data is attached to the email
<property
    as="xs:boolean"
    name="oxf.fr.email.attach-pdf.*.*"
    value="true"/>

<property
    as="xs:boolean"
    name="oxf.fr.email.attach-tiff.*.*"
    value="true"/>

<property
    as="xs:boolean"
    name="oxf.fr.email.attach-xml.*.*"
    value="true"/>

[SINCE Orbeon Forms 2016.1]

The following property controls whether file and image form attachments are attached to the email.

  • all: all form attachments are included (this is the default)
  • none: no form attachments is included
  • selected: only form attachments selected in the Form Builder with "Include as Email Attachment" are included
<property
    as="xs:string"
    name="oxf.fr.email.attach-files.*.*"
    value="all"/>

[SINCE Orbeon Forms 2018.1]

The following properties control the name of the PDF, TIFF and XML attachments:

  • oxf.fr.email.pdf.filename:
    • filename of the PDF attachment, when present
  • oxf.fr.email.tiff.filename
    • filename of the TIFF attachment, when present
  • oxf.fr.email.xml.filename
    • filename of the XML attachment, when present

The property contains an XPath expression which generates the filename. The expression runs in the context of the current form data but does not have a access to controls. Only a limited set of Form Runner XPath functions can be used, in particular:

  • fr:form-title()
  • fr:app-name()
  • fr:form-name()
  • fr:form-version()
  • fr:document-id()
  • fr:mode()
  • fr:is-readonly-mode()
  • fr:is-design-time()

NOTE: Control values must be extracted by searching for element values within the XML document. In the future, we hope to provide a function for that purpose.

<property as="xs:string" name="oxf.fr.email.pdf.filename.*.*">
    concat(
        fr:form-title(),
        ' - ',
        //case-id,
        '.pdf'
    )
</property>

<property as="xs:string" name="oxf.fr.email.tiff.filename.*.*">
    concat(
        fr:form-title(),
        ' - ',
        //case-id,
        '.tiff'
    )

<property as="xs:string" name="oxf.fr.email.xml.filename.*.*">
    concat(
        fr:form-title(),
        ' - ',
        //case-id,
        '.xml'
    )
</property>

Email subject and body

NOTE: Since Orbeon Forms 2018.1, you can set a form's email subject and body in the Form Builder user interface. You can also use template placeholders. See Email settings.

With any Orbeon Forms version, the following properties can be used to set default and per app/form email subject and body templates.

<property 
    as="xs:string"
    name="oxf.fr.resource.*.*.en.email.subject"
    value="Here is your confirmation: "/>

<property 
    as="xs:string"
    name="oxf.fr.resource.*.*.en.email.body"
    value="Hi, here is an email from Orbeon Forms!"/>

Styling HTML emails

[SINCE Orbeon Forms 2019.1]

When using HTML for an email body template in Email settings, you can provide inline CSS that will be included in the email messages. For example"

<property as="xs:string" name="oxf.fr.email.css.custom.inline.*.*">
    ul li { list-style-type: none; margin-left: 0; }
</property>

This is known to work with Gmail at least.

See also