The Hazard Services Focal Point User’s Guide is intended to describe to Focal Points how to configure and customize their Hazard Services to serve their local needs.  

The focus of the Focal Point Guide is on how Hazard Services works right now (Nov 2019).  For those of you that have been involved in Hazard Services through multiple releases, there may be some things you will need to unlearn.  This document has been created to describe some important features of Hazard Services that have changed since the early days.

For some earlier releases of Hazard Services, a standard production installation of CAVE including the Hazard Services software would result in Hazard Services not being able to do anything useful. There was always a small amount of manual customization required to get Hazard Services to function minimally.

Ever since 17.3.1, an out-of-the-box production installation of Hazard Services WILL function at least minimally without any manual customization.  That being said, there are still some aspects of Hazard Services that will not function WELL without some manual customization.  

Uninstalled support scripting.

In 19.2.1 and earlier releases, it was common for some of the support scripting that lives in dx3:/awips2/edex/scripts/HazardServices/ to not get distributed with releases as designed. Starting in 19.3.1 and onward, there should no longer be instances of this occurring.  Here are some files that previously failed to be distributed, along with download links.
verifyWgnThresholds.csh here 

updateSysPath.py here

cleanUpShapeFiles.py here

Override idiosyncracies.

There are two kinds of python one finds in the Hazard Services set of python files, class files and incremental override files. Prior to 19.2.x, the ability to see site and configured level files for the backup site while using Hazard Services service backup was often compromised for  incremental override files. That is, the site and configured level files for the primary site would be always be used even if one had chosen a backup site by way of the Change Site popup.  If you have had configured or site level incremental override files in place for some of your backup sites, installing 19.2.x Hazard Service will cause those files to begin impacting the behavior of Hazard Services, whereas previously those files would be ignored (unless one chose to do service backup by restarting all of Cave as the backup site).

For python class files, a different type of override inconsistency was in effect prior to 19.2.x.  If one had chosen a backup site by way of the Change Site popup, overrides for the primary site would get used if there was no override of the same module for the backup site.

For 19.2.x and onward, override behavior for service backup should be completely consistent.  Whether one does service backup by way of starting Cave as the backup site or by using the Change Site popup, the localization hierarchy will be the same.  Whether one is dealing with class files or incremental override files, the localization hierarchy will be the same.  For whichever site one is issuing hazards for, any site or configured level overrides for that site will apply, and no site or configured level overrides for any other site will ever apply.

Class and variable naming changes.

For all releases before 19.2.x, it was very common for python classes in the baseline Hazard Services code to have method names and member variable names that began with underscores. Starting with 19.2.x, almost all baseline Hazard Services python class methods and python class member variables will have any leading underscores removed from their names. The rationale for this is that someone creating an override will be able to create new methods and new member variables with leading underscores, and know for certain that they will not conflict with any existing method/variable names. This means that after 19.2.x hazard Services is installed, Focal Points will likely have to scrub any overrides they have for method  and variable names that will need to have leading underscores removed.

Shared GFE configuration files and Service Backup.

There has always been some GFE configuration files that Hazard Services also uses.  In the very earliest instances of Hazard Services these files were located at these paths:
   common_static/configured/LLL/gfe/python/SiteCFG.py

    cave_static/configured/LLL/gfe/userPython/textUtilities/regular/CityLocation.py

    cave_static/configured/LLL/gfe/userPython/textUtilities/regular/AreaDictionary.py

Furthermore, when in service backup mode via the Change Site popup, Hazard Services would still read these files on behalf of the primary site rather than the backup site.  Because AreaDictionary.py and CityLocation.py typically have content for neighboring sites, it was usually not necessary to do anything with any of these files in order to enable performing service backup for an immediately adjacent site.  In order to do service backup for a distant site, it would be necessary to obtain versions of AreaDictionary.py and CityLocation.py for that distant site and merge that content into your versions for your primary site.

Starting in 18.1.1, the content that previously resided in AreaDictionary.py, and CityLocation.py was moved to files named DefaultAreaDictionary.py and DefaultCityLocation.py in the same directory.  Furthermore, when Hazard Services is in service backup, SiteCFG.py, DefaultAreaDictionary.py and DefaultCityLocation.py are now all read on behalf of the backup site. Therefore, if there are not instances for each of these files present in the backup site directories, product generation will fail for service backup.  In a way this is simpler; there is no need to ever merge content in these files, one only need to obtain the versions from the site being backed up and drop them into the backup site directory.  Finally, starting in 18.2.1, DefaultAreaDictionary.py and DefaultCityLocation.py were moved up a level in the directory structure; their paths are now:

    cave_static/configured/LLL/gfe/userPython/textUtilities/DefaultCityLocation.py

    cave_static/configured/LLL/gfe/userPython/textUtilities/DefaultAreaDictionary.py

Updates to MapsDatabaseAccessor.py.

The method getPolygonDict() in the MapsDatabaseAccessor.py class has always been used to support retrieving impact areas for dam breaks, burn scars, and river reaches, and this continues to be true.  However, previously this information came out separate tables in the mapdata schema of the maps database; namely the tables daminundation, burnscararea, and riverpointinundation.  Now this information all comes out of a single table called hazardservicesarea, discriminated based on an attribute named ‘type’.  The method getPolygonDict() is now specifically designed to read information out of the hazardservicesarea table.  There is a new method called getPolygonDictForTable() which can read information out of any table in the mapdata schema of the maps database.

If you have customizations that call getPolygonDict() which are not designed to interface with impact areas for dam breaks, burn scars, or river reaches, they may need to be reworked to call getPolygonDictForTable() instead.  Calls that do read impact areas for dam breaks, burn scars, or river reaches may need to have the first argument tweaked. The good news is that the functionality in the new getPolygonDictForTable() method is now much more robust than before.

StartUpConfig.py.

It used to be true that if one did not define "possibleSites" and "visibleSites" in StartUpConfig.py, Hazard Services would not work at all.  Now, is it not absolutely necessary to configure these items.  Furthermore, these are now managed in settings rather than in StartUpConfig.py.  To configure these globally for the site, now one would override CommonSettings.py.

Most sites bordering an ocean, the Gulf of Mexico, or the Great Lakes will want to invoke the coastal extension area functionality.  There was a time when this was invoked through an override of StartUpConfig.py; at one time this involved setting “extensionAreaVisible”  to True, and then later it involved setting “extensionAreaVisible” to True.  Now neither of these items in StartUpConfig.py will do anything.  Invoking the coastal extension area functionality now involves overriding methods in HazardTypesUtils.py.

Formatters.

At one time the logic that generated the text content of product parts was often directly implemented in a “formatter” class. An example of such a class is Legacy_Base_Formatter.py, which actually no longer exists.  The functionality that used to be implemented by Legacy_Base_Formatter.py is now collectively implemented by NWS_Base_Formatter.py, ProductLevelMethods.py, SectionLevelMethods.py, SegmentLevelMethods.py, and EventLevelMethods.py.

In particular, this affects how one activates the product parts diagnostics.  This is still based on an override to the method _printDebugProductParts(), but this now occurs in the module NWS_Base_Formatter.py.

Most product part methods now consist of two instances of that method in two different classes; an instance in a formatter class and an instance in one of the LevelMethods classes.  The instance in the formatter is an interface to the product parts executive logic, and also handles whether existing edited text should be used for the part.  It is usually the instance in a LevelMethods class that actually generates the text content for the part.

If your installation has had Hazard Services installed for a long time, there are two things to be on the lookout for.  One, is if you have any overrides of Legacy_Base_Formatter.py; those of course will not do anything useful.  The other is if you have overrides to product part methods in other formatter classes where that override is generating text content.  Those overrides should be reengineered to the new paradigm, where the method instance in the formatter acts as an interface and the method instance in a LevelMethods class acts as the text content generator.

ProductEditorFields.py vs ProductParts.py

In 17.2.1 and before, there was an overridable file named ProductParts.py.  This file is now deprecated, and much of the information that used to be carried by ProductParts.py is now found in ProductEditorFields.py.  One obvious ramification is that any existing overrides dependent on updates to ProductParts.py will not work; they will need to be reengineered to account for the new code organization.  Another thing to be aware of is that it used to be possible to use ProductParts.py to specify the name of the product part method independent of the id of the product part.  This is no longer possible; the name of the product part method now is always exactly the same as the id of the product part, and this is enforced rigorously by the structure of the code.

Metadata.

One very important change to how metadata works is the  introduction of the class CallsToActionAndImpacts.py.  Previously, all the methods that generate megawidget content for individual CTAs were either in CommonMetaData.py or possibly in the individual metadata classes for each hazard type.  Now all the methods for individual CTA content are in CallsToActionAndImpacts.py.  If your installation has had Hazard Services installed for some time, you may have existing overrides for metadata functionality that used the old paradigm. These overrides will no longer work; such overrides should be reengineered so that all overrides of individual CTA methods are implemented as overrides of the CallsToActionAndImpacts.py class.

One challenge is introduced by this new organization for the metadata logic; it is not straightforward to make a Call to Action be different for different Hazard Types. However, this can be done; see the second customization example in section 3.2.1.1.

RiverFloodRecommender.py.

The set of attributes that RiverFloodRecommender.py adds to river hazard events is more extensive than it used to be.  For example, before 17.3.1, one would need to override RiverFloodRecommender.py if one wanted to have the ‘bankFull’ attribute (the stage at which the river is at the height of it banks) in river hazard events; this is no longer necessary.

Non-overridable python files.

Before 18.1.1, there were many python files that were not overridable.  One could use the localization perspective to create overrides of these files, but the resulting overrides were completely ineffectual. Here are some files that are now overridable that previously had not been:

Bridge.py HazardConstants.py HazardMetaDataAccessor.py MapsDatabaseAccessor.py
TextSegmentCheck.py CountyTypes.py CtaMarkerCheck.py
IQCCheck.py  MndHeaderCheck.py QualityControlFunctions.py QualityControl.py TwoDollarCheck.py WarningDecoderQCCheck.py WmoHeaderCheck.py
QualityControlCfg.py

Of particular importance is that Bridge.py is now overridable.  There are certain GFE configuration files that Hazard Services makes use of.  To make changes to that information such that it only manifests in Hazard Services, one can now override Bridge.py.  Previously this was not as straightforward.