Page History

Contents

...

<documentViewer>
  <hostCredentials>
    <user>user<<user>dummy_username</user>
    <password>pw<<password>dummy_password</password>
  </hostCredentials>
</documentViewer>

...

<documentViewer>
  <hostCredentials>
    <hostName>http://xxxx.com</hostName>
    <user>user<<user>dummy_username</user>
    <password>pw<<password>dummy_password</password>
  </hostCredentials>
  <hostCredentials>
    <hostName>http://yyyyy.com<dummy_hostname</hostName>
    <user>user<<user>dummy_username</user>
    <password>pw<<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 URL references were stored in the comments of a time series. The downside of that was it was not possible anymore to use the comments fieldscomments fields could therefore not be used anymore to store comments.

In the new approach which is available since Delft-FEWS 2020.01 the url URL references are determines determined by url 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 which should be set to to UR. This new flagsource value is now also supported in the pi-xml import.

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 appylying the location attributes and the actual date and time to the datetime-pattern.

. 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 exampleBelow 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>dummy_username</user>
      <password>myPassword<<password>dummy_password</password>
      <externalImages>
            <timeSeriesFilter>
					<parameterId>myParameter</parameterId>
					<qualifierId>myQualifier</qualifierId>
					<locationId>myLocation</locationId>
					<timeSeriesType>external historical</timeSeriesType>
					<timeStep unit="day"/>
					<ensembleId>myEnsembleId</ensembleId><locationSetId>OPVLWATER_PEILSCHALEN</locationSetId>        		
				</timeSeriesFilter>
         	<urlTemplate>
            	<baseUrl>http://myserverdummy_hostname:8080/images</baseUrl>
            	<fileUrl>'%myAttribute%'yyyy/MM/dd'/myimage.gif'</fileUrl>
         </urlTemplate>
      </externalImages>
   </externalImagesSource>
   <externalImagesSource>
      <user>myUser<<user>dummy_username</user>
      <password>myPassword<<password>dummy_password</password>
      <externalImages>
         <timeSeriesFilter>
            <parameterId>myParameter</parameterId>
					<qualifierId>myQualifier</qualifierId>
					<locationSetId>RIOOLGEMALEN</locationSetId>  
					<timeSeriesType>external  <locationId>H-2002</locationId>historical</timeSeriesType>
					<timeStep unit="day"/>
					<ensembleId>myEnsembleId</ensembleId>
         </timeSeriesFilter>
         <urlTemplate>
            <baseUrl>http://anotherserverdummy_hostname:8080/images</baseUrl>
            <fileUrl>'%locationId%%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 location H-2001 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 by 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 url 

http://myserver:8080/images/

...

'%myAttribute%'yyyy/MM/dd'/myimage.gif'. If the user selects time step 

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

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!

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
 Code Block
xml
xml
<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 referencesThe actual url will be used to retrieved the external image from the external server and will be shown in the document viewer.