The audit and upgrade datasets cover two scenarios:

1. A baseline building with a proposed work scope (see Audit)
2. A baseline building with a completed work scope (see Upgrade)

Both datasets describe a pre- and post-upgrade building and actions (or upgrades) that occur during both states. To accurately describe these scenarios, the HPXML document needs to have the top level nodes as described below.

All XML examples are taken from the examples/audit.xml document. It contains all of the required fields defined in the Audit dataset.

## Contractor¶

The Contractor elements should identify the name of the contractor (the person who is proposing and or completing the work), company and the email address.

    <Contractor>
<ContractorDetails>
<SystemIdentifier id="contractor1"/>
<Person>
<SystemIdentifier id="contractorperson1"/>
<Name>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
</Name>
<Email>
</Email>
</Person>
</ContractorDetails>
</Contractor>


## Customer¶

The customer is the homeowner or resident. The Customer element should include the customer’s name and phone number.

<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 the Audit and Upgrade document: pre- and post-upgrade. Each document includes a full description the house. The pre-upgrade condition of the house in the Audit dataset is the house prior to any work being completed on it (existing condition). The post-upgrade condition of the house describes the proposed work scope, usually completed by the contractor.

The pre-upgrade condition of the house in the Upgrade dataset is the state of the house prior to the completion of any work (existing condition). The post-upgrade condition of the house state describes the building after work has been completed.

The pre-upgrade Building element comes first in the document. It describes the initial state of the building (prior to work being completed). 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>


The post-upgrade Building element appears second in the document. It describes the “after” state of the building. In the audit dataset, that means the proposed improvements to the building (e.g., what the building would look like after proposed work has been completed). In the upgrade dataset, that means the actual condition of the building after the work is completed. The ProjectStatus/EventType element has a different value depending on the scenario:

Use Case Event Type
Audit proposed workscope

The post-upgrade building is mostly a duplicate of the pre-upgrade building; 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 describe the state of the building at points in time. The Project element describes what was done, or is planning to be done, to the building to get from one scenario 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"/>
<ProjectStatus>
<EventType>proposed workscope</EventType>
</ProjectStatus>
<EnergySavingsInfo>
</EnergySavingsInfo>
<Measures>
</Measures>
</ProjectDetails>
</Project>


### Energy Savings¶

EnergySavingsInfo is used to transfer 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 work completed 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 measure was installed without replacing an existing measure or component, the ReplacedComponent can be omitted. Similarly, if a component was removed and nothing was installed in its place, InstalledComponent would be omitted. The measure cost is also included in these files.

From the example file below, this measure replaces this furnace in the pre-upgrade building with this one.

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

<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>
</HeatingSystem>

<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>