ABOUT ENERGY STAR PARTNER RESOURCES

Search by Topic:

What changes were made in the August 2016 web services 7.0 release? Follow

The Portfolio Manager web services 7.0 schema release took place on August 8, 2016, with beta release occurring on June 13, 2016 and included the following elements:

  • *New* Waste Tracking:
    • Meter Services –The meter schema will be updated to support waste meters. There will be a total of 72 waste meter types. These types cover 29 different materials (e.g. trash, mixed recyclables, electronics, etc.) and 4 management methods (disposed, recycled, composted, and donated/reused. The full list is available here: https://portfoliomanager.zendesk.com/hc/en-us/articles/220686308
      • Each waste meter name will be specified by the Management Method first and then the Material type: Disposed – Trash, Disposed – Appliances, Recycled – Glass, etc.)
      • There will be new fields in the meter schema specific to Waste Meters
        • Indication of whether the material is collected regularly or intermittently
        • Indication of whether the meter will track quantities (e.g. a volume or a weight) or will be based on a container/dumpster size (e.g. my dumpster is 3 cubic yards and was emptied 4 times this month).
        • If the entries will be based on the container/dumpster size, then the size of the dumpster must be specified. This field can be left blank if this does not apply.
      • The specifics of the schema for these updates are still in development, but more information on the schema structure is available here: https://portfoliomanager.zendesk.com/hc/en-us/articles/220683607-How-will-the-schema-for-the-waste-tracking-web-services-be-structured-
      • More information about the different meters and tracking approaches is available here: https://portfoliomanager.zendesk.com/hc/en-us/categories/202589637

     

    • Waste Meter Data Services – Waste meters will be added and shared using the meter services. But, they will not use the “Meter Consumption” services, because people do not “consume” waste and because the required fields for input are different. New services will be as follows:
      • Waste Data will depend on the meter type (kind of like we have “bulk” and “metered” meter types for energy). There are three basic types:
        • Regular Meters that will track quantities will require:
          • Start Date & End Date
          • Quantity & Cost
          • Estimate (Yes or No)
          • If it is “Disposed” then a destination (Landfill, Incineration, Waste to Energy, or Other/Unknown)
        • Regular meters that are based on container/dumpster size will require:
          • Start Date & End Date
          • Number of Pickups
          • Average % Full
          • Cost
          • If it is “Disposed” then a destination (Landfill, Incineration, Waste to Energy, or Other/Unknown)
        • Intermittent Meters will require the following data:
          • Date of Pickup/Event (single date)
          • Quantity & Cost
          • Estimate (Yes or No)
          • If it is “Disposed” then a destination (Landfill, Incineration, Waste to Energy, or Other/Unknown)
      • The waste data URLs will be as follows
        • PUT /wasteData/(wasteDataId) (Update single waste meter entry)
        • DELETE /wasteData/(wasteDataId) (Delete single waste meter entry)
        • GET /idHierachy/wasteData/(wasteDataId) (Get the hierarchy based on a waste meter entry)
        • POST /meter/(meterId)/wasteData (Add waste meter entries)
        • GET /meter/(meterId)/wasteData?page=(page)&startDate=(YYYY-MM-DD)&endDate=(YYYY-MM-DD) (Get waste meter entries)

 

  • Updates to Meter and Sharing Web Services
    • Get “My” Meters: The existing Get Meters service will be modified so that you can choose to get only the meters to which you have access. You will also still be able to choose to get the full list, as you do today.

      • To run this call and retrieve only your meters:

                         GET  /ws/property/(property ID)/meter/list?myAccessOnly=true

      • To run this call and retrieve all meters, you have two options:

        GET  /ws/property/(property ID)/meter/list
        GET  /ws/property/(property ID)/meter/list?myAccessOnly=false

 

    • Property Share Notifications – We will add more granularity to the data exchange access levels. Instead of just including “Exchange Data” access, property share notifications will have three available levels:
      • Exchange Data - Read Only (all property-level permissions set to Read, except recognition which has no "Read" state and is set to "None")
      • Exchange Data - Full Access (all property-level permissions set to Read Write)
      • Exchange Data – Custom (Property-level permissions set to a mix of Read / Read Write / None) -
        • In this case you can use GET/property and the <accessLevel> field to retrieve the permission level for the property data access permission only. 

 

    • Meter Share Notifications - Meter share notification data exchange access level descriptions will be harmonized with the property share notifications as follows:
      • Exchange Data - Read Only (Read access to meter data)
      • Exchange Data - Full Access (Read Write access to meter data)

 

  • Water-Related Changes
    • Irrigated Area – This will be a new input at the Property Level, which will cover the outdoor area that is irrigated either by an irrigation system or by hand. The user will specify an area and units (unit options: ft2, m2, or acres). These two items (value and unit) will now be in the Property services (PUT, GET, POST). Design services are not affected. The irrigatedArea element added to the property schema won’t be required for a successful POST. If no value is passed via XML, no value will be stored.
    • Added Metrics – There will be 8 new metrics added to the user interface and to Web Services. These new metrics will be available via the GET metrics call, as shown in the following table.
      • Only two metrics (Outdoor Water Use Intensity and Outdoor Water Cost Intensity) are directly related to the new input for irrigated area (which is the denominator). The other metrics are being added to support more robust benchmarking. The 12 metrics can be broken into two groups: 6 represent water quantities (gal/ft2 or kgal), and the other 6 are the corresponding cost values (in $/ft2 or $).
      • The metric Water Intensity (All Water Sources) incorporates both indoor and outdoor use, even though it is divided by the indoor floor area only.

 

 

 

User Interface Metric Name

Web Services Name

 

Consumption Metrics

Municipally Supplied Potable Water - Total Use (All Meter Types) (kgal)

municipallySuppliedPotableWaterTotalUse

 

Municipally Supplied Reclaimed Water -Total Use (All Meter Types(kgal)

municipallySuppliedReclaimedWaterTotalUse

 

Alternative Water Generated On Site - Total Use (All Meter Types) (kgal)

alternativeWaterGeneratedOnsiteTotalUse

 

Other Water Sources - Total Use (All Meter Types) (kgal)

otherWaterSourcesTotalUse

 

Equivalent Cost Metrics

Municipally Supplied Potable Water - Total Cost (All Meter Types) ($)

municipallySuppliedPotableWaterTotalCost

 

Municipally Supplied Reclaimed Water - Total Cost (All Meter Types) ($)

municipallySuppliedReclaimedWaterTotalCost

 

Alternative Water Generated Onsite - Total Cost (All Meter Types) ($)

alternativeWaterGeneratedOnsiteTotalCost

 

Other Water Sources - Total Cost (All Meter Types) ($)

otherWaterSourcesTotalCost

 

 

    • Removed Metrics – The 8 metrics shown in the following table will be eliminated. They will be removed from the user interface in August with the 7.0 release.
      • These metrics are generally being removed because the list of metrics is lengthy and difficult to parse. Also, this level of detail (per square foot values) is not available for energy use by fuel type. Hence, this level is inconsistent with treatment of energy and planned treatment of waste.

 

 

User Interface Metric Name

Web Services Name

Consumption Metrics

Municipally Supplied Potable Water - Indoor Intensity (gal/ft²)

municipallySuppliedPotableWaterIndoorIntensity

Municipally Supplied Reclaimed Water - Indoor Intensity (gal/ft²)

municipallySuppliedReclaimedWaterIndoorIntensity

Alternative Water Generated On Site - Indoor Intensity (gal/ft²)

alternativeWaterGeneratedOnsiteIndoorIntensity

Other Water Sources - Indoor Intensity (gal/ft²)

otherWaterSourcesIndoorIntensity

Equivalent Cost Metrics

Municipally Supplied Potable Water - Indoor Cost Intensity ($/ft²)

municipallySuppliedPotableWaterIndoorCostIntensity

Municipally Supplied Reclaimed Water - Indoor Cost Intensity ($/ft²)

municipallySuppliedReclaimedWaterIndoorCostIntensity

Alternative Water Generated On Site - Indoor Cost Intensity ($/ft²)

alternativeWaterGeneratedOnsiteIndoorCostIntensity

Other Water Sources - Indoor Cost Intensity ($/ft²)

otherWaterSourcesIndoorCostIntensity

 

  • Other WS Enhancements & Defect Resolutions
    • Get Design Metrics – There will be a new ability to specify which metrics you would like to receive (optional) or to get the standard set of design metrics (default).
      • The URL to run this call is:
      • GET /property/(property ID)/design/metrics
      • To specify individual metrics, a comma delimited list of metric names should be added to the header of the call -- similar to how the other Get-Metrics web service functions.

 

 

    • Security Questions – Within the account services we will remove the fields for security questions. We are moving to a framework where we provide a reset link if the user provides us their username and email. As such, we no longer need to collect security questions. The following services will be affected:
      • GET /account
      • POST /account
      • PUT /account
      • POST /customer  Note: we don’t expose security questions in GET and PUT customer calls, so those are not affected.

 

    • List of Countries – Synch the list of countries used within the Property Service to designate the physical address of the property and to designate the country that is the federalOwner, if applicable.  These two lists had gotten out of synch with each other.  They will both be updated to reflect the most current list of countries under ISO Standard 3166: https://www.iso.org/obp/ui/#home.  However, note that U.S. Territories will not be accepted.  For these locations, the territory should be specified under the State field and the country should be the United States.  Changes to the current lists of country codes are as follows:
      • Country List for Property Address
        • Codes to be added (i.e. will now be accepted): TT
        • Codes to be removed: none
      • Country List for federalOwner
        • Codes to be added (i.e. will now be accepted):  AI, AX, BL, BQ, CW, GG, IM, JE, ME, MF, PT, RS, SS, SX, VA
        • Codes to be removed(i.e. will no longer be accepted): AN, AS, CS, GU, MH, MP, PR, UM, VI

 

 

Have more questions? Submit a request