Emailing Reports

With release 2.4.20 of Weave there has been some basic report emailing capability added, which is expected to be expanded upon over time.

At the moment the capabilities are limited to the simple report menu and simple report action, and is not supported by reports generated via the report view.

Additionally the emailing is currently limited to sending the email to a fixed address, this is because the initial use case for this operation was to submit information to a single entity, rather that being a general purpose emailing facility.

Additional functionality will hopefully come as the UI/configuration changes are worked out relating to how this will be configured and where the email options will fit in with the existing report generation UI.

To configure the ability to send an email containing a report requires up to three things to be setup:

1. The setting for a SMTP server that will be used to send the emails.
2. Optional settings for the email itself, for things like the from address, to address, email subject, etc.
3. The simple report action and/or simple report menu must be updated to include the email information, either directly, in which case the previous step isn't required or indirectly by referencing the information setup in the previous step

Setting up a SMTP server

To be able to send any emails from Weave you must provide Weave with the details of a mail server that will be used to send the emails.
This is done using the com.cohga.server.mail configuration options

<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="urn:com.cohga.server.config#1.0" xmlns:mail="urn:com.cohga.server.mail#1.0">

	<mail:smtp>
		<host>mail.sforbes.net</host>
		<username>sforbes</username>
		<password>ENCEAUFJCUABCFXEMFQABFJEBZJAKFCXGME</password>
	</mail:smtp>

</config>

The smtp config requires at least the host property, to provide the hostname or ip address of the mail server. It may also requires the username and password setting if the mail server requires authentication before it will send any email (the password can be encrypted using the encrpyt command and the osgi prompt).
Additionally any setting supported by the Java Mail API may also be specified, by removing the mail.smtp. prefix from the setting and including it in the smtp config.
The available Java Mail API setting are available here.

Setting up email settings

If you're going to have more that one report supporting emailing then it's probably a good option to set the default options for the email in a separate report email configuration item and then reference it in the report definitions. Alternatively you can skip this and apply those setting directly to the report item in the client config.

The default values that can be setup in an email config are the from address, the to addresses, the cc addresses, the bcc addresses, the email subject and the email message.

<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="urn:com.cohga.server.config#1.0" xmlns:report="urn:com.cohga.server.report#1.0">

	<report:email id="feedback">
		<from>noreply@sforbes.net</from>
		<to>feedback@sforbes.net</to>
	</report:email>

</config>

The minimum settings required are a from and to address.
You can specify multiple to addresses (and cc and bcc addresses) by either including multiple tags or comma separating the addresses in one tag.

There are a couple of special markers that can be used in the addresses, they are ${userid} and ${domain}.
They allow you to substitute the current userid and the servers domain into the address. Note that the domain is guessed based on the canonical host name of the Weave server, and defaults to 'local' if it can't be determined.
So you could use the following to try and guess the from address of the user

		<from>${userid}@${domain}</from>

or

		<from>${userid}@sforbes.net</from>

The default subject used to send the email is "Weave Report", which can be changed be either setting a subject property in the email config or by setting the report.email.subject i18n resource value.

Similarly the default message, which is only included when a report is sent as an attachment as would be the case if the report was generated as a PDF document, is "A report has been generated and sent to you", and can be changed by setting the message property or by setting the report.email.message i18n resource value.

<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="urn:com.cohga.server.config#1.0" xmlns:report="urn:com.cohga.server.report#1.0">

	<report:email id="feedback">
		<from>noreply@sforbes.net</from>
		<to>feedback@sforbes.net</to>
		<subject>Feedback</subject>
		<message>The following has been submitted as a feedback report</message>
	</report:email>

</config>

<?xml version="1.0" encoding="UTF-8"?>

<config	xmlns="urn:com.cohga.server.config#1.0" xmlns:report="urn:com.cohga.server.report#1.0" xmlns:client="urn:com.cohga.html.client#1.0">

	<client:resources>
		<resource id="report.email.subject">Feedback</resource>
		<resource id="report.email.message">The following has been submitted as a feedback report</resource>
	</client:resources>

	<client:resources lang="it">
		<resource id="report.email.subject">Retroazione</resource>
		<resource id="report.email.message">È stata presentata la seguente come un rapporto di feedback</resource>
	</client:resources>

	<report:email id="feedback">
		<from>noreply@sforbes.net</from>
		<to>feedback@sforbes.net</to>
	</report:email>

</config>

Updating the report component

One the smtp server and email configuration has been setup it's just a matter of referencing the email config in a simple report action or menu

	<item action="com.cohga.client.action.simplereport">
		<email>feedback</email>
		<format>html</format>
		<report>br_map</report>
		<label>Feedback</label>
		<tooltip>
			<title>Feedback</title>
			<text>Send a feedback report using the current map</text>
		</tooltip>
	</item>

The above report item will email the br_map report in HTML format directly to the user listed in the feedback email config.
If the report has any parameters then the user will be asked to enter the parameters before the report is sent, but if the report doesn't have any parameters then the report will be sent straight away.
Similarly, because the report config specifies a format that format will be used and the user not asked to pick a particular format, but if the format wasn't included the user would be asked to select the format before the report was emailed.

	<item action="com.cohga.client.action.simplereport">
		<email>
			<from>${userid}@sforbes.net</from>
			<to>feedback@sforbes.net</from>
		</email>
		<format>html</format>
		<report>br_map</report>
		<label>Feedback</label>
		<tooltip>
			<title>Feedback</title>
			<text>Send a feedback report using the current map</text>
		</tooltip>
	</item>

The above example does not require the email config at all, the values are directly set in the report action, using the default values for those properties that are not set.

	<item action="com.cohga.client.action.simplereport">
		<email id="feedback">
			<from>${userid}@sforbes.net</from>
			<to>feedback@sforbes.net</from>
		</email>
		<format>html</format>
		<report>br_map</report>
		<label>Feedback</label>
		<tooltip>
			<title>Feedback</title>
			<text>Send a feedback report using the current map</text>
		</tooltip>
	</item>

The above example does user the feedback email config, and replaces the values from it with those included in the report item, using those from the email config where the aren't set directly.