About Developing Operational Reports
The implementation of reports is based on three concepts:
- Report Definition
- Report XML
- Result Sets
The report definition serves as an object description. How the report XML and result sets are produced for this report.
The result set and report XML contains basically the same snapshot data of the report but the XML is the only thing used by Report Designer. The result set is in practice only used from Crystal Reports and it does not contain any Custom Field data.
The concept of the report definition serves to separate design-time behavior from runtime behavior. It also serves as a protocol for extracting information, in conjunction with the report XMLs and result sets, simply put 'the File format'.
In design-time these settings are placed as comments on the report view and it's columns, much in the same way as logical units. Ex:
COMMENT ON TABLE demo_customer_rep IS 'LU=<LU-name>^TITLE=<report title>^MODULE=<Module-name>^…' COMMENT ON COLUMN demo_customer_rep.customer_name IS 'TITLE=<column title>^DATATYPE=<datatype>^…' … …
These comments follow the same logic as for logical units, but also include some other features necessary for the report development, all of which is described in full in Foundation1 Developers Guide.
The report definition is actually a structure contained in two logical units ReportDefinition, and ReportColumnDefinition. The key in ReportDefinition is something called ReportId, a logical name, which is identical to the report view.
From the report definition, all required information can be read at runtime, to complete performing actions or scenarios.
- When creating a report XML and result set, call the report method with correct parameter values as entered by end user. For architectural reasons this must be done using dynamic PLSQL, but this is hidden in the implementation.
- When about to present (print or preview) a report, it builds a select statement to fetch information from the report view, processes the active print language and translations, etc.
- When about to finally delete a report XML and result set, they can be located by clean up jobs and deleted from the database.
The report definition also serves as a (scan) base for the translation tool and makes it possible to generate translation files that include reports.
Report Data Generation
There are two principal different ways of 'generating report data'.
- The end user orders or requests a report, online or in batch mode depending on the situation and control interface used.
- The report is part of some larger batch that as a result generates one or more reports.
In either way, report XML and result sets are used and maintained in the same way. The only difference is how and where public methods in the reporting framework are used.
Generally, it is possible to repeat the functionality in the client and in the server using public interfaces in the reporting framework, purposely to allow applications to 'hook' on to the flow of reports.
The purpose of the report method one: To generate the report xml and the result set. The report method does not include any specifics about which printer it is about to be printed on, or which user will have access to it et c. It's only purpose is to generate data using supplied selection criteria's (parameters). The flow of report data is governed by the reporting framework, which supplies public interfaces for specific purposes.
The runtime is also fully operational just from the contents of the RDF file (and the some kind of layout), which allows for reports to be added at a late stage in the application development, and also allows for the runtime to be used for both implementation and testing. It also makes it possible to write reports that are added into the runtime of existing applications, without necessarily rewriting them. If more specific order or printing forms are necessary, they should be developed within the application.
Report Data Storage
A result set is similar to a file, and for many purposes this is how it is treated. Each result set is stored in a location dedicated by the report in question, and the runtime of reproting framework maintains all necessary links. Report XMLs contains the same information as the result set and are in fact xml-files stored in the database.
The top level logical unit for representing the report data is a logical unit called Archive. Each row in the Archive represents data for one report, and to assist there are associated logical units ArchiveDistribution (report data distributed to user), ArchiveParameter (parameters used when generating report data) and ArchiveVariable (instance specific variables).
Logical unit ReportDefinition holds information from the design-time of the report. In effect it holds all the comments generated during design-time, and uses this information at runtime. This is especially used when the end user opens the 'Report Order' dialog, or when a report is printed, in which cases they are necessary.
The key in Archive is a sequence named ResultKey. This sequence is generated automatically and is sent along to the report method.
In the Archive, report data is maintained until is deleted. This is further described below, but this is done in two steps:
- First the users link is removed.
- When no more links are registered, then the actual report data is removed.
The first deletion can be performed both by the end user, and by a server process executing every night, the second is only performed by the server process
Report Data Deletion
There are two ways of deleting report data.
- Manually delete from 'Report Archive'
- Automatic delete after it has 'expired'.
Manual delete only removes the link. If the report data is still distributed to other user, then the data itself will not be removed. A link may not be removed if it is required by some foreign reference. If the foreign reference is a print job, then the data will enter a state of 'hidden'.
The deletion of report data follows a simple algoritm, which is implemented as an especially dedicated server process within Foundation1. This server process is started once every night and can be re-scheduled using Foundation1 properties.
The algorithm works like this:
- First delete all links in the Archive, that have expired. Every link is personal, and users only maintain their own 'Report Archive'. The field 'Expire Date' signals when report data should be deleted, and is derived by checking the time when a report is executed, and then to add the numeric Life property from logical unit ReportDefinition.
- For every result key, that does not have a link, check if there is any outside references. If there are no references then remove any associated structures and finally remove the data itself. The data is removed from the report table and XML data table by setting properties on the report properly.
- If there are outside references, change the state of the report data to 'hidden', which implies that it will still exist in the 'Report Archive', but it will not be shown by default. Hidden data will eventually be removed if the foreign reference is removed.
The concept of print language is necessary to make it possible to change translations at a late stage in the presentation of reports, f ex printing invoices for different customers in different languages..
A print language is obtained in several different ways, and it is important to note that every report data snapshot may ultimately have its own print language. It is also important to note that a print language is always used. The only difference lies in how it is obtained. Once a print language has been obtained, it is used until the end user changes it.
- Language can be set by report method. If matching translations can not be found, then this type of print language reverts to English ('en'), and if English translations do not exist it reverts to 'PROG'.
- If print language is not set, it will pick up its language from the used application language. Again if this language does not exist in the server, English and finally 'PROG' will be used instead.
This logic is performed whenever the report is passed through the presentation logic within the report formatter. When printing or previewing a reprot, it will appear as a dropdown 'Language' where the end-user can ultimately change the language.
A report has as many print languages as there are translations for the corresponding report definition. Reports that do not have translations will use 'PROG' instead. 'PROG' is only available under the development process in the meanwhile until the report definition has been translated.
The dictionary system is reused for report objects in exactly the same way as for logical units.
The reference system is not used within a report, but it may be used from a report and is then used to access LOV, explicitly from the Report Order dialog.
Although reports are not part of the reference system, result sets and report XMLs may be, whenever there are references to the Archive, as stated above.
Reports are translated using IFS/Localization in much the same way as logical units. More specifically:
- A report is translated at the same time as the associated logical unit.
- The translations of reports are store in the same files as for the corresponding component, i.e. in the corresponding SRD and TRS files.
The runtime of IFS/Info Services searches and maintains the usage of these translations as described above under 'Print Language'.
Security on reports is implemented in much the same way as security for logical units, by Oracle grants to make the objects accessible or not.
A report may be previewed/printed when the report view is granted with SELECT option.
A report may be ordered/executed when the report view is granted SELECT, the report package is granted EXECUTE and there is no restriction on the report method.
Security on report data is governed by demanding that they are distributed to a user, before he/she can actually see it.
Site Text and 'Company Name'
Foundation1 supports the use of global texts in Report, texts that are maintained on Site level. For this purpose, a logical unit called SiteText is created within IFS/Info Services, which holds all global texts for one installation.
One of the predefined texts are called companyName, and is used for the specific purpose of allowing the company name displayed in reports to be changed throughout the system.
A form for modification of these Site Texts is found in Foundation1 Administrator.
For more specific uses of the global Company, the concept of ArchiveVariables may be used, both for 'Company Name' and for 'Company Logo'.
Report Runtime Environment
The mechanisms involved in the reporting system are complex, but it is built on a few standardized components.
The following standard components are the general runtime part of Foundation1 Info Services. They represent the standard, built in functionality, whereas the applications generally have some more specific constructions.
The objects are somewhat connected to each other so that the end user may track the created objects. Therefore the keys from one object (f ex ScheduledReport) also exist in other objects as attributes. These attributes are not mandatory and can therefor be NULL when not used.
The following is a brief description on the most central components in Info Services.
ScheduledReport holds information specific for reports that are executed offline, at one specific time or regularly, Scheduled Reports are a part of the general concept Scheduled Tasks and they are displayed in the client for Scheduled Tasks.
A report is placed in ScheduledReport whenever the user chooses to execute a report in any other fashion than online.
The Archive represents the filing system for reports, although the actual file is not stored but rather the selected data (a concept called resultset). In the Archive every resultset in the system is stored, but they are linked so that the current user can only see resultset that are distributed to him/her. Application owner represents a special kind of end user which is allowed to see every resultset within the system, even when the resultset is not actually distributed to him/her.
The links in Archive also holds the very important property called EXPIRE_DATE, which tells the system how long the link to this user should remain in the system. The EXPIRE_DATE is set in two different ways.
- The EXPIRE_DATE is calculated by adding a report specific LIFE property to the actual time when the report was produced. This LIFE property can be set in three different ways described below.
- The end user alters his/her EXPIRE_DATE manually.
Note: Since Application Owner can see every report data instance in the system, but only EXPIRE_DATE for those that are linked to him, the rest will be shown with EXPIRE_DATE as NULL. Trying to set this value will have no effect in this case.
The report LIFE property comes originally as a design time default with the system (report type specific), but may also be changed from the menu 'Properties' in Archive form. These changes makes override in two levels on the designtime value:
- Values given by Application Owner will override the designtime value and apply to all end users, unless…
- A specific value is given by the end user, which will only apply for him/her.
The Archive is also cleaned by a background job, initially scheduled every night. This is executed in two steps:
- First all links with EXPIRE_DATE < system time is deleted.
- When a resultset no longer has any links, the resultset itself is deleted. Both the entry in Archive, and all the rows in the report are deleted (in report table/tables).
Distribution Groups is merely an opportunity for the end user to set up an environment for sharing resultsets, especially when ordering offline in a scheduled manner.
A Distribution Group is nothing but a list of end users that will pop up as an addition to available users when ordering a report (distribution), or when redistributing from the Archive.
All Distribution Groups are shown for all users, but the protection level determines which options are available.
1. Public groups can be altered and viewed by every end user.
2. Protected groups can be viewed and edited by its owner, while other end users may only add or remove themselves.
3. Private groups can only be viewed and edited by its owner.
A print job is a grouping of one or more repots that are intended for a specific destination. The destinations can be a server printer or it could be used in a message back to the client that the reports are ready. The best way to look upon a print job is to compare it with the contents of the Print Dialog since that is one way of creating print jobs.
The form 'Print Manager' shows available, or saved, print jobs. For the ordinary end user, only his/her print jobs are shown. For Application Owner, all print jobs in the system are shown.
There are several ways of creating print jobs.
- Manually selecting a number of reports from the Archive, and choosing a server printer as destination. When a client printer is selected, the print job will not be saved into the database.
- Ordering a report offline (through Scheduled Report). This will generate report data in Archive. Through messaging options when ordering the report, it could end up as a message to the client, as a mail or as printed on the server printer. If a message options is chosen, a print job will be created.
- Application specific batches generate printouts that are sent to the Report formatter.
Print Jobs also have an EXPIRE_DATE, which work in a different way than for report data (Archive). There is a system setting (F1 Property) which determines the lifetime for a print job. Print jobs are deleted when EXPIRE_DATE + lifetime < system time. Default is that lifetime here is set to 7 (seven) days, but since this is a F1 property it can of course be changed. However, print jobs with status Waiting, Working or Error are excluded from this deletion since they are about to or should have been processed.