Server side Email Scheduler Introduction

The server side Email Scheduler allows you to use the Windows Task Scheduler to email the contents of a report to specific individuals, member of a web and/or Owners and Assignees of list items returned by the report.

Suggested uses for this include:

  • Sending users a weekly email of their overdue work (across multiple sites and lists)
  • Sending users a weekly email of recently added items (across multiple sites and lists)
  • Sending a single user a list of all overdue work (across multiple sites and lists)

To use the server side Email Scheduler you must:

  1. Create or edit a manifest XML file for every report you want to run.
  2. Create a cmd file that runs the manifest XML file.
  3. Create a scheduled task to run the cmd file.

Intended Audience

This document is intended for BrightWork administrators with XML experience.

Schema

If you use Microsoft Visual Studio, or another software package that can validate XML, you can use the GenerateReportManifest.xsd schema file that ships with BrightWork (C:\Program Files (x86)\BrightWork\16\GenerateReport\bin).

To validate this file in Microsoft Visual Studio, add the schema file to the current solution and click on the XML menu option at the top of the screen and click Validate XML Data.

Quick Start

This section describes how to generate a My Work report for all the webs on a top-level BrightWork site. It will run the My Work report for every valid user in the top-level site and email each user a report detailing the work items where they are the owner or assignee.

  1. Login to your server and navigate to
    • SharePoint 2007: Drive:\Program Files\BrightWork\12\GenerateReport.
    • SharePoint 2010: Drive:\Program Files(x86)\BrightWork\14\GenerateReport.
    • SharePoint 2013: Drive:\Program Files(x86)\BrightWork\15\GenerateReport.
    • SharePoint 2016: Drive:\Program Files(x86)\BrightWork\16\GenerateReport.
    • SharePoint 2019: Drive:\Program Files(x86)\BrightWork\16\GenerateReport.
  2. Create the following 3 subfolders:
    • \ReportCommandFiles
    • \ReportLogs
    • \ReportManifests
  3. Navigate to
    • SharePoint 2007: Drive:\Program Files\BrightWork\12\GenerateReport\sample manifests.
    • SharePoint 2010: Drive:\Program Files(x86)\BrightWork\14\GenerateReport\sample manifests.
    • SharePoint 2013: Drive:\Program Files(x86)\BrightWork\15\GenerateReport\sample manifests.
    • SharePoint 2016: Drive:\Program Files(x86)\BrightWork\16\GenerateReport\sample manifests.
    • SharePoint 2019: Drive:\Program Files(x86)\BrightWork\16\GenerateReport\sample manifests.
  4. Copy ManifestMyWork.xml and paste it into
    • SharePoint 2007: Drive:\Program Files\BrightWork\12\GenerateReport\ReportManifests.
    • SharePoint 2010: Drive:\Program Files(x86)\BrightWork\14\GenerateReport\ReportManifests.
    • SharePoint 2013: Drive:\Program Files(x86)\BrightWork\15\GenerateReport\ReportManifests.
    • SharePoint 2016: Drive:\Program Files(x86)\BrightWork\16\GenerateReport\ReportManifests.
    • SharePoint 2019: Drive:\Program Files(x86)\BrightWork\16\GenerateReport\ReportManifests.
  5. Open ManifestMyWork.xml in Microsoft Visual Studio or another suitable text editor.
    1. Update the rootHref attribute to point to the web the report is supposed to be running on.
    2. Replace yourSMTPserver with the name of your SMTP server.
    3. Replace [email protected] with the email address you would like the email to appear to come from.
    4. Save the file.
  6. Open a text editor and paste in the below line:
    ..\bin\GenerateReport.exe ..\ReportManifests\ManifestMyWork.xml > ..\ReportLogs\EmailReport.log
  7. Give the file an appropriate name and a .cmd extension (e.g. mywork.cmd), and save it to
    • SharePoint 2007: Drive:\Program Files\BrightWork\12\GenerateReport\ReportCommandFiles.
    • SharePoint 2010: Drive:\Program Files\BrightWork\14\GenerateReport\ReportCommandFiles.
    • SharePoint 2013: Drive:\Program Files\BrightWork\15\GenerateReport\ReportCommandFiles.
    • SharePoint 2016: Drive:\Program Files\BrightWork\16\GenerateReport\ReportCommandFiles.
    • SharePoint 2019: Drive:\Program Files\BrightWork\16\GenerateReport\ReportCommandFiles.
  8. Open the Windows Task Scheduler and follow the steps in the Create Basic Task wizard to schedule the CMD file

Email Scheduler Files

The server side Email Scheduler uses GenerateReport.exe, a manifest XML file and a command (.cmd) file that is scheduled to run a specific manifest XML file(s) by Windows Task Scheduler.

Create Folder Structure

You should create a folder structure to store the Email Scheduler files that you will be working with. Files in these folders will not be affected by an upgrade.

  1. Login to your server and navigate to
    • SharePoint 2007: Drive:\Program Files\BrightWork\12\GenerateReport.
    • SharePoint 2010: Drive:\Program Files(x86)\BrightWork\14\GenerateReport.
    • SharePoint 2013: Drive:\Program Files(x86)\BrightWork\15\GenerateReport.
    • SharePoint 2016: Drive:\Program Files(x86)\BrightWork\16\GenerateReport.
    • SharePoint 2019: Drive:\Program Files(x86)\BrightWork\16\GenerateReport.
  2. Create the following 3 subfolders:
    • \ReportCommandFiles
      This folder is for the command files.
    • \ReportLogs
      This folder is for the system generated log files.
    • \ReportManifests
      This folder is for the XML files that run the Email Scheduler.

Manifest XML File

The manifest XML file is where you specify the report to be run and who is to receive the email.

The sections on the manifest XML file include:

  • Header and Footer
  • Report
    This node contains information about the report that is to be emailed.
  • Execute Report
    This node contains the parameters needed to run the report and information about the email that is to be sent.

Header and Footer

Every manifest XML file must have the below header and footer.

Header

<?xml version="1.0" encoding="utf-8" ?>
<GenerateReportManifest xmlns="http://schemas.brightwork.com/GenerateReportManifest/v2">

Footer

</GenerateReportManifest>

Report Node

The Report node is where the report that is to be run is defined. There are 2 options:

  • WebPart
    This is where you specify a specific web part on a specific page.
  • QueryFile
    This is where you point the server side Email Scheduler at a Report Definition file.
WebPart Report Node

This section outlines the options available with WebPart type Report nodes.

Nodes and Attributes

Description

<Report type="WebPart">

This is where you specify a specific web part on a specific page.

WebPart pageUrl=" //server/sites/site/Projects/default.aspx"

You must specify the URL of the page the BrightWork Reporter web part is installed on.

webPartId=" " />

You must specify the web part id - please see Identify the Web Part ID for more information on how to obtain the web part ID.

</Report>

This is the closing tag for the ReportType node.

QueryFile Report Node

This section outlines the options available with QueryFile type Report nodes.

Nodes and Attributes

Description

<Report type="QueryFile">

This is where you point the server side Email Scheduler at a Report Definition file.

<QueryFile fileSourceType=" "

Specify the gallery type that the Report Definition file is stored in. There are 3 options:

  • fileSourceType="BrightWork"
    This is the BrightWork Gallery that contains the reports supplied with BrightWork Reporter
    OR
  • fileSourceType="CustomShared"
    Specifying CustomShared means that the scheduler will look in the BrightWork Reporter Library. The library must be in the same site collection as the web specified in the rootHref (see below).
    OR
  • fileSourceType="CustomSourceHref"
    Specifying CustomSourceHref means you can use a Report Definition file stored in any document library on the server. You must provide the server relative URL of the document library that the file is stored in the filePath attribute.

filePath=" "

Specify the name and location of the Report Definition file that you want to run. The information you supply here is dependent on the fileSourceType attribute.

Sample file paths include:

  • <QueryFile fileSourceType="BrightWork" filePath="OpenWork.xml"/>
  • <QueryFile fileSourceType="BrightWork" filePath="Templates\Projects - Summary.xml"/>
  • <QueryFile fileSourceType="CustomShared" filePath="OpenWorkCopy.xml"/>
  • <QueryFile fileSourceType="CustomSourceHref" filePath="/sites/documentation/Projects/MSF/ Document%20Library/Document.xml" />

scope=" "

Specify the scope of the report you want to run, there are 3 options:

  • scope="SpecifiedWeb"
    This is the web specified in the rootHref attribute.
    OR
  • scope="SpecifiedWebAndSubWebs"
    This is the web, and its subwebs, specified in the rootHref attribute.
    OR
  • scope="QuerySources"
    This is where the web(s) is specified in the Report Definition file.
    To avoid anomalies you should ensure that the users who have access to the rootHref also have access to the webs specified in the QuerySource node in the Report Definition file.

roothref="http://server/sites/site/Projects/mysite"
/>

Here you specify the web BrightWork Reporter is running in. BrightWork Reporter does not actually have to be added to a web; however, so that it can have a context for generating the report, you must specify the URL of a web.

</Report>

This is the closing tag for the ReportType node.

Execute Report Node

The Execute Report Node is where the email that is to be sent is defined.

<ExecuteReport>
OR
<ExecuteReport forEachUser="true">

Specifying true means that the scheduler will generate an email for all members of the web (or in the case of My Work report, all members of the web who are Owners or Assignees of list items returned by the report). The email will only be sent if the $user parameter is in the <To> node (see below).

<QueryParams>

There are two conditions whereby you must have a QueryParam.

Note:

The QueryParam name must match the name used in the report.

  • If you are running a report (e.g. My Work) that contains a QueryParam that substitutes the SharePoint value [Me] with CurrentUser, for example:
    <QueryParams>
    <QueryParam name="CurrentUser" value="$user"/>
    </QueryParams>
    OR
  • If you are running a report that contains a QueryParam that requires user interaction with the web part because it does not have a default value set, for example a drop-down or a date picker.
    You must specify the default value, for example:
    <QueryParams>
    <QueryParam name="DateItemDue" value="2006-04-25T00:00:00" />
    </QueryParams>
    To pass a specific value to the QueryParam in BrightWork Reporter, follow the below guidelines:
    • Boolean Param: use 1 or 0 as the default value
    • Specific User: use the User ID as the default value
    • Text/Lookup/Choice: use a text value as the default value

<Email>

Here you define the email that gets sent.

<SMTPServer>
smtpServerName
</SMTPServer>

Enter the SMTP Server Name.

<From>
[email protected]
</From>

Enter the email address of sender.

<To>
$user;[email protected]
;</To>

Define the To list. The value $user is to be used if <ExecuteReport forEachUser="true"> and/or if $user has been mapped in the QueryParam as shown above.

You can also specify individual email addresses: each one must be separated by a ; (semi-colon).

<Subject> </Subject>

Subject of the email.

<Body> </Body>.

Here you add any text that you want to be included in the Body of the email

</Email>

This is the closing tag for the email section.

</ExecuteReport>

This is the closing tag for the execute report node.

Command File

The command file is the file you tell the Windows Task Scheduler to run. It in turn runs the manifest file through the GenerateReport.exe and generates a log file.

To create a command file:

  1. Open a text editor (e.g. Notepad) and create a file with the following format:
    [relative path to GenerateReport.exe] [relative path to Manifest XML file] > [relative path to the new Log file ]
    For example, if you have created the folder structure as described in Create Folder Structure on page 5, the line would look something like:
    .\bin\GenerateReport.exe ..\ReportManifests\Manifest.xml > ..\ReportLogs\EmailReport.log
  2. Give the file an appropriate name and a .cmd extension, and save it to
    Drive:\Program Files\BrightWork\16\GenerateReport \ReportCommandFiles
    .

Running Multiple Reports from a Single CMD File

You can have run multiple reports using the one command file, for example:
..\bin\GenerateReport.exe ..\ReportManifests\Manifest1.xml > ..\ReportLogs\EmailReport1.log
..\bin\GenerateReport.exe ..\ReportManifests\Manifest2.xml > ..\ReportLogs\EmailReport2.log
..\bin\GenerateReport.exe ..\ReportManifests\Manifest3.xml > ..\ReportLogs\EmailReport3.log
..\bin\GenerateReport.exe ..\ReportManifests\Manifest4.xml > ..\ReportLogs\EmailReport4.log

Task Scheduler

Use the Windows Task Scheduler on your server to run the command file at the desired time.

To schedule a new task

  1. Open the Windows Task Scheduler
  2. Select Create Basic Task wizard and follow the steps to schedule the CMD file

Tips

Identify the Web Part ID

To identify the web part ID, follow the steps below:

  1. Navigate to the page containing the BrightWork Reporter web part.
  2. Select Email Data on the web part menu.
  3. Right-click on the page and select View Source.
  4. Search for wpGUID.
    The numbers and characters after wpGUID= (excluding the " at the end) is the web part ID.

    wpGUID=6ee19d6f-4ba8-4799-bda5-dc9c87bee158

Was this article useful?

Back to Top