Introduction to Eliq Connect

Eliq Connect is a tool that allows end users to grant third-party energy data access consent to the national data hub of their supply address location, so it can be collected on behalf of the company requesting it. This is often, but not limited to, banks, hardware manufacturers, price comparison sites, and sometimes energy suppliers.

Once consent is obtained, Eliq imports the data and makes it available to clients via Eliq’s delivery mechanisms (Insights API, Web Component Pages, Web Apps, and White Label Mobile Applications). It enables energy application creators to avoid the heavy lifting and compliance requirements associated with national data hubs, providing an easy, single integration for companies wishing to offer a standardised customer experience across multiple countries.

How does the user give consent for their energy data to be collected?
Each national data hub has a different method of consent, and in some countries, there are multiple options for consent. Eliq provides clients with a web view hosted by Eliq that handles the consent journey, depending on the supply location’s country.

After consent has been provided by the user, Eliq Connect also manages non-ideal user journey paths that can sometimes be complex. For example, some national data hubs may return consent for more locations than are listed in our client’s system. In such cases, we ask the user to map the consented meters to the locations in the client’s system. In some countries, there may also be delays in receiving data from the national data hub. Eliq Connect has a user journey designed for this scenario as well.

How does the user give consent for their energy data to be collected?

Eliq Connect has four end-points that combined enable clients to implement Eliq Connect:

• Get Eliq Connect Web URI – returns the URI (a slightly different version of a URL) that can load the Eliq Connect web view in a browser or equivalent. All integrations must use this end-point.

• Get location connection metadata – provides statuses of energy data consent for the supply location which should be checked at the start of every session. All integration should use this end-point.

• Get user connections – this returns user information about which data hubs or DSO (connections) the user has a connection to along with status. This end-point is optional and we recommend that status is checked at the location level with Get location connection metadata.

• Get connection entities – this end-point returns all meters (entities) that are consented to and configured properly within Eliq Connect. This is normally used for countries where elec and gas meters can consent. This enables developers’ systems to know if there is consent for electricity only, gas only, or electricity and gas. This end-point is optional.

Example Implementation:

Step 1 – check the location status

The first step is to check the connection status for the location. Call GET locations/:id/connection-meta-data

This end-point returns the following statuses:

• “ok” – The connection related to the location is all ok. Connection entities (at least one) have been configured and data is available. No actions are needed by the user and a normal user experience can be provided with the latest energy data provided by Eliq’s Insights API
• “not_connected” – There are no connections related to the location. The user should be prompted with a message asking to set up a connection which sends the user to Eliq Connect (see Step 2).
• “action_required” – A connection exists, but there is an action required by the user to make it work. The user should be prompted with a message saying he/she needs to fill in some more information and send the user to Eliq Connect (see Step 2)
• “awaiting_confirmation” A connection has been created, but not yet validated by the data hub or DSO. E.g. awaiting approval from DSO. At this stage, there are no actions that can be done to change the status. The user should be managed in this scenario to explain that we are waiting for the data hub or DSO to confirm they are happy with the consent provided.
• “awaiting_first_data_sync” The connection has been configured and is ready to go. Energy data has though not been synced for at least one of the connection (meters) entities. This means that the user should be managed but the user should be managed with a message in the user experience that we are waiting for data from the data hub or DSO

If you have a user with multiple locations you may wish to check the status for all locations at the start of the session or only when your user transitions to a view for a particular location. Eliq cannot make this decision for clients because each client will have their own architecture and unique customer journeys.

Step 2 – sending the user to Eliq Connect

If the status is action_required, or not_connected, the user should be taken to the Eliq Connect Web. This is where all logic related to creating or configuring a connection is done. Use GET users/:user_id/connections/web-portal-uri?callback_uri={callbackUri} to generate the URL, and send the user of to Eliq connect.

The response with the uri will look like this example:

{
“uri”:”https://connect.eliq.io/login?callbackUri={callback_uri}&ticket={SSO TICKET}”
}

The callback_uri is the location that you wish Eliq Connect to return the user to once they have completed their user journey.

It is also possible to provide a an optional linkout callback uri when generating the link. If linkout is used during the consent flow, the linkout_callback_uri will be used to override navigation to Eliq connect web view. Instead user will be navigated to linkout_callback_uri: GET users/:user_id/connections/web-portal-uri?linkout_callback_uri={linkout_callback_uri}

The response with the uri will look like this example:

{
“uri”:”https://connect.eliq.io/login?linkOutCallbackUri={linkout_callback_uri}&ticket={SSO TICKET}”
}

Both optional parameters can be used in unison. Specifying both parameters can allow the app to know if the user navigates from back button callback_uri or from linkout_callback_uri: GET users/:user_id/connections/web-portal-uri?callback_uri={callback_uri}&linkout_callback_uri={linkout_callback_uri}

The response with the uri will look like this example:

{
“uri”:”https://connect.eliq.io/login?callbackUri={callback_uri}&linkOutCallbackUri={linkout_callback_uri}&ticketId={SSO_TICKET}”
}

Step 3 – the user provides consent in Eliq Connect

The user will now provide consent to Eliq Connect or complete the actions they are required to do. This is handled by Eliq Connect and therefore no development steps are required.

Design considerations when displaying Eliq Connect in a web view.

You may wish to maintain an element of the page that is owned by you. For example, on mobile the top banner of a mobile app could be client controlled with a back button in case the user wants to exit Eliq Connect mid-journey. The rest of the journey would be controlled by Eliq Connect.

This implementation would look like this screenshot:

Step 4 – Reload the app and start accessing Eliq insights

When the user has completed their journey they will be returned to the callback URI specified in the end-point and it will then be the responsibility of the client to bring the user back into the application.

‍