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>user</user>
<password>pw</password>
</hostCredentials>
</documentViewer>
You can also have multiple credentials for different websites:
<documentViewer>
<hostCredentials>
<hostName>http://xxxx.com</hostName>
<user>user</user>
<password>pw</password>
</hostCredentials>
<hostCredentials>
<hostName>http://yyyyy.com</hostName>
<user>user</user>
<password>pw</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 are applicable.
The URL template is used to determine the URL of the image.
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 parameterId equal to myParameter and a location equal to myLocation will be selected.
<timeSeriesFilter> <parameterId>myParameter</parameterId> <locationId>myLocation</locationId> </timeSeriesFilter>
A time series filter will determine for which time series the URL reference template can be used. To determine the actual URL reference for a the time step of time series the URL template will be used.
The template can contain location attributes and a datetime-pattern. The URL reference to be used will be determined by applying the location attributes and the actual date and time to the datetime-pattern.
Below an example to explain this concept is in more detail. The code snippet contains the part of the TimSeriesDisplay.xml in which two external image sources are configured.
<documentViewer>
<externalImagesSource>
<user>myUser</user>
<password>myPassword</password>
<externalImages>
<timeSeriesFilter>
<parameterId>myParameter</parameterId>
<qualifierId>myQualifier</qualifierId>
<locationId>myLocation</locationId>
<timeSeriesType>external historical</timeSeriesType>
<timeStep unit="day"/>
<ensembleId>myEnsembleId</ensembleId>
</timeSeriesFilter>
<urlTemplate>
<baseUrl>http://myserver:8080/images</baseUrl>
<fileUrl>'%myAttribute%'yyyy/MM/dd'/myimage.gif'</fileUrl>
</urlTemplate>
</externalImages>
</externalImagesSource>
<externalImagesSource>
<user>myUser</user>
<password>myPassword</password>
<externalImages>
<timeSeriesFilter>
<locationId>H-2002</locationId>
</timeSeriesFilter>
<urlTemplate>
<baseUrl>http://anotherserver:8080/images</baseUrl>
<fileUrl>'%locationId%'yyyy/MM/dd'/myimage.gif'</fileUrl>
</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).
In our example, if any time series is selected with location H-2001 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. The actual url will be determined by 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'. 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
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
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!
The actual url will be used to retrieved the external image from the external server and will be shown in the document viewer.
