7. Steps to Add a new question to the asset inventory

  • never use question_option

7.1. Checklist for adding/removing/updating a question in the asset inventory

Potential items to be accounted for when adding/removing/updating a question in the asset inventory:

  • adding/removing/changing the model field

  • contextual guidance: allowing contextual guidance to be added to the question

  • display in corresponding asset inventory page

  • display in corresponding upgrade option form

  • Audit API pearlcertification.api.audit

  • QA checks

  • scoring

  • scoring tests

  • Pearl API pearlcertification.public_api (mappings and tests). Pay close attention to removed or updated fields/choices and what to do about them in previous api versions

  • HPXML Import (pearlcertification.cert.hpxml_import)

  • HPXML export (pearlcertification.cert.hpxml_export)

  • Home Energy Score (pearlcertification.cert.hes usually a simple field name change if necessary)

  • Importing Homes from Resnet db (pearlcertification.cert.resnet_import)

  • Comparison statements (pearlcertification.comparison_statements.re_market)

  • CR characteristics (pearlcertification.reports.utils.cr)

  • HIP characteristics (pearlcertification.hip.report)

  • Green Door characteristics (pearlcertification.green_door.characteristics)

  • AI Addendum (pearlcertification.reports.utils.ai_addendum)

  • MLS’s (pearlcertification.reports.utils.mls)

  • Batch Home preprocessing for preprocessing_logic that uses the pearl API for creating assets (especially lennox)

  • check asset data stored in db (when removing or updating answers of a field): referencedata and recommendedimprovementsboilerplate

  • Baseline assets generation for recommended improvements

  • data migrations for existing homes data (pearlcertification.asset_inventory.utils.data_migration.HomeDataMigration.migrate_data)

  • data migrations for upgrade options (usually a one-time script needs to run to do this)

7.2. Sample detailed scenario of adding a new question to the asset inventory

The scenario for this case describes the addition of a new question to the asset inventory. This is just an overview of the steps that need to happen. To know how to set the different attributes, make sure to check the implementation of existing questions and follow it.

  • create the new field under the cert app and run migrations.

  • add the field_name to the model.CONTEXTUAL_GUIDANCE attribute if contextual guidance can be attached to the question.

  • add the new question under pearlcertification/asset_inventory/forms/<asset_category>.py.

The above steps will result in the question displayed in the asset inventory. The next steps depend on ticket requirements: some questions need to be displayed in one or many reports, some don’t need to.

7.3. Add a new asset characteristic based on the new question to the Certification Report (CR)

  • An entry under an asset in the CR is called “Asset Characteristic”. An Asset Characteristic is usually based on the answer to one question (but can also be based on many questions).

  • The asset characteristics are placed under reports/utils/cr/characteristics/<asset_category>/<asset_type>.py.

  • The characteristic class needs to implement the methods check_condition (contains the logic for when the asset characteristic should appear on the CR) and the get_characteristic_display (should return the text to be displayed in the CR).

  • Then, the new characteristic’s class needs to be added to the corresponding asset_type class under reports/utils/cr/cr_data/asset_types.py.

7.4. Add the new question to AI Addendum

  • An entry in the AI Addendum is called a Question. At a basic level, a Question needs just an answer and it belongs to a Section.

  • To make things easier, a Question can be either:

    • a CheckboxQuestion where the answer is a checked or unchecked checkbox if a certain condition is_verified or,

    • a TextQuestion where _asset_qs is expected to return the asset needed to generate the answer_display.

  • So, to add a new Question, we need to create a new Question class (or subclass CheckboxQuestion/TextQuestion) and implement the necessary methods.

  • A Question class (or subclass) must have a name attribute. The Section class also has a name attribute. Both are used to easily reference the Question answer in the template using {{ sections.<section_name>.<question_name>.answer }}. sections is a dict containing all the questions related to the AI Addendum.

  • The Question class should be added under under reports/utils/ai_addendum/data/<page>/<section>.py.

  • Add the new question to its section under reports/utils/ai_addendum/data/sections.py.

  • Then, the Question answer need to be referenced correctly in the template under reports/ai_addendum/<page>.html.