Introduction
The BusinessCraft Scheduled Reports Plugin Service provides the ability to generate and e-mail PDFs from the Contracts Module Report Writer or the User Labels Printer Template.
Set the Email & Plugins for BusinessCraft document for more information on the service in general; this document focuses solely on the Scheduled Reports Plugin Service.
Requirements
BusinessCraft Service installed (current version at time of writing is 5.9.6.3)
xfODBC Data Sources must be present on the System DSN tab within the required ODBC Data Source Administrator:
A plugin specific security group (e.g. BusinessCraftService) is created and all xfServerPlus users as well as the user/s BusinessCraft use to log in to the server are added to this group.
The plugin specific security group is given read and write permissions to the following directories:
C:\Windows\Temp folder if using Crystal Reports (Crystal uses this directory for its temporary files)
C:\Temp
C:\Program Files\Synergex and/or C:\Program Files (x86)\Synergex
C:\ProgramData\BusinessCraft Pty Ltd
The BusinessCraft directory containing the MapDr and xfSvr directories.
If, after these permissions have been applied, the report scheduler does not work, explicit read/write permissions should be given to the security group to the xfODBC entries in the Windows Registry.
Remote Procedures
The Remote Procedures tab contains the default settings for xfserverplus for the BusinessCraft Service. If it is blank as below, or contains a different port to the one that will be used for the Scheduled Reports Plugin, then the settings for the Scheduled Reports Plugin will need to be explicitly defined in the Alternate xfServerPlus Settings when configuring the Scheduled Reports Plugin as explained later in this guide.
Environment Variables
xfServerPlus uses environment variables which must be explicitly set within the Synergy Control Panel Environment Settings for the xfServerPlus service used for the Scheduled Reports Plugin. These variables and a brief explanation are available in the Remote Procedures tab of the BusinessCraft Service:
Report Considerations
When automating Contract Report Writer reports or sets of reports, their configuration may require modification to work as expected. For example, if the report currently displays on screen, the report will need to be modified to either export to PDF and/or email to specific recipients and/or groups of recipients.
Here is an example, with important fields from a Scheduled Report Plugin perspective explained:
| Output Opt | Set the Output option to E (Email) |
| Data Option | Set the Data Option to either Combine (C) or Separate (S) data |
| Source Path | Paths must be specified with the UNC name or the physical drive not mapped drives. |
| PDF File | A PDF File can be specified in the PDF File field - if not specified an automatically-generated name will be created. |
| To: | Individual email addresses as well as distribution lists can be included in the To list; email addresses must be separated by a semi-colon. |
| Auto Send | Auto Send must be checked in the Email Detail pop-up box - if this is not selected, the report will not be emailed. |
Adding the Scheduled Reports Plugin
Run the BusinessCraft Service by clicking on the BusinessCraft Service icon on the desktop:
Click the Plugins tab to open the Plugins which will look like the below depending on which plugins have already been installed:
To add the Scheduled Reports plugin, click the Add Plugin button and the new Plugin Details pop up is displayed:
Click the drop down arrow in the Plugin Type field and select the Scheduled Reports Plugin from the list displayed. The New Plugin Details pop up will be populated with default settings for the plugin:
Enter a Display Name or accept the default
Enter a Sort Name or accept the default
Enter a BusinessCraft Company Code if the plugin is to be configured for a specifc BusinessCraft dataset, otherwise leave blank to apply to all datasets. Individual reports can be set to run in different companies and override this default setting.
Accept the default for reporting the successful running of this plugin or if preferred choose from a Verbose or Summary Report
Leave the Enabled Box unticked until configuration of the plug in has been completed
Click the Save button and the Settings Maintenance screen will be displayed. This screen will be explained in the next section of this document, so, in this case, click the Cancel button to return to the Plugins Tab.
A warning will be displayed explaining that the BusinessCraft Service needs to be stopped and restarted for the changes made to take effect.
Click OK.
The Plugins Tab will display the Scheduled Reports Plugin added:
Editing the Scheduled Reports Plugin
The columns in the Plugins Tab for each plugin can be edited in the line:
| Sort Name | The Sort column is populated with the Display Name unless overwritten. |
| Enabled | A check box that indicates whether the plugin is enabled or not. |
| Sts | The operational status of the plugin – Running (Green), Starting, Stopping or Scheduled to Start (Orange), Stopped (Red), Disabled (Black), Pending Start Up or Configuration (White). Hovering over the indicator (other than White) provides additional information related to the status. |
| Display Name | A unique user defined name for the plugin if a name other than the actual name of the plugin is preferred. |
| Plugin Type | The system defined type for the plugin that was selected when the Plugin was added. |
| Company | The Scheduled Report Plugin will be run for this BusinessCraft Company Code. |
| Frequency | The polling frequency for the plugin. The Every Poll setting will poll in accordance with the Check Frequency in the Service Settings on the Service Tab. It is important for Scheduled Reports to change this to Advanced so that a suitable frequency can be set. |
| Log | Indicates whether a log is to be maintained of activities for the plugin. |
| Settings Filename |
The name and location of the file containing the settings for this plugin. This field will automatically populate and should not normally be changed. After at least 1 report has been added during the Configuration process, the information associated with the report is stored in the XML specified. To save time, the file can be copied, minor changes made, saved with a new name. With configuring another Scheduled Reports Plugin line, enter the path to the file created (or copy it over the default file created). The reports and report settings will be copied but not the scheduling information. |
Right clicking on the Plugin line opens a Context Menu:
| Test | Enables the plugin to be tested prior to prevent unexpected results after being enabled. |
| Config | Detailed configuration of the plugin – covered in a next section. |
| Schedule | Enables a custom schedule to be define for the plugin – covered in a following section of this document. |
| Edit Details | Opens the New Plugin Details pop up. |
| Request Stop | Stop the Plugin without stopping the BusinessCraft Service or impacting other plugins. |
| Request Start | Start the Plugin without re-starting the BusinessCraft Service or impacting other plugins. |
| Help | Opens a concise explanation of the plugin. |
Configuring the Scheduled Reports Plugin
To configure the Scheduled Reports Plugin, right click the plugin line and select Config from the Context Menu to open the Settings Maintenance screen:
Alternate xfServerPlus Settings
If the Scheduled Reports Plugin needs to use different xfServerPlus settings to the standard xfServerPlus Settings, alternate can be defined for this plugin. Only exceptions to the standard settings need to be completed here, for example a different port number.
Double click the Alternative xfServerPlus Settings heading or click the drop down arrow to the left of that heading to open the fields that can be configured:
| Description | A Text Field for any clarifying reason for the Alternate xfServerPlus settings |
| Server Name | The name of the server for the xfServerPlus installation to be used |
| Port No | The port number to be used |
| BC Username | The user name to be used to login to the BusinessCraft Dataset |
| BC Password | The password for the BC Username |
| BC Company | The Company Code for the BusinessCraft Data set from which the report is to be run. |
| Extra Params, Key Value and Timeout | Not used by the Scheduled reports plugin |
| Description | A Text Field to provide a name, if required for this specific instance of the Scheduled Reports plugin. |
Reports List
The reports to be run by the plugin run are listed by clicking the ellipsis (…) to the right of the Collection heading:
This will open the Reports Collection Editor screen:
Any existing reports already on the Report List will be shown in the Members Panel with the Properties of the selected report in the Properties panel.
Click the Add button to add a report to the Report List and use the Remove button to remove the selected report from the Report List.
Click the Add button and the Members Panel creates a Report Name (RPT: whilst the Properties panel shows the available settings and configuration available for Reports:
The following tables explain the properties and the values required to schedule Contract Report Writer reports:
Settings
| Enabled | Indicates whether this report is to be included in the Schedule (True) or not (False). |
| Description | Used to provide a name for the report in the Member Panel after Rpt: |
| Report Source | Choose from Contract Report Writer, User Labels, Vendor Labels, Customer Labels, Job Turnover Report |
| Report Defaults Name | If the report currently uses a default range, specify the name of that Default in this field, otherwise defaults will not be used. |
| Report Additional Params | Specify any additional parameters required in this field. |
| Alternate xfServerPlus Settings |
If Alternate xfServerPlus Settings are to be used for the report, instead of those on the Remote Procedures Tab, double Click the Heading or use the drop down arrow to open the available Alternate xfServerPlus Settings fields to be used for this report. Each field has been previously explained in this document. |
Template Reports – Leave Blank for Contract Writer Reports
| Report Template | Enter the Printer Template Code to be used to generate the report. |
Contract Report Writer Settings (CORW)
| Report Type | Select Report for a specific Contract Report Writer report or Set for a Contract Report Writer Set. |
| Report Name (Code) | Enter the Contract Report Writer Report Name or Report Set Code. |
| Sub Report No |
Enter 0 to run all reports associated with the specified report. To run only one sub report within a report, enter the sub report number as per the Contract Report Writer definition screen for the report. |
| Report Password | If the Contract Report Writer report requires a password, enter that password here. |
Emailing for Standard Reports (Standard)
| Report Filename | The Source of the Report Filename (~PDFSAVE for inbuild PDF) |
| Output Filename | The generated report filename For example, C:\temp\generatedreport_%YYYY_%MM_%DD.pdf |
| Email To, CC, BCC | The email recipients or recipient lists |
| Email Subject, Body and File | The Email Subject, Body Text and attached file, if required |
| Email Additional Attachment | Any additional attachment required |
| Email From | The Sender Email Address |
Testing the Scheduled Reports Plugin
The Scheduled Reports Plugin can be tested by right-clicking the Scheduled Reports Plugin line and selecting Test from the Context menu:
A Working message is displayed while the report/s is/are running and once complete, a results pop-up will be displayed:
Scheduling Reports and Templates
Each Scheduled Reports Plugin line can be set to a customised schedule by right clicking the line and selecting Schedule from the Context Menu:
The Schedule screen is displayed providing a wide range of options to define the scheduling frequency for the sending of the reports linked to that Scheduled Reports Plugin line:
Additional options will be displayed based on each setting chosen. For example, if Daily is selected a start time is displayed; if Weekly is selected a list of days are offered etc.
To make the Schedule Active, ensure that the Enabled checkbox is ticked.
Use the Test button to check the accuracy of the schedule. A Log Form shows the next times the schedule is set to run.
Status Column Colour Explanation
Black Report is not scheduled or is scheduled incorrectly.
Red Report is scheduled incorrectly.
Orange Report has been scheduled and has not yet been run
Green Report is scheduled, has run at least once, and is scheduled to run again.
