diff --git a/README.md b/README.md index 23c2476b..38c8b5cb 100644 --- a/README.md +++ b/README.md @@ -7,55 +7,54 @@ This is the repository for the BuildingSync Validator web application. ## Installation 1. Clone the repository. -1. Setup python 3. You can use a virtual environment: +1. Setup python 3. You can use a virtual environment: ```bash pyenv install 3.6.5 pyenv virtualenv 3.6.5 bsync-validator-3.6.5 pyenv local bsync-validator-3.6.5 ``` 1. Install PostgreSQL server for local development (if desired) - * Once installed, create your local database and user: - ```bash - psql -c 'DROP DATABASE bsync_validator;' - psql -c 'CREATE DATABASE bsync_validator;' - psql -c "CREATE USER bsync_validator WITH ENCRYPTED PASSWORD 'bsync_validator';" - psql -c 'GRANT ALL PRIVILEGES ON DATABASE bsync_validator TO bsync_validator;' - psql -c 'ALTER USER bsync_validator CREATEDB;' - ``` + * Once installed, create your local database and user: + ```bash + psql -c 'DROP DATABASE bsync_validator;' + psql -c 'CREATE DATABASE bsync_validator;' + psql -c "CREATE USER bsync_validator WITH ENCRYPTED PASSWORD 'bsync_validator';" + psql -c 'GRANT ALL PRIVILEGES ON DATABASE bsync_validator TO bsync_validator;' + psql -c 'ALTER USER bsync_validator CREATEDB;' + ``` 1. Install Django and associated requirements: - ```bash - pip install -r requirements.txt - ``` -1. Initialize the database: - ```bash - python manage.py migrate - ``` -1. Create a superuser: - ```bash - python manage.py createsuperuser - ``` + ```bash + pip install -r requirements.txt + ``` +1. Initialize the database: + ```bash + python manage.py migrate + ``` +1. Create a superuser: + ```bash + python manage.py createsuperuser + ``` 1. Start the app: - ```bash - python manage.py runserver - ``` - + ```bash + python manage.py runserver + ``` ## Local Development * When making changes to models, run the following command to make migrations: - ```bash - python manage.py makemigrations - python manage.py migrate - ``` + ```bash + python manage.py makemigrations + python manage.py migrate + ``` * To test schema import, you can run this command: - ```bash - python manage.py reset_schema --schema_version=1.0.0 - ``` + ```bash + python manage.py reset_schema --schema_version=1.0.0 + ``` -**NOTE**: You will need to be off the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbxml schema cannot be imported when on the NREL VPN. +**NOTE**: You will need to be _off_ the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbXML schema cannot be imported when on the NREL VPN. -### Precommit +### Pre-commit This project used `pre-commit `_ to ensure code consistency. To enable pre-commit, run the following from the command line. @@ -73,9 +72,9 @@ pre-commit run --all-files ### Testing * To run test: - ```bash - ./manage.py test - ``` + ```bash + ./manage.py test + ``` * To calculate coverage: ```bash @@ -85,7 +84,7 @@ pre-commit run --all-files ### Pep -* Run the following command to clean-up your code before committing: +* Run the following command to clean up your code before committing: ```bash autopep8 --in-place --aggressive --aggressive --recursive --max-line-length 100 --ignore E501,E402,W503,E731 --exclude=conf.py,structure.py . @@ -96,26 +95,26 @@ tox -e flake8 ### BuildingSync Schema -The BuildingSync Schema Viewer can support multiple versions of the BuildingSync schema. Admin users can manage schemas from the Django Administration console. Click on the 'Admin' link in the top navigation bar to access the Django Administration pages. +The BuildingSync Schema Viewer can support multiple versions of the BuildingSync schema. Admin users can manage schemas from the Django Administration console. Click on the 'Admin' link in the top navigation bar to access the Django Administration pages. -To add a schema, specify the name, version, and schema file (XSD) to parse and save the record. The schema file will be parsed automatically. **NOTE**: You will need to be off the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbxml schema cannot be imported when on the NREL VPN. +To add a schema, specify the name, version, and schema file (XSD) to parse and save the record. The schema file will be parsed automatically. **NOTE**: You will need to be _off_ the NREL VPN to import a schema, otherwise you'll get an error related to http://www.gbxml.org/schema}Area' as the gbXML schema cannot be imported when on the NREL VPN. -To modify an existing schema, click on the edit link. If changes are made to the uploaded XSD schema file and re-uploaded, ensure that the 'schema parsed' checkbox is unchecked before saving the record. This will trigger the automatic schema parsing. +To modify an existing schema, click on the edit link. If changes are made to the uploaded XSD schema file and re-uploaded, ensure that the 'schema parsed' checkbox is unchecked before saving the record. This will trigger the automatic schema parsing. ### Use Cases -Authenticated users can add private use cases to the BuildingSync Schema Viewer. Use cases are represented by a schematron file that defines a set of rules and patterns. +Authenticated users can add private use cases to the BuildingSync Schema Viewer. Use cases are represented by a schematron file that defines a set of rules and patterns. To add a use case, click on the 'Use Case' link in the top navigation bar, then click on the '+ New Use Case' button. -Select a name and a BuildingSync schema version. Select your use case definitions schematron file and upload, then click 'Submit'. +Select a name and a BuildingSync schema version. Select your use case definitions schematron file and upload, then click 'Submit'. Once ready, contact a BuildingSync admin to make the use case public. Public use cases will be available on the 'Validator' page to validate XML files submitted by users. -Admin users: Find the use case in the Django Administration console and click the edit button. Check the 'Make public' checkbox and save. +Admin users: Find the use case in the Django Administration console and click the edit button. Check the 'Make public' checkbox and save. ### Validator -The validator page allows users to validate XMLs against the BuildingSync schema and its public use cases. It can be tried with selected example files, or custom XML files can be uploaded for validation. +The validator page allows users to validate XMLs against the BuildingSync schema and its public use cases. It can be tried with selected example files, or custom XML files can be uploaded for validation. #### Validator API @@ -124,7 +123,7 @@ There is also a validator endpoint to validate XML files against the BuildingSyn #### SINGLE XML Request: POST to https://buildingsync.net/api/validate -Use form-data to specify the following parameters for schema version and XML file: ```schema_version``` and ```file```. +Use form-data to specify the following parameters for schema version and XML file: `schema_version` and `file`. Example Response: ```json @@ -165,7 +164,7 @@ Example Response: #### ZIP with multiple XMLs Request: POST to https://buildingsync.net/api/validate -Use form-data to specify the following parameters for schema version and XML file: ```schema_version``` and ```file```. +Use form-data to specify the following parameters for schema version and XML file: `schema_version` and `file`. Example Response: ```json @@ -236,25 +235,24 @@ Example Response: } ``` - ### BEDES BEDES parsing and mapping to the BuildingSync schema is not an automated process, due to the manual inspections/corrections required. To parse and map a new BEDES version: -1. Download the ```bedes_online_dictionary_uuid-lo.xml``` and the ```bedes_online_dictionary_uuid-terms.xml``` files from the BEDES website. +1. Download the bedes_online_dictionary_uuid-lo.xml` and the `bedes_online_dictionary_uuid-terms.xml` files from the BEDES website. -1. Place these new BEDES XMLs in the lib/bedes/vX.X directory. vX.X refers to the BEDES version here. +1. Place these new BEDES XMLs in the lib/bedes/vX.X directory. vX.X refers to the BEDES version here. 1. Parse the BEDES XMLs into a JSON file and map the BEDES terms to the BuildingSync attributes: ```bash python manage.py bedes --schema_version=X.X.X --bedes_version=X.X ``` Note that the bedes_version contains a v, ex: v2.2. - This will create a ```bedes_vX.X.json``` file in the lib/bedes/vX.X directory. It will also create 2 CSV files: ```bedes-mappings-enumerations.csv``` and ```bedes-mappings-terms.csv``` in the lib/bedes/vX.X/schemaX.X directory. + This will create a bedes_vX.X.json` file in the lib/bedes/vX.X directory. It will also create 2 CSV files: `bedes-mappings-enumerations.csv` and `bedes-mappings-terms.csv` in the lib/bedes/vX.X/schemaX.X directory. - *Note* — The BEDES terms must be mapped for each version of the BuildingSync schema by calling the ```python manage.py bedes``` command above. + _Note_ — The BEDES terms must be mapped for each version of the BuildingSync schema by calling the python manage.py bedes` command above. 1. Review these mapping files and make changes as needed. @@ -273,8 +271,8 @@ Admin interface is available at `/admin` Follow these steps to add a new schema version to the selection tool: -1. Add the schema file in the admin interface. Must have admin privileges. The schema will get automatically parsed. -1. Convert existing use cases schematron files to the new schema. Add the new use cases. +1. Add the schema file in the admin interface. Must have admin privileges. The schema will get automatically parsed. +1. Convert existing use cases schematron files to the new schema. Add the new use cases. 1. When the use cases have been reviewed, make them public in the admin interface. 1. Create XML example files and place them in the `lib/validator/examples/schema` directory. 1. Test the validator with the new XML example files. @@ -287,14 +285,14 @@ Follow these steps to add new example tables from the TestSuite repo 1. Clone the [TestSuite](https://github.com/BuildingSync/TestSuite) repo 2. Install [pandoc](https://pandoc.org/installing.html) 3. Convert the TestSuite README to html: - ``` pandoc README.md -s -o README.html ``` -4. Copy the tables part of the README.html and paste to replace the old content in ```bsyncviewer/templates/examples.html```. + `pandoc README.md -s -o README.html` +4. Copy the tables part of the README.html and paste to replace the old content in `bsyncviewer/templates/examples.html`. ### Adding an OpenStudio Simulation Use Case from the TestSuite repo -1. The relevant files are currently on the `develop` branch of the [TestSuite](https://github.com/BuildingSync/TestSuite/tree/develop) repo. Clone the repo locally. -1. OpenStudio Simulation use case schematron files include patterns from a [library of schematron files](https://github.com/BuildingSync/TestSuite/tree/develop/lib). Copy these files from the TestSuite repo into the selection-tool at the following location: ```bsyncviewer/testsuitelib```. -1. Open the relevant use case file from the TestSuite repo. For example: [L00_OpenStudio_Simulation.sch](https://github.com/BuildingSync/TestSuite/blob/develop/schematron/v2.2.0/v2-2-0_L000_OpenStudio_Simulation.sch). Edit the include statements at the top of the file with relative paths to the buildingsync-website testsuitelib directory. Save the file. +1. The relevant files are currently on the `develop` branch of the [TestSuite](https://github.com/BuildingSync/TestSuite/tree/develop) repo. Clone the repo locally. +1. OpenStudio Simulation use case schematron files include patterns from a [library of schematron files](https://github.com/BuildingSync/TestSuite/tree/develop/lib). Copy these files from the TestSuite repo into the selection-tool at the following location: `bsyncviewer/testsuitelib`. +1. Open the relevant use case file from the TestSuite repo. For example: [L00_OpenStudio_Simulation.sch](https://github.com/BuildingSync/TestSuite/blob/develop/schematron/v2.2.0/v2-2-0_L000_OpenStudio_Simulation.sch). Edit the include statements at the top of the file with relative paths to the buildingsync-website testsuitelib directory. Save the file. ```bash @@ -305,10 +303,10 @@ Follow these steps to add new example tables from the TestSuite repo ``` -1. Add the use case to the selection-tool by browsing to the ```/use_cases``` URL and clicking the *New Use Case* button. +1. Add the use case to the selection-tool by browsing to the `/use_cases` URL and clicking the _New Use Case_ button. 1. Fill out the name, description, and schema version 1. Upload the file that was modified in the previous step 1. Save 1. Make the use case public from the selection-tool admin interface. -1. If you have any example files to add to the selection-tool (for example, for the L000 OpenStudio Simulation use case, there are [2 examples files](https://github.com/BuildingSync/TestSuite/tree/develop/spec/use_cases/schema2.0.0/examples)), add them in the appropriate schema directory in ```bsyncviewer/lib/validator/examples```. Regenerate the ```example_files.zip``` archive. This will make the files available as examples at the ```/validator``` URL. +1. If you have any example files to add to the selection-tool (for example, for the L000 OpenStudio Simulation use case, there are [2 examples files](https://github.com/BuildingSync/TestSuite/tree/develop/spec/use_cases/schema2.0.0/examples)), add them in the appropriate schema directory in `bsyncviewer/lib/validator/examples`. Regenerate the `example_files.zip` archive. This will make the files available as examples at the `/validator` URL. 1. You can now validate XMLs against the new use case. diff --git a/bsyncviewer/management/commands/generate_onboarding.py b/bsyncviewer/management/commands/generate_onboarding.py new file mode 100644 index 00000000..ae8342aa --- /dev/null +++ b/bsyncviewer/management/commands/generate_onboarding.py @@ -0,0 +1,14 @@ +import os +import subprocess + +from django.core.management.base import BaseCommand + + +class Command(BaseCommand): + help = 'Generate onboarding html and pdf' + + def handle(self, *args, **options): + subprocess.check_output('pandoc --wrap=none ../../docs/onboarding.md -o onboarding_content.html', + cwd='bsyncviewer/templates').decode() + subprocess.check_output('pandoc ../../docs/onboarding.md -o documents/BuildingSync-on-boarding.pdf', + cwd='bsyncviewer/static').decode() diff --git a/bsyncviewer/static/documents/BuildingSync-on-boarding.pdf b/bsyncviewer/static/documents/BuildingSync-on-boarding.pdf index 25013fd8..559c4da7 100644 Binary files a/bsyncviewer/static/documents/BuildingSync-on-boarding.pdf and b/bsyncviewer/static/documents/BuildingSync-on-boarding.pdf differ diff --git a/bsyncviewer/static/images/buildingsync-logo.png b/bsyncviewer/static/images/buildingsync-logo.png new file mode 100644 index 00000000..b3608ca7 Binary files /dev/null and b/bsyncviewer/static/images/buildingsync-logo.png differ diff --git a/bsyncviewer/static/images/cerl.png b/bsyncviewer/static/images/cerl.png new file mode 100644 index 00000000..a55a232a Binary files /dev/null and b/bsyncviewer/static/images/cerl.png differ diff --git a/bsyncviewer/static/images/doee.jpg b/bsyncviewer/static/images/doee.jpg new file mode 100644 index 00000000..5703b704 Binary files /dev/null and b/bsyncviewer/static/images/doee.jpg differ diff --git a/bsyncviewer/static/images/invalid_xsd1.png b/bsyncviewer/static/images/invalid_xsd1.png deleted file mode 100644 index 048519f8..00000000 Binary files a/bsyncviewer/static/images/invalid_xsd1.png and /dev/null differ diff --git a/bsyncviewer/static/images/invalid_xsd2.png b/bsyncviewer/static/images/invalid_xsd2.png deleted file mode 100644 index d4d7ce0c..00000000 Binary files a/bsyncviewer/static/images/invalid_xsd2.png and /dev/null differ diff --git a/bsyncviewer/static/images/open_files.png b/bsyncviewer/static/images/open_files.png deleted file mode 100644 index aaaa74d7..00000000 Binary files a/bsyncviewer/static/images/open_files.png and /dev/null differ diff --git a/bsyncviewer/static/images/openstudio.png b/bsyncviewer/static/images/openstudio.png new file mode 100644 index 00000000..dc761cc9 Binary files /dev/null and b/bsyncviewer/static/images/openstudio.png differ diff --git a/bsyncviewer/static/images/valid_xsd.png b/bsyncviewer/static/images/valid_xsd.png deleted file mode 100644 index e4fc8e4f..00000000 Binary files a/bsyncviewer/static/images/valid_xsd.png and /dev/null differ diff --git a/bsyncviewer/static/img/adding-use-cases.jpg b/bsyncviewer/static/img/adding-use-cases.jpg new file mode 100644 index 00000000..c27c960c Binary files /dev/null and b/bsyncviewer/static/img/adding-use-cases.jpg differ diff --git a/bsyncviewer/templates/about.html b/bsyncviewer/templates/about.html index b122ab52..8a9519fb 100644 --- a/bsyncviewer/templates/about.html +++ b/bsyncviewer/templates/about.html @@ -110,7 +110,7 @@
Leverage expert support from DOE and the National Renewable Energy Laborator -

Get started by downloading the BuildingSync schema or +

Get started by downloading the BuildingSync schema or validating your use case.

diff --git a/bsyncviewer/templates/adopters.html b/bsyncviewer/templates/adopters.html index ae2563b0..84c44f14 100644 --- a/bsyncviewer/templates/adopters.html +++ b/bsyncviewer/templates/adopters.html @@ -13,19 +13,19 @@
- PNNL logo + CERL logo
- PSD logo + DOEE logo
- Buildee logo + OpenStudio logo
@@ -35,19 +35,19 @@
- Bright Power logo + PNNL logo
- AECOM logo + PSD logo
-
- Brand New Box logo +
+ SF Environment logo
@@ -55,23 +55,15 @@
-
-
- LBL logo -
-
- -
-
- SF Environment logo -
-
+
- Audette logo + Buildee logo
+ +
diff --git a/bsyncviewer/templates/collaborators.html b/bsyncviewer/templates/collaborators.html index 1022a627..5b81491b 100644 --- a/bsyncviewer/templates/collaborators.html +++ b/bsyncviewer/templates/collaborators.html @@ -7,67 +7,65 @@ {% block content %}
-

The following entities collaborated in the BuildingSync® development working group:

-

Adopters

+

Industry collaborators

    +
  • ACEEE
  • AECOM
    • +
  • AEI
    • +
  • arbnco
    • +
  • ASHRAE
  • Audette
    • -
  • Berkeley Lab
    • +
  • Automatic Magic
    • +
  • Big Ladder Software
  • Brand New Box
  • Bright Power
    • -
  • Buildee
    • +
  • BuildSimHub, Inc
    • +
  • Carbon Exchange
  • Carmel Software
    • +
  • CIMNE
    • +
  • City University of New York (CUNY)
  • Code Green Solutions
    • -
  • Performance System Development (PSD)
    • -
  • PNNL
    • -
  • SF Environment
    • -
-
-

Industry collaborators

-
-
    -
  • ActioNet
    • -
  • Advanced Energy
    • -
  • ASHRAE
    • -
  • Building Energy
    • -
  • Concept 3D
    • -
  • Consortium for Building Energy Innovation (CBEI)
    • -
  • Consortium for Energy Efficiency (CEE)
    • -
  • Descartes
    • -
  • ecoInsight
    • -
  • EcoPros, LLC
    • -
  • EMAT
    • -
  • Empowered Energy Solutions
    • +
  • ComRent/IEEE
    • +
  • Con Edison
    • +
  • Cornell University
    • +
  • CU Boulder
    • +
  • DEPT
    • +
  • Digital Alchemy
    • +
  • EDC NYC
    • +
  • Eley Consulting
  • The Energy Coalition
    • -
  • EnergyAction
    • -
  • FirstFuel
    • +
  • GBS-LLC
  • Grumman/Butkus Associates
  • Hitchcock Consulting
    • +
  • HSA Fort Worth
    • +
  • Intertek Building Science Solutions
    • +
  • Interval Data Systems
    • +
  • ISHRAE
    • +
  • Kolderup Consulting
  • kW Engineering
    • -
  • Improvement Facilitation
    • -
  • Institute for Market Transformation (IMT)
    • -
  • kWhOURS
  • L&S Energy Services
    • -
  • National Home Performance Council (NHPC), now Home Performance Coalition (HPC)
    • -
  • Performance Systems Development (PSD)
    • -
  • Philips Lighting
    • -
  • Philips Research North America
    • -
  • Retroficiency
    • -
  • Shakti Consultants, Inc.
    • -
  • Smart Buildings Center
    • -
  • Sustainable Energy Partnerships
    • -
  • VCA Green
    • -
  • Utility Systems Solutions, Inc.
    • +
  • Maalka
    • +
  • NUS
    • +
  • ORNL
    • +
  • PassiveLogic
    • +
  • Popli Design Group
    • +
  • RPI
    • +
  • S&P Fans
    • +
  • Saudi Aramco
    • +
  • Taylor Engineering
    • +
  • TESS
    • +
  • University of Cincinnati
    • +
  • University of Santa Catarina
    • +
  • VEIC
    • +
  • Weidt Group

National laboratories and government agencies

    -
  • California Energy Commission (CEC)
  • Federal Emergency Management Program (FEMP)
    • -
  • Ft. Carson U.S. Army Base
  • Lawrence Berkeley National Laboratory (LBNL)
  • National Renewable Energy Laboratory (NREL)
  • New York City
    • diff --git a/bsyncviewer/templates/contact.html b/bsyncviewer/templates/contact.html index f94d9e5f..674674f9 100644 --- a/bsyncviewer/templates/contact.html +++ b/bsyncviewer/templates/contact.html @@ -8,8 +8,8 @@

    - BuildingSync has a Groups.io forum where you and find, ask, and answer questions. To post, join - the group or send your question to BTODataTools@ee.doe.gov. + BuildingSync has a Groups.io forum where you can find, ask, and answer questions. To post, join + the group or send your question to BuildingSync@lists.buildingenergytools.org.

    diff --git a/bsyncviewer/templates/faq.html b/bsyncviewer/templates/faq.html index c89f3c31..d3613813 100644 --- a/bsyncviewer/templates/faq.html +++ b/bsyncviewer/templates/faq.html @@ -21,7 +21,7 @@

    What is BuildingSync?

    What are the elements of BuildingSync?

    -

    BuildingSync consists of two files and a reference sheet, which are all offered as free downloads. +

    BuildingSync consists of two files and a reference sheet, which are all offered as free downloads.

    diff --git a/bsyncviewer/templates/index.html b/bsyncviewer/templates/index.html index 2b2a1cf4..f306dd06 100644 --- a/bsyncviewer/templates/index.html +++ b/bsyncviewer/templates/index.html @@ -109,7 +109,7 @@
    For Implementers

    This streamlines the energy audit process, improving the value of the data, minimizing duplication of effort for subsequent audits, and facilitating achievement of greater energy efficiency.

    BuildingSync was developed to address the lack of an industry-standard collection format for energy audit data. Standardizing energy audit data can help energy auditors, - software providers, building owners, utilities, and other entities by maximizing the value that can be obtained from each set fo data – value obtained through collaboration, + software providers, building owners, utilities, and other entities by maximizing the value that can be obtained from each set of data – value obtained through collaboration, comparison, and reuse.

    Find out more
    diff --git a/bsyncviewer/templates/onboarding.html b/bsyncviewer/templates/onboarding.html new file mode 100644 index 00000000..c585396d --- /dev/null +++ b/bsyncviewer/templates/onboarding.html @@ -0,0 +1,32 @@ +{% extends 'base2.html' %} + +{% load staticfiles %} + +{% block title %}Onboarding{% endblock title %} + +{% block content %} + + + +
    + {% include "onboarding_content.html" %} +
    + +{% endblock content %} diff --git a/bsyncviewer/templates/onboarding_content.html b/bsyncviewer/templates/onboarding_content.html new file mode 100644 index 00000000..99ff6d4e --- /dev/null +++ b/bsyncviewer/templates/onboarding_content.html @@ -0,0 +1,152 @@ +

    +

    BuildingSync Onboarding Guide

    +

    National Renewable Energy Laboratory

    +

    Jie Xiong, Lauren Adams, Alex Swindler, Katherine Fleming, Cory Mosiman, Nicholas Long

    +

    Last Updated: December 8, 2022

    +

    Version 1.3

    +

    Overview

    +

    BuildingSync is a building data exchange schema to better enable integration between software tools and building data workflows. The schema’s original use case was focused on commercial building energy audits; however, several additional use cases have been realized including building energy modeling and generic building data exchange.

    +

    BuildingSync helps streamline the data exchange process, improving the value of the data, minimizing duplication of effort for subsequent building data collection efforts (including audits), and facilitating the achievement of greater energy efficiency.

    +

    BuildingSync Use Cases

    +

    A BuildingSync use case is an (auditing) workflow within which BuildingSync is leveraged for data exchange in platform(s). Depending on the connected platform(s), various users can collect, report, process, and analyze audit data through BuildingSync for their specific objectives. BuildingSync considers the needs and interests of a wide range of users in the energy audit industry, including building owners, auditors, software developers, utilities, and program managers. Typical BuildingSync use cases include:

    +
      +
    • Building energy assessment software integrating the ability to export BuildingSync-compatible files into their software;
      • +
    • Energy auditing services choosing to use software that can output BuildingSync-compatible files;
      • +
    • Building owners incorporating BuildingSync into their next RFP for a building energy audit by requiring the auditor to provide data in a BuildingSync-compatible format;
      • +
    • Utilities choosing to recommend or require software that uses BuildingSync-compatible files for any programs involving energy audits.
      • +
    +

    BuildingSync has traditionally been focused on exchanging data from auditing workflows in a linear fashion: typically an auditing tool would write a BuildingSync file which would then be read by a portfolio type tool to store the results. Note, though, that this is simply a single use case for BuildingSync and plenty more use cases exist, both real as well as aspirational.

    +

    Table 1 below shows the existing BuildingSync use cases approved and validated:

    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDescription
    BETTERUse case for BETTER analysis
    BRICR SEEDUse case for BRICR files on SEED Platform
    BsyncrUse case for the R package bsyncr
    L000 OpenStudio Pre-SimulationLevel 000 OpenStudio Pre-Simulation Use Case. In alignment with ASHRAE Standard 211
    L100 AuditUse case for the ASHRAE Standard 211 level 1 audits
    L100 OpenStudio Pre-SimulationLevel 100 OpenStudio Pre-Simulation Use Case. In alignment with ASHRAE Standard 211
    L200 AuditUse case for the ASHRAE Standard 211 level 2 audits
    New York City Audit Use CaseNY LL87 use case for schema version 2.4.0
    San FranciscoUse case for the city of San Francisco
    SEEDGeneral use case for files on SEED Platform
    +

    Table 1. List of currently supported use cases

    +

    This document will describe the necessary steps to create a new BuildingSync use case to enable interoperability with software, tools, or databases.

    +

    Use Case Definition

    +

    The first step is to define and design the use case framework. The following questions are to be answered and determined:

    +
      +
    • What is the workflow of the use case?
      • +
    • What tool is adopting/connecting to the BuildingSync schema?
      • +
    • Will the tool read from or write to BuildingSync files?
      • +
    • Is there an existing schema the tool is using? +
        +
      • Does the schema interact with BuildingSync already?
        • +
      • Are two schemas merging together or do translations need to be developed?
        • +
      • +
    • What Modeling Level of Detail (MLOD) will be considered in this use case?
      • +
    +

    Use Case Implementation

    +

    The use case implementation is a set of rules applied to the BuildingSync schema and is defined in the language Schematron. Schematron allows us to define special requirements for XML documents by writing rules. The rules are used to define stricter or more specific documents that can be used in the workflow enabled by the use case. These rules are generally written using XPaths and assertions about element counts, contents, properties, etc. Schematron also allows you to specify the “severity” of an assertion (e.g., INFO, WARNING, or ERROR) along with a custom message for the user running the validation.

    +

    Documents that are valid with respect to the use case are also valid with respect to the more general BuildingSync schema. For example, while the BuildingSync schema has multiple optional fields that can represent a building’s location (latitude, longitude, street address, city, state, zip code, country, etc.), a use case may require that all documents contain the building’s zip code.

    +

    The use case Schematron should define:

    +
      +
    • Required and optional data.
      • +
    • Valid options for enumeration fields
      • +
    • Required data format
      • +
    • Data quality and quantity
      • +
    • Dependencies between data fields
      • +
    +

    To begin writing a Schematron use case, you can refer to existing use cases published on the BuildingSync website and check out these general resources on Schematron:

    + +

    We have also created a tool which eases the process of writing Schematron. It allows you to write Schematron in a CSV format and then generate a Schematron document from that CSV. Refer to the docs in the BuildingSync TestSuite repo for more information.

    +

    Gotchas

    +

    There are some common gotchas that can occur when writing Schematron which we outline below:

    +
      +
    • Rule contexts that don’t match an XML node will be ignored. If you want to test in the context /a/b/c, but b does not exist, the tests within the rule will not be run. Thus if you want to make sure it always runs, you need to first assert the path to your context exists (recursively…)
      • +
    • If two rule contexts match the same XML node, only the first is fired/used. For example, if you had two rules, the first with the context /a/b and the second with the context /a/b[@id = 1], the first rule matches all b elements, so there are none “left” to match the second rule context. To get around this you need to move the tests into separate patterns b/c starting a new pattern resets this condition.
      • +
    • It’s really easy to make semantic typos when writing long/complex XPaths. This is obviously a problem because, due to the first gotcha mentioned, your rule may never be run because of your typo and you’d have no idea. For example, if you wanted to test /animals/dogs but misspelled it as /aminals/dogs the rule would get skipped. The only workaround for this is to write meta-tests for your use case. This means using another test framework, like python’s unittest, to run the schematron against many different documents to make sure everything is as it should be.
      • +
    +

    Examples

    +
      +

    1. Problem: I need to check some element that’s conditionally selected by an ancestor or sibling element

      +

      Example: For the Standard 211 Level 2 Schematron, we wanted to make sure the gross floor area was provided for a building, but we don’t care if the other floor area types (e.g. Heated, Cooled, Open, etc) have the floor area provided. Using XPath predicates we can select the floor area we want to test like so:

      +
      <sch:rule context="//auc:Buildings/auc:Building/auc:FloorAreas/auc:FloorArea[auc:FloorAreaType/text() = 'Gross']">
+    <sch:assert test="count(auc:FloorAreaValue) > 0">FloorAreaValue must be provided for Gross floor area</sch:assert>
+<sch:rule>
      +

      XPath predicates are very powerful and can allow you to even reach across the entire XML tree (see the example below for checking linked elements).

      2. +

    2. Problem: I need to check that an element is properly linked to another element somewhere else in the XML tree

      +

      Example: BuildingSync uses IDref attributes to link one element to another. For the Standard 211 Level 2 Schematron, we needed to make sure that the building included auc:PrimaryContactID with the attribute IDref which pointed to the ID attribute of an auc:Contact. We use XPath predicates again to make this happen:

      +
      <sch:rule context="//auc:Buildings/auc:Building">
+    <sch:assert test="auc:PrimaryContactID[@IDref=//auc:Contacts/auc:Contact/@ID]">auc:PrimaryContactID must exist and link to a valid auc:Contact</sch:assert>
+<sch:rule>
      3. +

    3. Problem: I need to do a simple summation of multiple elements to check a value

      +

      Example: You might want to assert that the sum of all electricity meter usage reports are equal to the reported annual fuel use (auc:AnnualFuelUseNativeUnits or auc:AnnualFuelUseConsistentUnits). This can be accomplished using the XPath sum() function. See the example below which also demonstrates how to use variables to make the tests more easily readable:

      +
      <sch:rule context="//auc:Buildings/auc:Building">
+    <sch:let name="summedMeters" value="sum(//auc:TimeSeriesData/auc:TimeSeries/auc:IntervalReading)"/>
+    <sch:assert test="$summedMeters //auc:ResourceUses/auc:ResourceUse/auc:AnnualFuelUseNativeUnits">auc:AnnualFuelUseNativeUnits must equal the sum of auc:TimeSeries readings</sch:assert>
+<sch:rule>
      +

      This test makes a few assumptions (that there’s only one resource use type, the reported interval reading is in the native units) but it gets the point across.

      4. +
    +

    Use Case Publication

    +

    Use cases are published in the BuildingSync/use-case repository. These use cases are also included on the BuildingSync website’s Use Case Validator tool, allowing users to check if their BuildingSync document passes your use case’s requirements.

    +

    To publish a use case, please refer to the repository’s documentation; in summary you need a Schematron which meets the specification as well as at least one example BuildingSync file which should be valid according to your Schematron. Once your Schematron has been approved and added to the repository, the BuildingSync team will add it to the BuildingSync website. Figure 1 below illustrates the publication workflow.

    +

    +

    Figure 1. Adding and validating BuildingSync use case

    +

    Validation

    +

    Users can use the BuildingSync Use Case Selection Tool / Validator to validate XML documents against both the general BuildingSync schema in different versions and public use cases. The validator can be used directly on the BuildingSync Selection Tool, and example files are also provided. Other customizable validation methods and examples can be found on the BuildingSync Technical Resources website.

    +

    Additionally, a Validator API has been developed to programmatically validate XML files within a third-party web tool or software package. More information on the API can be seen on the Validator on GitHub.

    +

    Resources

    +

    The following resources may be useful for use case development.

    +
      +
    • BuildingSync TestSuite - example BuildingSync files and tools for writing and validating BuildingSync use cases as Schematron files
      • +
    • BuildingSync use cases repo - BuildingSync use case files defined in Schematron. And within the BuildingSync TestSuite, there are several XML examples that are validated for published use cases
      • +
    • More example XML files - there are more XML examples for specific use cases
      • +
    • Interactive Tutorial - an annotated Jupyter Notebook for walking through a Level 1 Audit for a small office building
      • +
    • Schematron Website - for general information about the Schematron format
      • +
    diff --git a/bsyncviewer/templates/technical_resources.html b/bsyncviewer/templates/technical_resources.html index 5c476243..4576fc12 100644 --- a/bsyncviewer/templates/technical_resources.html +++ b/bsyncviewer/templates/technical_resources.html @@ -11,10 +11,14 @@

    Guides

    @@ -22,8 +26,7 @@

    Guides

    File Validation

    -

    For validation of BuildingSync XML files, the XML file undergoes a two step validation process (see Validation Using OxygenXML for an - example).

    +

    For validation of BuildingSync XML files, the XML file undergoes a two-step validation process.

    1. Validation against an XML XSD document

      @@ -84,57 +87,6 @@

      File Validation

    -

    Validation Using OxygenXML

    -

    Clone the BuildingSync/schema repository locally, and open the following files:

    -
    -
      -
    • 'BuildingSync.xsd'
      • -
    • 'examples/BuildingSync Website Invalid Schema.xml'
      • -
    • 'examples/BuildingSync Website Valid Schema.xml'
      • -
    -
    - -
    - open files -
    - -

    Validation Against XSD

    - -

    Using the OxygenXML Validate button, the Valid Schema shows a valid result against the XSD:

    -
    - valid schema -
    - -

    For the invalid schema, we can see all of the errors found, with descriptions:

    - -
    - invalid schema example 1 -
    -
    - invalid schema example 2 -
    - - -
    - open files -
    - -

    Validation Against XSD

    - -

    Using the OxygenXML Validate button, the Valid Schema shows a valid result against the XSD:

    -
    - valid schema -
    - -

    For the invalid schema, we can see all of the errors found, with descriptions:

    - -
    - invalid schema example 1 -
    -
    - invalid schema example 2 -
    -

    Validation Against Schematron

    Download the Schematron document Selection Tool Validator

 diff --git a/bsyncviewer/templates/topnav.html b/bsyncviewer/templates/topnav.html index d24bc835..e701fdb7 100644 --- a/bsyncviewer/templates/topnav.html +++ b/bsyncviewer/templates/topnav.html @@ -42,6 +42,7 @@
  • References
  • Case Study
  • Model Level of Detail Definitions
    • +
  • Onboarding
  • Technical Resources
    • diff --git a/bsyncviewer/urls.py b/bsyncviewer/urls.py index a47249c2..ff241fee 100644 --- a/bsyncviewer/urls.py +++ b/bsyncviewer/urls.py @@ -49,6 +49,7 @@ path('documents', views.references, name='references'), path('references', views.references, name='references'), path('contact', views.contact, name='contact'), + path('onboarding', views.onboarding, name='onboarding'), path('technical_resources', views.technical_resources, name='technical_resources'), re_path(r'^dictionary/(?P[0-9a-zA-Z_\.-]+)/$', views.dictionary, name='dictionaryversion'), re_path(r'^ajax/enum/$', views.retrieve_additional_dictionary_data, name='get_additional_data'), diff --git a/bsyncviewer/views.py b/bsyncviewer/views.py index b8766fcf..2b4438cf 100644 --- a/bsyncviewer/views.py +++ b/bsyncviewer/views.py @@ -214,6 +214,11 @@ def releases(request): return render(request, 'releases.html', context) +def onboarding(request): + context = {} + return render(request, 'onboarding.html', context) + + def technical_resources(request): context = {} return render(request, 'technical_resources.html', context) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..165a807b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Generating Onboarding Resources + +1. Install pandoc +2. Install MiKTeX +3. Install `fvextra` package + +```bash +python manage.py generate_onboarding +``` diff --git a/docs/onboarding.md b/docs/onboarding.md new file mode 100644 index 00000000..c0aeee2b --- /dev/null +++ b/docs/onboarding.md @@ -0,0 +1,163 @@ +--- +geometry: margin=1in +header-includes: + - \usepackage{fvextra} + - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,breakanywhere,commandchars=\\\{\}} +urlcolor: blue +--- + +![](../static/images/buildingsync-logo.png) + +# BuildingSync Onboarding Guide + +**National Renewable Energy Laboratory** + +Jie Xiong, Lauren Adams, Alex Swindler, Katherine Fleming, Cory Mosiman, Nicholas Long + +Last Updated: December 8, 2022 + +Version 1.3 + +\newpage + +## Overview + +BuildingSync is a building data exchange schema to better enable integration between software tools and building data workflows. The schema's original use case was focused on commercial building energy audits; however, several additional use cases have been realized including building energy modeling and generic building data exchange. + +BuildingSync helps streamline the data exchange process, improving the value of the data, minimizing duplication of effort for subsequent building data collection efforts (including audits), and facilitating the achievement of greater energy efficiency. + +## BuildingSync Use Cases + +A BuildingSync use case is an (auditing) workflow within which BuildingSync is leveraged for data exchange in platform(s). Depending on the connected platform(s), various users can collect, report, process, and analyze audit data through BuildingSync for their specific objectives. BuildingSync considers the needs and interests of a wide range of users in the energy audit industry, including building owners, auditors, software developers, utilities, and program managers. Typical BuildingSync use cases include: + +- Building energy assessment software integrating the ability to export BuildingSync-compatible files into their software; +- Energy auditing services choosing to use software that can output BuildingSync-compatible files; +- Building owners incorporating BuildingSync into their next RFP for a building energy audit by requiring the auditor to provide data in a BuildingSync-compatible format; +- Utilities choosing to recommend or require software that uses BuildingSync-compatible files for any programs involving energy audits. + +BuildingSync has traditionally been focused on exchanging data from auditing workflows in a linear fashion: typically an auditing tool would write a BuildingSync file which would then be read by a portfolio type tool to store the results. Note, though, that this is simply a single use case for BuildingSync and plenty more use cases exist, both real as well as aspirational. + +Table 1 below shows the [existing BuildingSync use cases](https://buildingsync.net/use_cases) approved and validated: + +| Name | Description | +|--------------------------------|-------------------------------------------------------------------------------------| +| BETTER | Use case for BETTER analysis | +| BRICR SEED | Use case for BRICR files on SEED Platform | +| Bsyncr | Use case for the R package bsyncr | +| L000 OpenStudio Pre-Simulation | Level 000 OpenStudio Pre-Simulation Use Case. In alignment with ASHRAE Standard 211 | +| L100 Audit | Use case for the ASHRAE Standard 211 level 1 audits | +| L100 OpenStudio Pre-Simulation | Level 100 OpenStudio Pre-Simulation Use Case. In alignment with ASHRAE Standard 211 | +| L200 Audit | Use case for the ASHRAE Standard 211 level 2 audits | +| New York City Audit Use Case | NY LL87 use case for schema version 2.4.0 | +| San Francisco | Use case for the city of San Francisco | +| SEED | General use case for files on SEED Platform | + +Table 1. List of currently supported use cases + +This document will describe the necessary steps to create a new BuildingSync use case to enable interoperability with software, tools, or databases. + +## Use Case Definition + +The first step is to define and design the use case framework. The following questions are to be answered and determined: + +- What is the workflow of the use case? +- What tool is adopting/connecting to the BuildingSync schema? +- Will the tool read from or write to BuildingSync files? +- Is there an existing schema the tool is using? + - Does the schema interact with BuildingSync already? + - Are two schemas merging together or do translations need to be developed? +- What [Modeling Level of Detail (MLOD)](https://buildingsync.net/mlod) will be considered in this use case? + +## Use Case Implementation + +The use case implementation is a set of rules applied to the BuildingSync schema and is defined in the language [Schematron](https://schematron.com/). Schematron allows us to define special requirements for XML documents by writing rules. The rules are used to define stricter or more specific documents that can be used in the workflow enabled by the use case. These rules are generally written using XPaths and assertions about element counts, contents, properties, etc. Schematron also allows you to specify the "severity" of an assertion (e.g., INFO, WARNING, or ERROR) along with a custom message for the user running the validation. + +Documents that are valid with respect to the use case are also valid with respect to the more general BuildingSync schema. For example, while the BuildingSync schema has multiple optional fields that can represent a building's location (latitude, longitude, street address, city, state, zip code, country, etc.), a use case may require that all documents contain the building's zip code. + +The use case Schematron should define: + +- Required and optional data. +- Valid options for enumeration fields +- Required data format +- Data quality and quantity +- Dependencies between data fields + +To begin writing a Schematron use case, you can refer to existing use cases published on the [BuildingSync website](https://buildingsync.net/) and check out these general resources on Schematron: + +- [BuildingSync and Schematron Presentation](https://drive.google.com/file/d/1hvwEWCA03dHQez3QRBdwi9I1rUBWgfy3/view?usp=sharing) +- [Tutorials on Schematron](https://www.xfront.com/schematron/index.html) +- [Explain Schematron](https://upg-dh.newtfire.org/explainSchematron.html#:~:text=The%20skeleton%20of%20a%20Schematron%20rule) +- [Schematron 2016 ISO](https://standards.iso.org/ittf/PubliclyAvailableStandards/c055982_ISO_IEC_19757-3_2016.zip) + +We have also created a tool which eases the process of writing Schematron. It allows you to write Schematron in a CSV format and then generate a Schematron document from that CSV. Refer to the docs in the [BuildingSync TestSuite repo](https://github.com/BuildingSync/TestSuite#generate-schematron) for more information. + +## Gotchas + +There are some common gotchas that can occur when writing Schematron which we outline below: + +- Rule contexts that don't match an XML node will be ignored. If you want to test in the context `/a/b/c`, but `b` does not exist, the tests within the rule will not be run. Thus if you want to make sure it always runs, you need to first assert the path to your context exists (recursively...) +- If two rule contexts match the same XML node, only the first is fired/used. For example, if you had two rules, the first with the context `/a/b` and the second with the context `/a/b[@id = 1]`, the first rule matches _all_ `b` elements, so there are none "left" to match the second rule context. To get around this you need to move the tests into separate patterns `b/c` starting a new pattern resets this condition. +- It's really easy to make semantic typos when writing long/complex XPaths. This is obviously a problem because, due to the first gotcha mentioned, your rule may never be run because of your typo and you'd have no idea. For example, if you wanted to test `/animals/dogs` but misspelled it as `/aminals/dogs` the rule would get skipped. The only workaround for this is to write meta-tests for your use case. This means using another test framework, like python's unittest, to run the schematron against many different documents to make sure everything is as it should be. + +## Examples + +1. Problem: I need to check some element that's conditionally selected by an ancestor or sibling element + + Example: For the Standard 211 Level 2 Schematron, we wanted to make sure the gross floor area was provided for a building, but we don't care if the other floor area types (e.g. Heated, Cooled, Open, etc) have the floor area provided. Using [XPath predicates](https://www.tutorialspoint.com/xpath/xpath_predicate.htm) we can select the floor area we want to test like so: + + ```xml + + FloorAreaValue must be provided for Gross floor area + + ``` + + XPath predicates are very powerful and can allow you to even reach across the entire XML tree (see the example below for checking linked elements). + +2. Problem: I need to check that an element is properly linked to another element somewhere else in the XML tree + + Example: BuildingSync uses `IDref` attributes to link one element to another. For the Standard 211 Level 2 Schematron, we needed to make sure that the building included `auc:PrimaryContactID` with the attribute `IDref` which pointed to the ID attribute of an `auc:Contact`. We use XPath predicates again to make this happen: + + ```xml + + auc:PrimaryContactID must exist and link to a valid auc:Contact + + ``` + +3. Problem: I need to do a simple summation of multiple elements to check a value + + Example: You might want to assert that the sum of all electricity meter usage reports are equal to the reported annual fuel use (`auc:AnnualFuelUseNativeUnits` or `auc:AnnualFuelUseConsistentUnits`). This can be accomplished using the XPath `sum()` function. See the example below which also demonstrates how to use variables to make the tests more easily readable: + + ```xml + + + auc:AnnualFuelUseNativeUnits must equal the sum of auc:TimeSeries readings + + ``` + + This test makes a few assumptions (that there's only one resource use type, the reported interval reading is in the native units) but it gets the point across. + +## Use Case Publication + +Use cases are published in the [BuildingSync/use-case repository](https://github.com/BuildingSync/use-cases). These use cases are also included on the BuildingSync website's [Use Case Validator tool](https://buildingsync.net/validator), allowing users to check if their BuildingSync document passes your use case's requirements. + +To publish a use case, please refer to the [repository's documentation](https://github.com/BuildingSync/use-cases#contributing); in summary you need a Schematron which meets the specification as well as at least one example BuildingSync file which should be valid according to your Schematron. Once your Schematron has been approved and added to the repository, the BuildingSync team will add it to the BuildingSync website. Figure 1 below illustrates the publication workflow. + +![](../static/img/adding-use-cases.jpg) + +Figure 1. Adding and validating BuildingSync use case + +## Validation + +Users can use the [BuildingSync Use Case Selection Tool / Validator](https://buildingsync.net/validator) to validate XML documents against both the general BuildingSync schema in different versions and public use cases. The validator can be used directly on the BuildingSync Selection Tool, and example files are also provided. Other customizable validation methods and examples can be found on the [BuildingSync Technical Resources website](https://buildingsync.net/technical_resources). + +Additionally, a Validator API has been developed to programmatically validate XML files within a third-party web tool or software package. More information on the API can be seen on the [Validator on GitHub](https://github.com/BuildingSync/BuildingSync-website#validator). + +## Resources + +The following resources may be useful for use case development. + +- [BuildingSync TestSuite](https://github.com/BuildingSync/TestSuite) - example BuildingSync files and tools for writing and validating BuildingSync use cases as Schematron files +- [BuildingSync use cases repo](https://github.com/BuildingSync/use-cases) - BuildingSync use case files defined in Schematron. And within the BuildingSync TestSuite, there are several XML examples that are validated for published use cases +- [More example XML files](https://github.com/BuildingSync/schema/tree/develop-v2/examples) - there are more XML examples for specific use cases +- [Interactive Tutorial](https://nbviewer.jupyter.org/github/BuildingSync/schema/blob/develop/docs/notebooks/bsync_examples/Small-Office-Level-1.ipynb) - an annotated Jupyter Notebook for walking through a Level 1 Audit for a small office building +- [Schematron Website](http://schematron.com/) - for general information about the Schematron format