CSSTUDIO-2167 Support for "decorations" in the Logbook application

[abrahamwolk]

At ESS, we have implemented a "decoration" feature into the Logbook application.

Using this feature, it is possible to enter PV Names of VEnum-type into the "Advanced Search" part of the Logbook UI, and the logbook entries are then decorated by the status of the specified VEnum PVs using color coding: each possible Enum-value is represented using one color. A graphical symbol next to the logentry displays the value of the PV.

The intention is to be able to see, at a glance, what state the corresponding PV was in when a log entry was made and to see where the PV changed its value.

Since this feature is very likely to be of interest to ESS only, the feature itself has been implemented in a ESS-specific module. However, for the feature to function, there needs to be support for adding the decoration in the main Phoebus source code. This pull request adds this functionality to Phoebus.

In particular, this pull request adds the SPI interface org.phoebus.logbook.olog.ui.spi.Decoration, which has the following signature:

public interface Decoration {
    public Node getDecorationInputNode();

    public void setLogEntries(List<LogEntry> logEntries);

    public void setRefreshLogEntryTableView(Runnable refreshLogEntryTableView);

    public Node createDecorationForLogEntryCell(LogEntry logEntry);
}

A new decoration (displayed next to the search results in the Logbook application) is added by implementing these four methods:

• createDecorationForLogEntryCell() computes a decoration to be displayed next to one line of the search results (corresponding to the logEntry that is its argument) in the Logbook application.
• setRefreshLogEntryTableView() receives as an argument the Runnable refreshLogEntryTableView which refreshes the LogEntryTableView that displays the search results. This can be used by the implementation of the decoration to update the LogEntryTableView. In our case, the data that the decoration depends on needs to be fetched from the archiver, and when the data has arrived and the correct decoration has been determined, refreshLogEntryTableView() is called in order to refresh the UI.
• setLogEntries() is called by the Logbook application when it has received a new set of log entries to be displayed. (E.g., when a search query has returned, or when the user clicks to see the next page of the results list.)
• getDecorationInputNode() specifies a JavaFX node that is displayed under "Advanced Search" in the Logbook UI, and where the user can specify input for a given decoration. In our case, this is implemented by textfields where the user can specify PVs of type VEnum.

To make the use-case more concrete, the following is a screenshot of some results in the result list of the Logbook application, decorated using a decoration that has been implemented using this interface:

[kasemir]

This is specific to the OLog. Since I don't use that, I'm fine with the PR.

I would worry a little about adding a dependency from the logbook viewer to the archive. Logbook and archive are separate services which so far were completely independent. For some sites, the logbook is a legal record. As a consequence, one may annotate but not otherwise edit existing entries. In that scenario, a logbook needs to reproducibly show the content of each entry in the legal record. Showing some aspect of it, but then connecting to the archive to complete the display of each entry would be problematic. If entries should be augmented by the machine state, that should be done in the logbook system whenever an entry is created. Add some "augmentation" hook to the olog which for example adds the value of certain key PVs to each logbook entry. Each entry then contains this information, it will never change after the entry has been created, and all the information for an entry can be displayed right away without need to query separate services like the archive, channel finder, ...

[georgweiss]

A few comments inlined.
In my view any UI visualization of decorations configuration does not belong in the advanced search view since it is not related to how search is performed in Elasticsearch.

[abrahamwolk]

In my view any UI visualization of decorations configuration does not belong in the advanced search view since it is not related to how search is performed in Elasticsearch.

That is a valid point. It has been decided to remove the ability to input PV names at runtime, and therefore no options will appear under "Advanced Search".

[abrahamwolk]

@kasemir wrote:

I would worry a little about adding a dependency from the logbook viewer to the archive. Logbook and archive are separate services which so far were completely independent. For some sites, the logbook is a legal record. As a consequence, one may annotate but not otherwise edit existing entries. In that scenario, a logbook needs to reproducibly show the content of each entry in the legal record. Showing some aspect of it, but then connecting to the archive to complete the display of each entry would be problematic. If entries should be augmented by the machine state, that should be done in the logbook system whenever an entry is created. Add some "augmentation" hook to the olog which for example adds the value of certain key PVs to each logbook entry. Each entry then contains this information, it will never change after the entry has been created, and all the information for an entry can be displayed right away without need to query separate services like the archive, channel finder, ...

Thank you for your thoughtful input! I have raised the issue here, and after discussion it has been decided that it is not an issue for us that data is retrieved from the archiver and displayed next to the log entries in the Logbook application.

For clarity, I would like to point out that the dependency on the archiver is added in our site-specific customization of Phoebus; what is added in this pull request to Phoebus is an interface that enables the addition of (possibly site-specific, as in our case) decorations to the Logbook application in Phoebus.