Change Log

v2021.6.2 bug-fix-2 (March 16, 2022)

• GUI Bug-fix: Fixed error with Training Type and Dates for reset Assessors in the Administrator Training View

v2021.6.2 bug-fix (March 4, 2022)

• GUI Bug-fix: Resolved an error redirecting Partners from Scoring Form to Dashboard, and resolved a hang with QA Links from the Dashboard

v2021.6.2 (March 2, 2022)

• Update: Lowered home match radius to decrease number of results from get_buildings_with_same_location

v2021.6.1 (February 25, 2022)

• Bug-fix: Resolved bug where recommendations would not be listed on label if only one recommendation present

v2021.6.0 (February 23, 2022) 

• New Feature: Half-Address Creation 

  • This update includes notable API additions/changes: 

    • update_geolocation allows for assigning a coordinates to a home.  This will be used to link assessments by home/building. 

    • submit_address now includes geolocation inputs, which will be used to track buildings by location.  These can be provided alongside or in place of the street and city fields of the address. 

    • get_buildings_with_same_location is updated to have improved area checking using the geolocation that can be provided above.  This will allow partners and assessors to retrieve a more accurate list of previous assessments at or near a home. 

  • From the DOE GUI, assessors can mark the home’s location on a Google map if the assumed location is incorrect. This also allows homes without an address to be scored. 

  • From the DOE GUI, after verifying the home’s location on the Google map, a list of previous scores at or near that location is provided for the purposes of matching a final with an initial score or a corrected score with the score it is correcting. 

• New Feature: Validate HPXML 

  • A new validate_hpxml method allows users to validate an HPXML inputs file prior to submitted to Home Energy Score 

  • There is an equivalent feature in DOE's GUI 

• New Feature: GUI Guest Access 

  • Allows guest access to the GUI for the purpose of trying out the HEScore Tool to produce an unofficial score of a home. Intended users include policy makers, instructors, and students 

• New Feature: Public GUI access that allows lenders, and others, to verify an existing Home Energy Score Label 

• New Feature: Assessors will now receive email notifications when lapsed. 

• Improvement: The readability of the Roof help dialog was improved. 

• Improvement: From the DOE GUI, “Oil Instantaneous” is now allowed for “Hot Water Type” regardless of the type of heating system chosen. 

• Admin Features: Several administrative features were added or updated. 

• Bug-fix: False error on Admin/Partner batch updates 

v2021.5.0 (January 12, 2022)

• Upgrades for 15 and 30 year packages

• Updated to Home Energy Score OpenStudio v1.1.5

v2021.4.0 (October 20, 2021)

• Label recommendations now include ten-year payback packages; these improvements are estimated to pay back in about ten years based on national average installation costs

  • This includes a breaking change to the retrieve_recommendations method response

• The building comments field on submit_inputs now allows up to 512 characters (rather than 256)

• Multiple GUI improvements to satisfy Level-A ADA compliance 

• General updates and bug-fixes

• Continued additions to Administration features, in particular assessor email triggers and stylings

v2021.3.1 (August 24, 2021)

• Bug-fix: Translation fixed to resolve dpeaw assembly on windows/skylights to Air Fill, rather than Argon

• Bug-fix: Resolved inconsistency between validations that caused certain assessments to fail during label generation

v2021.3.0 (July 28, 2021)

• New Partner API method: export_partner_label_recommendations to export recommendations data by partner

• New Admin API method: export_label_recommendations to export recommendations data by building filter

• Added new emails to inform assessors of training requirements and advancement information

• Updated the assessor status to allow Partners to have assessor accounts that are always active (regardless of training/history)

• Continued upgrades to administration features

• Bug-fix: Public Profiles can be unpublished

• Bug-fix: Date validation for data exports

v2021.2.0-hotfix1 (June 21, 2021)

• Bug-fix: Resolution for homes that fail to retrieve energy cost estimates

• Improvement to get_session_token and Assessor Administration performance

v2021.2.0 (June 9, 2021)

• Bug-fix: Out of date energy estimates

• Bug-fix: Floating point in ducts percentages in HESCORE-HPXML

• Continued additions to the administration features

• New emails for assessors

v2021.1.0 (May 12, 2021)

• Modeling process is now using OpenStudio/Energy Plus

• Migrated to Laravel-8/PHP7.4

• Continued additions to the administration features

• The retrieve_buildings_* methods now include a create_label_date field in the response.  This is the date the label was initially generated for an assessment.

• Updated Validation Rules:

  • envelope_leakage, roof_area, and floor_area are now exclusive ranges

  • roof_area and floor_area have a min value of 4

  • Fuel oil is not valid for tankless water heaters

v2020.1.2 (February 11, 2021)

• Added support for HPXML v3 in HESCORE-HPXML v6

v2020.1.1 (February 4, 2021)

• Minor display updates for administration features

• Bug-fix: Login/account edit username checks are now case-insensitive 

• Validation Engine updated for roof/floor consistency checks

• Added the UBID-0 to the data export

v2020.1.0 (November 18, 2020)

• We have retired the "Admin Tool" and migrated all of its functionality into the Home Energy Score GUI. For most users, the biggest difference you will notice is that you will no longer be transferred to a different site to log in.

• API Updates:

  • Bug-fix: text overlap on certain labels runs

  • Handle disabled GUI access for third party users

  • Handle specific API access on Sandbox and Production

  • Add new home validation constraint over consistency roof/floor area and home footprint (see validation documentation for details)

v2019.2.4 (August 12, 2020)

• Added Energy Cost Estimate to Labels

• Added tracking for Calculation and Label versions separately

v2019.2.3 (March 31, 2020)

• The "blocked" User attribute is now respected by the API. Attempts to call get_session_token for a blocked user will fail with a SoapFault response, with the text "user <user_name> is blocked".

• The API method user_exists has been removed. Use get_user_info instead, which will retrieve certain values for valid user names and return a SoapFault response indicating that the user does not exist otherwise.

• Income eligibility is no longer included among the Home Performance with Energy Star fields. This change impacts the GUI, the submit_hpwes API method, the retrieve_hpwes API method, and the submit_hpxml_inputs API method, all of which have had the corresponding field removed.

• The export_label_results and export_partner_label_results methods have been updated to include the new solar_screen values on roof and skylight objects.

• Additions and style changes to Home Energy Score Label:

  • New formatting for the comparison page on custom labels, keeping notes to one page and columns consistent

  • Added costs comparison to the second page of label

• The Home Energy Score GUI and API now support "maintenance mode", which can be activated by HES administrators during the deployment of system updates that are likely to cause unpredictable behavior. During a maintenance period, all requests by non-administrators to the Home Energy Score GUI will receive a 503 error response and be directed to an error page with an explanatory message. All requests by non-administrators to the SOAP API will receive a 503 error response and a SoapFault with the same message. The path /st_rest/get_maintenance_mode_message is available on all Home Energy Score API domains (e.g. https://hesapi.labworks.org/st_rest/get_maintenence_mode_message) to check whether the system is in maintenance mode; a GET request to that URI will return the maintenance mode message during a maintenance period, or an empty response during other times. 

v2019.2.2 (November 22, 2019)

• Upgrade to hpxml-hescore v5.2.1

• Added HPXML support of Home Performance with Energy Star (HPwES)

• Remove constraints on zip codes to accept any user-entered six-digit value

• Bug fixes

  • Resolved bug showing any assessment not linked to assessor to all partners

  • Added validation check for invalid wall furnace  combinations

v2019.2.1 (October 22, 2019)

• Updated to HPXML version 5.1

• Resolved modeling error in Duct Locations

v2019.2.0-hotfix1

• We now run package calculations for all label generations, including custom labels

v2019.2.0 (August 20, 2019)

NOTE: This is a major release that provides additional, non-breaking, updates to the home energy score modeling behavior.  This release also includes new features intended to increase the usability of the HEScore Gateway for Assessors, Partners, Quality Assurance Providers, Mentors, and DOE Administrators.

• New modeling features

  • Added Solar Screens                    

  • Added Tankless Water Heaters                  

  • Added electric boiler 

• Increased HVAC options, with supporting validation

• Provide Average $ and kBtu/sq ft in retrieve_label_results   

• Add validation that ducts have to be in a floor space that was chosen

New / updated HEScore graphical user interface features:

• Assessors:

  • Updated logic to ensure correct watermarking of 'unofficial' labels

  • Provide more ‘comparison’ information in Alternate EEM report

  • Provide ability to generate ‘Comparison’ report of two homes with the same address

  • Calculator functions added to the Assessment interface

  • Portal graphical interface updated to better comply with American with Disabilities Act recommendations

• Partner

  • Now able to copy any official label and generate a Final label.

  • Continued refinement of custom labels to allow Partners more control over what’s displayed

• Training API: 

  • Enables third party training providers to directly query the HEScore Gateway to identify ‘trainee candidates’ that have been authorized access to the 3-D Simulation Training services.

  • Enables third party training providers to identify which ‘trainee candidates’ have passed / failed 3-D Simulation Training.

• DOE Admin

  • Added ability for DOE Admin to identify QA Providers in the Portal

  • Added ability for DOE Admin to associate a user with ‘QA’ role set to a specific QA Provider in the Portal

  • Added ability for DOE Admin to associate an Assessor with a QA Provider in the Portal

  • Added ability for DOE Admin to associate a user with ‘Mentor’ role set to a specific QA Provider in the Portal

  • Added ability for DOE Admin to associate an Assessor with a Mentor in the Portal

• Quality Assurance

  • Provided QA Dashboard for user with ‘QA’ role set

  • QA provider able to see all official homes for their Partner

  • QA provider able to copy official homes to make comparative assessment

  • QA report provides comparison of QA Provider’s / Assessors home facts

• Mentor

  • Provided Mentor Dashboard for user with ‘Mentor’ role set

  • Mentor able to see all official homes of Assessors with ‘Mentee’ role set

  • Mentor able to copy official homes to make comparative assessment

  • Mentor report provides comparison of mentor/mentee home facts

v2019.1.0 (February 11, 2019)

NOTE: This is a major release and introduces breaking changes that will require developers using our API to make updates to their client code

• We no longer recommend NuSOAP as a PHP client library, instead we recommend using the native SoapClient class (http://php.net/manual/en/class.soapclient.php). There is no need for existing clients to be updated, this is simply a change in our recommendation. Anecdotally, SoapClient appears to run much faster against our service, and it's easier to use and better maintained (NuSOAP was last updated in 2016). We are now using SoapClient for the Home Energy Score GUI and for API-internal SOAP calls and can verify that it works without any issues.

• A new GUI is available for testing. After logging in, the user will now have access to two new applications, marked "Beta," which can be used as alternatives to the Home Energy Score GUI. In an upcoming release, this "Beta" GUI will become the new Home Energy Score GUI, and will replace the old GUI.

• The API now features several new methods: 

  • available only to HES Administrators - csv_batch_import and csv_batch_import_status

  • for retrieving buildings - retrieve_buildings_by_mentor for mentor assessors, and retrieve_buildings_by_quality_assurance_provider, for QA Service Providers

  • to copy a building and create ancestor relationship - copy_building_address

• The retrieve_buildings_by_id method has been updated: 

  • the date_range and building_id_range fields no longer exist. They have been replaced with min_building_id, max_building_id, min_assessment_date, and max_assessment_date. 

  • The page_number and rows_per_page parameters are now optional, and default to 1 and 1000 respectively if not passed. 

  • Response now includes "archive" status (true if archived, false if not)

  • The "create_date" and "assessment_date" fields in the response are now of type "xsd:date" rather than "xsd:string"

• The get_user_info method has been updated:

  • Return new quality_assurance_provider field, that is the name of the QA Service Provider

• The process of creating a new label has been streamlined by consolidating methods:

  • The calculate_base_building, commit_results, and calculate_package_building methods no longer exist

  • The workflow required to create a building is now: (submit_hpxml) OR (submit_address, submit_inputs) followed by generate_label OR generate_custom_label. The upload_label method may be called after generate_label or generate_custom label has been called, and the uploaded label will supersede the one generated by the API.

• The is_final element of the generate_label API method has been made optional, and defaults to "false"

• validate_inputs has been rewritten to use a new and improved validation engine, and its response format has been greatly simplified - for example it no longer returns results for fields that pass validation. See the documentation of the validate_inputs method for details.

• The new validation engine is a Node.js project that is available for download and use in third-party applications (https://github.com/hes-pnnl/hes-validation-engine.git). It requires converting a home definition into JSON representation, but then can be run from the command-line, allowing third-party developers to use the same validation engine as the API does. This should make it possible to avoid submitting invalid homes without the need to develop your own validation code.

• Throughout the application, all request fields that were defined as type xsd:int but allowed only the values 0 and 1 have been converted to type xsd:bool. Because xsd:bool allows values "0" and "1" in addition to allowing "false" and "true" this should not require any change on developers' parts.

• We have changed the following response fields from xsd:int to xsd:bool

  • archive_buildings_by_id_result.status

  • delete_buildings_by_id_result.status

• We have removed the "result" element from the response of the building_ca_id method. That element was always set to 1 and thus had no value.

• The comment_api_only field has been removed from the submit_inputs method. That element served no purpose, as its value could not be retrieved again by any other method.

• We have removed the "message" element from the response of the delete_buildings_by_id method. That element never contained any value, because any error in the method results in a SoapFault response.

• The user_exists method has been updated so that instead of returning a SoapFault if the requested user does not exist, it returns a response with result set to FALSE.

• All methods that only take session_token, user_key and building_id as arguments now use building_info as the name of their wrapper element (which is now centrally defined). This was previously inconsistent, with some methods using building_info and other methods using other names.

v2018.2.1-hotfix1 (October 4, 2018)

• Partners may now call generate_custom_label as long the base and comparison buildings were both created by assessors associated with the partner

v2018.2.1 (September 10, 2018)

• retrieve_buildings_by_id has been updated so that the date_range filter now correctly filters by the date a building was created rather than the assessment date

• The API now features a new method, copy_building, which allows a new building to be created based on the values in another building. See the documentation under http://hes-documentation.labworks.org/home/api-definitions/api-methods/copy_building

• The XSD has been updated to define a number of entities that were previously redundantly defined to refer to common definitions. None of these changes should require client updates, as they are simply consolidation of redundant code.

• The GUI no longer offers "Puerto Rico" as a state -- this state was never supported by the API, and selecting it triggered an error.

• The Partner and Administrator export methods have been updated so that the field create_label_date now correctly reflects the date on which the label was actually generated. Previously it contained the most recent date on which calculate_base_building or calculate_package_building had been called for that building, which could introduce inaccurate information for some buildings.

v2018.2.0 (August 2018)

• Buildings now have a "status" attribute, accessible via the new "get_building_status" method. The method's documentation explains the meaning of each status. This feature supports a number of enhancements to the API, for example it makes it impossible to generate a label while calculate_package_building is running, and allows us to change how building deletion works in the backend to reduce the risk of losing historical data.

v2018.1.3 (July 2018)

• An error that occurred for some buildings with evaporative coolers has been resolved.

• upload_label can now optionally be called with the parameter pdf_url rather than pdf_base64. Using the new parameter allows passing the URL of a label PDF file, which is then downloaded and stored as the canonical copy of the label.

• The API's XSD files have been updated to be more consistent with each other and with the underlying API functionality

  • user_key now has an identical definition across all methods

  • generate_custom_label's and generate_label's responses' "file" field now correctly includes only "png" and "pdf" values

v2018.1.2 (June 2018)

• Added the new submit_hpwes and retrieve_hpwes methods.

• The `archive` field of the retrieve_buildings_by_id method may now be omitted from the request, in which case both archived and unarchived buildings will be included in the result.

• The export_label_results method now includes the label URL in the exported CSV files

• The batch_update method now accepts a "void" assessment type, which cannot be assigned to a home via any other method

• Updated internal SOAP client and server from the obsolete Zend_Soap_Server and nusoap classes to use the native SoapServer and SoapClient classes. This should be a seamless transition - the only known change is to the handling of invalid inputs, which will sometimes be cast automatically to a valid type in some circumstances. However, since this is a change to a library that is used in every call, there is the potential for unintended backwards compatibility breaks. These will be documented here if discovered.

GUI

• Removed the "Detailed Label Results" page for Administrator users, as the information there is now available from the CSV export 

• Added new "Home Performance with Energy Star" (HPwES) fields to the Systems page.

• The batch update feature of the administrator's dashboard now supports setting assessment type to "void"

v2018.1.1 (May 2018)

• Custom logos for the label footer were previously required to be exactly 550 or 820 pixels wide (the wider width was used for landscape) and the uploaded image was stretched to fit those proportions. This caused a problem with wide logos because they couldn't be made to fit properly on the portrait pages of a label. This has been changed in two ways: The maximum width of logos is now uniformly 550 pixels, and narrower images are no longer stretched.

v2018.1.0 (March 2018)

• Added the new batch_update method

• The methods export_label_results and export_partner_label_results now generate CSV files rather than Excel files

GUI

• Administrator users can now batch edit the external_building_id and assessment_type values of a building in the Administrator Dashboard

• It is now possible to have a heatpump that provides only heating or only cooling by setting the other system type to “None” (though some such combinations will result in a model validation error)

• Increased the size of the dashboard table in all dashboard views. The additional space was used to add more fields.

• Fixed a validation error that allowed homes without any floor area

• Fixed an issue that could cause an invalid address to be accepted without validation in some circumstances

• Numerous minor bugfixes 

v2017.3.1 (February 2018)

• retrieve_buildings_by_partner now correctly generates an error message when an invalid partner ID is passed

• If a request is not parseable (invalid SOAP XML) it will now return an error response instead of failing silently

v2017.3 (January 2018)

• Added the new "preconstruction" assessment type

• The API now has a new upload_label method that allows an Assessor user to upload a label PDF rather than using the API's internal label generation.

• Numerous improvements in error handling to make error messages more verbose and to provide meaningful specific errors rather than generic "unexpected error" responses in more situations.

v2017.2 (October, 2017)

This release adds authentication to the API to prevent inappropriate access to data.

New methods: get_session_token and destroy_session_token. A call to get_session_token requires the user's qualified_assessor_id (user name) and password. The response contains a session_token field, which must be provided as a parameter for every other API method. Upon completion of a session, the destroy_session_token method can be triggered to invalidate the session token.

The session_token allows the API to permit and deny access to methods or results depending on the logged in user's permissions. Attempting to access methods or values that are not permitted results in a SOAP Fault response.

We have also taken this opportunity to clean up the API a bit by removing obsolete methods and fields.

Every method (except for get_session_token) now includes a mandatory session_token field. In addition, the following methods have been altered as documented:

• archive_buildings_by_id, delete_buildings_by_id: 

  • qualified_assessor_id is removed. The user is determined from the session token.

  • The user must have the Assessor role and be the creator of the requested building (Note: This is not changed behavior but was hard-coded into the method previously and is now handled by the common access control layer).

• calculate_base_building, calculate_package_building, commit_results

  • The fields validate_inputs, log_type, and is_polling have been removed

  • Admin: All building IDs are permitted

  • Assessor: Only buildings assessed by the assessor are permitted

• retrieve_extended_results, retrieve_inputs, retrieve_recommendations, retrieve_results, retrieve_label_results

  • The fields validate_inputs, log_type, and is_polling have been removed

  • The values allowed to be in buildings or building_id are restricted based on the user's role(s)

    • Admin: All building IDs are permitted

    • Partner: Only buildings assessed by an assessor belonging to the Partner are permitted

    • Assessor: Only buildings assessed by the assessor are permitted

• export_label_results

  • assessor_id is removed. The user is determined from the session token.

  • User must have the Admin role to call this method

• export_partner_label_results

  • assessor_id is removed. The user is determined from the session token.

  • User must have the Partner role to call this method

• generate_custom_label

  • The user must have the Admin role or must have the Assessor role and be the assessor that created both buildings

• generate_label

  • is_polling is removed - this method already does not support asynchronous calls, so this has no impact on the method

  • The user must have the Admin role or must have the Assessor role and be the assessor that created the building

• retrieve_buildings_by_id

  • If the user has the Admin role, no restrictions apply

  • Otherwise, if the user has the Assessor role, qualified_assessor_id must be set to the user's name

  • Users with only the Partner role may not use this method. They should use retrieve_buildings_by_partner instead

• submit_address, submit_hpxml_inputs

  • assessor_id is removed. The user is determined from the session token.

  • User must have the Assessor role

• submit_inputs, validate_inputs

  • User must have the Assessor role and must be the user that created the building to be updated

• retrieve_buildings_by_partner

  • partner is now optional

  • Admin: Must pass the partner field 

  • Partner: May not pass the partner field. Instead the method always returns results filtered for the currently logged-in partner.

• These methods have been removed from the HEScore API

  • calculate_package_building_poll

  • calculate

  • doe2sim

  • doe2sim_multi

  • nearest_weather

  • retrieve_buildings_by_address (Use the address field of retrieve_buildings_by_id instead)