Contact

For questions about the OCLO community or if you have suggestions for how to evolve this community to be more effective, please contact Michael.A.Magsig@noaa.gov.

Asset Publisher

Appendices

Table of Content

  1. How to Get Help
  2. List of All Best Practices
  3. List of Some Cautions
  4. List of Troubleshooting Items
  5. References

1. How to Get Help

  • NCF

    • The way to get help from the NCF is by calling the NCF and having the NCF create/open a Trouble Ticket (TT). When you call the NCF, the NCF should always create/open a TT. If they don't, be sure to ask for a TT number. There are two different procedures for creating TTs with the NCF. There is a procedure for critical issues and for non-critical issues.
    • The critical issue procedure is the following:
      1. Call the NCF at 888-808-8624 .
        • Provide name and site Id.
      2. The NCF creates a TT.
      3. The NCF provides the requester with a TT number.
    • The non-critical issue procedure is the following:
      1. Call the NCF at 888-808-8624 .
        • Provide name and site Id.
        • Ask for a non-critical TT to be opened with details to follow via email.
      2. The NCF creates a TT.
      3. The NCF provides the requester with a TT number.
      4. Provide details by filling out this form. When filling out the form, be sure to include screenshots and create as many as possible. Also, provide supporting documentation.
      5. Submit the form.

  • AWIPS Community Support Google Space and A2 Dev List

    • The AWIPS Community Support Google Space allows you to chat with National Weather Service staff to ask questions about different issues that may arise with GFE (and anything else related to AWIPS2). To join this google space click this link.
    • The awips2dev list allows you to send emails to National Weather Service staff to ask questions about different issues that may arise with GFE (and anything else related to AWIPS2). To sign up for the list go here. (If you are not a member of the AWIPS Community on VLab, you will need to join the community before you will be able to sign up for the list.) Find the awips2dev forum, left-click on the three dots on the right-side and left-click subscribe. Note that this listserv isn't used very much any more and the AWIPS Community Support Google Space is a better option to use for help with GFE and AWIPS2 issues.

  • ADEPT (NIC) Team

    • You can email the ADEPT (NIC) team at gfe.nwsinitsconfig-support@noaa.gov or use the AWIPS Community Support Google Space to get help with Smart Inits and localConfig.py configuration issues. For more information about the ADEPT (NIC) team go here. That link will allow you to learn about Smart Inits, learn about the NIC, and submit a ticket.

  • Regional Focal Points

    • The regional focal points for each NWS region and the National Centers for Environmental Prediction (NCEP) are listed below:
      • Alaska Region
        • Steve Mercier
      • Central Region
        • Greg Noonan
        • Andy Just
      • Eastern Region
        • Joshua Watson
      • Pacific Region
        • Eric Jacobsen
      • Southern Region
        • Eric Holweg
      • Western Region
        • Gary Abadian
      • NCEP
        • Monica Bozeman
    • You can email the focal point in your region or at NCEP to ask questions about the best practices for your region or NCEP and to get help with issues you may have.

  • National Text Formatter Task Force

    • You can email the NWS Formatter Task Force (NFTF) at nws.formatter-support@noaa.gov to get help with anything related to the Text Formatters. For more information about the NTFT go here. That link will allow you to learn about all of the different national formatters, create a new formatter request, and submit a ticket.

  • Redmine Wiki

    • The Redmine Wiki allows you to create tickets for the various applications and GFE configurations on the NWS Software Collaboration Portal (SCP) that your site uses. This allows you to be able to get help with different SCP applications that your site uses when there is a bug.
    • The following steps explain the process of how to create a ticket for applications or GFE configurations on the NWS Software Collaboration Portal (SCP):
      1. Go to the application's or GFE configuration's Redmine Wiki NWS SCP page.
      2. Click the Report a problem link under Table of contents on the right side of the page.Report a problem link under Table of contents example
      3. Search the existing tickets for the application or GFE configuration before opening a new ticket.
      4. Provided there isn't an open ticket for the bug you found or desired new feature, then click either the bug or feature link.
        Report a bug or Request a feature link example
      5. Type a descriptive subject in the Subject box.
      6. Type a description in the Description box. The description should include all relevant information to help solve this issue by including any steps you have taken to duplicate or try to remedy the issue.
      7. If needed, you can set the Priority from the scroll box.
      8. Leave the Assignee blank.
      9. Leave Target Version blank.
      10. If you have screenshots of the problem, upload them using the Choose Files button.
      11. Left-click Create if you are done or left-click Create and Continue to submit the ticket and reopen the form for a new Issue.Create Ticket Dialog Box example for a Bug with the CrGfeTools Application
    • By default you will get email notifications as work on the ticket progresses. After the ticket has been created you can add other people to the ticket as Watchers of the ticket by clicking the ticket (ticket number or Subject) and click the Add button on the bottom left side of the screen where it says Watchers (0).

2. List of All Best Practices

  1. Best Practices for Editing Files in Localization Perspective
    • Always edit available SITE- and USER-level files only in the Localization Perspective.
    • Creating vs. Importing
      • If your site desires a new Smart Tool, Procedure, Utility, Smart Init, or Text Formatter, then look on the NWS SCP for the type of file that will do what your site desires. If there is a file on the NWS SCP that your site desires, then use the Subversion checkout out command to download the file (or files in the case of a Text Formatter). If the file (or files in the case of a Text Formatter) you downloaded is not a Smart Init, then copy the file (or each file in the case of a Text Formatter) to a .py file with the same name. For non-Text Formatter files, go into the Localization Perspective and right-click on the folder of the type of file you downloaded and click Import File... . Then navigate to your file and left-click okay. For Text Formatter files, go into the Localization Perspective and for each previously named .TextProduct file (i.e., TTT, TTT_RR, TTT_XXX, where TTT is the three letter product name, XXX is wfo/site id, and RR might be the specific region or might just be RR) right-click on the Text Products Folder and click Import File... . Then navigate to your file and left-click okay. Next for each previously named .TextUtility file (i.e., TTT_Overrides, TTT_RR_Overrides, where TTT is the three letter product name, and RR might be the specific region or might just be RR) right-click on the Text Utilities Folder and click Import File... . Then navigate to your file and left-click okay. Next for each previously named .template file (i.e. TTT_SiteOverrides, TTT_SiteDefinition, where TTT is the three letter product name) right-click on the Text Utilities Folder and click Import File... . Then navigate to your file and left-click okay. The SiteOverrides and SiteDefinition files will have to be edited before the Text Formatter will be able to be used.
      • When there is not an existing Smart Tool, Procedure, Utility, Smart Init, or Text Formatter on the NWS SCP that your site desires to carry out a certain purpose, then you can create one from scratch for non-Text Formatters by clicking on the folder of the type of file your site desires and left click New... . For Text Formatters you will click on the Text Product Folder and left click New... and if desired you can create Text Utilities for the Text Formatter too in a similar manner.
      • Whenever possible import files as opposed to creating your own from scratch.
    • Whenever you make changes to GFE files, they should be backed up to VLab using subversion (svn).
  2. How to set up and use <backuser>
    • Edit the SITE-level scvbu.properties file by setting SVCBU_USER equal to 1 and SVCBU_USER_ID equal to backuser.
    • Save these changes and then open GFE and Deactivate and Reactivate your site using the Site Activation GUI under the GFE Menu.
    • Open a terminal window on an AWIPS workstation.
    • Type ps -efw | grep "alertviz -p".
      • Write down the number after -p for your username.
    • Type xhost +SI:localuser:backuser
      • The response from the terminal should be: localuser:backuser being added to access control list
    • Type sudo -u backuser /awips2/cave/cave.sh
      • If you get a permission denied error, then only the ITO and ESA can run this command. You will need to ask one of them to run it for you.
    • When CAVE starts up, the Connectivity Preferences window will popup.
      • Enter your site id (XXX) in the Site Box.
      • Enter the port number you wrote down in the Alert Server box at the end of the line in the box after the colon.
      • Validate and left-click OK.
    • Open the Localization Perspective and it should be running as the <backuser> account.
    • You can now edit any <backuser> file.
    • You can copy any SITE- and/or CONFIGURED-level file to <backuser> to make changes to them for the <backuser> account.
  3. Documentation
    • Comments
      • Use comments to document your code and any changes made to existing code.
      • Every Python and XML file should have a comment at the beginning of the file describing what the file does and/or is used for.
      • Important Python methods/functions should have a comment explaining what the method/function does.
    • Change logs
      • Create and update change logs to document all changes that are made to BASE-level files and for files that are a part of applications developed locally.
      • Also create and update change logs to document changes that are made to every Python and XML file.
  4. Annual Clean-up of SITE-level Files
    • New data sets and regional changes should be incorporated when available and at least once a year.
    • Frequently and at least once a year, ensure no specific user has unneeded files or files that may prevent them from using required SITE-level configuration settings.
    • Frequently and at least once a year, remove duplicate or obsolete entries from configuration files, including localConfig and your SITE-level gfeConfig.
    • At least once a year, remove duplicate or obsolete entries from Smart Tools, Procedures, Text Products, Text Utilities, Utilities, and Smart Init files.
    • At least once a year perform a cleanup of SITE-level edit area files, the SITE-level gfeLevelMappingFile.xml file, the SITE-level gfeParamInfo.xml file, the SITE-level gfeParamName.xml file, SITE-level Parameter Info Files, and the SITE-level iscSendSampleDef file.
      • For all of the files listed above cleanup consists of removing duplicate or obsolete entries.
      • Edit areas need to be cleaned up due to the addition of new shapefiles like zone changes or CWA swaps.
    • If backup pairings change, then localVTECPartners.py will need to be cleaned up.
    • At least once a year remove obsolete or unnecessary files from the GFE and GFE Server directories in the Localization Perspective.
  5. Make Backups
    • Prior to making changes to any file in the Localization Perspective, make a backup copy. The backup copy should be saved somewhere so it isn't visible in the Localization Perspective.
  6. Old Files on the Server-side (and CAVE-side)
    • Prior to removing any files from the Localization Perspective, copy them to a backup directory with an appended date in the filename. These files should not be visible in the Localization Perspective. This is especially important for Server-side files as having lots of old Server-side files can affect GFE start-up.
  7. GFE Restarting
    • After overriding/changing a GFE configuration or utilities file, you will need to restart GFE/CAVE.
  8. GFE Server Restarting
    • After overriding/changing a GFE server configuration file, you will need to restart the GFE server.
    • Prior to restarting the GFE server, let your office know and kick everyone out of GFE.
    • When GFE is back up, let your office know.
    • Find a good time at your office when this will cause the least amount of inconvenience.
  9. Have GFE in its own CAVE
    • Whenever you are working in GFE, have it in its own CAVE.
  10. Python
    • When writing new code, break the code up into smaller pieces.
    • Use comments to document your code and any changes made to existing code.
    • Add new code and make modifications to existing code incrementally and then test.
    • When writing code, use logical naming conventions so that other members of your office will be able to understand what the code does.
    • When troubleshooting code, use print statements.
      • In Python 3 be sure to use parentheses around what you want to print (e.g., print ("hi"))
    • When importing numpy, use import numpy as np.
      • Use np.method (i.e., np.min, np.where, etc.,) to call the various numpy methods.
  11. Practice Database
    • Whenever possible if you are going to be making changes to the database, use practice mode and the practice database first. If everything works in practice mode after making the database changes, then you can make the changes in operational mode and to the official/forecast database.
  12. Testing Under USER-level
    • Whenever making changes to a SITE-level file, copy the file to USER-level first and then make the changes. Next, test the changes and if everything works properly, then you can copy the changes into the SITE-level file.
      • This is especially important when updating Text Formatters.
  13. ISC
    • The extraISCparms and REQUESTED_ISC_PARMS lists MUST be overridden/added to use plus equals (+=) and NOT equals (=).

3. List of Some Cautions

  1. Configuration Files
    • Use caution when editing server-side files so that you do not make syntax errors or make some other change that causes the GFE Server to not be able to run.
    • Changing your Site's Domain in localConfig with SITES Dictionary
      • Do not make your domain larger than necessary otherwise you might have performance issues.
      • Use caution while shrinking your domain because there is a small risk you could lose your Fcst and Official databases.
  2. Databases
    • Use caution when making changes to databases especially the forecast or official database.
  3. ISC
    • Use caution when using the ISC Request/Reply dialog box to request ISC grids, so that you don't request grids multiple times.
      • This can cause performance issues for your site and your neighbors.
    • Use caution so that you don't blindly change your grids to match your neighbors' grids when in ISC mode.
    • Use caution so that you don't run the smooth Smart Tool when in ISC mode.
  4. BOIVerify
    • Use caution when changing the site domain as this will have an effect on BOIVerify.
  5. Service Backup
    • Use caution if backing up multiple offices simultaneously, so that you don't have too many files accumulate on your system.
      • This can cause Service Backup to have performance issues.

4. List of Troubleshooting Items

  • Generic Troubleshooting
    • Look through the various log files to find and diagnose problems/errors.
    • Once an issue has been identified and isolated begin diagnosing the situation.
    • Start with the most probable and common issue and progress to the least probable and uncommon issue.
    • Check the syntax when making changes to any GFE config or GFE server config file in the Localization Perspective.
    • Restart GFE.
    • Restart the GFE server process using the GFE Site Activation GUI or by manually running the scripts via the command line in a terminal to deactivate and then activate the site.
    • Start GFE via the command line with the noredirect switch in a terminal.
      • This will output any errors GFE encounters to the terminal.
    • Ask forecasters to save off AlertViz messages and send to you for evaluation and troubleshooting.
  • Smart Init Troubleshooting
    • Look at all the methods and make sure they all have proper python syntax.
    • If they don't, then fix them so that they do and manually rerun the Smart Init using ifpInit.
  • Formatter Troubleshooting
    • Text Products Troubleshooting
      • Run text products locally and view error messages in the Process Monitor.
      • Look at the console logs for help with diagnosing problems that occur when running the formatter launcher.
      • Look at the EDEX logs for issues that occur when configureTextProducts.py is run.
    • Formatter Fails
      • The above link goes to a Wiki created by Jonathan Lamb that explains how to perform troubleshooting when a formatter fails.
    • Getting Undesirable Results with the Baseline Formatter
      • Check the TextRules Reference documentation to see if there are thresholds and variables that you might set to produce desired results.
    • Getting Undesirable Results and You have Overridden some Thresholds and/or Variables in Your Overrides File
      • Run the baseline version of the product to see if you get the same results.
      • If so, use the strategy above.
      • If not, comment out the overrides in your Overrides file and run it as the baseline.
      • Now begin adding in the overrides one-by-one until the problem re-occurs.
    • Get the Error Message: WARNING: TOO MANY PASSES ON TREE or WARNING EMPTY WORDS FROM TREE
      • Isolate the edit area for which there is a problem. Run the product for that area only by altering your Combination file or the "defaultEditAreas" list.
      • Isolate the time period for which there is a problem. Override the issuance_list for the product and comment out all periods except the first for the issuance causing the problem. Run the product for this time period and see if you get the same error. If not begin uncommenting the periods one at a time until you get the error. For any components prior to the one causing the trouble override the product component definition and remove all the entries in the "analysisList" and "phraseList" variables.
      • Isolate the phrase method. Determine which phrase is causing the problem by overriding the product component definition for the time period causing the trouble. Comment out all but the first phrase method and run the product. If the problem does not occur, begin uncommenting each phrase one-by-one and running the product until you find which phrase is causing the problem. Then comment out all but that phrase method and run the product again to see that the problem occurs. In some rare cases, you may have to uncomment more than one phrase to get the problem to occur.
      • Check the offending phrase method code. Find the phrase "word" method in the TextRules Library (or your Overrides file if you have overridden or added methods) and ensure that all of its return statements return with a self.Done() call or a self.setWords() call. If not correct the code and run your product again. If that was not the problem, proceed to the next step.
      • Turn on the trace messages. Now you can turn on the trace messages in your Overrides file by setting the Definition["trace'] flag to run. Re-run the product and examine the end of the trace messages. You are looking for a method that is repeating without returning a status of 'done' as reported in the message or is continually returning None for the value of 'Words' in the trace message. If you find the offending method, you can begin to investigate why it is not completing.
      • Check your overrides. You will want to isolate which of your overrides introduces the problem.
    • Formatter Does Not Appear in Formatter Launcher
      • Make sure the formatter has the Display Name set to something other than None in the lowest level override, usually SITE-level, Definition or Text Product file. Also make sure there isn't an override in the lowest-level override, usually SITE-level, Overrides file (if it exists for the Text Product) that has the Display Name set to None.
    • Missing a Configured File (using the Hazard_AQA formatter as an example)
      • In the Localization Perspective under the EDEX Folder, under the AFOS2AWIPS2 Folder:
        • Make sure the line PHXAQAXXX AEUS75 KXXX is removed from the SITE version of afos2awips.blacklist.txt where XXX is your site id.
        • Make sure the line PHXAQAXXX AEUS75 KXXX is added to the SITE version of afos2awips.txt.
      • Check the afosMasterPIL.txt and textCategoryClass.txt files located in /awips2/edex/data/utility/common_static/configured/XXX/textdb/ where XXX is your site id.
        • Do this per the instructions in the AWIPS II System's Manager Manual (SMM) section 16.6.2.
        • Make sure PHXAQAXXX is in afosMasterPIL.txt.
        • Make sure AQA is in textCategoryClass.txt
      • Touch one of the formatter files in common_static/base/gfe/textproducts/templates/product/
        • Run in terminal touch /awips2/edex/data/utility/common_static/base/gfe/textproducts/templates/product/DGT.py .
      • Touch the localConfig.py file in the Localization Perspective under the GFE Server Folder under the Server Config Files Folder
        • Make a minor change, save it, and then remove the minor change .
      • Run in terminal /awips2/GFESuite/bin/configureTextProducts XXX as user awips on dv3, where XXX is your site id.
  • ISC Troubleshooting
    • User Errors in localConfig.py
      • Ensure all necessary settings have been added.
      • Ensure there are no typos.
      • Make sure that the extraISCparms and REQUESTED_ISC_PARMS lists use plus equals (+=) and NOT equals (=). 
      • Validate your config using the instructions in the Server-side files section of the Configuration and Management section to check for syntax errors.
    • Use the IRT website within AWIPS to troubleshoot ISC problems.
  • BOIVerify Troubleshooting
    • Missing Model Data
      • Check to see if the database is available in BOIVerifyConfig.py.
      • Check to see if the database is included in SAVE_MODELS in BOIVerifyConfig.py.
      • If the database is available and included in SAVE_MODELS, then there may be a problem with the cron or available storage space.
    • Bias Corrected Grids not Calculating
      • Check to see if model data is available in GFE.
      • Check to see if the entry to create the bias corrected database for the model is in localConfig.py.
      • Check to see if the model is listed in BiasCorrModels.txt
      • Check to see if there are enough days of archived grids to begin calculating bias corrected grids which is set in BOIVerifyConfig.py.
      • Check to see if there are observation grids stored for the element.
      • If the first five do not solve the problem, then there may be a problem with the cron or available storage space.
    • Data Missing in the Automated (BOIVerifySumAll.py/BOIVerifySumTemps.py) Summary
      • Check to see if the correct models are defined in the BOIVerifySumAll.py/BOIVerifySumTemps.py procedure.
      • Check to see if BOIVerifySumAll.py/BOIVerifySumTemps.py can create statistics for the desired element.
      • If the first two do not solve the problem, then there may be a problem with the cron or available storage space.
    • System Issues (cron, space)
      • Check to see if the AWIPS-2 apps package is running on pv2.
      • Check to see if the user password has expired.
      • Check to see if there is any storage space left on the drive.
  • Service Backup Troubleshooting
    • Failed Site's Data on the Central Server.
      • If the failed site's data cannot be download, then there is a problem with the failed site's data on the central server.
      • If the failed site's grid database is incomplete, then there is a problem with the failed site's data on the central server.
      • If there are error messages or disabled functions in the failed site's GFE, then there is a problem with the failed site's data on the central server.
    • Backup site's Service Backup files.
      • If the site data cannot be imported, then there is a problem with the backup site's Service Backup files.
      • If Service Backup cannot be exited, then there is a problem with the backup site's Service Backup files.
      • If the system indicates you are backing up a site erroneously, then there is a problem with the backup site's Service Backup files.