Using the Portfolio Manager Test User Interface (Test UI)

  • Updated

NOTE: as of December 9, 2024 the guidance below supersedes the following sections in the resource titled Testing Web Services:

  • Testing Part A
    • Create an Account
  • Testing Part C
    •  “Generate & Accept a Customer Connection Request” (specifically, steps 3a – 3e)
    • “Generate & Accept a Property Share” (specifically, steps 4a – 4e)
    • “Generate & Accept a Meter Share Request” (specifically, steps 5a – 5e)

The “Testing Web Services” resource is currently being updated to reflect the introduction of the Test UI, and the revised version will be made available as soon as possible.

 

Using the Test UI to Set Up a Test API User (Web Services Provider) Account

Prior to December 2024, creation of API user accounts in the Test Environment was performed via a dedicated, Test-only API call (POST /account). This was due to the lack of a Test UI through which new account creation could be performed, and through which Test API access could be requested/granted.

With the Beta release of web services version 24.0 in December 2024, the initial creation of "Test API user" accounts will now take place via the Portfolio Manager Test UI. This process will use the same “Create a New Account” workflow that is available in the Live/Production UI.

Any accounts that were created via the Test API prior to the launch of the Test UI will still be available; however, you will need the login credentials that you originally defined when you set up your Test account(s). If you no longer have access to this information, the best approach would be to create a new account via the Test UI.

New Test accounts that will be used to represent the API user/web service provider account will need to take the further step of enabling account-level API access. To do this:

  1. Log in to your "Test API user” account (via the Portfolio Manager Test UI) and click on “Account Settings” at the top of the page.
  2. From the subsequent “Edit Account” page, select the “Software Development” tab.
  3. On the “Software Development” tab, select “Yes” for the question “Will this account be used to test web services in the Test environment?” Additional text will appear below.
  4. At the bottom of the screen, click the button labeled “Start Using the Test Environment.”
  5. You will then be taken to another page, where you will be asked to make certain selections about your Web Services settings. At this stage, it is recommended that you indicate that you will be supporting data exchange for all energy meter types – but please note that any selections you make here can be easily updated in the future via your “Account Settings” in the Test UI.
  6. Click “Submit” and your Test account will be immediately registered and approved for API access.
  7. Begin working with the Test API and use the Test UI to validate the impact of these calls on the corresponding record(s).

Test accounts used solely to represent “test customer” accounts do not need to take further action before property records can be created within these accounts.

 

Using the Test UI to Work Through the Connection/Sharing Process

Similar to the Live/Production environment, "test customer" accounts that already have property records established will need to provide the "test API user" account with access to their data via the Connection and Sharing functions of Portfolio Manager.

In the Portfolio Manager Live/Production environment, these sharing actions must be initiated from within the customer’s account in the Portfolio Manager UI. Prior to the launch of the Test UI in December 2024, it was necessary to simulate the customer initiation of these connection and sharing requests via a series of dedicated, Test-only API calls. Since December 2024, these calls are no longer required and have been removed from the Test API.

Connection and Sharing requests must now be initiated from within a “test customer” account within the Test UI. Once initiated, these requests can be queried and accepted/rejected by the “test provider” via the corresponding Connection/Share services documented in the Test API. In short, the Connection/Share workflows are now identical in both the Test and Live environments.

Given these changes, the most appropriate guidance regarding the navigation of the Connection/Sharing process by API users will be the resource How to Use Web Services: Connection and Sharing Guidance for Providers. This resource presents the Connection/Sharing process from the dual perspective of the customer and the API user/web service provider. With the launch of the Test UI, the API user can follow this guide to work through both sides of the process in real time.

If you choose to create “test customer” accounts and/or property and meter records within those customer accounts via the Test API, then please note that the account-level Connection and property- and/or meter-level shares will already be in place. Therefore, if you wish to test the Connection/Sharing workflow from these accounts in the Test UI, you will need to disconnect and/or unshare the customer account/properties/meters before you can work through the end-to-end Connection and Sharing processes. Guidance on how to do this can be found in section 3 (“Manage Your Shared Properties”) in the guide How to Share Properties with Other Portfolio Manager Users.

 

Other Key Items

  • When you move from the Test environment to the Live environment, no data is migrated from your test account. In fact, you must create a new (or use an existing) Portfolio Manager account within the Live UI. This new account will have no relation to your Test account, and data created in the Test environment will not be available via your Live account. Similarly, existing data in the Portfolio Manager Live environment cannot be accessed via the Test environment.
  • The Test environment’s infrastructure consists of its own database and application servers, which are separate from the Live environment. Since this is a Test environment, it is configured on a smaller scale and is not intended to reflect the actual level of speed and performance that you would experience in the Live environment. Notably, the Test environment is not intended for production-level volume testing. In fact, the rate limit for the Test environment is intentionally set low – 10 requests per second – to allow providers to more easily test/verify their error handling and retry logic.

Was this article helpful?