Automated Benchmarking System _ABS_

Automated Benchmarking System (ABS) USER’S GUIDE (version 2.2) 8/31/2009 U.S. Environmental Protection Agency Climate Protection Partnership Division (CPPD) ABS User’s Guide 1.0 2.0 2.1 About this Guide ........................................................................................................... 1 Overview of the Automated Benchmarking System (ABS) ........................................ 2 National Energy Performance Rating System ....................................................................... 2 How is the rating calculated?............................................................................................ 3 2.1.1 2.2 Automated Benchmarking System (ABS) .............................................................................. 3 ABS Website ....................................................................................................................... 3 ABS Web Services ............................................................................................................. 4 2.2.1 2.2.2 2.3 2.4 2.5 3.0 3.1 Portfolio Manager ....................................................................................................................... 6 Energy Service Provider System ............................................................................................. 7 Minimum Requirements for Using ABS .................................................................................. 7 Getting Started .............................................................................................................. 9 Setting up an ABS Account ...................................................................................................... 9 System Notifications .......................................................................................................... 9 3.1.1 3.2 3.3 Read Technical Documentation ............................................................................................. 10 Set up a Web Services Client ................................................................................................. 10 ABS Website Web Services Client ................................................................................ 11 3.3.1 3.4 Sending Web Services Requests to ABS ............................................................................. 11 Transaction ID................................................................................................................... 13 Response Time for ABS Asynchronous Web Services Requests ............................ 13 3.4.1 3.4.2 3.5 Retrieving Responses from ABS (Asynchronous services only) ...................................... 13 Handling Web Services Errors ....................................................................................... 14 3.5.1 3.6 Integration.................................................................................................................................. 14 Determining an Integration Approach ........................................................................... 15 Structuring Data for the Web Services .......................................................................... 15 3.6.1 3.6.2 ABS User’s Guide 3.6.3 4.0 4.1 Setting Up Meter Data ..................................................................................................... 16 Testing Your System ....................................................................................................17 About the ABS TEST Environment........................................................................................ 17 Test Copies of your Customers‘ LIVE data .................................................................. 17 4.1.1 4.2 4.3 5.0 5.1 5.2 Accessing the TEST Environment from the ABS Website................................................. 18 Beta Releases........................................................................................................................... 18 Registering to use ABS Web Services in the LIVE Environment ..............................18 What does it mean to be Registered to use the LIVE Environment? ............................... 18 How to Register to use the LIVE Environment .................................................................... 19 5.2.1 Setting up Automated Data Mapping between Your System and Your Customers‘ Existing Portfolio Manager Accounts ............................................................................................ 19 6.0 6.1 Managing Customer Data through ABS Web Services ..............................................21 Submitting a New Building ...................................................................................................... 22 6.1.1 Setting up an Account for New Buildings with No Existing Portfolio Manager Account 26 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 6.10 6.11 6.12 Deleting a Building ................................................................................................................... 27 Submitting a New Space ......................................................................................................... 28 Updating a Space ..................................................................................................................... 29 Deleting a Space ...................................................................................................................... 31 Submitting a New Energy Meter ............................................................................................ 32 Updating an Existing Energy Meter ....................................................................................... 35 Deleting a Meter ....................................................................................................................... 37 Submitting New Energy Consumption Data ......................................................................... 37 Updating or Replacing Energy Consumption Data ......................................................... 39 Deleting Energy Consumption Data .................................................................................. 41 Managing Renewable Energy Certificate data ................................................................ 43 ABS User’s Guide 6.13 Downloading Building and Energy Data from a Customer‘s Portfolio Manager Account 45 7.0 7.1 7.2 Rating Exchange Service (RES) USAGE GUIDELINES ..............................................46 Rating Exchange Service (RES) ............................................................................................ 46 Rating Exchange Service (RES) Request: Ratings ........................................................... 46 Single Point-in-Time Metrics Request ........................................................................... 46 Date Range Metrics Request ......................................................................................... 47 7.2.1 7.2.2 7.3 Rating Exchange Service (RES) Response ......................................................................... 48 Sample XML Excerpts ..................................................................................................... 49 7.3.1 8.0 8.1 8.2 8.3 8.4 8.5 Mapping to an Existing Customer’s Portfolio Manager Account ..............................50 Step 1: Customizing the Data Authorization and Mapping Process ............................... 51 Step 2: Your Customer Authorizes You to Provide Automated Benchmarking ............. 54 Step 3: Getting Pending Authorizations ............................................................................... 55 Step 4: Verifying the Customer and Their Data.................................................................. 56 Step 5: Completing the Mapping Process ........................................................................... 56 Approving an Authorization Request (i.e., Mapping) .................................................. 56 Denying an Authorization Request ................................................................................ 58 8.5.1 8.5.2 8.6 8.7 9.0 9.1 9.2 10.0 11.0 11.1 ESP Access Privileges ............................................................................................................ 60 Testing the Authorization and Mapping Process ................................................................. 60 Ending Automated Benchmarking Services...............................................................61 Terminating Service for an Existing Customer .................................................................... 62 Removing Your Account from ABS ....................................................................................... 64 Monitoring ABS Activity...............................................................................................64 Troubleshooting ...........................................................................................................64 Duplicate Data in the System ............................................................................................. 64 ABS User’s Guide 11.1.1 11.1.2 11.2 11.3 11.4 12.0 12.1 12.2 12.3 13.0 13.1 13.2 Tips for Avoiding Duplication .......................................................................................... 65 Steps to Correct a Duplicate Building, Space, Meter, or Meter Reading ................ 65 Change Mapping to a Customer‘s Data............................................................................ 66 Remove Mapping to a Customer‘s Data ........................................................................... 66 Error Messages and Alerts ................................................................................................. 67 Getting Help ..................................................................................................................71 Frequently Asked Questions (FAQs) ................................................................................ 71 Additional XML Resources.................................................................................................. 73 Contacting Technical Support ............................................................................................ 73 APPENDICES ................................................................................................................73 SOAP Attachments .............................................................................................................. 73 Setting Username/Password in an SSL Invocation from Web Service Clients/Proxies 74 Downloadable ABS 2.0 Web service Client Tools .......................................................... 76 Space Attribute Characteristics .......................................................................................... 76 Valid Fuel Type/Unit Combinations ................................................................................... 82 USER’S GUIDE CHANGE HISTORY .............................................................................85 13.3 13.4 13.5 14.0 ABS User’s Guide 1.0 About this Guide Welcome to the User‘s Guide for the second generation of EPA‘s Automated Benchmarking System (ABS). In this Guide, we will introduce you to the primary features of ABS and step you through how to use this system to benchmark the energy performance of your customers‘ buildings. This Guide has been developed for Energy Service Providers (ESPs) who intend to exchange building and/or energy consumption data from their own system, through XML-based Web Services, with EPA. In the following sections, we will better explain the Automated Benchmarking System; help you to get started; provide details on how to use our services to manage building and energy data; and help you to troubleshoot common problems that ESPs experience. 1 ABS User’s Guide 2.0 Overview of the Automated Benchmarking System (ABS) EPA‘s Automated Benchmarking System (ABS) is provided as a solution for third-party Energy Service Providers (ESPs) to exchange building usage and energy consumption data with EPA‘s Portfolio Manager system. We typically define an ESP as a commercial energy information provider, bill handling service, or utility. Using EPA-provided XML-based Web Services, ESPs can securely provide building data from their systems to Portfolio Manager in exchange for receiving the ENERGY STAR national energy performance rating and other related environmental performance metrics (see Figure 2-1). Web Services Clients ESP System (your system) LIVE Services TEST Services Web Services Request/ Automated Benchmarking System (ABS) Response National Energy Performance Rating System LIVE environment TEST environment Portfolio Manager System ABS Website Figure 2-1: Major Systems involved in Automated Benchmarking In the following sections, we will provide a more detailed description of the four primary systems involved in using ABS:     National Energy Performance Rating System Automated Benchmarking System Portfolio Manager System Energy Service Provider (ESP) System 2.1 National Energy Performance Rating System The national energy performance rating is a type of external benchmark that helps energy managers assess how efficiently their buildings use energy relative to similar buildings nationwide. The rating system‘s 1–100 scale allows everyone to quickly understand how a building is performing — a rating of 50 indicates average energy performance, while a rating of 75 or better indicates top performance. 2 ABS User’s Guide EPA, in conjunction with stakeholders, developed the energy rating as a screening tool; it does not by itself explain why a building performs a certain way, or how to change the building‘s performance. It does, however, help organizations assess performance and identify those buildings that offer the best opportunities for improvement and recognition. 2.1.1 How is the rating calculated? Based on the information entered about your customer‘s building, such as its size, location, number of occupants, number of PCs, etc., the rating system estimates how much energy the building would use if it were the best performing, the worst performing, and every level in between. The system then compares the actual energy data you entered to the estimate to determine where your customer‘s building ranks relative to its peers. All of the calculations are based on source energy. The use of source energy is the most equitable way to compare building energy performance, and also correlates best with environmental impact and energy cost. To estimate how much energy your building would use at each level of performance, EPA conducts statistical analysis on the data gathered by the Department of Energy‘s Energy Information Administration during its quadrennial Commercial Building Energy Consumption Survey (CBECS). For each type of building for which EPA offers a rating, EPA goes through a rigorous process that involves:    Ensuring that the quality and quantity of the data will support a rating Creating a statistical model that correlates the energy data to the operational characteristics for each building to identify the key drivers of energy use Testing the model with real buildings Please refer to EPA‘s Model Technical Descriptions for more information on the specific data analysis for each available building type. See Section 12.4 for more information about particular Spaces and their attributes. For rules on how to earn the Rating, please refer to EPA‘s Criteria for Rating Building Energy Performance. 2.2 Automated Benchmarking System (ABS) ABS commonly refers to both the ABS Website and the set of Web Services that can be accessed through it. It is the platform and associated tools that EPA has provided to enable the data exchange between an ESP‘s billing or energy management system and EPA‘s Portfolio Manager which houses our national energy performance rating system. 2.2.1 ABS Website The ABS Website is a central resource that ESPs can use to:    set up and manage your ABS account; access ABS technical documentation; manually run our Web-based Web Services client or get instructions to build your own; 3 ABS User’s Guide      test your XML submissions prior to deployment in the LIVE environment; register to use EPA‘s Web Services in the LIVE environment; view information about all Web Services transactions; view information about the customers for whom you provide benchmarking services; and access EPA technical support. Our technical documentation includes:     XML Schemas for all EPA-provided ABS Web Services Sample XML documents for each XML schema that illustrate the type of data the ESP should expect to send or receive through ABS Web Services Web Service Description Language (WSDL) that describes each Web Service and how to invoke it Sample Java Web Services client and Instructions for developing a VB.Net client The ABS Website is a secure application and, therefore, requires the use of a Username and Password. For more on setting up a Username and Password, see Section 3.1. 2.2.2 ABS Web Services EPA offers a suite of Web Services that enable ESPs to completely manage building and energy data for their customers and access the EPA Rating and related performance metrics. In our second generation of this system, we have migrated to a new set of Services that provide a richer and more robust set of features for ESPs (Table 2-1). Access to each schema, a Sample XML document, and WSDL is provided directly through the ABS Website. Table 2-1 Web Service Get Pending Authorizations Description Used to get information about ESP customers that have requested you to provide automated benchmarking through Portfolio Manager. Note: this service is only required when mapping data from the ESP System to a customer who already has data in Portfolio Manager. It is not required if the ESP is submitting buildings for a customer that did not already have a Portfolio Manager account. When to Use  To identify customers who have requested that an ESP map to and manage their existing Portfolio Manager account, building, and/or meter  To identify and verify an ESP customer before performing any data mapping Type Synchronous Schemas PendingAuthResponse.xsd 4 ABS User’s Guide Web Service Confirm Pending Authorizations Description Used by the ESP to send back an approval or denial of any authorization request received through the Get Pending Authorizations service along with all appropriate IDs from the ESP System that are needed to initially map that system to Portfolio Manager. Note: similar to Get Pending Authorizations, this service is only required to be used when mapping data from the ESP System to a customer who already has data in Portfolio Manager. It is not required if the ESP is submitting buildings for a customer that did not already have a Portfolio Manager account. Used to upload, modify, and remove general building information for an ESP customer. When to Use  To map account, building and/or meter IDs from the ESP System to a customer‘s existing Portfolio Manager account  To reject authorization requests to map to account, buildings, and/or meters and communicate those issues to the customer through Portfolio Manager Type Synchronous Schemas ConfirmAuthRequest.xsd ConfirmAuthResponse.xsd Manage Building Information  To manage all general building information (e.g., facility name, address) and space types and their attribute values (e.g., gross floor area, number of occupants)  To set up a meter in Portfolio Manager (e.g., meter name, fuel type) Asynchronous ManageBuildingsRequest.xsd ManageBuildingsResponse.xsd 5 ABS User’s Guide Web Service Manage Meter Information Description Used to upload, replace, and remove meter and energy consumption information for an ESP customer. Used to get all general building and space usage information for any ESP customer‘s building in Portfolio Manager. When to Use  To manage all meter or energy consumption information  To update or fill data gaps within an ESP‘s system for any customer‘s building  To get a list of all customers and buildings for which an ESP is currently providing automated benchmarking services  To update or fill data gaps within an ESP‘s system for any customer‘s building  To remove any existing mappings to a customer‘s buildings  To retrieve ratings and other metrics for 12-month periods not provided by the management services Type Asynchronous Schemas ManageMetersRequest.xsd ManageMetersResponse.xsd Get Building Details Asynchronous DetailRequest.xsd BuildingDetailResponse.xsd Get Meter Details Used to get all authorized meter and energy consumption data for any ESP customer‘s building in Portfolio Manager. Used to formally end the automated benchmarking process for any customer‘s buildings. Used to retrieve ratings and other metrics from different 12-month periods Asynchronous DetailRequest.xsd MeterDetailResponse.xsd End Automated Benchmarking Synchronous DeauthRequest.xsd DeauthResponse.xsd Rating Exchange Service (RES) Asynchronous RESRequest.xsd RESResponse.xsd 2.3 Portfolio Manager Portfolio Manager, which hosts the EPA national energy performance rating system, is EPA‘s premier web-based solution for managing and tracking the energy consumption and environmental footprint of buildings.. For a growing list of facility types, energy performance can 6 ABS User’s Guide be rated against a peer group of facilities, with adjustments for climate, facility size, hours of operation, and number of occupants. Portfolio Manager provides a big picture of how much energy is being used and by which facilities, how energy performance compares to similar facilities, and progress reports for established energy reduction goals. Centralized and decentralized organizations benefit equally from the ability to share facility specific energy information in a secure environment. ESPs are encouraged to create a Portfolio Manager account and input sample facilities to see an example of how Portfolio Manager captures data and presents the energy performance rating. This exercise could provide ideas for the ESP‘s system design. Portfolio manager users can centrally view all facilities and all energy data, which otherwise is maintained at a local level. Users may also group facilities together to track their progress separately and customize their own views allowing them to see the information they value most. Portfolio Manager also contains the processes for applying to earn the ENERGY STAR or ENERGY STAR Leaders. Applications for recognition remain solely a function of Portfolio Manager. ABS customers must login to their Portfolio Manager account to submit and track applications for recognition. NOTE: If an ESP customer already has a Portfolio Manager account, the ESP will need to work with the customer to map to the customer’s existing Portfolio Manager account (more on this in Section 7.0). If the customer does not have a Portfolio Manager account, all building and energy data provided by an ESP will be stored in a new Portfolio Manager account. The ESP can provide information on this newly created account to the customer if they choose (more on this in Section 6.1.1). 2.4 Energy Service Provider System ABS is designed to facilitate electronic data exchange, through XML-based Web Services, between EPA‘s Portfolio Manager and any ESP System. By ESP System, we are referring to any application that you are using, from within your own information technology (IT) enterprise, to conduct electronic data exchange with EPA through ABS. It is expected that your ESP System will be able to exchange building, space usage, and/or energy consumption data for commercial buildings. To automate this data exchange with EPA, it is recommended that you implement a Web Services client within your ESP System. 2.5 Minimum Requirements for Using ABS The following represent the minimum technical requirements for using ABS and implementing a secure data exchange with EPA:  ESP System (see Section 2.4 for definition) 7 ABS User’s Guide  Web Services client – refers to an application that runs from within your IT enterprise that can communicate using XML messages that follow a SOAP standard (currently version SOAP 1.1). Additional information and support for developing a Web Services client can be found in Section 3.3. Building data – to input any data into Portfolio Manager through ABS, an ESP System should be able to provide, at a minimum, building type, building address, and energy consumption data. Other types of data that can be provided include year built and space usage information (e.g., gross floor area, number of occupants). The space usage information varies based on the building type chosen and is optional. If you do not include space usage information, then default values will be provided based on national averages for buildings of a similar size. An ABS username and password (see Section 3.1 for guidance on how to get a username and password) Well-formed XML documents – all XML documents that are submitted through the ABS Web Services must conform to their representative schemas. Internet Browser – the browser is only required to access the ABS Website. Ability to Store an ABS Transaction ID – to support asynchronous services, ABS will provide ESPs with a transaction ID upon successful submission of a Web Services request. That same transaction ID will be required to be sent by the ESP in order to retrieve the matching response from our system. Unique Identifiers for each individual Customer (espCustID), Building (espBldgID), Space (espSpaceID), and Meter (espMeterID) – ABS requires that an ESP provide a unique identifier for each of the main data elements that Portfolio Manager supports. These IDs will ensure that we are able to consistently map your transactions to the right customers and buildings. If you do not already have these IDs, you can use our internal IDs for this purpose. Each is identified with a prefix of ―pm‖ (e.g., pmCustID, pmBldgID). If you choose to use our IDs, you will need to store them in your ESP System for future Web Services transactions. Please note that espCustID, espBldgID, and espMeterID are required for all ESPs. espSpaceID is only required for those ESPs that are providing Space information for their customers. To access our internal Portfolio Manager IDs, you must be mapped to an existing Portfolio Manager account and/or building (see Section 7.0 for more details on mapping). Once mapped, you can access them using the Get Building Details Web Service. If you are in the process of mapping, and need them to complete the mapping process, they are available through the Get Pending Authorizations Web Service. EPA Approval (to use ABS Web Services in the LIVE environment) – ABS Web Services are available for any ESP to use in our TEST environment. To obtain access 8        ABS User’s Guide for these Web Services in the LIVE environment, you will need to register with EPA (see Section 5.0 for details on registering to use the LIVE ABS environment). 3.0 Getting Started ABS makes it easy to get started by offering ESPs the ability to self-register for an ABS account; technical documentation to get familiar with EPA‘s ABS Web Services and Portfolio Manager; and guidance on setting up your own Web Services client. 3.1 Setting up an ABS Account Any ESP can set up an ABS Account by going to the ABS Website login page and selecting ―Create a New ABS Account‖. To complete registration, you will need to provide the following information:  Username and Password – this username and password will not only be used to access the ABS Website but will also be used for authenticating any Web Services transactions that are requested from your Web Services client. Contact Information – information about the ABS Account owner. All system notifications will be delivered to this individual. Organization Name – the name of the company for which the account is being set up. ENERGY STAR Partner – indicate whether you are an ENERGY STAR partner. You do not need to be a partner to create an ABS account. However, if you are an ESP who will be providing this service to external customers, you will be required to sign an ENERGY STAR partnership agreement before you can perform any LIVE transactions. If you have submitted an application for partnership but have not received confirmation of your status as a partner, please contact us at buildings@energystar.gov. We will process your application quickly.    3.1.1 System Notifications To ensure that ABS users are made aware of changes to the system or events or issues regarding their account or transactions, EPA provides a set of email notifications that will be delivered to ABS Account contacts and any individuals that they set up to also receive these messages (see Section 5.2 for details on how to set up additional contacts). These notifications are sent regarding the following events:  Completion of Setting up an ABS Account (see Section 3.1 for more on this process). You will receive two emails. One will welcome you as user to our system. The second will send confirmation of your username and password. Completion of EPA Review of your Registration to use ABS Services in the LIVE environment (see Section 5.0 for more on this process). After EPA has reviewed your 9  ABS User’s Guide request, we will send you a notification as to whether your request was approved or rejected.  Account De-authorization (see Section 8.0 for more on this process). If one of your customers de-authorizes you from providing automated benchmarking services for their Portfolio Manager account, you will receive an email notification. Upcoming ABS Releases. EPA will release changes to the ABS Website and Web Services a few times a year. We will send out a notification in advance of those changes to notify you of what‘s changing, when it will occur, and how it may impact you.  3.2 Read Technical Documentation Before registering for ABS or, at a minimum, submitting data to EPA through ABS, it is highly recommended that you read through the Technical documentation provided regarding both Portfolio Manager and ABS. These documents may help you to determine the best system design for implementing these Web Services. Recommended Technical documents, besides this User‘s Guide, include:  Portfolio Manager Overview – a set of web pages that provide an overview of what Portfolio Manager does and describes what types of spaces are supported and the data requirements for each. ABS Schemas and Sample XML documents – the set of XML Schemas that provide a detailed description of what types of data are required to use all of EPA‘s ABS Web Services.  If you would like to talk with one of our technical engineers about your proposed design before implementing it, please contact us at buildings@energystar.gov 3.3 Set up a Web Services Client As noted in Section 2.5, we recommend that you build your own Web Services client to send and receive XML documents through our ABS Web Services. Our Web Services can be invoked by any of the following Web Service clients/proxies:     Dynamic Proxy Static Proxy Dynamic Invocation Interface (DII) Application Client 10 ABS User’s Guide For those ESPs choosing to build an application client, we have provided a Java/J2EE client that will work on a Windows operating system (see Appendix 12.3 for more details). Additionally, we provide instructions and sample code for building a VB.Net Web Services client. You can access this sample code and/or guidance from the ABS Website Home Page by selecting ―Sample Clients for ABS Web Services.‖ 3.3.1 ABS Website Web Services Client EPA has also provided a web-based Web Services client that can be used right from the ABS Website Home Page. It requires no downloading or installation and can be used to submit data to both the ABS TEST environment (discussed more in Section 4.0) and your customers‘ LIVE accounts. Please note that the web-based Web Services client is a stand-alone application, hosted on EPA‘s servers, and cannot be integrated into your ESP System. It is primarily designed to help new ESPs when they are first using ABS to test the Web Services and their XML documents. The tool will allow an ESP to upload their XML document and invoke any of the ABS Web Services. This process is manual and has a current file size restriction set to 10MB. This means that the client cannot accept any XML document that is greater than 10MB in file size. 3.4 Sending Web Services Requests to ABS To interface with ABS, the ESP must be able to send and receive Simple Object Access Protocol (SOAP)/Extensible Markup Language (XML) formatted messages. ESP developers should refer to our suite of XML Schemas for specifications on our data library, definitions, and formats, and refer to our published WSDLs for access methods and protocols necessary for your Web Services clients to make a request to ABS. All of these reference documents can be accessed from the ABS Website Home Page. Once you have deployed your own Web Services client, you will be able to submit XML documents directly from your system to Portfolio Manager. All Web Services invocations are conducted over a Secure Sockets Layer (SSL). Each TEST and LIVE transaction requires you to provide your ABS username and password to authenticate and the location of the correct WSDL. For additional information on setting the username and password in an SSL invocation from your ESP Web Service client/proxy, refer to Appendix 12.2. We have provided one WSDL to be used for all TEST transactions and a separate one for all LIVE transactions. These WSDLs can be found at the following locations: TEST WSDLs for ABS Web Services: String Version: http://estar8.energystar.gov/ESES/ABS20/WSDL/ABS20_String_test.wsdl Attachment Version: http://estar8.energystar.gov/ESES/ABS20/WSDL/ABS20_Attachment_test.wsdl 11 ABS User’s Guide LIVE WSDLs for ABS Web Services: String Version: http://estar8.energystar.gov/ESES/ABS20/WSDL/ABS20_String.wsdl Attachment Version: http://estar8.energystar.gov/ESES/ABS20/WSDL/ABS20_Attachment.wsdl ABS offers a suite of synchronous and asynchronous Web Services. For our asynchronous Services, it will be necessary for the ESP to implement some sort of polling solution to retrieve response data. Table 3-1 lists the basic steps that an ESP, who is developing their own Web Services client, can use to interface with ABS when sending a request. Table 3-1 Step 1. Process Open an HTTPS connection using the connection address for the service to be invoked. Create a SOAP/XML Request message for the service. Send the SOAP/XML Request message to the service via the open connection. Receive the SOAP/XML Response via the connection. Parse the SOAP/XML Response to retrieve data. Identify and handle response codes and error conditions (refer to Section 3.5.1 for more details) 2. 3. 4. 5. 6. Once your Web Services client application is able to call an ABS Web Service, our Web Service will authenticate your user credentials (username and password). Username and password should part of the soap message. If the credentials are not supplied, or the ESP Username and Password combination is not valid, our Web service will return a 401 HTTP error code, and the request will be denied. When sending any request to ABS, the following elements must be provided for each transaction: 12 ABS User’s Guide Table 3-2 Element ESPUsername Description Uniquely identifies the ESP submitting the SOAP/XML request (also referred to as ABS Account Username) Password associated with the ESPUsername (also referred to as ABS Account Password) The XML file that matches the Web Services request OR the Transaction ID for the request if checking on the status of that request. Data Type String 64 characters (max) ESPPassword String 64 characters (max) XML File OR Transaction ID text/XML 3.4.1 Transaction ID Once a successful Web Services transaction has occurred, a Request will be sent in a standard SOAP/XML formatted message containing the Transaction ID (TXNS_ID) that the ESP System must use to retrieve the response data for any asynchronous request submission. It is, therefore, important that the ESP System store the Transaction ID which is passed as an Integer (38 digits). Please note that all synchronous Web Services transactions do not require the use of a Transaction ID since a complete response is delivered while the ESP System is still connected. However, a Transaction ID will still be assigned to that transaction and can be viewed through the ABS Website. 3.4.2 Response Time for ABS Asynchronous Web Services Requests Our system will deliver a response to all ABS asynchronous Web Services transactions within 24 hours of receipt. Requests may be fulfilled in a shorter timeframe than that depending on their place in our queue and general level of activity on the system. RECOMMENDATION: We recommend that Web Services requests be submitted by ESPs during non-business hours (between 9pm and 6am EST) if possible to better ensure faster response times from our system. 3.5 Retrieving Responses from ABS (Asynchronous services only) Retrieving a response through an asynchronous Web Service from ABS follows the same requirements as sending a request (Section 3.3). The fundamental difference is that retrieving a response also requires the submission of the Transaction ID (TXNS_ID) (Section 3.4.1). Table 13 ABS User’s Guide 3-3 lists the basic steps that an ESP, who is developing their own Web Services client, can use to interface with ABS when retrieving a response. Table 3-3 Step 1. Process Using the SOAP Client Proxy, create a SOAP/XML Request message for the Service with the appropriate credentials. Send the SOAP/XML Request message to the service via the open connection. Receive the SOAP/XML Response via the connection. Parse the SOAP/XML Response to retrieve data. Identify and handle response codes and error conditions (refer to Section 3.5.1 for more details) The Request Response will contain a Transaction ID rather than the actual requested data (asynchronous services only). Repeat Steps 2 - 6 to send a Response Request message with the Transaction ID returned from the first response (the Request Response). The second response (the Response Message), if successful, will contain the requested data embedded in the SOAP message. 2. 3. 4. 5. 6. The Web Service invoked will send a Response Message with the response data embedded inside the SOAP message, provided no system error occurred. If an error did occur, or the transaction has not been completed, the ESP Web Services client will need to parse the SOAP message for information on the returned status and/or error codes. The response message will match the ServiceStatusResponse.xsd schema that is available on the ABS Website. 3.5.1 Handling Web Services Errors If ABS encountered any Web Services errors (listed in Section 9.4), a Response Message that corresponds to the Services Status schema is returned. In most instances, the return codes indicate what action the client application should take. For example, after submitting a Rating Exchange System (RES) request for response, a System Return Code of 12020 indicates that the data is not yet ready for pickup and the ESP Web Services client application should poll again at a later time. 3.6 Integration ABS provides enough flexibility to allow various ESPs to use the service to manage data without locking the ESP into a specific integration approach. In order to help you determine the 14 ABS User’s Guide approach that is appropriate for your organization, this section provides some common highlevel integration plans and a few implementation tips to help you get the most out of ABS. 3.6.1 Determining an Integration Approach There are various ways to use ABS to get the ENERGY STAR rating and other energy use metrics into your system. The following approaches are among the most common used for ABS integration. You are not limited to these approaches when integrating with ABS, but these examples should help you to formulate your own integration plan.  End-to-End Data Management: ESPs can use ABS to add and update all facility and meter data to receive the ENERGY STAR rating and other energy use metrics into your system. This approach makes little to no use of the authorization and mapping services, and focuses on using the data management services to provide facility and meter data to ABS. This approach is best suited for ESPs that already collect and manage facility and meter data for their customers. Energy Data Management: ESPs can use ABS to add and update energy consumption data for their customers without managing the building and space data. This approach makes more extensive use of our authorization and mapping services and relies on customers providing building and space data that may not be managed by the ESP. Utilities and other ESPs that do not have access to customer building and space data should consider this approach. Working with other ESPs: Multiple ESPs can work together to provide data to ABS in order to retrieve rating data for their customers. Utilities and utility ESPs can work in conjunction to provide building/space data and meter data separately in order to get accurate metrics using the unified data. Multiple ESPs are allowed to manage user accounts and buildings through ABS (only a single ESP can manage any meter). For example, a utility ESP can work with a customer‘s electric and natural gas providers to have energy consumption data provided by those companies directly so they can retrieve metrics from ABS for their customers.   3.6.2 Structuring Data for the Web Services Depending on how data in your system is structured, the data you provide to ABS will need to be manipulated to match the format of our data structure. When submitting data to ABS, the following structural concerns should be taken into consideration:  Splitting vs Combining Transactions: ABS allows you to submit data for multiple customers, multiple buildings, and multiple meters all within a single transaction. Depending on the volume of data you need to submit to ABS and your business needs, you will need to consider whether to submit data for all of your customers to ABS in a single transaction, submit an individual service request for each customer or building, or 15 ABS User’s Guide otherwise organize your data for submission for ABS. Larger single transactions may put higher load on your system in order to create the larger XML requests and parse the larger XML responses, and will take longer for ABS to process. Multiple smaller requests may be easier to manage and may be the only option for certain architectures, but those requests may be queued for longer periods as ABS attempts to manage request load.  Updating Data: While ABS provides the ability to edit existing data in Portfolio Manager, some ESP systems are not configured to track what data has been submitted to Portfolio Manager. In previous iterations of ABS, users would delete and resubmit entire buildings or meters in order to update the data to get around this system limitation. This technique was primarily used to update energy consumption data for meters. In order to support the updating of meter data without the need to delete and reinsert entire meters, ABS now provides the ability for ESPs to replace energy consumption data for entire meters or for specific date ranges. The sections on Submitting New Energy Consumption Data and Updating or Replacing Energy Consumption Data provide more details on this topic. 3.6.3 Setting Up Meter Data In order to receive an ENERGY STAR rating for a facility Portfolio Manager requires 12 months of consecutive, non-overlapping energy consumption data for each individual meter of every energy source. However, there can be a potential issue if a new meter is added or an existing meter is assigned a new meter ID (making it appear as a new meter in an ESP‘s system). Portfolio Manager will not give that building a rating until 12 months of data are submitted for the new (or renamed) meter. To overcome this issue, there are two approaches to submit meter data to ABS that meet the data requirements for obtaining ratings.  Solution #1 – Virtual Metering: The first approach, called ―virtual metering,‖ allows ESPs to combine all meters of the same fuel type (i.e. all electricity meters) into a single meter for submission to ABS. A virtual meter could be created to aggregate all electricity meters so it appears as if there is one electricity meter for the building. Using a virtual meter protects against the possibility of Portfolio Manager not returning a rating due to the addition of a new meter, a gap or overlap in dates. This approach can be used when a customer wants to focus on the total consumption for each energy type, rather than looking at multiple individual meters in the building. However, some customers may prefer to view the detailed meter data. 16 ABS User’s Guide  Solution #2 – Individual metering: The second approach entails sending all individual meter data, but with data checks built into the ESP‘s system, to make sure there are 12 months of consecutive, non-overlapping data for each meter. Data checks could include marking meters as ―inactive‖ if they have been removed or replaced. This can be done by setting the ―meterActiveIndicator‖ in the schema to ―N‖ for ―no‖ which tells Portfolio Manager that the ESP has intentionally stopped submitting data for the meter. Similarly, when a new meter is added to an existing facility, the ESP must backfill the previous months with zero values for energy consumption until the meter has 12 months of data. Incorporating these checks into the ESP‘s system will ensure that incomplete meter data errors preventing a building from receiving a rating are minimized, maintaining the granularity of actual meter data without additional programming. 4.0 Testing Your System ABS provides a TEST environment to allow ESPs to try out the ABS Web Services before they connect to their customers‘ accounts for LIVE data exchanges. In this section, we will describe the ABS TEST environment and how to access it and discuss EPA Beta releases and how they impact ESPs and their ABS Accounts. 4.1 About the ABS TEST Environment The ABS TEST environment represents a separate database that ESPs can use to test their XML documents and Web Services transactions without affecting their customers‘ LIVE accounts. The TEST environment can be accessed either through the ABS Website or through a Web Services call from an ESP Web Services client. Please note that an ESP will only have access to the ABS TEST environment until they have been formally approved by EPA to submit to the LIVE environment (see Section 5.0 for more on registering to use the LIVE environment). 4.1.1 Test Copies of your Customers’ LIVE data For each of your customers‘ buildings for which you are authorized to provide LIVE data (see Section 7.0 for more details on customer authorization of data), a copy of that data will be placed into the TEST environment and made accessible to you. In this TEST environment, you can safely perform any tests you require without affecting their LIVE account. The ABS Website will also allow you to refresh that data from the LIVE environment whenever you want. Please note that refreshes occur at the Customer level. This means that performing a refresh of building data for any customer will result in all TEST copies of buildings that you are mapped to, for that customer, being overwritten with the latest data available in the LIVE environment. This refresh can be done as often as needed. However, during a Beta Release period, this capability will be deactivated (see Section 4.3 for more details). 17 ABS User’s Guide 4.2 Accessing the TEST Environment from the ABS Website When you log into the ABS Website, you will have access to view and submit data to both TEST and LIVE environments. Indicators have been provided to help you know which environment you are currently viewing as you navigate through the ABS Website. When you use our web-based Web Services client, you will have the ability to submit data to either the TEST environment or your customers‘ LIVE accounts. Please note to make sure you are in the appropriate environment before uploading your XML document. 4.3 Beta Releases When newer versions of ABS Web Services are being prepared for release, EPA will release them as Beta versions one month prior to going live with them. These Beta versions will only be available for use in the TEST environment. Please note that during the month of the Beta release an ESP will not be able to refresh their TEST environment with any data from their customers‘ LIVE accounts (see Section 4.1.1 for more information about refreshing TEST data). This is to prevent errors from occurring with possible incompatible formats in the LIVE environment versus the TEST environment. Please note that when we release our Beta version, we will refresh the entire TEST environment which will overwrite all TEST copies of your customer‘s buildings with the most current data from the LIVE environment. Any buildings you have created directly in the TEST environment will also be deleted. 5.0 Registering to use ABS Web Services in the LIVE Environment To ensure the security and integrity of Portfolio Manager and the Automated Benchmarking System (ABS), we require ESPs that wish to submit data to Portfolio Manager in the LIVE environment to first be approved by EPA (Figure 5-1). This process is performed online through the ABS Website. After you have properly tested your system, and are prepared to move forward with connecting to the LIVE environment, follow the registration process detailed in this section. Please note that some ESPs may not be able to create an entire Test building record using ABS. To effectively test your ESP System, you may need to register to use the LIVE environment during your Test phase in order to get Test copies of your customer‘s buildings with which to properly test your ESP System. Figure 5-1: Select “Register Now” to register to use ABS Web Services in the LIVE environment 5.1 What does it mean to be Registered to use the LIVE Environment? Being approved by EPA allows you to use your ABS account username and password to invoke our Web Services in the LIVE environment. It also lists your company‘s name in Portfolio Manager as an automated benchmarking service provider. 18 ABS User’s Guide This is particularly important for those ESPs that need to map to their customers‘ existing Portfolio Manager building data (see Section 5.2.1 for more information on mapping). 5.2 How to Register to use the LIVE Environment To access the Registration form, select ―Register Now‖ from the ABS Website Home Page. You will be asked to provide a set of information that will help us plan for your usage of the system and help us to configure your account for interaction with your customers who use Portfolio Manager. To complete this registration process, here is the information that you will need to be able to provide:  Your Organization Name as you would like it displayed to your customers in Portfolio Manager. RECOMMENDATION: choose a naming convention that your customers will easily recognize, particularly if you plan to have them use the data release authorization interface to help you map to their Portfolio Manager data (see Section 7.0 for more details). Contact information for this request for approval in case we need to come back to you with any questions. Additional Contacts for your organization that should also be recipients of any ABS notifications. Service Contact information that can be displayed in Portfolio Manager to enable any one of your customers to contact you should they have a question or issue with your automated benchmarking services. ABS allows you to set the Service Contact as an individual, a company email address, and/or a link to your Website. Planned usage of ABS to help us capacity plan for the future. We encourage you to be as accurate as you can be and recognize that this will just be your best estimate. Service Customization requirements that help us configure your account and those of your customers using Portfolio Manager to allow you to more easily map to their existing Portfolio Manager account and/or building data. Please note that this information is required from you only if you plan to map to any one or more of your customers‘ existing Portfolio Manager accounts. If your customers are not currently using Portfolio Manager, then you will be able to bypass these screens.      Setting up Automated Data Mapping between Your System and Your Customers’ Existing Portfolio Manager Accounts ABS makes it possible for you to automatically map data from your system to your customers‘ existing data in Portfolio Manager through the new Data Release Authorization and Mapping feature. This feature can be accessed through the Registration forms for accessing the LIVE 5.2.1 19 ABS User’s Guide environment or from the ABS Website Home Page (after you have been approved to use the LIVE environment). Your customers who already have existing Portfolio Manager accounts can use this feature to formally authorize the release of their data to you through Portfolio Manager (see Figure 5-2 for a diagram that depicts how this process works). You can then receive all customer data release requests and fully map your system to your customers‘ Portfolio Manager data through the Get Pending Authorizations and Confirm Pending Authorizations Web Services (see Section 7.0 for more information on how to map using these Web Services). STEP STEP 1 5 ESP System ESP (using ABS website) ESP uses ABS website to tell the Portfolio Manager system what data they need from their customers (e.g., billing account number, meter number) to verify the customer and map their own system to that customer‘s Portfolio Manager data. ESP sends an authorization approval or denial by invoking the new Confirm Pending Authorizations web service. For an approved request, ESP must also send all IDs needed to fully map from their system to Portfolio Manager. Confirm Pending Authorizations web service STEP 4 ESP or ESP System Portfolio Manager Database STEP 2 Get Pending Authorizations web service ESP or ESP system verifies information received and determines whether to approve or deny the request. ESP Customer (using Portfolio Manager) ESP customer uses Portfolio Manager to submit an Authorization Request to the ESP to perform automated benchmarking for their account. ESP customer is asked by Portfolio Manager to provide data elements that the ESP set up through the ABS website in Step 1. STEP 3 ESP System ESP system ―listens‖ for any new customer Authorization Requests by invoking the new Get Pending Authorizations web service. Figure 5-2: Data Release Authorization and Mapping process As depicted in Steps 1 and 2, this process is customizable so that you have the option to ask your customers to submit specific data, such as a billing account number or meter number, that you need to be able to map to their data. Please note that performing any kind of mapping between your system and your customers‘ existing Portfolio Manager account and/or data requires you and your customer to follow this type of process. The level of automation you want to apply to this process is up to you but these basic steps will need to be performed. EPA will no longer be providing any manual mapping services through our technical support group. Your settings for this data release authorization and mapping process will be presented to your customers to allow you to map to their existing Portfolio Manager data. Please note that you 20 ABS User’s Guide can go in and change these settings at any time and without EPA approval. Any saved changes will affect only new customer requests for data mapping. Already mapped buildings will be unaffected. 6.0 Managing Customer Data through ABS Web Services ABS provides ESPs with the ability to add, update, and delete building, space, and energy information for any building for which they have access in Portfolio Manager. We have deployed four primary services to perform these actions (Table 6-1). Each of these services is asynchronous and, therefore, includes both a Request and a Response schema. Table 6-1 Web Service Manage Building Information Service Description Use this Service to upload, modify, and remove general building information for any of your customers. Please note that this service cannot be used to add, modify, or remove energy consumption data. However, it can be used to add, modify, or remove a meter. Use this Service to upload, replace, and remove meter and energy consumption information for any of your customers. Use this Service to get all general building and space usage information for any of your customer‘s buildings in Portfolio Manager. Use this Service to get all authorized meter and energy consumption data for any your customer‘s buildings in Portfolio Manager. XML Schemas ManageBuildingsRequest.xsd ManageBuildingsResponse.xsd Manage Meter Information ManageMetersRequest.xsd ManageMetersResponse.xsd Get Building Details DetailRequest.xsd BuildingDetailResponse.xsd Get Meter Details DetailRequest.xsd MeterDetailResponse.xsd 21 ABS User’s Guide In the following sections, we will provide more details on how to use each of these Web Services to perform the data management functions they support. 6.1 Submitting a New Building Adding a new building to Portfolio Manager requires the use of the Manage Building Information Web Service. A building can be added to either an existing customer Portfolio Manager account (Scenario 1 below) or to a brand new account (Scenario 2 below) that EPA will automatically set up as part of the transaction (see Section 6.1.1 for more details about EPA Portfolio Manager account setup). To submit a new building, follow the general instructions for submitting a Request outlined in Section 3.4 along with any one or more of the following specific scenarios using the Manage Building Information Web Service (refer to the Manage Building Information schema on the ABS Website for element definitions): SCENARIO 1: Submit a New Building into a Customer’s Existing Account 1. Make sure that you are correctly mapped to that customer‘s existing Portfolio Manager account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have already mapped to this customer‘s Portfolio Manager account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is New or Existing. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. espBuildingID [required] – provide us with the unique identifier that you would like us to store for this building in our system. This will be the ID that you will then use for any future Web Services requests regarding this building. d. bldgNewExisting [required] – set this to ‗New‘ to inform our system that this building is new to this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new Building if it can‘t find a matching espBuildingID in Portfolio Manager. e. Other Building information (includes the elements bldgName, bldgAddress, bldgCity, bldgState, bldgZipCode, bldgYearBuilt) [all elements required except for bldgYearBuilt] – these are building level details about the building. 22 ABS User’s Guide f. espSpaceID [required if providing Space information for the building] – provide us with the unique identifier that you would like us to store for each individual Space type (e.g., Office, Computer Data Center) that makes up this building‘s total gross floor area. More about our Space types. This will be the ID that you will then use for any future Web Services requests regarding this Space. g. spaceNewExisting [required] – set this to ‗New‘ to inform our system that this Space is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Space. Please note that if you set this element to ‗Unknown‘, ABS will add a new Space if it can‘t find a matching espSpaceID in Portfolio Manager. h. Other Space Information (includes elements like spaceName, spaceType, space Attributes are specific to the types) – refer to the ManageBuildingsRequest.xsd schema to see which elements are required and the full list of Space Types and Attributes available. For any Space that you provide data for, only include the elements for which your ESP System is able to provide actual values. For those elements not included, ABS will automatically assign a default value. Please note that gross floor area is required for nearly all Spaces and no default value can be set. i. espMeterID [required if providing Meter information for the building] – provide us with the unique identifier that you would like us to store for each individual meter that you add for this customer‘s building. This will be the ID that you will then use for any future Web Services requests regarding this meter. meterNewExisting [required] – set this to ‗New‘ to inform our system that this Meter is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this to element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. j. k. Other Meter Information (includes the elements meterName, meterEnergyType, meterEnergyUnit, meterActiveIndicator, meterAddtoTotal) [all elements are required except meterAddtoTotal] – refer to the ManageBuildingsRequest.xsd schema for complete definitions of these elements. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that the corresponding Transaction ID (TXNS_ID) for the request. Responses to 23 ABS User’s Guide asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. SCENARIO 2: Submit a New Building into a New Portfolio Manager Account (see Section 6.1.1 for more details about how ABS sets up Portfolio Manager Accounts) 1. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – provide us with the unique identifier that you would like us to store for this customer in our system. This will be the ID that you will use for any future Web Services requests regarding this customer. See Section 6.1.1 for more information about how EPA automatically creates a new Portfolio Manager account. b. custNewExisting [required] – set this to ‗New‘ to inform our system that this is a new customer to Portfolio Manager. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. custEmailAddress [optional] – if the customer‘s email address is provided when setting up a new Portfolio Manager account, ABS will automatically email registration information to the end user when the account is created. See Section 6.1.1 for more information about your customer‘s registration in Portfolio Manager. d. espBuildingID [required] – provide us with the unique identifier that you would like us to store for this building in our system. This will be the ID that you will then use for any future Web Services requests regarding this building. e. bldgNewExisting [required] – set this to ‗New‘ to inform our system that this building is new to this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new building if it can‘t find a matching espBuildingID in Portfolio Manager. 24 ABS User’s Guide f. Other Building information (includes the elements bldgName, bldgAddress, bldgCity, bldgState, bldgZipCode, bldgYearBuilt) [all elements required except for bldgYearBuilt] – these are building level details about the building. g. espSpaceID [required if providing Space information for the building] – provide us with the unique identifier that you would like us to store for each individual Space type (e.g., Office, Computer Data Center) that makes up this building‘s total gross floor area. More about our Space types. This will be the ID that you will then use for any future Web Services requests regarding this Space. h. spaceNewExisting [required] – set this to ‗New‘ to inform our system that this Space is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Space. Please note that if you set this element to ‗Unknown‘, ABS will add a new Space if it can‘t find a matching espSpaceID in Portfolio Manager. i. Other Space Information (includes elements like spaceName, spaceType, space Attributes are specific to the types) – refer to the ManageBuildingsRequest.xsd schema to see which elements are required and the full list of Space Types and Attributes available. Please note that if you define a Space but are unable to provide specific values for all Attributes, Portfolio Manager will automatically set those attributes to a default value. You can set those attributes that are unknown to a NULL value. espMeterID [required if providing Meter information for the building] – provide us with the unique identifier that you would like us to store for each individual meter that you add for this customer‘s building. This will be the ID that you will then use for any future Web Services requests regarding this meter. j. k. meterNewExisting [required] – set this to ‗New‘ to inform our system that this Meter is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. l. Other Meter Information (includes the elements meterName, meterEnergyType, meterEnergyUnit, meterActiveIndicator, meterAddtoTotal) [all elements are required except meterAddtoTotal] – refer to the ManageBuildingsRequest.xsd schema for complete definitions of these elements. 2. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 3. Store the Transaction ID (TXNS_ID) in your ESP System. 25 ABS User’s Guide 4. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.1.1 Setting up an Account for New Buildings with No Existing Portfolio Manager Account Every building that resides in Portfolio Manager must be connected to a Portfolio Manager account. When an ESP submits a building for a customer that does not already have a Portfolio Manager account set up, ABS automatically assigns a Portfolio Manager account name for that ESP customer. All future buildings sent for that same ESP customer will also be stored within that account. For each new Portfolio Manager account that is set up, the ESP will be provided with a set of information that they can pass along to their customer should that customer want to view these buildings in Portfolio Manager. If the ESP provides a customer email address when creating the customer‘s account, this registration information will automatically be emailed to the customer. That information includes:    Energy Service Provider Number – this number is created automatically when you register for ABS. It is different than your username and is only used for this purpose. ESP Customer ID (espCustID) – this unique identifier is used by you to identify this customer when submitting Web Services transactions to ABS. Portfolio Manager Username (pmCustID) – this username is created automatically the first time you submit a building for this customer. This is the username that they will be required to use each time they log into Portfolio Manager. URL for Completing Portfolio Manager Registration – to complete the account registration process, your customer must go to a special page where they will input the items listed above. After that, they will be asked to specify a password and complete the remainder of the Portfolio Manager account registration form. The URL to this site is: https://www.energystar.gov/istar/pmpam/index.cfm?fuseaction=userreg.showEUOConfir m  To access all of this information about each of your ESP customers that you have automatically set up a new Portfolio Manager account for, select ―Customer List‖ from the ABS Website Home Page. In the table on the following page, that information will be listed. Please note that you can use the ―Registered in Portfolio Manager?‖ column in the Customer List table to determine whether that customer already has registered the account. 26 ABS User’s Guide 6.2 Deleting a Building Deleting a Building in Portfolio Manager requires the use of the Manage Building Information Web Service. Deleting a Building requires that the Building already be stored in Portfolio Manager (see Section 6.1 for guidance on submitting a new Building) and mapped to your ESP System (see Section 7.0 for more information on Mapping). To delete a Building, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schema on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. Under the buildingDelete element, set the espBldgID element to the ID of the building that you want to delete 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 27 ABS User’s Guide 6.3 Submitting a New Space Submitting a new Space to Portfolio Manager requires the use of the Manage Building Information Web Service. Submitting a new Space requires that the building already be stored in Portfolio Manager (see Section 6.1 for guidance on submitting a building) and mapped to your ESP System (see Section 7.0 for more information on Mapping). To submit a new Space, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schema on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. d. bldgNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new building if it can‘t find a matching espBuildingID in Portfolio Manager. e. espSpaceID [required if providing Space information for the building] – provide us with the unique identifier that you would like us to store for each individual Space (e.g., Office, Computer Data Center) that makes up this building‘s total gross floor area. More about our Space types. This will be the ID that you will then use for any future Web Services requests regarding this Space. f. spaceNewExisting [required] – set this to ‗New‘ to inform our system that this Space is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Space. 28 ABS User’s Guide Please note that if you set this element to ‗Unknown‘, ABS will add a new Space if it can‘t find a matching espSpaceID in Portfolio Manager. g. Other Space Information (includes elements like spaceName, spaceType, space Attributes are specific to the types) – refer to the ManageBuildingsRequest.xsd schema to see which elements are required and the full list of Space Types and Attributes available. Please note that if you define a Space but are unable to provide specific values for all Attributes, Portfolio Manager will automatically set those attributes to a default value. You can set those attributes that are unknown to a NULL value. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.4 Updating a Space Updating a Space in Portfolio Manager requires the use of the Manage Building Information Web Service. Submitting an update to a Space requires that the Space already be stored in Portfolio Manager (see Section 6.3 for guidance on submitting a new Space) and mapped to your ESP System (see Section 7.0 for more information on Mapping). There are two types of updates that can be made to a Space, a correction and a revision (also referred to as ‗Update‘). A correction simply involves overwriting one Space attribute value with another, including replacing a default value with an actual value. A revision, however, involves adding a new value while keeping the historical value. Revisions are important for understanding a particular space‘s usage over time. More about how to make a correction versus a revision is available in Step 2.g below. To update a Space, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schema on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 29 ABS User’s Guide 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. d. bldgNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new building if it can‘t find a matching espBuildingID in Portfolio Manager. e. espSpaceID [required] – must match an espSpaceID that you have previously provided for this Space within the building. f. spaceNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this Space within the building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Space. Please note that if you set this element to ‗Unknown‘, ABS will add a new Space if it can‘t find a matching espSpaceID in Portfolio Manager. g. correctionUpdateIndicator [required if changing a Space Attribute] – set this to ‗C‘ (for Correction) if you wish to overwrite the current value or replace a default with an actual value. Set this to ‗U‘ (for Update) if you wish to add a new value but keep the historical value intact. Please note that you must also provide an Effective Date (effectiveDate) for that value so that our system knows how long that value has been true for this particular space. For both revisions, or updates, and corrections, this date should reflect the earliest point in time when this value is true. h. Other Space Information (includes elements like spaceName, spaceType, Space Attributes are specific to the types) – refer to the ManageBuildingsRequest.xsd schema to see which elements are required and the full list of Space Types and Attributes available. Space Names can only be 30 ABS User’s Guide corrected. They cannot be revised. All Space Attributes can be corrected or revised. Provide the new value for any that you wish to change. For all others, you can leave the value as NULL to avoid making any changes to them. Please note that a Space Type cannot be changed. If you need to modify the Space Type, you will need to add a new Space (see Section 6.1) of the new type and delete this existing Space (see Section 6.4). 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.5 Deleting a Space Deleting a Space in Portfolio Manager requires the use of the Manage Building Information Web Service. Deleting a Space requires that the Space already be stored in Portfolio Manager (see Section 6.3 for guidance on submitting a new Space) and mapped to your ESP System (see Section 7.0 for more information on Mapping). To delete a Space, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schema on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS 31 ABS User’s Guide will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. d. bldgNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new building if it can‘t find a matching espBuildingID in Portfolio Manager. e. Under the spaceDelete element, set the espSpaceID element to the ID of the space that you want to delete. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.6 Submitting a New Energy Meter Submitting a new Meter to Portfolio Manager requires the use of the Manage Building Information Web Service or the Manage Meter Information Web Service. Submitting a new Meter requires that the building already be stored in Portfolio Manager (see Section 6.1 for guidance on submitting a building) and mapped to your ESP System (see Section 7.0 for more information on Mapping). Please note that new meters can also be submitted when the building is first being added to Portfolio Manager (see Section 6.1). To submit a new Meter, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information or Manage Meter Information Web Service (refer to the Manage Building Information and Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 32 ABS User’s Guide 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. c. espMeterID [required if providing Meter information for the building] – provide us with the unique identifier that you would like us to store for each individual Meter that you place into Portfolio Manager. This will be the ID that you will then use for any future Web Services requests regarding this Meter. d. meterNewExisting [required] – set this to ‗New‘ to inform our system that this Meter is new to the customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. e. meterName [required] – provide a unique name for this meter. This is the name that your customer will be able to reference this meter by when using Portfolio Manager. f. meterEnergyType [required] – indicate what type of fuel this meter is measuring. g. meterEnergyTypeOther – if the energy type for this meter is ―Other‖, you must specify what type of fuel is being tracked by this meter h. meterGenerationMethod – indicate the generation method for Electricity and District Chilled Water energy types. A generation method must be specified for District Chilled Water meters. For Electricity, if a generation method is not specified, the generation method will default to Grid Purchased. This element should not be provided for energy types other than Electricity and Natural Gas i. meterEnergyUnit [required] – indicate the unit of measure for which consumption data will be provided for this meter. meterActiveIndicator [required] – set this to ‗Y‘ to indicate that this meter is active within the building. j. k. meterAddToTotal – set this ‗Y‘ or NULL if you would like the energy consumption for this meter factored into the rating or overall energy consumption calculations Portfolio Manager provides for this building. Please note that this element should only be set to ‗N‘ if the ESP is accounting for this meter‘s energy 33 ABS User’s Guide consumption in one or more other active meters for this building in Portfolio Manager l. meterSellback – for On-Site Solar and On-Site Wind electric meters, if you are selling energy back to a utility, set this value to ‗Y‘. This element is optional and should not be included unless energy associated with this meter is generated On-Site. If this element is not included for an On-Site meter, ABS will default this value to ‗N‘ m. meterEnviroAttributeOwned – for On-Site Solar and On-Site Wind meters, if the facility owner continues to own the environmental attribute for this meter, set this element to ‗Y‘. If the environmental attribute has been sold, set this element to ‗N‘. This element is optional and should not be included unless energy associated with this meter is generated On-Site. If this element is not included for an On-Site meter, ABS will default this value to ‗Y‘ n. temporaryMeterReading -- identifies whether consumption data provided for this meter is for temporary use. This feature should only be used if the actual meter readings for a specific period of time are unknown, but would still like to be able to estimate their energy performance for that period. To indicate the period for which temporary meter readings are used, specify a start and end date using the temporaryMeterReadingStartDate and temporaryMeterReadingEndDate elements. If you want to always use the earliest meter reading start date then you can specify ―Earliest Date‖ for temporaryMeterReadingStartDate. Similarly, if you want to always use the most current meter reading end date then you can specify ―Present Date‖ for temporaryMeterReadingEndDate. Next adjust the end date to indicate the temporary energy end date or specify ―Present Date‖. To activate this temporary meter reading setting, set the activeIndicator element to ‗Y‘, otherwise set to ‗N‘. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd and ManageMetersResponse.xsd schemas for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 34 ABS User’s Guide 6.7 Updating an Existing Energy Meter Updating a Meter in Portfolio Manager requires the use of the Manage Building Information Web Service or the Manage Meter Information Web Service. Submitting an update to a Meter requires that the Meter already be stored in Portfolio Manager (see Section 6.6 for guidance on submitting a new Meter) and mapped to your ESP System (see Section 7.0 for more information on Mapping). There are four common changes that ESPs make to a customer‘s meter in Portfolio Manager:     Change the Meter Name Replace the existing ESP Meter ID (espMeterID) with a new Meter ID Set the meter to Inactive once it is no longer in use Set the meter to use or not use temporary metering consumption data. Please note that if you need to modify the fuel type unit of measure, it is recommended that you delete this meter (see Section 6.8) and create a new meter in its place (see Section 6.6), particularly if energy consumption has already been provided for this meter. Portfolio Manager does not have the capability to automatically convert values of one energy unit to another energy unit if the ESP changes these units. To update a Meter, for any of these purposes, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information or Manage Meter Information Web Service (refer to the Manage Building Information and Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. c. espMeterID [required] – must match an espMeterID that you have previously provided for this Meter within the building. d. meterNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this Meter within the building. Set this to 35 ABS User’s Guide ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. e. To change the meterName, simply provide a new name for this element and it will automatically overwrite what is there. f. To replace the current espMeterID with a new espMeterID, set espNewMeterID to the new value and it will overwrite the existing value g. To change an active meter to inactive, set the meterActiveIndicator to ‗N‘. Please note that an inactive meter will continue to be visible in your customer‘s Portfolio Manager account and will be accounted for in any energy or carbon calculations only during the time in which it was active. h. To turn off temporary metering, reference the temporaryMeterReading element and set the activeIndicator to ‗N‘. To turn on temporary metering, set the activeIndicator to ‗Y‘ and indicate the period for which temporary meter readings are used by specifying a start and end date using the temporaryMeterReadingStartDate and temporaryMeterReadingEndDate elements. If you want to always use the earliest meter reading start date then you can specify ―Earliest Date‖ for temporaryMeterReadingStartDate. Similarly, if you want to always use the most current meter reading end date then you can specify ―Present Date‖ for temporaryMeterReadingEndDate. Next adjust the end date to indicate the temporary energy end date or specify ―Present Date‖. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd and ManageMetersResponse.xsd schemas for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 36 ABS User’s Guide 6.8 Deleting a Meter Deleting a Meter in Portfolio Manager requires the use of the Manage Building Information Web Service or the Manage Meter Information Web Service. Deleting a Meter requires that the Meter already be stored in Portfolio Manager (see Section 6.6 for guidance on submitting a new Meter) and mapped to your ESP System (see Section 7.0 for more information on Mapping). To delete a Meter, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information or Manage Meter Information Web Service (refer to the Manage Building Information and Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. c. Under the meterDelete element, set the espMeterID element to the ID of the Meter that you want to delete. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd and ManageMetersResponse.xsd schemas for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.9 Submitting New Energy Consumption Data Submitting new energy consumption for a Meter in Portfolio Manager requires the use of the Manage Meter Information Web Service. Submitting new energy consumption for a Meter requires that the Meter already be stored in Portfolio Manager (see Section 6.6 for guidance on 37 ABS User’s Guide submitting a new Meter) and mapped to your ESP System (see Section 7.0 for more information on Mapping). Energy consumption information refers to individual meter readings that consist of a start date, end date, energy consumption value, and cost (optional). To submit new energy consumption for a Meter in Portfolio Manager, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Meter Information Web Service (refer to the Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. c. espMeterID [required] – must match an espMeterID that you have previously provided for this Meter within the building. d. meterNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this Meter within the building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. e. meterReadingSet [required] – set this to ‗New‘ to inform our system that this set of meter readings should be added to Portfolio Manager without affecting any existing meter readings. f. meterReadingStartDate [required] – set this to the Start Date for each individual meter reading. g. meterReadingEndDate [required] – set this to the End Date for each individual meter reading. h. meterReadingConsumption [required] – set this to the particular energy consumption value for the Start Date and End Date identified. i. meterReadingCost [optional] – set this to the US Dollar amount for this particular meter reading. 38 ABS User’s Guide j. meterReadingSellback [optional] – for On-Site Solar and On-Site Wind electric meters, indicate the quantity of energy sold back to utilities if energy from this meter is being sold back to utilities. k. meterReadingSellbackRevenue [optional] – for On-Site Solar and On-Site Wind electric meters, indicate the revenue earned from energy sold back to utilities if energy from this meter is being sold back to utilities. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageMetersResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.10 Updating or Replacing Energy Consumption Data Updating or replacing energy consumption for a Meter in Portfolio Manager requires the use of the Manage Meter Information Web Service. Updating energy consumption for a Meter requires that the Meter already be stored in Portfolio Manager (see Section 6.6 for guidance on submitting a new Meter) and mapped to your ESP System (see Section 7.0 for more information on Mapping). ABS provides the ability for an ESP to replace distinct meter readings over a range of time, defined by a Start Date and End Date, or all meter readings for the Meter. To update energy consumption for a Meter in Portfolio Manager, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Meter Information Web Service (refer to the Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. 39 ABS User’s Guide b. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. c. espMeterID [required] – must match an espMeterID that you have previously provided for this Meter within the building. d. meterNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this Meter within the building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. e. meterReadingSet [required] – set this to ‗ReplaceAll‘ if you want to direct our system to delete all existing meter readings and replace them with what is being provided in your XML document. Set this to ―ReplaceRange‖ if you want to direct our system to delete a specific set of meter entries, defined by a Start Date and End Date, and replace them with what is being provided in your XML document. i. mrsReplaceStartDate – set this to the Start Date of the date range of meter readings you want to delete for this Meter. Please note that this is only relevant for when you set meterReadingSet to ‗ReplaceRange‘. If this Start Date does not match an existing Start Date in Portfolio Manager, ABS will begin its deletion with the meter reading that has a Start Date closest to that date but not before it. ii. mrsReplaceEndDate – set this to the End Date of the date range of meter readings you want to delete for this Meter. Please note that this is only relevant for when you set meterReadingSet to ‗ReplaceRange‘. If this End Date does not match an existing End Date in Portfolio Manager, ABS will complete its deletion with the meter reading that has an End Date closest to that date but not after it. f. meterReadingStartDate [required] – set this to the Start Date for each individual meter reading that replaces what is being deleted. g. meterReadingEndDate [required] – set this to the End Date for each individual meter reading that replaces what is being deleted. h. meterReadingConsumption [required] – set this to the particular energy consumption value for the Start Date and End Date identified. i. meterReadingCost [optional] – set this to the US Dollar amount for this particular meter reading. 40 ABS User’s Guide j. meterReadingSellback [optional] – for On-Site Solar and On-Site Wind electric meters, indicate the quantity of energy sold back to utilities if energy from this meter is being sold back to utilities. k. meterReadingSellbackRevenue [optional] – for On-Site Solar and On-Site Wind electric meters, indicate the revenue earned from energy sold back to utilities if energy from this meter is being sold back to utilities. 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageMetersResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.11 Deleting Energy Consumption Data Deleting energy consumption for a Meter in Portfolio Manager requires the use of the Manage Meter Information Web Service. Deleting energy consumption for a Meter requires that the Meter already be stored in Portfolio Manager (see Section 6.6 for guidance on submitting a new Meter) and mapped to your ESP System (see Section 7.0 for more information on Mapping). ABS provides the ability for an ESP to delete distinct meter readings over a range of time, defined by a Start Date and End Date, or all meter readings for the Meter. This process is very similar to updating energy consumption with the exception that no energy consumption data is being submitted to replace what is being removed. To delete energy consumption for a Meter in Portfolio Manager, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Meter Information Web Service (refer to the Manage Meter Information schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. 41 ABS User’s Guide b. custNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s account. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing customer. Please note that if you set this element to ‗Unknown‘, ABS will add a new Customer account if it can‘t find a matching espCustID in Portfolio Manager. c. espBuildingID [required] – must match an espBuildingID that you have previously provided for this customer‘s building. d. bldgNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this customer‘s building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing building. Please note that if you set this element to ‗Unknown‘, ABS will add a new building if it can‘t find a matching espBuildingID in Portfolio Manager. e. espMeterID [required] – must match an espMeterID that you have previously provided for this Meter within the building. f. meterNewExisting [required] – set this to ‗Existing‘ to inform our system that you have previously provided data for this Meter within the building. Set this to ‗Unknown‘ if your ESP System is unable to tell whether the submission is for a New or Existing Meter. Please note that if you set this element to ‗Unknown‘, ABS will add a new Meter if it can‘t find a matching espMeterID in Portfolio Manager. g. meterReadingSet [required] – set this to ‗ReplaceAll‘ if you want to direct our system to delete all existing meter readings. Set this to ―ReplaceRange‖ if you want to direct our system to delete a set of meter entries defined by a Start Date and End Date. i. mrsReplaceStartDate – set this to the Start Date of the date range of meter readings you want to delete for this Meter. Please note that this is only relevant for when you set meterReadingSet to ‗ReplaceRange‘. If this Start Date does not match an existing Start Date in Portfolio Manager, ABS will begin its deletion with the meter reading that has a Start Date closest to that date but not before it. ii. mrsReplaceEndDate – set this to the End Date of the date range of meter readings you want to delete for this Meter. Please note that this is only relevant for when you set meterReadingSet to ‗ReplaceRange‘. If this End Date does not match an existing End Date in Portfolio Manager, ABS will complete its deletion with the meter reading that has an End Date closest to that date but not after it. 42 ABS User’s Guide 3. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 4. Store the Transaction ID (TXNS_ID) in your ESP System. 5. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageMetersResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.12 Managing Renewable Energy Certificate data Adding, editing, and deleting Renewable Energy Certificate (REC) data in Portfolio Manager requires the use of the Manage Building Information Web Service. Editing and deleting RECs requires that the REC already be stored in Portfolio Manager. All management of REC data is accomplished using Portfolio Manager‘s REC identifier. There is no mapping to external ESP identifiers for RECs, so the Portfolio Manager REC identifier will need to be provided when editing or deleting an REC. When adding an REC, the Portfolio Manager REC identifier will be provided in the Manage Building Information response file. To add or edit an REC, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schemas on the ABS Website for element definitions): 1. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. bldgREC [required] – this is the parent element encompassing all REC add/edit requests. One instance of this element must be included for each REC you wish to add or edit b. recNewExisting [required] – when adding an REC, specify this element as ―New‖. When editing an REC, specify this element as ―Existing‖. If you would like ABS to determine whether to add a new REC or edit an existing REC, specify this element as ―Unknown‖ c. pmRECid [required for editing] – for each REC that you want to edit, provide the pmRECid of the REC to be edited. The pmRECid will be provided in the service response for RECs that are added through the Manage Building Information service 43 ABS User’s Guide d. recProviderName [required] – the name of the organization that provided the Renewable Energy Certificate e. recQuantity [required] – the amount of energy offset by the purchase of this REC, specified in kWh or MWh f. recQuantityUnitType [required] – specifies whether the quantity is provided in kWh or MWh g. recQuarterGenerationPeriod [required] – notes whether the REC was generated in the 1st, 2nd, 3rd, or 4th quarter of the specified calendar year. h. recYearGenerationPeriod [required] – the year in which the REC was generated i. recGeneratorFacilityName [required] – the name of the Power Generation Plant where the REC was generated recGeneratorFacilityID [required] – the 5 digit ORIS ID of the Power Generation Plant where the REC was generated j. k. recEnergyType [required] – the renewable energy type represented by this REC 2. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 3. Store the Transaction ID (TXNS_ID) in your ESP System. 4. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. To delete an REC, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Manage Building Information Web Service (refer to the Manage Building Information schemas on the ABS Website for element definitions): 44 ABS User’s Guide 1. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: l. bldgRECdelete [required if deleting an REC] – one instance of this element must be included for each REC that you want to delete m. pmRECid [required] – for each REC that you want to delete, provide the pmRECid of the REC to be deleted 2. Upon a successful Request, ABS will submit back to your ESP System a Transaction ID (TXNS_ID) that can be used to retrieve a response (asynchronous services only). 3. Store the Transaction ID (TXNS_ID) in your ESP System. 4. Send a Request to Retrieve a Response using a method call in your SOAP message that includes the corresponding Transaction ID (TXNS_ID) for the request. Responses to asynchronous requests will be ready for pickup within 24 hours of request receipt by EPA. RECOMMENDATION: We recommend waiting at least 2 hours before polling ABS for a Response to an asynchronous request. Refer to the ManageBuildingsResponse.xsd schema for a complete list of elements that are returned in our response to your request. See section 9.0 for suggestions on troubleshooting any issues or errors. 6.13 Downloading Building and Energy Data from a Customer’s Portfolio Manager Account ABS provides ESPs with the ability to get all building, space usage, and energy consumption data for any customer‘s buildings that they have submitted or been authorized to map to. This can be done through the Get Building Details Web Service and Get Meter Details Web Service. Please note that if multiple ESPs are providing energy consumption for the same customer‘s building, each ESP will only be allowed to download energy consumption for the Meter(s) for which they are providing data. However, all building and space usage information for that building will be available for download. Both the Get Building Details and Get Meter Details Web Services use the same request schema: DetailRequest.xsd. For both Services, you can choose to receive all responses or to filter by a particular customer or building:   To receive building information or meter information for all customers and buildings you are mapped to, provide the ―All‖ element when submitting the Details service request. To receive building information or meter information for a specific customer or set of customers, set espCustID to a matching set of espCustIDs that are already stored in Portfolio Manager. 45 ABS User’s Guide  To receive building information or meter information for a specific customer, set espCustID to a matching set of espCustIDs that are already stored in Portfolio Manager. To receive building information or meter information for a specific building or set of buildings, set espBldgID to a matching set of espBldgIDs that are already stored in Portfolio Manager. When your ESP System is ready to retrieve a Response from ABS, make sure to indicate which set of data you want to have returned for that Transaction ID by requesting either the Get Building Details or Get Meter Details Web Service. 7.0 7.1 Rating Exchange Service (RES) USAGE GUIDELINES Rating Exchange Service (RES) The RES Usage Guidelines explain the actions that can be taken using the RES Request schema. The Guidelines also describe the data returned in the RES Response file. RES‘s primary function is to request ratings and other metrics for a specific time period. The RES Request section explains the two methods in which ratings and other metrics can be requested using RES. The two methods are the ―point-in-time‖ and date range requests. The RES Response section explains the information that is returned in a response file after a request file is processed. A list of the calculated metrics is provided in this section. 7.2 Rating Exchange Service (RES) Request: Ratings There are two types of RES metrics requests that can be submitted. A single point-in-time metrics request will return metrics for a single 12-month period. Requests for metrics over a date range will return metrics for all 12-month periods where the period ending falls within the requested date range. 7.2.1 Single Point-in-Time Metrics Request The ―single point-in-time‖ metrics request requires a specific period ending month and year (period ending date) to retrieve a rating and other metrics for that period ending date. NOTE: only one single ―point-in-time‖ period ending date can be requested per transaction. The response file would return a single set of metrics for the period ending date specified. The following sample excerpt of an XML request file displays a request of a single 12-month period ending date: 12/2008: 100 46 ABS User’s Guide 12 2008 7.2.2 Date Range Metrics Request The second RES metrics request allows for a date range to be specified by providing a start month and year, and an ending month and year. The system will then return multiple sets of metrics for each month/year ending within that date range. For example, to request metrics for the time period covering 3/2008-7/2008, a date range with a starting date of March 2008 and an ending date of July 2008 would be specified. Assuming there are sufficient meter entries prior to 3/2008 (at least 12 months are required to obtain a rating), RES would return five sets of ratings and related metrics for the following period ending dates: 3/2008 4/2008 5/2008 6/2008 7/2008 The following sample excerpt of an XML request file displays a request for a range of dates starting in 1/2008 and ending in 3/2008: 200 1 2008 47 ABS User’s Guide 3 2008 7.3 Rating Exchange Service (RES) Response The RES Response is an XML file the web service returns and that follows the RESResponse.xsd schema. The response file provides a unique transaction ID that identifies this particular submission. In subsequent requests, this transaction ID is used as a reference that the system will recognize. Also returned for each facility are the Building ID, total floor space, and a flag that indicates if the space is using default values. Certain alerts may optionally be returned as well. The RES Response file includes the complete set of calculated metrics. This includes the following (NOTE: all energy metrics are reported in kBtu):           Indicator signifying whether or not a facility is eligible for the ENERGY STAR Label. The year or years in which the facility was Labeled (displays only if a facility has been Labeled previously). The period ending date associated with last (i.e. most recent) Label received. The facility rating generated for the Period Ending Date. The annual weather-normalized annual energy consumption for a facility. The annual non-weather-normalized annual energy consumption for a facility. The weather-normalized annual energy intensity, or energy consumption per square foot, for a facility. The non-weather-normalized annual energy intensity, or energy consumption per square foot, for a facility. The non-weather-normalized site energy intensity for this particular facility for a rating of 50. The non-weather-normalized site energy intensity for this particular facility for a rating of 75. 48 ABS User’s Guide  The estimated emissions for this building, based on its energy use measured in metric tons CO2-equivalents. 7.3.1 Sample XML Excerpts The following lines from a sample XML response file show the metrics returned. 220 N Y 31430 N/A 5 2009 9005206 10661837 286.52 339.22 19249079 22716624 612.4 722.8 299.15 767.34 1066.49 0 0 10 Space types within the same facility are incompatible ID = 2 18 Less than One Full Year of Space Attribute Data 7 In order to receive a rating, more than 50% of your building must be defined by a benchmarkable space type. 49 ABS User’s Guide 8.0 Mapping to an Existing Customer’s Portfolio Manager Account Mapping refers to the process required to connect existing data from your ESP System to data in your customer‘s existing Portfolio Manager account. It is relevant to any ESP that must do one or more of the following:  Provide all building, energy, or meter consumption data for buildings that don’t already exist in Portfolio Manager because some of your customers expect you to set up new buildings in their existing Portfolio Manager account. Provide building, meter, or energy consumption data for existing buildings in existing Portfolio Manager accounts because some of your customers already have buildings set up and expect you to manage both building and energy data for them. Provide energy consumption data for existing meters in existing Portfolio Manager accounts because some of your customers already have meters set up and they expect you to provide consumption data for those meters.   Please note that if you are providing all building, energy, and meter consumption data for customers that do not already have a Portfolio Manager account, mapping is not required. Successfully mapping your ESP System to existing data in Portfolio Manager requires the completion of five principal steps (illustrated in Figure 7-1). In the following sections, we will describe each step in further detail. 50 ABS User’s Guide STEP 1 STEP 5 ESP System ESP (using ABS website) ESP uses ABS website to tell the Portfolio Manager system what data they need from their customers (e.g., billing account number, meter number) to verify the customer and map their own system to that customer‘s Portfolio Manager data. ESP sends an authorization approval or denial by invoking the new Confirm Pending Authorizations web service. For an approved request, ESP must also send all IDs needed to fully map from their system to Portfolio Manager. Confirm Pending Authorizations web service STEP 4 ESP or ESP System Portfolio Manager Database STEP 2 Get Pending Authorizations web service ESP or ESP system verifies information received and determines whether to approve or deny the request. ESP Customer (using Portfolio Manager) ESP customer uses Portfolio Manager to submit an Authorization Request to the ESP to perform automated benchmarking for their account. ESP customer is asked by Portfolio Manager to provide data elements that the ESP set up through the ABS website in Step 1. STEP 3 ESP System ESP system ―listens‖ for any new customer Authorization Requests by invoking the new Get Pending Authorizations web service. Figure 7-1: Data Release Authorization and Mapping process 8.1 Step 1: Customizing the Data Authorization and Mapping Process Mapping your ESP System to a customer‘s existing Portfolio Manager account requires that your customer formally authorize you, through a web interface in Portfolio Manager, to provide automated benchmarking on their behalf. This authorization can include any one or more of the following: 1. Providing new buildings in their existing Portfolio Manager account (Customer-level mapping) 2. Providing building, meters, and energy consumption data for specific buildings within their account (Building-level mapping) 3. Providing energy consumption data for specific meters that have already been set up within their account (Meter-level mapping) 51 ABS User’s Guide Through the ABS Website, you have the ability to customize the interface that your customers use in Portfolio Manager when authorizing you to provide automated benchmarking. ABS provides you with a wizard to guide you through this customization process. This wizard is first presented to you when you register to use the LIVE environment (see Section 5.2 for more details). During registration, you will be asked whether or not you will need to connect to your customers‘ existing Portfolio Manager data. If you select ―Yes, some or all of my customers have Portfolio Manager accounts and I need to connect to them‖, you will then be taken through a series of web forms to help us set up your customer‘s Portfolio Manager accounts to simplify the data release authorization and mapping process. The following are specific questions or activities that you will need to be prepared to respond to: 1. Identify what mapping scenario(s) you expect to encounter (Customer-level, Buildinglevel, Meter-level). 2. Specify any custom fields you would like your customers to fill out when they authorize you to perform automated benchmarking (see Figure 7-2 for example). Custom fields are essentially additional form fields that you create for the purpose of gathering additional data (e.g., account number, billing address) from your customers when they go through the data authorization process in Portfolio Manager. These custom fields are meant to help you identify and verify your customer or their data through this automated transaction. You can access the data your customers provide in these custom fields through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). 52 ABS User’s Guide Figure 7-2: Provide your customers with custom questions to help you more easily map to their data 3. Provide a Terms of Use disclaimer or statement that your customers can agree to through Portfolio Manager (see Figure 7-3 for example). This is an optional feature that enables you to provide a statement or a hyperlink to your customer whenever they authorize you to perform automated benchmarking through Portfolio Manager. This disclaimer or statement is meant to help you provide language or a link to additional information that helps to complete the data release authorization and mapping process. 53 ABS User’s Guide Figure 7-3: Use Portfolio Manager to help facilitate your data release authorization process Once you have completed this data release authorization and mapping customization, any customer who uses Portfolio Manager to authorize you to map to their account, buildings, and/or meters will be required to provide the information you requested and agree to the disclaimer you publish (if provided). Please note that these customization settings can be modified whenever you want by accessing the ―Edit Automated Benchmarking Settings‖ from the ABS Website Home Page. 8.2 Step 2: Your Customer Authorizes You to Provide Automated Benchmarking To authorize you to provide automated benchmarking services for their account, buildings, and/or meters, and to facilitate the mapping process, your customers will need to log into their Portfolio Manager account and follow these basic steps: 1. Select your company’s name from the list of service providers in the Automated Benchmarking area of Portfolio Manager. Please note that you must have already completed the registration process to use the LIVE environment (see Section 5.0) for your company name to be listed. 2. Read and accept the ESP Terms of Use disclaimer or statement. This is only displayed if the ESP creates one during Step 1 (see Section 7.1 for more details on Terms of Use disclaimers and statements). 3. Select what they want you to map to. This can include just their account, one or more of their buildings, and/or one or more building meters. 54 ABS User’s Guide 4. Answer any ESP-specific questions. These questions are based on the custom fields set up by you in Step 1 (see Section 7.1 for more details on custom fields). Once your customer has completed this process, the new authorization request can be accessed through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). 8.3 Step 3: Getting Pending Authorizations The Get Pending Authorizations Web Service is designed to enable ESPs to get important data about their customer‘s account and buildings from Portfolio Manager to complete the mapping process. By default, this Web Service will provide you with the following information for each account, building, and/or meter that your customer authorizes you to map to:  Portfolio Manager User ID (pmCustID) – this will be provided with every pending authorization response. This ID is required for you to map to your customer‘s existing Portfolio Manager account (see Section 7.5 for more details on how this element is used for mapping). Portfolio Manager Building ID (pmBldgID) – this will be provided for every building that a customer has authorized you to map to. This ID is required for you to map to your customer‘s existing building in Portfolio Manager (see Section 7.5 for more details on how this element is used for mapping). Building Information – this includes building name (bldgName) and address (bldgAddress, bldgCity, bldgState, bldgZipCode). This information will be provided for every building that a customer has authorized you to map to. Portfolio Manager Space ID (pmSpaceID) – this will be provided for every Space that exists in the building(s) your customer has authorized you to map to. This ID is required for you to map to these existing Spaces in Portfolio Manager. Space Information – this includes space name (spaceName), space type (spaceType), and all attribute values for every Space that exists in the building(s) your customer has authorized you to map to. See Get Pending Authorization schema on the ABS Website for a complete list of elements. Portfolio Manager Meter ID (pmMeterID) – this will be provided for every building that a customer has authorized you to map to. This ID is required for you to map to these existing Meters in Portfolio Manager (see Section 7.5 for more details on how this element is used for mapping). Meter Information – this includes meter name (meterName), fuel type (meterEnergyType), and units (meterEnergyUnit).       55 ABS User’s Guide  ESP Custom Fields – if you specify data that you want your customer to provide, this data will be provided through this Web Service. Since custom data can be requested at the Portfolio Manager account, building, and/or meter level, we provide a name and value pair for each corresponding level (custCustomIDName, custCustomIDValue; bldgCustomIDName, bldgCustomIDValue; meterCustomIDName, meterCustomIDValue) The Get Pending Authorizations Web Service is synchronous. To request this Web Service, follow the general instructions for submitting a Request outlined in Section 3.4. Please note that this Web Service will return all ―Pending‖ authorizations. Once a pending authorization is either approved or denied by the ESP (see Section 7.5 for more details on approving and denying authorizations), that authorization request and all associated data will no longer be available through the Get Pending Authorizations Web Service. RECOMMENDATION: if you need to access data about a particular customer‘s building or meter in Portfolio Manager after an authorization has been approved, use the Get Building Details and/or Get Meter Details Web Services (see Section 6.12 for more details on these Web Services). 8.4 Step 4: Verifying the Customer and Their Data For an ESP to complete the authorization and mapping process, we expect that you will need to verify the data provided through the Get Pending Authorization Web Service to ensure a proper mapping can and will occur. We do not provide any specific tools beyond the data provided in the Get Pending Authorization Web Service to support this effort since every ESP may perform this step a little differently. RECOMMENDATION: If you are not getting enough data from this Web Service to completely perform this step, either manually or through automation, you may want to consider adding new Custom Fields to the authorization process or possibly using the Terms of Use disclaimer (see Section 7.1 for more details on setting up Custom Fields and Terms of Use disclaimers) to notify your customers to conduct additional activities with you that they cannot do using Portfolio Manager. 8.5 Step 5: Completing the Mapping Process An ESP can perform two actions after your customer has authorized you to perform automated benchmarking services for their account, building, and/or meters: approve or deny the request. Approving the request is synonymous with ―mapping‖ (see Section 7.5.1 for more details). Denying the request allows you to inform your customer that you cannot map to their account, building, and/or meter and provide an explanation (see Section 7.5.2 for more details). 8.5.1 Approving an Authorization Request (i.e., Mapping) To approve an authorization request and complete the mapping, you will need to use the Confirm Pending Authorizations Web Service. This Web Service is synchronous. In this request, you will be asked to provide corresponding ESP IDs from your system that map to our internal Portfolio Manager IDs. To complete this request, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the 56 ABS User’s Guide Confirm Pending Authorizations Web Service (refer to the Confirm Pending Authorization schemas on the ABS Website for element definitions): 1. To map to a customer‘s existing Portfolio Manager account: a. Provide our internal Portfolio Manager User ID (pmCustID) for this customer. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). b. Provide your corresponding ESP Customer ID (espCustID) to map to this customer‘s account. The espCustID refers to the unique ID that your ESP System will use to reference this customer‘s Portfolio Manager account when you provide/request any data through our Web Services. Please note that if your ESP System does not have a corresponding account ID, you can use our pmCustID as your espCustID. If you choose to do this, you will need to store this ID somewhere within your system. c. Indicate that you approve this Customer-level authorization request by setting custAcceptYN to ‗Y‘. 2. To map to a customer‘s existing Building in Portfolio Manager: a. Follow steps 1a-1c above. b. Provide our internal Building ID (pmBldgID) for each building that you are mapping to. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). c. Provide your corresponding ESP Building ID (espBldgID) for each of your customer‘s buildings that you are mapping to. The espBldgID refers to the unique ID that your ESP System will use to reference this customer‘s building in Portfolio Manager when you provide/request any data through our Web Services. Please note that if your ESP System does not have a corresponding building ID, you can use our pmBldgID as your espBldgID. If you choose to do this, you will need to store this ID somewhere within your system. d. Indicate that you approve this building-level authorization request by setting bldgAcceptYN to ‗Y‘. 3. To map to a customer‘s existing Spaces in Portfolio Manager: a. Follow steps 2a-2d above. b. Provide our internal Space ID (pmSpaceID) for each Space that you are mapping to. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). 57 ABS User’s Guide c. Provide your corresponding ESP Space ID (espSpaceID) for each of your customer‘s Spaces that you are mapping to. The espSpaceID refers to the unique ID that your ESP System will use to reference this customer‘s Space in Portfolio Manager when you provide/request any data through our Web Services. Please note that if your ESP System does not have a corresponding Space ID, you can use our pmSpaceID as your espSpaceID. If you choose to do this, you will need to store this ID somewhere within your system. 4. To map to a customer‘s existing meter in Portfolio Manager: a. Follow steps 2a-2d above. b. Provide our internal Meter ID (pmMeterID) for each meter that you are mapping to. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). c. Provide your corresponding ESP Meter ID (espMeterID) for each of your customer‘s meters that you are mapping to. The espMeterID refers to the unique ID that your ESP System will use to reference this customer‘s meter in Portfolio Manager when you provide/request any data through our Web Services. Please note that if your ESP System does not have a corresponding meter ID, you can use our pmMeterID as your espMeterID. If you choose to do this, you will need to store this ID somewhere within your system. d. Indicate that you approve this Meter-level authorization request by setting meterAcceptYN to ‗Y‘. Once you have successfully mapped to your customer‘s Portfolio Manager account, buildings, and/or meters, a Test copy of this data will be placed in the TEST environment and you can then begin to submit data to their account (see Section 6.0 for details on how to send data to and request data through ABS). 8.5.2 Denying an Authorization Request If you are unable to complete the mapping process, you can use the Confirm Pending Authorizations Web Service to deny the authorization request and provide your customer with an explanation. If you deny the request, your customer will need to go through the data release authorization process (see Section 7.3) again in order to request that you provide automated benchmarking for their account, buildings, and/or meters. To send a denial of request, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the Confirm Pending Authorization Web Service (refer to the Confirm Pending Authorization schemas on the ABS Website for element definitions): 1. To deny a customer‘s request for you to map to their Portfolio Manager account: 58 ABS User’s Guide a. Provide our internal Portfolio Manager User ID (pmCustID) for this customer. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). b. Indicate that you deny this Customer-level authorization request by setting custAcceptYN to ‗N‘. c. Provide a reason for the denial, or possibly a set of instructions for correcting the problem, using the custMappingError element. This is optional. 2. To deny a customer‘s request for you to map to a specific building in Portfolio Manager: a. Follow steps 1a-1c listed in Section 7.5.1 to authorize the Customer-level mapping. b. Provide our internal Building ID (pmBldgID) for each building that you are unable to map to. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). c. Indicate that you deny this Building-level authorization request by setting bldgAcceptYN to ‗N‘. d. Provide a reason for the denial, or possibly a set of instructions for correcting the problem, using the bldgMappingError element. This is optional. 3. To deny a customer‘s request for you to map to a specific Meter in Portfolio Manager: a. Follow steps 2a-2d listed in Section 7.5.1 to authorize the Building-level mapping. Please note that if you are trying to deny the request to map to a meter in a Building you have not previously mapped to, you can simply follow steps 2a-2d listed above to deny the Building. This will result in the Meters also being denied. If you have previously mapped to this Building, then continue with steps 3b-3d below. b. Provide our internal Meter ID (pmMeterID) for each Meter that you are mapping to. You will have received this through the Get Pending Authorizations Web Service (see Section 7.3 for more details on this Web Service). c. Indicate that you deny this Meter-level authorization request by setting meterAcceptYN to ‗N‘. d. Provide a reason for the denial, or possibly a set of instructions for correcting the problem, using the meterMappingError element. This is optional. 59 ABS User’s Guide 8.6 ESP Access Privileges Once you submit a new building or successfully map to a customer‘s existing building, you will have access to the general building information, space usage data, and any meter for which you are providing energy consumption data. You will not be able to view or access meters that are created by the customer unless that customer authorizes you to map to that meter. You will also not be able to view or access any meter that is being managed by another ESP. However, you will be able to see whether other meters do exist for that building, along with who is managing that meter, through the Facility Summary page on the ABS Website. To get to the Facility Summary, first log in to the ABS Website. From the ABS Website Home Page, select ―Energy Service Provider Portfolio‖ to navigate to the list of customers and buildings you are mapped to. From this list of buildings, select the one that you want to view. 8.7 Testing the Authorization and Mapping Process Since there is no Test version of Portfolio Manager to compliment the Test Environment in ABS, ABS provides a mechanism for ESPs to verify their authorization and mapping functionality before exposing it to all Portfolio Manager users. During the registration process, ESPs will be given the opportunity to specify whether to allow a single Portfolio Manager user or the entire Portfolio Manager user community to authorize their data for management (see Figure 7-4 below). Making your services available to a single Portfolio Manager user allows you to test the authorization and mapping process with that user before opening your services to the entire Portfolio Manager user community. Once the authorization process has been sufficiently tested, you can change your ABS Service Visibility in the Automated Benchmarking Settings to make your services available to all Portfolio Manager users. 60 ABS User’s Guide Figure 7-4: Setting ABS Service Visibility for Testing Purposes 9.0 Ending Automated Benchmarking Services When an ESP is ready to terminate automated benchmarking services for a particular customer, building, or meter, you can submit a Web Services transaction that will remove your access to the building, eliminate any existing mappings between your ESP System and Portfolio Manager for that particular customer or building, and notify your customer of this change. Please note that performing this Web Services transaction is irreversible. If you have ended automated benchmarking in error, you will need to remap to this building (refer to Section 7.0 for more information on Mapping) to re-connect to the building. Your customers, through their Portfolio Manager account, also have the option to terminate automated benchmarking services with you for their entire account or particular buildings or meters within it. When your customer indicates they want to end automated benchmarking, you will be sent an email notification and be able to see this status update on the ABS Website by accessing the ―Customer List‖ from the ABS Website Home Page. Please note that a customer can remove authorization to specific buildings or meters or to their entire account. When a customer removes authorization to specific buildings or meters, that 61 ABS User’s Guide removal will occur in real-time and the ESP will no longer be able to provide data for those buildings or meters. When a customer removes authorization to their entire account, however, there is a two business day delay before ABS removes authorization to their entire account and all mappings are deleted. This is to prevent a customer from ending their automated benchmarking relationship in error and requiring that you go through the entire remapping process to fix the issue. If you think that a customer termination of benchmarking has been done in error, contact that customer and request that they cancel their termination request before the end of the second business day. 9.1 Terminating Service for an Existing Customer Terminating automated benchmarking for a particular customer can be performed through the End Automated Benchmarking Web Service or directly from the ABS Website. Ending automated benchmarking for a particular customer requires that the customer already have data stored in Portfolio Manager and that it is mapped to your ESP System (see Section 7.0 for more information on Mapping). ABS provides the ability for an ESP to end automated benchmarking for a customer‘s entire Portfolio Manager account or for specific buildings or meters within that account. To end automated benchmarking for a customer in Portfolio Manager using the End Automated Benchmarking Web Service, follow the general instructions for submitting a Request outlined in Section 3.4 along with the following instructions for using the End Automated Benchmarking Web Service (refer to the End Automated Benchmarking schemas on the ABS Website for element definitions): 1. Make sure that you are correctly mapped to that customer‘s account (see Section 7.0 for more details on Mapping) 2. Make sure to, at a minimum, submit the following data elements in your XML document when requesting this Web Service: a. espCustID [required] – must match an espCustID that you have previously provided for this customer. b. custDeauthorizeYN [required] – set this to ‗Y‘ to direct our system to end automated benchmarking for this customer and all buildings within their account. Set this to ‗N‘ if you are ending automated benchmarking for only a specific set of buildings or meters for that customer. c. custDeauthorizeMessage [optional] – you can provide a message to your customers, that will be displayed to them in Portfolio Manager, to explain or provide further detail regarding this termination of automated benchmarking for their account. 62 ABS User’s Guide d. espBldgID [required if ending automated benchmarking for either a building or a meter] – must match an espBuildingID that you have previously provided for this customer‘s building. e. bldgDeauthorizeYN [required if ending automated benchmarking for either a building or a meter] – set this to ‗Y‘ to direct our system to end automated benchmarking for this building. Set this to ‗N‘ if you are ending automated benchmarking for only a specific set of meters. f. bldgDeauthorizeMessage [optional] – you can provide a message to your customers, that will be displayed to them in Portfolio Manager, to explain or provide further detail regarding this termination of automated benchmarking for their building. g. espMeterID [required if ending automated benchmarking for a meter] – must match an espMeterID that you have previously provided for this Meter within the building. h. meterDeauthorizeYN [required if ending automated benchmarking for a meter] – set this to ‗Y‘ to direct our system to end automated benchmarking for this meter. i. meterDeauthorizeMessage [optional] – you can provide a message to your customers, that will be displayed to them in Portfolio Manager, to explain or provide further detail regarding this termination of automated benchmarking for their meter. 3. Upon a successful Request, ABS will submit back to your client the following elements defined in the DeauthResponse.xsd schema. To end automated benchmarking through the ABS Website, perform the steps outlined for each of the following relevant scenarios:  To end automated benchmarking for an existing Customer’s entire account, first log in to the ABS Website. From the ABS Home Page, select ―Customer List‖. Select the name of the customer that you want to stop providing automated benchmarking services for. On the Account Detail page, select ―Terminate Automated Benchmarking Services for this Customer‘s Account‖. To end automated benchmarking for one or more of your Customer’s buildings, first log in to the ABS Website. From the ABS Home Page, select ―Energy Service Provider Portfolio‖. Select the name of the building that you want to stop providing automated benchmarking services for. On the Facility Summary page, select ―Stop Automated Benchmarking Services for this Facility‖. 63  ABS User’s Guide  To end automated benchmarking for one or more of your Customer’s Meters, first log in to the ABS Website. From the ABS Home Page, select ―Energy Service Provider Portfolio‖. Select the name of the building that contains the meter you want to stop providing automated benchmarking services for. On the Facility Summary page, select the name of the meter that you want to stop providing automated benchmarking services for. On the Meter Detail page, select ―Stop Automated Benchmarking Services for this meter‖. 9.2 Removing Your Account from ABS At any time, an ESP can choose to close their ABS account and remove it from our system. This will effectively remove all mappings to customer data in Portfolio Manager and delete your account information from our system. If it is necessary to remove your ABS account from our system, log in to the ABS Website Home Page and select ―Terminate automated benchmarking services‖. You will then be asked to confirm this request. Upon confirmation, your account will be immediately removed. Please note that once you have removed your account, you will no longer be able to access the system or any of your customer‘s data through ABS. 10.0 Monitoring ABS Activity Through the ABS Website, ESPs can access automated benchmarking activity logs. Using these logs, you will be able to view summary information on how many transactions have occurred over the last 30 days and drill down to see detailed information on each transaction including who performed the transaction, the type of transaction, how many buildings were affected, whether there were any errors or alerts, and when the transaction occurred. Logs will be updated in real-time so each activity view always represents the latest information. To access these logs, first log in to the ABS Website. From the ABS Website Home Page, select ―View ABS Activity Log‖ to see building-by-building detailed activity logs showing every update made through your ESP System over the last 30 days. Select ―View XML Transaction Log‖ to see all of your XML Response documents over the last 30 days. 11.0 Troubleshooting 11.1 Duplicate Data in the System Duplication refers to the unintentional creation of a second building, space, meter, or meter reading record in Portfolio Manager. Duplication in Portfolio Manager typically occurs when an ESP does one of the following: 1. Sends building, space, or meter data through ABS for an existing building, space, or meter using an ESP ID (espBldgID, espSpaceID, espMeterID) that ABS doesn‘t recognize. This often occurs because the ESP did not correctly map to the existing building, space, or meter prior to sending through their data (see Section 7.0 for details 64 ABS User’s Guide on Mapping). The result of this is that ABS will create a second building, space, and/or meter in the same account. 2. Sends meter readings for a period that overlaps one that is already stored for that particular meter. The result of this is that ABS will create a second overlapping meter reading. ABS provides a set of tools to help ESPs avoid this kind of duplication and, if they occur, to remove them from the system. In the following sections, we will present tips to avoid creating duplicates and steps to remove them if they occur. 11.1.1 Tips for Avoiding Duplication 1. Make sure your ESP System is correctly mapped to any existing data. This is at the center of most duplication errors. See Section 7.0 for more details on how to properly map to your customer‘s data. 2. Use the NewExisting elements in the Management Services. Within the Manage Building Information Web Service and Manage Meter Information Web Service, there are a set of elements that occur at the customer (custNewExisting), building (bldgNewExisting), space (spaceNewExisting), and meter (meterNewExisting) levels. These elements are designed to enable your ESP System to inform ABS as to whether the data you are submitting is for a new customer, building, space, or meter or for one that already exists in Portfolio Manager. If you set this flag to ‗New‘, our system will check to make sure no matching ESP ID exists and, if none do, add this new data to Portfolio Manager. Please note that if you set this flag to ‗New‘, and we find a matching ESP ID for that account, building, space or meter, we will not add the new data and, instead, send an error message back to you through our Response XML documents. To indicate that what you are sending is for an existing account, building, space or meter, set the appropriate NewExisting element to ‗Existing‘. Our system will look for a matching ESP ID in Portfolio Manager. If we find one, we will add the data you submitted. If we are unable to find one, we will not add the data you submitted and send you an error message through our Response XML documents. 11.1.2 Steps to Correct a Duplicate Building, Space, Meter, or Meter Reading ABS provides two primary methods for ESPs to correct a duplicate once it has occurred. The first method is to use one of the two Management Services (Manage Building Information and Manage Meter Information) to delete the duplicate record. The second method is to use the ABS Website to delete the duplicate. More on each of these methods is described below: 1. Using the Management Services to delete duplicates. If you need to delete a duplicate building, space, or meter, simply send a request using either the Manage Building Information or Manage Building Information Web Service. In that request, under the appropriate parent delete element (buildingDelete, spaceDelete, meterDelete), provide the ESP ID for the duplicate building (espBldgID), space (espSpaceID), or meter 65 ABS User’s Guide (espMeterID) that you want removed. Refer to Sections 6.2, 6.5, and 6.8, respectively, to learn more about how to delete a building, space, or meter. Refer to Section 6.11 to get details on how to delete specific meter readings 2. Using the ABS Website to delete duplicates. To delete a building, space, meter, or meter readings, you must access the Facility Summary page for that particular building using the ABS Website. To get to the Facility Summary, first log in to the ABS Website. From the ABS Website Home Page, select ―Energy Service Provider Portfolio‖ to navigate to the list of customers and buildings you are mapped to. From this list of buildings, select the one that is a duplicate or has duplicate spaces, meters, or meter readings. On the Facility Summary page, you will see a set of delete links for the building, particular spaces, and meters. Please note that you will only see delete links next to buildings, spaces, and meters that you created through ABS. You cannot delete any data, through the ABS Website, that you did not create. To delete a duplicate meter reading, first select the appropriate meter from the Facility Summary page. Choose all duplicate meter readings you want to delete and then select ―Remove Checked Entries‖. All deletions are final and cannot be restored without sending a new Web Service request. 11.2 Change Mapping to a Customer’s Data Changing mapping refers to the situation where an ESP has assigned a specific ID to a customer‘s account (espCustID), building (espBldgID), or meter (espMeterID) in error. Through the ABS Website, you can manually change these ESP IDs to the desired ID as needed. To change an ESP ID for a building or meter, you must access the Facility Summary page for that particular building. To get to the Facility Summary, first log in to the ABS Website. From the ABS Website Home Page, select ―Energy Service Provider Portfolio‖ to navigate to the list of buildings you are mapped to. From this list of buildings select the one that is incorrectly mapped. On the Facility Summary page, select the ―edit mapping‖ link that is next to the particular ID that is incorrect. To change an ESP ID for a customer‘s account, you must access the Account Detail page for that particular customer. To get to the Account Detail page, first log in to the ABS Website. From the ABS Website Home Page, select ―Customer List‖ to navigate to the list of customers you are mapped to. From this list of customers, select the one that is incorrectly mapped. On the Account Details page, select the ―edit mapping‖ link that is next to the espCustID displayed. Please note that you can only modify ESP IDs that you have provided for this customer, building, or meter. Saved changes will be updated in real time. 11.3 Remove Mapping to a Customer’s Data If you have mapped to a customer‘s Portfolio Manager account, building, or meter in error, you can remove your mapping through the ABS Website. . To remove mapping for a building or meter, you must access the Facility Summary page for that particular building. To get to the 66 ABS User’s Guide Facility Summary, first log in to the ABS Website. From the ABS Website Home Page, select ―Energy Service Provider Portfolio‖ to navigate to the list of buildings you are mapped to. From this list of buildings select the one that is incorrectly mapped. On the Facility Summary page, select the ―Stop Automated Benchmarking for this Facility‖ link to remove all mappings to that particular building. If you need to remove mappings to a particular meter, select that meter from the Facility Summary page. On the Meter Details page, select ―Stop Automated Benchmarking for this Meter‖. To remove mapping for an entire customer, you must access the Account Detail page for that particular customer. To get to the Account Detail page, first log in to the ABS Website. From the ABS Website Home Page, select ―Customer List‖ to navigate to the list of customers you are mapped to. From this list of customers, select the one that is incorrectly mapped. On the Account Details page, select the ―Terminate Automated Benchmarking Services for this Customer‘s Account‖. 11.4 Error Messages and Alerts The following section lists and describes each error message and/or alert that ABS will provide back to the ESP. Table 10-1 Error Code Type (Alert or Error) Alert Alert Alert Alert Alert Alert Alert Alert Alert Alert Alert Description 1 2 3 4 5 6 7 8 9 10 11 Defaults were used in calculation of metrics Less than a full year of energy data Values exceeded the upper/lower bounds for this attribute Meter has gaps of more than 1 day of data Meter has overlaps of more than 1 day of data Meter has at least one electrical entry period that is greater than 65 days Less than 50% of floorspace is benchmarkable The floor area for computer data center is greater than 10% of the total floorspace The floor area for garage is greater than 100% of the total floorspace Space types within the same facility are incompatible There is no electricity use for the time period specified 67 ABS User’s Guide Error Code Type (Alert or Error) Alert Alert Alert Alert Alert Alert Alert Alert Description 12 13 14 15 16 17 18 There is no energy use for the time period specified Energy use is greater than the maximum allowable for a rating Cannot set default attribute value after actual value is provided Meter data is greater than 120 days old No metric information available to provide a period ending date Floor Area for "Other" Space Type Is Greater than 10% of the Gross Floor Area. Less than One Full Year of Space Attribute Data Energy rate for electricity varies by more than 20% from the average rate for this ZIP code Energy rate for non-electrical fuel varies by more than 20% from the average rate for this ZIP code No Pending Authorizations for this ESP Bad Ref_abs_transaction_type.abs_transaction_code No Customer Objects sent by WebService EspCustID not in PM An authorization request must have a value for either espCustID or pmCustId. General building level alert code used for each specific building level alert message. General meter level alert code used for each specific meter level alert message. General space level alert code used for each specific space level alert message espCustID / pmUserID does not match an authorized User ID espBldgID / pmBldgID does not match an authorized Building ID espMeterID / pmMeterID combination does not match an authorized set of Meter IDs pmSpaceID provided does not match an authorized Space ID 30 Alert 31 101 102 103 104 105 200 300 400 8810 8820 Alert Error Error Error Error Alert Alert Alert Error Error Error 8830 8840 Error 68 ABS User’s Guide Error Code Type (Alert or Error) Error Description 8850 8860 8870 8880 8890 8900 9010 11000 11010 11020 11030 11040 11050 11060 11090 11100 Error Error Error Error Error Error Error Error Error Error Error Error Error Error Error Error 11110 11120 11130 11140 12000 12010 Error Error Error Error Error pmRECid provided does not match an authorized Renewable Energy Certificate identifer espBldgID already exists espMeterID already exists espSpaceID already exists Invalid espSpaceID espCustID already exists Customer Org Name was not provided for new customer Building ID cannot be found in system The unit of measure is incompatible with the fuel type specified The Space ID does not exist for the facility being updated The Meter ID does not exist for the facility being updated The first 3 digits of the zip code are not valid Cannot respond with metrics for meters set as inactive Space attribute effective date cannot be later than the current date Must specify Warehouse type (Refrigerated or Unrefrigerated) Future dates not allowed for meter entries The temporary meter end date cannot be the same as or earlier than the temporary meter start date The fuel generation method is required for the fuel type specified The fuel generation method is incompatible with the fuel type specified A description of the Other fuel type is required A general error occurred while processing request The submitted transaction ID is invalid 69 ABS User’s Guide Error Code Type (Alert or Error) Error Error Error Error Error Error Description 12020 12030 12040 12060 13020 13030 Transaction currently being processed, please try retrieving results at a later time. Transaction results already retrieved or expired XML document is invalid or does not comply with schema This account is not registered Internal error occurred. Please resubmit your request or contact technical support IO error occurred. Please resubmit your request or contact technical support The errors in Table 10-2 are not returned in a response document but are instead errors that may occur when attempting to make a call to ABS. Table 10-2 Possible Problem Possible Cause Troubleshooting Tips 70 ABS User’s Guide Possible Problem No response from Web Service Possible Cause 1. Network is down 2. Web listener is down 3. Database is down Troubleshooting Tips 1. Ping Web Services URL. If there is no response, the network is down. Contact Production Support. 2. Check the Web Service URL using a web browser. If ―HTTP 400 - Bad Request‖ is displayed, the web container is up and running. If ―HTTP 404 - File not found‖ is displayed, the web container is down. Contact Production Support. 3. Contact Production Support. Data errors on response from Web Services Incorrect schema version 1. Make sure the latest schema version from the ABS web site is being used. Revalidate the XML document against the provided schema. 1. Check the Web Service URL using a web browser. If ―HTTP 400 - Bad Request‖ is displayed, the web container is up and running. If ―HTTP 404 - File not found‖ is displayed, the web container is down. Contact Production Support. File Not Found when sending request or response Client couldn't connect to the URL supplied. 12.0 Getting Help 12.1 Frequently Asked Questions (FAQs) Are there any limits to the number of buildings for which I can submit data? ABS can process hundreds to thousands of records per hour. There is no explicit limitation to the size of the file or number of facilities that can be submitted. The actual processing speed will be determined by the complexity of the request and the load on the system at the time the request is made. Overall throughput may also be throttled by the bandwidth of the client connection. Generally speaking, limitations can be imposed by the network, hardware, and/or software used to directly call the rating system. 71 ABS User’s Guide When making requests that return a large number of records, ESPs must make sure that your client parsing engine and hardware will provide satisfactory performance. How frequently can I submit data? There is no limit on the number of submissions allowed. The Manage Building Information, Manage Meter Information, and Rating Exchange Service Web Services have special performance considerations. Due to the high levels of processing required to generate the ENERGY STAR Rating and other metrics, processing times can vary depending on the number of updates provided in the request file. How can I check the status of the data that I have submitted? How often can I do this? Due to the differences in the amount of data returned in response to ESP requests, the length of time it takes for asynchronous Web Services transactions to process records will vary. If a client application is used, it will need to poll the Response Web Services until processing is complete (or until an error condition other than 12020, i.e., ―still processing‖, occurs). A polling interval of 2 hours is generally recommended. You may also view the status of your submissions by logging into ABS Website and selecting ―View ABS Activity Log‖. As mentioned earlier, the request frequency should be designed such that processing completes within two hours. If processing has not completed within two hours from the initial Request Inquiry, the client application should continue to poll for two additional hours. If processing is still not complete after one business day, you should contact technical support. Note: Testing submissions via ABS will give you an idea about the length of time required for processing requests. The ABS Website displays start and end processing times in the ABS Transaction Log (see Section 9.0 for details on the ABS Activity Log). Please note that sending multiple Web Service requests during the same time period may result in subsequent Web Service requests taking longer to return results. How often is the data I submitted processed? Data processing begins immediately but the length of the process can vary. It is based roughly on the amount of data submitted. What is the degree of uniqueness for a given ID (customer, building, space, or meter)? The ID must be unique within the appropriate scope of the element. For example, a meter ID must be unique within a building, and a building ID must be unique within a customer. Does “energy cost” refer to the cost per unit of energy consumed or the overall cost for the total amount consumed? ―Energy cost‖ refers to the overall cost for the total amount of energy consumed. 72 ABS User’s Guide Do the energy consumption and cost elements require 2 decimals? No, these numbers do not require 2 decimals, but they will be accepted if they are provided. Can I submit data for buildings located outside of the United States? No. Currently, ABS handles U.S. facilities only. Portfolio Manager can be used to benchmarking international facilities. 12.2 Additional XML Resources For additional guidance around creating and reading XML documents, we recommend that you reference information provided by the World Wide Web Consortium (W3C). In particular, check out their information about XML as well as some their tutorials. 12.3 Contacting Technical Support If you have any questions or comments related to ABS, or Portfolio Manager, please access the ―Contact Us‖ help page on the ABS Website by selecting the ―Contact Us‖ button at the top of any ABS page. You can also reach us directly by sending an email to buildings@energystar.gov. Once submitted, a User Support Specialist will contact you within one business day. For issues that cannot be resolved within one business day, a User Support Specialist will escalate the issue to an ABS Technical Expert and will contact you to keep you apprised of the status. A User Support Specialist or ABS Technical Expert may also follow up by telephone with you if more information is needed to resolve your issue. While this User‘s Guide provides a thorough overview of ABS, we understand that additional technical consultation is highly beneficial in completing your systems integration. If you wish to receive further technical guidance, either at the onset of your ABS integration planning or during integration development, the ABS technical team is available for conference calls to discuss systems design and development as it pertains to ABS. In order to efficiently manage technical support resources, EPA asks that ESPs initially use the User‘s Guide and user support email to gain an initial understanding of ABS. ABS can be accessed at https://www.energystar.gov/istar/abs. 13.0 APPENDICES 13.1 SOAP Attachments Due to the potential volume of data being sent, ABS provides the option of sending the XML file as a SOAP attachment, in addition to as a string element contained within the SOAP message. If the XML file is sent as a SOAP attachment, it must be encapsulated using Multipurpose Internet Mail Extensions (MIME) as outlined in the W3C SOAP With Attachments (SwA) 73 ABS User’s Guide document. MIME encapsulation is required for SOAP attachments as a result of the ABS implementation using a J2EE 1.4 platform that supports SOAP Specification 1.1 with SwA extension. Table 13-1 summarizes technologies that support SwA using MIME encapsulation. Table 13-1 Technology Platform Java 2 Enterprise Edition (J2EE) .NET Framework – includes Web Services built using Visual C++, C#, J#, Visual Basic.NET   Support for SOAP Message Attachments Supports SOAP messages and SOAP attachments using MIME encapsulation. Support for MIME encapsulation is possible through MIME SOAP with Attachment SOAP Extension for C# and VB.NET by Alotsoft and possibly other third party vendors. Supports SOAP messages with MIME attachments, depending upon the C++ application server in use. Systinet Server for C++ supports SOAP attachments over MIME. Supports SOAP messages and SOAP attachments using DIME encapsulation through the MS SOAP Toolkit (add-on for ASP 3.0 and VB 6.0). Note that vendor support for the most recent version ended in April 2005. Supports SOAP messages. No native support for creating or parsing SOAP attachments. tag can be used to call a Java object on underlying Java Server (JRun) to create SOAP messages that will support MIME attachments. C++  ASP 3.0, Visual Basic 6.0   ColdFusion MX    13.2 Setting Username/Password in an SSL Invocation from Web Service Clients/Proxies An external user may choose to use the following client/proxy implementation to call the Web Services:  Dynamic Proxy 74 ABS User’s Guide    Static Proxy Dynamic Invocation Interface (DII) Application Client In all of the above cases, to make an authorized invocation to the Web Services enabled with SSL, the following steps are essential: 1. Provide Username and Password for a basic authentication. 2. Make an HTTPS request to the server and accept server certificates. If you have the Java Secure Socket Extension (JSSE) package available, the following instructions show how to set username/password from Sun implementation: Once a client stub is created, username / password can be set as: // setting the username stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, "username"); // setting the password stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, "password"); For a javax.xml.rpc.Call object the following properties are used: // setting the username javax.xml.rpc.Call.USERNAME_PROPERTY // setting the password javax.xml.rpc.Call.PASSWORD_PROPERTY SSL is often used as the underlying communication protocol of HTTPS. If a client is talking to an HTTPS server, the server will present its certificate to the client, which must verify the certificate by using the client truststore. Internally, the HTTPS Protocol handler will examine the server certificate received to verify that the server ESP System is indeed the ESP System that the client is expecting. 75 ABS User’s Guide The following code is required for communicating over SSL and then accepting the server certificate: // Dynamic registration of JSSE provider java.security.Security.addProvider (new com.sun.net.ssl.internal.ssl.Provider()); // Sun's reference implementation of a URL handler for the "https" URL protocol System.setProperty("java.protocol.handler.pkgs","com.sun.net.ssl.internal.www.protocol"); // Specify the location of where to find key material for the // TrustManager (this overrides jssecacerts and cacerts). Please See Note below. System.setProperty("javax.net.ssl.trustStore", " C:\\jdkXXX\\bin\\client.keystore"); For further information on building Web Service clients, please visit http://java.sun.com/j2ee/1.4/docs/tutorial-update2/doc/JAXRPC5.html. For more information on SSL, please visit http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security6.html. Note: if jssecacerts exists along with the cacerts in the jdk‘s default directory, then jssecacerts takes precedence. In that case it is better to use system property to explicitly specify the truststore location. 13.3 Downloadable ABS 2.0 Web service Client Tools ABS 2.0 Web service Client Tools: String version and Attachment version are available at https://estar8.energystar.gov/ESES/ABS20/ClientTool/StringVersion/ https://estar8.energystar.gov/ESES/ABS20/ClientTool/AttachmentVersion/ The install instructions are included in the downloadable. Please note that the client tools are intended for use as an example only. This code can be edited to fit your customized needs. 13.4 Space Attribute Characteristics Table 13-2 lists the attributes for each space type supported through ABS. The ―Used in Generating a Rating?‖ column indicates those attributes that are used in the benchmarking procedures to generate a rating for that space type. The ―Default Available?‖ column indicates those attributes where ABS can use a system-generated default value if an actual value is not provided by the ESP System. 76 ABS User’s Guide Table 13-2 Space Type Name Attribute Name Gross Floor Area Operating Hours/Week Hospital (Acute Care or Children's) Gross Floor Area Maximum Number of Floors Number of Licensed Beds Tertiary Care Laboratory Laundry Facility Number of Buildings Ownership Status Hotel Food Preparation Facility Gross Floor Area Number of Rooms Workers on Main Shift Number of Refrigeration/Freezer Units % Heated % Air conditioned Average Occupancy Laundry Facility Guest Hours Guest Meals Spa Floor Area Used in Generating a Rating? Y Y Y Default Available? N Y N Computer Data Center Y Y Y Y N N N N Y Y Y Y Y Y N N N N Y N Y Y Y Y Y N N N N N Y Y Y N N N N N 77 ABS User’s Guide Space Type Name Attribute Name Gym Floor Area Laundry Quantity Used in Generating a Rating? N N Y Y Y Y N Y N Default Available? N N Y Y Y N N Y N K-12 School % Air-Conditioned % Heated Cooking Facility Gross Floor Area Months in use Number of PCs School district Number of Refrigeration/Freezer Units High School Open Weekends Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y N Y Y Y Y Y N Medical Office % Air-Conditioned % Heated Gross Floor Area Number of Workers Operating Hours/Week Bank/Financial Institution Gross Floor Area Number of PCs Workers on Main Shift Operating Hours/Week Percent Air conditioned Percent Heated Courthouse Gross Floor Area 78 ABS User’s Guide Space Type Name Attribute Name Number of PCs Workers on Main Shift Operating Hours/Week Percent Air conditioned Percent Heated Used in Generating a Rating? Y Y Y Y Y Y Y Y Y Y Y Default Available? Y Y Y Y Y N Y Y Y Y Y Office Gross Floor Area Number of PCs Workers on Main Shift Operating Hours/Week Percent Air conditioned Percent Heated Parking Parking ft2 that is enclosed (with roof) Parking ft2 that is unenclosed (with roof) Parking ft2 that is open Weekly Hours of Access Y N Y Y Y Y Y Y Y Y Y N N Y N N Y N Y Y Y N Y N N N Other Gross Floor Area Operating Hours/Week Residence Hall/Dormitory % Air-Conditioned % Heated Gross Floor Area Number of Rooms Dorm Computer Lab Dorm Dining Hall Retail Gross Floor Area 79 ABS User’s Guide Space Type Name Attribute Name Operating Hours/Week Open and Closed Refrigeration/Freezer Cases Walk-in Refrigeration/Freezer Units Workers on Main Shift Number of PCs Number of Cash Registers Percent Air conditioned Percent Heated Exterior Entrance Used in Generating a Rating? Y Default Available? Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y N Y Y Supermarket/Grocery Percent Heated Percent Air-Conditioned Cooking Facilities Gross Floor Area Workers on Main Shift Operating Hours/Week Walk-in Refrigeration/Freezer Units Y N Y Y Y Y Y Y N Y N N Y Y Swimming Pool Months in Use Indoor/Outdoor Pool Size Warehouse (Refrigerated) Gross Floor Area Number of Workers Operating Hours/Week 80 ABS User’s Guide Space Type Name Attribute Name % Air-Conditioned % Heated Gross Floor Area Number of Workers Operating Hours/Week Walk-in Refrigeration/Freezer Units Distribution Center Used in Generating a Rating? Y Y Y Y Y Default Available? Y Y N Y Y Warehouse (Unrefrigerated) Y N Y N N N Y N N N N N Multifamily Housing Gross Floor Area Number of Units Bedrooms per Unit Number of Floors Percentage of square footage for living units Number of laundry hookups in individual units Number of common laundry hookups Number of dishwashers in individual units % Heated % Air Conditioned Regulation Type N N N N N N N N N N Y Y Y Y N N N N N Y Y Y House of Worship Gross Floor Area Seating Capacity Weekdays in Operation Operating Hours 81 ABS User’s Guide Space Type Name Attribute Name PCs Commercial Food Prep Commercial Refrigerator/Freezers Used in Generating a Rating? Y Y Default Available? Y Y Y Y 13.5 Valid Fuel Type/Unit Combinations Table 13-3 lists the valid combinations of fuel types and units of measure accepted by ABS Any meter with a combination of fuel type and unit of measure not listed in the table below will result in an error for that meter. Table 13-3 Fuel Type Electricity Electricity Electricity Electricity Natural Gas Natural Gas Natural Gas Natural Gas Natural Gas Natural Gas Natural Gas Natural Gas Fuel Oil (No. 2) Fuel Oil (No. 2) Fuel Oil (No. 2) Fuel Oil (No. 2) Unit of Measure kBtu kWh MWh MBtu kBtu MBtu ccf therms kcf cf Mcf Cubic meters kBtu MBtu Gallons Liters 82 ABS User’s Guide Fuel Type District Steam District Steam District Steam District Steam District Steam District Steam District Chilled Water District Chilled Water District Chilled Water Wood Wood Wood Propane Propane Propane Propane Propane Propane Liquid Propane Liquid Propane Liquid Propane Liquid Propane Liquid Propane Liquid Propane Other Kerosene Unit of Measure kBtu Pounds MBtu Therms kLbs MLbs kBtu MBtu Ton hours kBtu MBtu Tons kBtu MBtu Kcf Gallons Cf Liters kBtu MBtu Kcf Gallons Cf Liters kBtu kBtu 83 ABS User’s Guide Fuel Type Kerosene Kerosene Fuel Oil (No. 1) Fuel Oil (No. 1) Fuel Oil (No. 1) Fuel Oil (No. 1) Fuel Oil (No. 5 and No. 6) Fuel Oil (No. 5 and No. 6) Fuel Oil (No. 5 and No. 6) Fuel Oil (No. 5 and No. 6) Diesel Diesel Diesel Diesel Coal (anthracite) Coal (anthracite) Coal (anthracite) Coal (anthracite) Coal (anthracite) Coal (anthracite) Coal (bituminous) Coal (bituminous) Coal (bituminous) Coal (bituminous) Coal (bituminous) Coal (bituminous) Unit of Measure Gallons Liters kBtu MBtu Gallons Liters kBtu MBtu Gallons Liters kBtu MBtu Gallons Liters kBtu Pounds MBtu kLbs MLbs Tons kBtu Pounds MBtu kLbs MLbs Tons 84 ABS User’s Guide Fuel Type Coke Coke Coke Coke Coke Coke Fuel Oil (No. 4) Fuel Oil (No. 4) Fuel Oil (No. 4) Fuel Oil (No. 4) District Hot Water District Hot Water District Hot Water Unit of Measure kLbs MLbs Tons Pounds kbtu Mbtu kBtu MBtu Gallons Liters kBtu MBtu therms 14.0 USER’S GUIDE CHANGE HISTORY Date 2/23/2009 Version 2.1 Changes - Added RES to services in table 2.1 - Removed links to separate RES WSDLs since RES is now included in the ABS 2.0 WSDLs - Added Section 3.6 (Integration) - Added Section 7.7 (Testing the Authorization and Mapping Processes) - Added Error 9010 to Section 10.4 - Updated Section 11.3 (Contacting Tech Support) - Updated the Hotel, School, Swimming Pool, Multifamily Housing Space attribute listings in section 12.4 - Added section 12.5 (Fuel Type/UOM listing) 85 ABS User’s Guide 06/09/2009 2.1 - Updated Document Name to read 2.1 (instead of 2.0) -Updated Section 3.6.3. Added a sub-section for virtual metering immediately following where it used to be (and removed the old paragraph) -Updated the table of contents to reflect these changes 07/09/2009 2.1 - Added detailed RES Usage Guidelines information (New Section 10) - Updated formatting for sections after Section 10 8/31/2009 2.2 Updates in support of ABS 2.2 including: - Section 6.1 – Updated to include information on custEmailAddress - Sections 6.6, 6.9, and 6.10 – Updated to include On-site renewable meter data - Section 6.12 – New section detailing renewable energy certificates - Section 7.3.1 – Adjusted RES response example to use bldgMetrics element in place of the deprecated metrics element - Section 11.4 – Alerts list updated - Section 13.4 – Space attribute list updated - Section 13.5 – Fuel/Unit combinations updated 10/15/2009 2.2 Updated section 6.6 and 6.7 to include Temporary Meter Data 86