The Report Record functionality originally added in v15 has since been integrated into the Managed Report functionality introduced in v21. If you are upgrading from an old version, refer to the newer methods used by Scheduler and CM4D Web when it comes to creating and accessing reports, tags and depositories.
The intended audience for the Report Record Administration topics is an application developer that will create a user interface to provide access to CM4D Scheduler-generated Reports.
The CM4D Report Record database consists of three tables and eight stored procedures. These objects reside in the CM4D Site database. The CM4D administrator will need to provide database connection information, and the application developer will be responsible for providing a mechanism to connect at runtime.
The stored procedures act as the Application Programming Interface (API) for the CM4D Report Record Database. Each API call results in a record set of the data requested. The application developer is then responsible for utilizing this record set. Some API calls result in a single record, some result in multiple records, and an empty record set is always a possibility.
To the application developer, the database is considered to be read-only. CM4D will provide mechanisms for populating and maintaining the content of the tables. At no time should the app developer alter the data in the database, add data to existing database tables, or alter existing stored procedures. It is permissible to modify the existing Indexes, or to add user-defined indexes. The user, however, will be responsible for maintaining any and all non-standard index definitions, and to re-implement them after CM4D upgrades have been applied.
Any access to the data should only be made via the API (stored procedures) provided. Direct access to the tables is neither recommended nor supported, and could result in incompatibilities with future versions of CM4D. ATS reserves the right to alter the database objects (tables, indexes, constraints, stored procedures) at any time. ATS will, however, endeavour to maintain consistency to the signature of the API, and any changes will be documented.
The CM4D Report Record architecture is comprised of the following user objects that exist on disk:
Report file
Generated by CM4D Scheduler
Any report type supported by CM4D Scheduler (typically a .PDF file)
One report can contain one or more pages
Thumbnail file
Generated by CM4D Scheduler
A .JPG image that corresponds to the report file
One thumbnail represents one report file
Report Record database
Created as part of the CM4D installation process
Populated by CM4D Scheduler when a Report is generated
Resides within the CM4D Site database
Depository
A folder on the network that contains report and thumbnail files
No hard limit to the number of depositories
The CM4D Report Record data structure is comprised of the following user objects within the database.
|
Object |
Description |
Db Object |
|
Report Depository table |
[ReportDepository] |
|
|
|
Depository label |
[RD_Label] |
|
Depository folder path |
[RD_FolderPath] |
|
|
Report Record table |
[ReportRecord] |
|
|
|
File name of the report |
[RR_Filename] |
|
Date/time of report creation |
[RR_DateTime] |
|
|
File name of the Thumbnail for report |
[RR_Thumbnail] |
|
|
Relationship to the Depository that contains the report |
||
|
Report Filter (name/value pair) table |
[ReportFilter] |
|
|
|
Name of filter |
[RF_Name] |
|
Value of the filter |
[RF_Value] |
|
|
Relationship to the Report that the Filter represents |
||
The CM4D Report Record API consists of the following methods (stored procedure calls):
|
Method |
Returns |
|
SearchReports |
Query for a list of Reports |
|
ListReportDepositories |
Query for a list of Report Depositories |
|
ListReportRecords |
Query for a list of Report Records |
|
ListReportFilterNames |
Query for a list of Filter Names |
|
ListReportFilterValues |
Query for a list of Filter Values |
|
GetReportDepository |
Query for a specific Report Depository |
|
GetReportRecord |
Query for a specific Report Record |
|
GetReportFilters |
Query for a list of Filters for a specific Report |
There are three method types:
“Search” procedure –returns a list of reports based on the input (query) parameters
“List” procedures – return summarized lists of available objects
“Get” procedures – return a record for a specific object
Each API method has individual input parameters, which result in a record set with a particular structure, as defined in Report Record Database and API.
To utilize the CM4D Report Record API, a connection to the CM4D Report Record database must first be established. The API methods provided are calls to stored procedures within the database. Each method accesses table within the database as well.
At no time do the API methods access the data outside of the database, such as the report files or thumbnail files. The existence and integrity of these external objects is not guaranteed. It is the responsibility of the application developer to validate the usefulness of the data provided regarding the report files and to handle error conditions.
Once the database connection has been established, Report Record data can be accessed immediately. The primary (and most useful) method is SearchReports(). This method returns a list of Reports based on the input (query) parameters. The parameter defaults would result in the entire list of Reports in the database being returned.
In an application’s simplest form, it is feasible that SearchReports() would be the only API method used. If it were the intention of the developer to merely display a list of Reports for the end user to choose from, then using SearchReports() with the default parameters would be sufficient.
By providing refined input parameters, however, the application developer could produce a refined list of Reports that would be better suited to the task of presenting a lighter, easy to use interface that allows the end user to navigate to the desired Reports more quickly and with less clutter.
An easy “next step” in the evolution of application development might be to provide edit boxes where the end user would enter search patterns for certain input parameters, such as the Report filename, Depository label, or Filter values.
Of course, an improvement on this might be to provide lists (perhaps dropdown lists) that would allow the end user to easily select actual values. The “List” methods provide this type of data. The Depository, for example, could be presented early to allow the end user to quickly narrow the list of Reports to an area of interest. The ListReportDepositories () method provides this list.
As with all “List” methods, the ListReportDepositories () method accepts input parameters that would result in a refined list of data. Therefore, a combination of a search pattern edit box and a drop list would be a powerful combination. The “List” methods allow SQL wildcards (%,?) within the input parameters.
In addition to search patterns, date/times can also used as search parameters, so a calendar control may be appropriate.
As the end user navigates through the data and makes selections, a series of “Get” methods are provided to retrieve data for a specific object. These methods will not work properly if the input parameters contain wildcards. The input parameters are expected to exactly match the content of that particular field.
The ReportRecord data, as returned by either SearchReports() or GetReportRecord(), contains information for a thumbnail image. This thumbnail is intended to be displayed with the Report data to create a more robust user interface.
Whatever combination of the “List”, “Get” and “Search” methods are used, eventually a user will select a Report. At this point, the application developer will need to locate the Report. The path to the Report file is derived by combining the Report Depository FolderPath field [ReportDepositopry.RD_FolderPath] with the Report Record Filename field [ReportRecord.RR_Filename].
What action is taken on a Report is up to the application developer, but certainly the most common action would be to view the Report. How the Report is viewed is the responsibility of the application developer. Most Reports will be Adobe PDF files, and all common browsers have a plug-in for viewing them.
It is possible, however, that a file format other than PDF has been used. These other formats are .BMP, .JPG, and Windows metafile. It is the responsibility of the application developer to handle (or not) this possibility.
The Report Filters are provided to allow the user to attach information to the Report for searching and documentation purposes. These Filters exist as name/value pairs, and are defined during the configuration of CM4D Scheduler.
To use the Filter information effectively, the application developer may need to organize the Filters by Name, and perhaps even Report Depository.
It may also prove useful to provide a summary of all Filter Values for a Report.
See Report Record Database & API for reference tables and API code.
Can we improve this topic?