Audit-Upgrade

The audit-upgrade use case covers two scenarios:

  1. A baseline building with a proposed work scope
  2. A baseline building with a completed work scope

Both scenarios describe a pre- and post-upgrade building and the actions (measures) that occur between the two states to make the difference. To achieve this the HPXML document needs to have the top level nodes described as below.

All xml examples are taken from the examples/audit.xml document. It contains all of the required fields for an audit use case data transfer.

Contractor

The Contractor elements should list the name of the contractor–the person who is proposing and or completing the work. The company being represented and an email address are also included.

    <Contractor>
        <ContractorDetails>
            <SystemIdentifier id="contractor1"/>
            <BusinessInfo>
                <SystemIdentifier id="business1"/>
                <BusinessName>ACME Home Performance Company</BusinessName>
                <BusinessContact>
                    <Person>
                        <SystemIdentifier id="contractorperson1"/>
                        <Name>
                            <FirstName>John</FirstName>
                            <LastName>Doe</LastName>
                        </Name>
                        <Email>
                            <EmailAddress>john.doe@hpxmlonline.com</EmailAddress>
                        </Email>
                    </Person>
                </BusinessContact>
            </BusinessInfo>
        </ContractorDetails>
    </Contractor>

Customer

The customer is the homeowner or resident. The Customer element should include their name and phone number as shown.

    <Customer>
        <CustomerDetails>
            <Person>
                <SystemIdentifier id="customer1"/>
                <Name>
                    <FirstName>Jane</FirstName>
                    <LastName>Customer</LastName>
                </Name>
                <Telephone>
                    <TelephoneNumber>555-555-5555</TelephoneNumber>
                </Telephone>
            </Person>
        </CustomerDetails>
    </Customer>

Building

There are two Building nodes in an Audit-Upgrade use case document: pre- and post-upgrade. Each is a full description the house. For the audit use case, the pre-upgrade condition is the house as audited and the post-upgrade condition is the proposed work scope. For the upgrade use case, the pre-upgrade building is the state of the house before any work was done and the post-upgrade state is the final building state audit.

Pre-upgrade

The pre-upgrade Building element comes first in the document. It describes the initial state of the building. It should have a ProjectStatus/EventType of audit.

 <Building>
        <BuildingID id="bldg1"/>
        <ProjectStatus>
            <EventType>audit</EventType>
        </ProjectStatus>
    </Building>

Many items within the building require a unique SystemIdentifier element. The id attribute is used to specify this id within the document (see ID and IDREF).

For example, the water heater in the pre-upgrade building has an id of dhw1.

                    <WaterHeatingSystem>
                        <SystemIdentifier id="dhw1"/>
                        <FuelType>natural gas</FuelType>
                        <WaterHeaterType>storage water heater</WaterHeaterType>
                        <Location>conditioned space</Location>
                        <CombustionVentingSystem idref="combvent1"/>
                    </WaterHeatingSystem>

Post-upgrade

The post-upgrade Building element appears second in the document. It describes the “after” state of the building. In the audit use case, that means the proposed state of the building after the upgrades. In the upgrade use case, that means the actual audited state of the building after the work is completed. The ProjectStatus/EventType element has a different value depending on the use case:

Post-upgrade Event Types
Use Case Event Type
Audit proposed workscope
Upgrade job completion testing/final inspection

The post-upgrade building is mostly a duplicate of the pre-upgrade building where components of the building that do not change remain the same. However, each component in the post-upgrade building needs a unique identifier that is different from the unique identifier in the pre-upgrade building. The sameas attribute of the SystemIdentifier element is used to link identical elements in the pre- and post-upgrade buildings (see sameas).

Going back to the water heater example, the water heater in the post-upgrade building has a different id than the identical water heater in the pre-upgrade building, but it has a sameas attribute to link it back to the pre-upgrade water heater and indicate it is indeed the same equipment.

                    <WaterHeatingSystem>
                        <SystemIdentifier id="dhw1p" sameas="dhw1"/>
                        <FuelType>natural gas</FuelType>
                        <WaterHeaterType>storage water heater</WaterHeaterType>
                        <Location>conditioned space</Location>
                        <CombustionVentingSystem idref="combvent1"/>
                    </WaterHeatingSystem>

Note: When a measure changes a component between a pre- and post-upgrade building, the SystemIdentifier/@sameas attribute is omitted because the measure references the relationship between components.

Project

In this paradigm, the Pre-upgrade and Post-upgrade building elements describes the state of the building at points in time. The Project element describes what was done or is to be done to get from one state to another.

The ProjectSystemIdentifiers are used to reference the pre- and post- building ids. The redundant BuildingID element should reference the post- building.

    <Project>
        <BuildingID id="bldg1p"/>
        <ProjectDetails>
            <ProjectSystemIdentifiers id="bldg1"/>
            <ProjectSystemIdentifiers id="bldg1p"/>
            <EnergySavingsInfo>
            </EnergySavingsInfo>
            <Measures>
            </Measures>
        </ProjectDetails>
    </Project>

Energy Savings

EnergySavingsInfo is used to transmit either or both the estimated or measured energy use and savings achieved in an upgrade.

            <EnergySavingsInfo>
                <EnergySavingsType>estimated</EnergySavingsType>
                <FuelSavings>
                    <Fuel>electricity</Fuel>
                    <Units>kWh</Units>
                    <TotalSavings>3000</TotalSavings>
                    <TotalDollarSavings>55</TotalDollarSavings>
                    <PctReduction>0.1</PctReduction>
                </FuelSavings>
                <FuelSavings>
                    <Fuel>natural gas</Fuel>
                    <Units>therms</Units>
                    <TotalSavings>100</TotalSavings>
                    <TotalDollarSavings>123</TotalDollarSavings>
                    <PctReduction>0.3</PctReduction>
                </FuelSavings>
                <AnnualPercentReduction>0.25</AnnualPercentReduction><!-- 25% -->
            </EnergySavingsInfo>

Note:  All percentages are expressed in the form of fractions. i.e. 10% => 0.1

Measures

The Measure element describes a piece of work done for a job. Each measure references one or more replaced components in the pre-upgrade building and one or more (usually one) installed components in the post-upgrade building. In cases where a component was installed without replacing an existing component the ReplacedComponent can be omitted. Similarly if something was removed and nothing was installed in its place InstalledComponent would be omitted. The measure cost is also included.

From the example file, this measure

                <Measure>
                    <MeasureSystemIdentifiers>
                        <SystemIdentifiersInfo id="furnacereplacement"/>
                    </MeasureSystemIdentifiers>
                    <Cost>3000</Cost>
                    <ReplacedComponents>
                        <ReplacedComponent id="htgsys1"/>
                    </ReplacedComponents>
                    <InstalledComponent id="htgsys1p"/>
                </Measure>

replaces this furnace in the pre-upgrade building

                        <HeatingSystem>
                            <SystemIdentifier id="htgsys1"/>
                            <UnitLocation>basement - conditioned</UnitLocation>
                            <CombustionVentingSystem idref="combvent1"/>
                            <HeatingSystemType>
                                <Furnace/>
                            </HeatingSystemType>
                            <HeatingSystemFuel>natural gas</HeatingSystemFuel>
                            <AnnualHeatingEfficiency>
                                <Units>AFUE</Units>
                                <Value>0.80</Value>
                            </AnnualHeatingEfficiency>
                            <FractionHeatLoadServed>0.7</FractionHeatLoadServed>
                        </HeatingSystem>

with this one.

                        <HeatingSystem>
                            <SystemIdentifier id="htgsys1p"/>
                            <UnitLocation>basement - conditioned</UnitLocation>
                            <CombustionVentingSystem idref="combvent1p"/>
                            <HeatingSystemType>
                                <Furnace/>
                            </HeatingSystemType>
                            <HeatingSystemFuel>natural gas</HeatingSystemFuel>
                            <AnnualHeatingEfficiency>
                                <Units>AFUE</Units>
                                <Value>0.92</Value>
                            </AnnualHeatingEfficiency>
                            <FractionHeatLoadServed>0.7</FractionHeatLoadServed>
                        </HeatingSystem>