Contents
Intro
It is possible to view related documents or pictures through the document viewer. There are two options to configure this.
The first option is available since FEWS 2013.01. However since FEWS 2020.01 a new option is available.
The option will be described below (XML configuration in the Explorer.xml). The second option will be described after this block.
XML configuration in Explorer.xml
To enable this feature the document viewer should be configured as an explorer task only.
<explorerTask name="Document viewer"> <mnemonic>X</mnemonic> <taskClass>nl.wldelft.fews.gui.plugin.information.ForecasterAidDocumentPanel</taskClass> <toolbarTask>false</toolbarTask> <menubarTask>false</menubarTask> <toolWindow>true</toolWindow> <loadAtStartup>true</loadAtStartup> </explorerTask>
Optionally you also may need to configure some credentials for links to websites or hosts that need a user/password.
You can have one general credential for all URLs:
<documentViewer>
<hostCredentials>
<user>dummy_username</user>
<password>dummy_password</password>
</hostCredentials>
</documentViewer>
You can also have multiple credentials for different websites:
<documentViewer>
<hostCredentials>
<hostName>http://xxxx.com</hostName>
<user>dummy_username</user>
<password>dummy_password</password>
</hostCredentials>
<hostCredentials>
<hostName>http://dummy_hostname</hostName>
<user>dummy_username</user>
<password>dummy_password</password>
</hostCredentials>
</documentViewer>
Configuration in the TimeSeriesDisplay.xml
Why did Deltares decide to implement a new configuration option?
The downside of the approach described above is that the URL references were stored in the comments of a time series. The comments fields could therefore not be used anymore to store comments.
In the new approach which is available since Delft-FEWS 2020.01 the URL references are determined by URL templates which are configured in the TimeSeriesDisplay.xml.
How are the URL's of the images determined in the new approach?
If for a certain timestep of a time series an external image is available then this will be indicated by the value of the flag source. If the value is set to "UR" then FEWS will assume that an external image is available. By using the configured templates the correct URL will be determined to show the image in the document viewer.
How do I configure the URL templates?
The templates can be configured in the TimeSeriesDisplay.xml. It is possible to define 1 or more external image sources.
An external image source is a server which hosts images which can be shown in the document viewer.
For each external image source an user and password can be defined.
Within the element <externalImages> the URL templates and the time series filters can be defined. The time series filter determines to which time series the templates apply.
The URL template is used to determine the URL of the image. Both the time series filters and the URL templates will be explained in more detail below.
How do I configure a time series filter?
A time series filter can be used to configure easily to which time series the URL templates apply.
A very basic example of a time series filter is shown below.
<timeSeriesFilter> <locationId>myLocation</locationId> </timeSeriesFilter>
In this case the filter will select all time series which have a locationId equal to myLocation.
Below an example with a parameterId and a location configured. In this case all time series which have a parameterId equal to myParameter and a location equal to myLocation will be selected.
<timeSeriesFilter> <parameterId>myParameter</parameterId> <locationId>myLocation</locationId> </timeSeriesFilter>
All the elements which are available in the well known element timeSeriesSet are also available in the time series filter.
How do I configure the URL template?
The URL template is used to build the URL of the image.
Below an example of an URL template.
<urlTemplate>
<baseUrl>http://myserver:8080/images</baseUrl>
<fileUrl>'%myAttribute%'yyyy/MM/dd'/myimage.gif'</fileUrl>
</urlTemplate>
The URL template consists of two elements the baseURL and the fileUrl. The URL is created by combining them in the following way:
URL = baseURL + fileURL.
The baseURL is always static. The fileURL however is dynamic. It can contain location attributes and a time stamp. The location attributes and the time step are substituted with the actual values after selecting a time step in a time series.
An example!
It now time for an example. All the configuration elements are now explained. The example will be used to explain how the indivual elements are used to determine the correct URL for retrieving the correct image.
Below an configuration example
<documentViewer>
<externalImagesSource>
<user>dummy_username</user>
<password>dummy_password</password>
<externalImages>
<timeSeriesFilter>
<locationSetId>OPVLWATER_PEILSCHALEN</locationSetId>
</timeSeriesFilter>
<urlTemplate>
<baseUrl>http://dummy_hostname:8080/images</baseUrl>
<fileUrl>'%myAttribute%'yyyy/MM/dd'/myimage.gif'</fileUrl>
</urlTemplate>
</externalImages>
</externalImagesSource>
<externalImagesSource>
<user>dummy_username</user>
<password>dummy_password</password>
<externalImages>
<timeSeriesFilter>
<parameterId>myParameter</parameterId>
<qualifierId>myQualifier</qualifierId>
<locationSetId>RIOOLGEMALEN</locationSetId>
<timeSeriesType>external historical</timeSeriesType>
<timeStep unit="day"/>
<ensembleId>myEnsembleId</ensembleId>
</timeSeriesFilter>
<urlTemplate>
<baseUrl>http://dummy_hostname:8080/images</baseUrl>
<fileUrl>'%anotherAttribute%'yyyy/MM/dd'/myimage.gif'</fileUrl>
<timeZone>CET</timeZone>
</urlTemplate>
</externalImages>
</externalImagesSource>
</documentViewer>
In the example above we have 2 servers to hosts our images (myserver and anotherserver). When FEWS detects that for an certain time series an image is available (flag source is equal to "UR" then it will start searching for a matching template by using the time series filter).
When a user selects a time series the actual URL will be determined in several steps. They will be explained below.
Step 1 Select the correct URL template
In our example, if any time series is selected with a location that is part of the location set OPVLWATER_PEILSCHALEN then the first external image source will be used.
When multiple external image sources match then the first one found will be used. FEWS will also log a warning that multiple external image sources were found.
Step 2 Determine the URL by combining the baseURL and the fileURL
The actual url will be determined in several steps. First step is combining the baseUrl with the fileUrl. For the first external image source that would lead the following url
http://myserver:8080/images/'%myAttribute%'yyyy/MM/dd'/myimage.gif'.
Step 3 Apply the current time step to the template
If the user selects time step 20-01-2020 18:00 then the url would be after applying this date http://myserver:8080/images/%myAttribute%2020/01/20/myimage.gif
Also note the use of the quotes ' in the fileUrl. The parts of the fileUrl which are not a datetime pattern should be in between these quotes!
Step 4 Apply the location attributes to the template
The last step would be applying the actual values of the location attributes to the url templates. In our example that would be lead to the following url, when the attribute myAttribute has the value measurement
http://myserver:8080/images/measurement2020/01/20/myimage.gif
Now the actual URL for the selected time step and time series is determined. FEWS will now retrieve the image and show it in the document viewer.
Using the location id's in the template
If you want to use the location id in the template then the location id should be available as a location attribute.
If your file url is configured like this: '%:LOC_ID%'yyyy/MM/dd'/myimage.gif' then LOC_ID should be available as location attribute for the selected location.
timeZone
it is possible to configure a <timeZone> for the <fileUrl>. When not configured the date will be shown in GMT otherwise in the configred time zone.
How did I migrate to using URL templates?
Migrating to using the URL templates consists of several steps.
Step 1 Configure the URL templates
The first is to start configuring your templates in the TimeSeriesDisplay.xml. This step is explained in detail above.
Step 2 Adjust the data feed
The data feed needs to be changed. Because the URL references are now no longer stored in the comments. The data feed needs to be adjusted so that the comments no longer contain the
URL references.
Last part of step 2 (usage of flagSource="UR") is only necessary for Delft-FEWS versions before stable2021.02 #116612 & stable2022.01 #116611, after these versions flagSource="UR" is removed so no longer needed for URL references and will be ignored during an import
Instead of defining the URL the comments it is now only necessary to set the flag source value to "URL" to indicate that an external image is available.
After migration the event line should like this
<event date="2018-02-02" time="05:00:00" value="72.661" flagSource="UR"/>
More information about pi-xml import can be found here Delft-Fews Published Interface timeseries Format (PI) Import
Step 3 Removing the old URL references in the comments
Last step is to remove the 'old' comments from the time series. This can be done in several ways.
First option is write an custom transformation which reads the time series and writes them again after removing the URL references from the comments.
Another option is to export the time series to pi-xml and import them again after removing the URL references.
