Report Export Module Configuration
This Report Export module is one of the DELFT-FEWS export modules. This export module is responsible for retrieving reports from the database, and exporting these to the relevant directory structure on the web server. Reports can then be accessed from there via the web interface to DELFT-FEWS. All reports are exported as is, by the report module. The report export module is only responsible for distributing reports created.
Access to these reports through the web server may be at different levels depending on the user in question. The report export module itself does not explicitly consider these access rights, but exports the reports in such a structure to allow the static part of the web server to correctly administer the access rights.
Two options are available for the export of reports:
- Export of the current forecast reports
- Export of most recent system reports
The web server will control access to all or some reports in these categories to appropriate users.
In addition to the export of reports from the database to a web server, the Report Export module can also 'export' reports (in image format) to Telegram (www.telegram.org) a mobile messaging application. For this purpose, the html pages in the report first need to be converted to an image format (i.e. jpeg, png) before they can be published to a "bot channel" on Telegram.
When available as configuration on the file system, the name of the XML file for configuring an instance of the correlation module called for example Report_Export may be:
Report_Export 1.00 default.xml
Report_Export | File name for the Report_Export configuration. |
1.00 | Version number |
default | Flag to indicate the version is the default configuration (otherwise omitted). |
Figure 133 Elements of the Report Export module configuration
reportExportRootDir
Root directory to which the all reports are to be exported to. This directory is typically the root directory of the web server.
currentForecastReports
Root element for definition of exporting reports for the current forecast
currentForecastSubDir
Root directory for exporting current forecasts to.
NOTE: The number defined here should comply with the number of links to other forecasts in the index_template.html file. This file is located in the reportExportRootDir directory.
numberCurrentForecasts
Number of most recent current forecast reports to keep in the output directory.
zipReports
Set the value of this element to 'true' to export the reports as zip files, instead of extracting the zip files content to directories. This option cannot be combined with the reportExportTelegramPhoto option.
dateTimeFormat
Date time format of the timestamp that is used for the output directory.
exportTimeZone
The time zone for the timestamp in the zip file or output directory.
prefix
Prefix for the destination zip file or directory
excludeModuleInstanceId
Optional list of reports generated by report module instances that should not be included in the export of current forecasts.
includeModuleInstanceId
List of reports identified by moduleInstanceId of the report module instances that created them that should be included in the export of other system status reports. Should not be used together with excludeModuleInstanceId.
incremental
This option can be used for writing reports incrementally. When true, older forecast reports will not be deleted.
generatePdf
Include this optional element with the value 'true' to convert each html page in the report to a pdf file.
N.B. This option works similar to the <generatePdf> element in the Report Module configuration. An external conversion program (default is wkthtmltopdf) needs to be configured using the global property REPORT_HTML2PDF_PROGRAM defined in the global properties file.
generateImage
Include this optional element to cause each html page in the report to be converted to an image of specified format.
N.B. This option works the same as the <generateImage> element in the Report Module configuration. An external conversion program (default is wkthtmltoimage) needs to be configured using the global property REPORT_HTML2IMG_PROGRAM defined in the global properties file.
exportForecastReports
This element is obsolete and not supported anymore.
Root element for definition of exporting reports from recent forecasts made. Includes both the current forecast and a configurable number of recently made forecasts.
exportSystemStatusReports
Exports the most recent reports from the datastore that are in the list of _includeModuleInstanceId_s.
exportSystemStatusSubDir
Directory to use as directory for exporting system status reports. For identification a sub-directory is created for each report exported. This sub-directory is constructed using the id of the taskRun it was created by.
zipReports
Set the value of this element to 'true' to export the reports as zip files, instead of extracting the zip files content to directories. This option cannot be combined with the reportExportTelegramPhoto option.
dateTimeFormat
Date time format of the timestamp that is used for the output directory.
prefix
Prefix for the destination zip file or directory
exportSystemStatusZipFile
Name of the zip file to create.
reportExportTelegramPhoto
Root element for defining the (encrypted) access token and channel ID that are required to publish messages to Telegram (www.telegram.org) as well as a list of image files to publish from the report.
To use this feature, the html pages in a report that are to be published first need to be converted to images (png or jpeg format), using the generateImage option in the currentForecastReports element described above.
Please refer to the telegram.org website for more information on how to create a so-called Telegram-bot with related chat 'channel'
N.B. you can only publish pages from a forecast report to Telegram, there is no option for exporting page from a system status report.
telegramBotToken
The Telegram bot access token, which allows anyone to control a Telegram bot and related channel. Please be aware that anyone with access to this token can control the used bot. In order to encrypt your token you first put the unencrypted token in the report export xml configuration file, then you start up FEWS explorer using the relevant configuration. FEWS will now generate an error message in the log stating that you cannot use the token in this unencrypted form, providing the encrypted token string in the log message. Then you copy paste this encoded version of the token in the configuration xml file.
telegramChatId
The ID of the chat channel for the telegram bot, which is provided to you when creating the bot (see www.telegram.org) Any Telegram user can subscribe to this channel to receive the photo messages send to this channel by FEWS.
telegramSendPhoto
One or more elements that define the image files within the report that are to be published. Each photo is defined by it's filename in the <reportTelegramFile> element and in the <reportTelegramCaption> element you can provide a caption (optional text) to be displayed below the photo in Telegram. You can use wildcards to specifiy multiple files, but in order to be able to specify a caption specific to each page (normally the location name) you need to specify a separate <telegramSendPhoto> tag for each page.
N.B. please note that at this point the report being exported is just a zip file and the report export module has no knowledge of the structure of the report, therefore you need to specify exactly which files you wish to publish to Telegram, there is no option to automatically export the page for eacht location that is present in the report.
Example report export configuration, which exports the last current forecast report, generating an image for each html page, and sends three specific locations to a telegram channel:
<reportExport ...>
<reportExportRootDir>$REPORT_EXPORT_ROOT_DIR$</reportExportRootDir>
<reportExportTelegramPhoto>
<telegramBotToken>NNdDxIKKEe0ioFhF/v9V3coUf/fFG94HgP+16hvYQsJfdSR/s3JJx+9MzMoLA82S</telegramBotToken>
<telegramChatId>-1001345024100</telegramChatId>
<telegramSendPhoto>
<reportTelegramFile>Telegram_Inhambane_2.jpeg</reportTelegramFile>
<reportTelegramCaption>Inhambane, Morungulo (Massinga)</reportTelegramCaption>
</telegramSendPhoto>
<telegramSendPhoto>
<reportTelegramFile>Telegram_Inhambane_5.jpeg</reportTelegramFile>
<reportTelegramCaption>Inhambane, Zavora (Inharrime)</reportTelegramCaption>
</telegramSendPhoto>
<telegramSendPhoto>
<reportTelegramFile>Telegram_Pemba_1.jpeg</reportTelegramFile>
<reportTelegramCaption>Pemba, 'offshore' </reportTelegramCaption>
</telegramSendPhoto>
</reportExportTelegramPhoto>
<currentForecastReports>
<currentForcastSubDir>ForeCast</currentForcastSubDir>
<numberCurrentForecasts>1</numberCurrentForecasts>
<includeModuleInstanceId>Report_Telegram_Create</includeModuleInstanceId>
<generatePdf>true</generatePdf>
<generateImage>
<format>png</format>
<options>--width 720</options>
</generateImage>
</currentForecastReports>
</reportExport>
