4.3. Setting up the Scheduler

With ReportServer you can schedule reports and distribute the result either using mail, directly into a TeamSpace, or sent to a FTP server. The next section discusses the relevant settings.

4.3.1. Mail Server Configuration

In order for ReportServer to be able to send mails you must specify the mail server settings. Make the following configurations in the file /fileserver/etc/mail/mail.cf.

Setting up the SMTP server. Replace the values host, port, username, and password according to your SMTP server.

	<smtp>
		<host>mail.yourmailserver.com</host>
		<port>25</port>
		<username>rs@yourmailserver.com</username>
		<password>passwordsecret</password>
		<ssl>false</ssl>
		<tls>
			<enable>false</enable>
			<require>false</require>
		</tls>
	</smtp>

If you are using SSL or TLS please also specify these values. Next, configure the sender name, email address and forceSender options. If the forceSender option is set to true, the emails will be sent using the given (generic) sender details. If set to false, the specific user sending the email will determine the sender details.

	<mail>
		<sender>rs@yourmailserver.com</sender>
		<senderName>ReportServer</senderName>
		<forceSender>false</forceSender>
		<encryptionPolicy>allow_mixed</encryptionPolicy>
	</mail>

The encryption policy option controls whether or not mails have to be encrypted or whether it is ok to send mails unencrypted if a user's public key is not specified. Choose between strict and allow_mixed. Note that if you choose strict then mails to users that do not have public key registered with ReportServer will not receive any messages.

4.3.2. FTP Server Configuration

In order for ReportServer to be able to send reports via FTP you must specify the FTP server settings. Make the following configurations in the file /fileserver/etc/exportfilemd/storage.cf.

Setting up the FTP server. Replace the values host, port, username, and password according to your FTP server.

  <ftp disabled="false" supportsScheduling="true">
    <host>ftp.host.net</host>
    <port>21</port>
    <username>rs@host.net</username>
    <password></password>
    <defaultFolder>./</defaultFolder>
  </ftp>

The disabled option controls if FTP is overall enabled or disabled. Further, scheduling via FTP can be enabled or disabled via the supportsScheduling setting. Note that you can not enable scheduling via FTP if FTP is disabled.

The defaultForder allows you to specify where exactly the reports should be saved by default in the FTP server. This can be overwritten by the specific scheduler job.

4.3.3. Scheduler settings

ReportServer comes with a powerful scheduler. ReportServer's scheduler allows you to schedule the execution of reports. The executed report can then either be emailed, stored in a folder in a TeamSpace, or sent to a FTP server.

The schedule and report recipients are user provided on scheduling. You can configure the messages that ReportServer will send out on certain events. Each message can be customized to your specifications.

ReportServer will send out the following emails:

  • email with attached completed report (mailaction),
  • email if a report has been placed into a TeamSpace (fileaction),
  • email if a report has been placed into a FTP server (fileactionFtp),
  • email on schedule (notification - scheduled),
  • email if a schedule job is revoked (notification - unscheduled),
  • email if a scheduled job failed (notification - failed)

The following configurations are done in the file /fileserver/etc/scheduler/scheduler.cf. To include information such as "the user who created the schedule entry", "the report's name" etc. in your message you can use a variety of expressions. Substitutions are defined in the ReportServer formula language. You will find further information about the ReportServer formula language in the Administrator's, as well as in the User Guide.

4.3.4. Available Substitutions
Expression Description
${report.getName()} report's name
${report.getDescription()} report's description
${report.report.getKey()} report's key
${report.getId()} report's ID
${user.getUsername()} username
${user.getFirstname()} first name of user
${user.getLastname()} last name of user
${user.getEmail()} user's email address
${user.getTitle()} user's title
${user.getId()} id of user
${executor} job's executor. You can use the same methods above as with user
${scheduledBy} job's scheduler. You can use the same methods above as with user
${teamspace.getName()} name of TeamSpace (only available in fileaction)
${folder.getName()} name of folder in TeamSpace (only available in fileaction)
${folder} name of folder in FTP server (only available in fileactionFtp)
${message} the message that was specified by the user on scheduling
${subject} the subject that was specified by the user on scheduling
${recipients} A list of the job recipients. Please check below for the exact configuration (list of users)
${owners} A list of the job owners. Please check below for the exact configuration (list of users)
${filename} filename as specified by the user (report is scheduled in teamspace)
${nextDates} date of next execution
${RS_CURRENT_DATE} current date
${errMsg} error message on erroneous execution
${stacktrace} detailed stacktrace on failed execution
List of users

For substitution of a list of users (currently supported: list of job recipients and list of job owners), you can use a fluent API that allows you to configure the output exactly as you need. Available methods for this are:

${withSeparator()} use a given separator between users. Default is a new line.
${addString('','')} add a String, e.g. a comma
${addBlankspace()} add a blank space
${addNewline()} add a new line
${addUsernames()} add usernames
${addFirstnames()} add first names
${addLastnames()} add last names
${addEmails()} add emails
${addTitles()} add titles
${addIds()} user ids
${print()} create the result string. This method has to be called in the last place.

As mentioned, you can use a fluent API for configuring the output. E.g.,

${recipients.
      addFirstnames().
      addBlankspace().
      addLastnames().
      addBlankspace().
      addString("(").
      addUsernames().
      addString(")").
      print()
 }

will print the following:

Barry Jones (bjones)

Diane Murphy (dmurphy)

Gerard Hernandez (ghernande)

Larry Bott (lbott)

If you want to separate the users by a comma instead of a new line, you can enter use the withSeparator() method as follows:

${recipients.
      withSeparator(", ").
      addFirstnames().
      addBlankspace().
      addLastnames().
      addBlankspace().
      addString("(").
      addUsernames().
      addString(")").
      print()
 }

which will print the following data:

Barry Jones (bjones), Diane Murphy (dmurphy), Gerard Hernandez (ghernande), Larry Bott (lbott)

Below you can find some example configurations:

Configuration of email message with attached report (successful execution)

	<mailaction html="false">
	<subject>${subject}</subject>
	<text>Text of message: ${message}</text>
	<attachment>
		<name>rep-${report.getName()}-${RS_CURRENT_DATE}</name>
	</attachment>
	</mailaction>

Configuration on successful execution of report and storage in TeamSpace

	<fileaction disabled="false" html="false">
	    <subject></subject>
	    <text></text>
	</xmlcode>

Configuration on successful execution of report and storage in FTP server

	<fileactionFtp disabled="false" html="false">
	    <subject></subject>
	    <text></text>
	</fileactionFtp>

Configuration of notifications on scheduling, unscheduling and execution errors

	<notification disabled="false" html="false">
	<scheduled>
		<subject></subject>
	<text></text>
	</scheduled>
	<unscheduled>
		<subject></subject>
	<text></text>
	</unscheduled>
	<failed>
		<subject></subject>
	<text></text>
	</failed>
	</notification>

If you would like to send emails in the HTML format please set the corresponding html attribute to "true".

In case you do not want to have one or more notifications, you can disable the individual notifications using the disabled attribute:

<fileaction disabled="true" html="false">

If you do not want to use the scheduler you can disable it using

	<properties>
		<disabled>true</disabled>
	</properties>

You can also disable the scheduler by setting the following property in your reportserver.properties file:

rs.scheduler.disable = true

If the property is set both in reportserver.properties and in /fileserver/etc/scheduler/scheduler.cf, the property set in reportserver.properties is taken into account, while the one set in /fileserver/etc/scheduler/scheduler.cf is ignored.

Keep in mind that this changes will only take effect after reboot. To enable or disable the scheduler while ReportServer is running, use the terminal command scheduler daemon start/stop. This command only works if the scheduler is not disabled in the file reportserver.properties. If it is, you first have to delete this property in order to be able to enable/disable the scheduler while ReportServer is running. Refer to the Administration Guide for more information on this command.