Region Connector for the USA and Canada (Green Button Connect My Data)

This README will guide you through the process of configuring a region connector for the permission administrators in Canada and the United States which supports the Green Button Connect My Data standard. Green Button permission process is based on an OAuth 2.0 Authorization Code Grant. This region connector uses an event sourcing approach to create permission requests with the permission administrator. Currently, it emits the following information:

• Connection Status Messages for changes in statuses of permission requests

Prerequisites

• Register at UtilityAPI
• Register at the utility you want to support, those can be found here
• After registration, all your utilities will be listed under Utility Registration in your settings
• For each registered utility, you will have OAuth settings in which you can find the following needed information for the configuration:
  • Client ID
  • Client Secret
  • Redirect URI, which you can add yourself
• At the section API Settings you can generate an API token which is needed to check the status of the green button API
• Another section down you can find the Webhook Settings where you can add the path to the webhook of the EDDIE framework
  • You also are able to generate a Webhook Secret which is needed for the configuration
  • More on the webhook can be found under the section Webhook or here

Webhook

tbd

Configuration of the Region Connector

The region connector needs a set of configuration values to be able to function correctly, how you provide these values depends on the way you deploy the region connector.

Configuration values	Description
region-connector.us.green.button.basepath	Base path for the client (default is https://utilityapi.com/)
region-connector.us.green.button.redirect.url	The redirect url for the OAuth flow
region-connector.us.green.button.webhook.secret	The webhook secret in order to validate webhook events. Not used yet, can contain any value.
region-connector.us.green.button.client-ids.REPLACE_ME	The client ids of the utilities you want to support. The name of the utility should replace the REPLACE_ME placeholder.
region-connector.us.green.button.client-secrets.REPLACE_ME	The client secrets of the utilities you want to support. The name of the utility should replace the REPLACE_ME placeholder.
region-connector.us.green.button.tokens.REPLACE_ME	The API token for the utilities you want to support. The name of the utility should replace the REPLACE_ME placeholder.
region-connector.us.green.button.termination.retry	When termination of permission requests with the green button API should be retried. Uses Spring cron syntax. Default is hourly
region-connector.us.green.button.polling	Optional configuration variable that sets the time when the region connector should poll future validated historical data. Uses Spring CRON syntax. Default is 0 0 17 * * *.

The region connector can be configured using Spring properties or environment variables. When using environment variables, the configuration values need to be converted in the following way:

• Replace all non-alphanumeric characters with an underscore (_)
• Optionally convert all letters to upper case

application.properties

region-connector.us.green.button.basepath=https://utilityapi.com/
region-connector.us.green.button.redirect.url=https://your-eddie-instance.example/region-connectors/us-green-button/authorization-callback
region-connector.us.green.button.webhook.secret=REPLACE_ME
region-connector.us.green.button.client-ids.REPLACE_ME=REPLACE_ME
region-connector.us.green.button.client-secrets.REPLACE_ME=REPLACE_ME
region-connector.us.green.button.tokens.REPLACE_ME=REPLACE_ME
region-connector.us.green.button.polling=0 0 17 * * *

application.yml

region-connector:
  us:
    green:
      button:
        basepath: https://utilityapi.com/
        redirect:
          url: https://your-eddie-instance.example/region-connectors/us-green-button/authorization-callback
        webhook:
          secret: REPLACE_ME
        client-ids:
          REPLACE_ME: REPLACE_ME
        client-secrets:
          REPLACE_ME: REPLACE_ME
        tokens:
          REPLACE_ME: REPLACE_ME
        polling: 0 0 17 * * *

Environment Variables

REGION_CONNECTOR_US_GREEN_BUTTON_BASEPATH=https://utilityapi.com/
REGION_CONNECTOR_US_GREEN_BUTTON_REDIRECT_URL=https://your-eddie-instance.example/region-connectors/us-green-button/authorization-callback
REGION_CONNECTOR_US_GREEN_BUTTON_WEBHOOK_SECRET=REPLACE_ME
REGION_CONNECTOR_US_GREEN_BUTTON_CLIENT_IDS_REPLACE_ME=REPLACE_ME
REGION_CONNECTOR_US_GREEN_BUTTON_CLIENT_SECRETS_REPLACE_ME=REPLACE_ME
REGION_CONNECTOR_US_GREEN_BUTTON_TOKENS_REPLACE_ME=REPLACE_ME
REGION_CONNECTOR_US_GREEN_BUTTON_POLLING=0 0 17 * * *

Running the Region Connector via EDDIE

If you are using EDDIE, the region connector should appear in the list of available region connectors if it has been configured correctly.