Running a report applies the appropriate data to a Report Definition at a moment in time and generates report. Report Definitions can be set to run immediately when a user selects Run from within the application, or set to be part of a queue of reports that runs at a scheduled time when the user selects Run.

Refresh report data

Report data is automatically refreshed in the system every 20 minutes for all reports except activity reports. Activity data is refreshed once per day at midnight. For example, when you align content to a goal, that alignment does not appear in goals-related reports until the refresh occurs at a 20-minute interval. You can refresh the report data manually from the Administrator Panel > Tools and Utilities > System Reporting > Refresh Report Data.

Run reports

Reports are run from various places within the application. For example, from the Administrator Panel > Tools and Utilities section > System Reporting and various instructor, student, and institutional assessment workflows throughout the product.

  1. Navigate to the item you want to report on, or locate the appropriate report.
  2. Open the item or report's menu and select either Run Reports or Analyze Results. If there are multiple reports to choose from, a list of available reports appears.
  3. Navigate to the report you want to run and open the menu.
  4. Select Run.

Some reports run as HTML and display within the context of the users work flow. Other reports allow the user to select the format of the output file. Upon submission, the report is run and displays in the selected format. Some reports are automatically stored in the Content Collection while others can be downloaded and saved on your computer.

Set report schedules

If you select Run on a scheduled report, the report runs at the scheduled time. Schedules are defined by the Institution Administrator to ensure that large reports do not take up system resources at times of peak load.

Administrators set the report schedules from the Administrator Panel > Tools and Utilities section > System Reporting. The list of reports to schedule is provided on the Report Definitions page.

Administrators set the start time for the scheduled report queue and the length of time the queue will process reports on the Manage Report Schedule page. If the system does not complete all scheduled reports in the allotted time frame, the system begins where it left off during the next scheduled processing window.

Individual reports cannot be set to run at a specific time. All reports that are scheduled enter the queue. Automatic or recurring scheduling is not available. Users must run the scheduled report to have it added to the nightly queue.

Scheduled reports are stored in the Reports Archive, which is accessed by the system administrator. Archived reports can be stored in the content collection where permission to view the reports is managed by issuing passes or by system role and user account.

Scheduled reports queue

The list of reports that are scheduled to run is accessed in System Reporting > Scheduled Reports Queue. The Schedule Reports Queue lists pending and completed reports. Administrators can remove scheduled reports from the queue.

Set a time for scheduled reports to run

This section applies to Self-Hosted customers only.

The time that reports are scheduled to run is set in the bb-tasks.xml file. Setting this value requires access to Blackboard Learn application files and a text editor. Before making changes to the bb-tasks.xml file, make a backup copy of the original.

The bb-tasks.xml file is located in the following directory:





Follow these steps to change the scheduled time for running reports:

  1. Stop Blackboard services using the ServiceController command line tool.
  2. Open the bb-tasks.xml file and locate the following section:

    <task-entry key="" version="60">
        <task classname="blackboard.platform.reporting.service.ScheduledReportQueuingTask" >
        <property name="db.registered.delay" value="scheduled_report_queuing_start_time" />
        <property name="db.registered.period" value="scheduled_report_queuing_interval" />
        <property name="time_sync_pause" value="60000" />

  3. Replace the scheduled_report_queuing_start_time with a time of day expressed as hh:mm. This value uses a 24 hour clock. For example, 13:30 is equivalent to 1:30 p.m.
  4. Replace the scheduled_report_queuing_interval with duration expressed in hours. For example, a value of 48 will run the scheduled reports once every two days.
  5. The section should now resemble the example below:

    <task-entry key="" version="60">
        <task classname="blackboard.platform.reporting.service.ScheduledReportQueuingTask" >
            <property name="xml.registered.delay" value="13:30" />
            <property name="xml.registered.period" value="24" />
            <property name="time_sync_pause" value="60000"

  6. Save the changes to the bb-tasks.xml file and restart services.

Purge data in the databases

This section applies to Self-Hosted customers only. More information is available on Behind the Blackboard.

Every day an automatic process synchronizes the data in the stats database with the data in the main database and then deletes the statistical data from the main database that is more than 180 days old. This process can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can also be used to delete data from the statistics database.

Administrators may modify the length of time that statistical data is kept in the main database. This is changed by editing the days_to_keep value in the config/bb-tasks.xml file.

The PurgeAccumulator tool is installed as part of Blackboard Learn. It is run from the $blackboard/tools/admin directory.


./ <command> <Virtual_Installation> <days_or_date>

PurgeAccumulator Commands
Argument Description
command purge-live -Takes data from Blackboard database and syncs with tables in the statistics database. After synching, it purges statistical data in the main database that is older than the number of days or date set.

purge-stats - goes to stats DB and purges all data older than the last x days or older than a specific date.

Virtual_Installation Provide the name of the main database (bbuid) of the Virtual Installation to be purged.
days_or_date The number of days (from the current date) that should not be processed by the PurgeAccumulator tool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will be purged.

To verify that the data has been purged, view the update-tool-log.txt file in the /usr/local/blackboard/logs/update-tools directory.