OCPI 2.3.0 Chapter 15

HubClientInfo Module - Developer Guide

Based on OCPI 2.3.0 Specification (Chapter 15). This module provides parties connected to a Hub with the connection status of other parties, enabling CPOs and eMSPs to know which parties are online.

6 Sections

2 Interfaces

4 Connection States

1. Overview

Introduction

The HubClientInfo module provides parties connected to a hub with the connection status of other parties that are connected to the hub and that they can communicate with. This allows CPOs to know which eMSPs and other parties are online and vice versa.

Module Identifier

hubclientinfo

Data Owner

Hub

Module Type

Configuration Module

Direction

Between eMSP/CPO and Hub (not between eMSP and CPO)

Hub Communication

Unlike the usual OCPI modules, this module operates between eMSP/CPO and Hub instead of between eMSP and CPO. The Hub acts as the central authority that tracks the connection status of all connected parties and distributes this information to enable parties to know which other parties are reachable.

2. Scenarios

Connection States

This section describes the expected behavior when a party receives information of a ConnectionState change.

15.1.1

Another Party becomes CONNECTED

Party is (back) online. Requests can be sent again. Every party receiving Client Owned Objects from this party should be prepared to receive Client Owned Objects with URLs that contain the party_id and country_code of this party.

Action: Resume normal communication. Be prepared to receive and process Client Owned Objects from this party.

15.1.2

Another Party goes OFFLINE

Connection to party is not available: No requests can be sent. Do not queue Push messages. When the other party comes back online, it is their responsibility to do a GET to get back in sync.

Expected behavior:

Stop sending requests to this party
Do not queue Push messages for later delivery
When the party comes back online, it is their responsibility to perform a GET to synchronize

15.1.3

Another Party becomes PLANNED

No requests can be sent to this new party yet. It can be a good idea to send some notification to an operator to get into contact with the new party so contracts can be set up.

Note: This state may also be used when a Hub has some configuration indicating which parties have contracts with each other. When a company does not have a connection configured, this state may also be sent to parties.

Expected behavior:

Do not send requests to this party
Consider notifying an operator to initiate contact for contract setup

15.1.4

Another Party becomes SUSPENDED

Like with OFFLINE, no requests should be sent to this party, they cannot be delivered.

Important: When, for example, CDRs still have to be delivered (there is some unfinished business), parties are advised to get into contact with the other party in some other way: call them, or send an e-mail.

Expected behavior:

Do not send requests to this party
If there is unfinished business (e.g., undelivered CDRs), contact the party through alternative channels

3. Flow and Life-cycle

Operations

The HubClientInfo module supports both Push and Pull models for distributing connection status information, along with a mechanism for the Hub to verify that connections are still alive.

3.1 Push Model

New ClientInfo Created

When the Hub creates a new ClientInfo object, they push it to the connected parties by calling PUT on the connected party ClientInfo endpoint with the newly created ClientInfo object.

ClientInfo Updated

Any changes to ClientInfo in the Hub system are sent to the connected party system by calling the PUT method on the connected party ClientInfo endpoint with the updated ClientInfo.

ClientInfo Invalidated

When the Hub invalidates a ClientInfo object (deleting is not possible), the Hub will send the updated ClientInfo object (with the field: status set to SUSPENDED) by calling the PUT method on the connected party ClientInfo endpoint with the updated ClientInfo object.

Verification: When the connected party is not sure about the state or existence of a ClientInfo object in the Hub system, the connected party can call the GET to request the ClientInfo object from the Hub system.

3.2 Pull Model

When a connected party is not sure about the state of the list of known connected parties of a Hub, or wants to request the full list at the start-up of their system, the connected party can call the GET on the Hub's ClientInfo endpoint to receive all ClientInfo objects.

Note: This method is not for operational flow. It is intended for initial synchronization or recovery scenarios only.

3.3 Still Alive Check

The Hub needs to determine if a connection is still "alive".

To do this, the Hub should keep track of the time that has passed since the last message was received from a connected party. When this is longer than X minutes (when unsure, start with 5 minutes), the Hub should send a GET to the Version information endpoint.

Why the Version endpoint? The Version information endpoint is always required in OCPI, is provided by all parties, and a GET to the versions endpoint does not have any side effects. This makes it the best way to perform a "still-alive" check.

4. Interfaces

API Reference

There is both a Sender (typically Hub) and a Receiver interface for ClientInfo. It is advised to use the Push direction from Sender to connected clients during normal operation. The Hub interface is meant to be used when the connected client is not 100% sure the ClientInfo cache is still correct.

4.1 Receiver Interface

Typically implemented by all parties connecting to a Hub. With this interface the Hub can push the ClientInfo information to a connected client (eMSP/CPO etc).

Example endpoint structure

/ocpi/cpo/2.0/clientinfo/{country_code}/{party_id}

Method	Description
`GET`	Retrieve a ClientInfo object as it is stored in the connected client’s system.
`POST`	n/a
`PUT`	Push new/updated ClientInfo object to the connected client.
`PATCH`	n/a
`DELETE`	n/a, Use PUT, ClientInfo objects cannot be removed.

4.1.1 GET Method

If the Hub wants to check the status of a ClientInfo object in the connected client's system, it might GET the object from the connected client's system for validation purposes. The Hub is the owner of the objects, so it would be illogical if the connected client system had a different status or was missing an object.

Request Parameters

The following parameters shall be provided as URL segments.

Parameter	Datatype	Required	Description
`country_code`	CiString(2)	yes	Country code of the requested ClientInfo object.
`party_id`	CiString(3)	yes	Party ID (Provider ID) of the requested ClientInfo object.

Response Data

The response contains the requested object.

Type	Card.	Description
`ClientInfo`	1	The requested ClientInfo object.

4.1.2 PUT Method

New or updated ClientInfo objects are pushed from the Hub to a connected client.

Request Body

In the PUT request, the new or updated ClientInfo object is sent.

Type	Card.	Description
`ClientInfo`	1	New or updated ClientInfo object.

Request Parameters

The following parameters shall be provided as URL segments.

Parameter	Datatype	Required	Description
`country_code`	CiString(2)	yes	Country code of the eMSP sending this PUT request to the CPO system.
`party_id`	CiString(3)	yes	Party ID (Provider ID) of the eMSP sending this PUT request to the CPO system.

Example: PUT a new ClientInfo object

PUT To URL: https://www.server.com/ocpi/cpo/2.0/clientinfo/NL/ALL

{
    "country_code": "NL",
    "party_id": "ALL",
    "role": "CPO",
    "status": "PLANNED"
}

4.2 Sender Interface

Typically implemented by the Hub. This interface enables Receivers to request the current list of ClientInfo objects from the Sender, when needed.

Method	Description
`GET`	Get the list of known ClientInfo objects, last updated between {date_from} and {date_to} (paginated)
`POST`	n/a
`PUT`	n/a
`PATCH`	n/a
`DELETE`	n/a

4.2.1 GET Method

Fetch information about clients connected to a Hub.

Endpoint structure definition:

{locations_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

Examples:

Example URLs

https://www.server.com/ocpi/cpo/2.2.1/hubclientinfo/?date_from=2019-01-28T12:00:00&date_to=2019-01-29T12:00:00
https://ocpi.server.com/ocpi/2.2.1/hubclientinfo/?offset=50
https://www.server.com/ocpi/2.2.1/hubclientinfo/?date_from=2019-01-29T12:00:00&limit=100
https://www.server.com/ocpi/cpo/2.2.1/hubclientinfo/?offset=50&limit=100

4.2.2 Request Parameters

If additional parameters: {date_from} and/or {date_to} are provided, only ClientInfo objects with last_updated between the given {date_from} (including) and {date_to} (excluding) will be returned. This request is paginated and supports the pagination related URL parameters.

Parameter	Datatype	Required	Description
`date_from`	DateTime	no	Only return ClientInfo that have last_updated after or equal to this Date/Time (inclusive).
`date_to`	DateTime	no	Only return ClientInfo that have last_updated up to this Date/Time, but not including (exclusive).
`offset`	int	no	The offset of the first object returned. Default is 0.
`limit`	int	no	Maximum number of objects to GET.

4.2.3 Response Data

The endpoint responds with a list of valid ClientInfo objects, the header will contain the pagination related headers. Any older information that is not specified in the response is considered as no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.

Type	Card.	Description
`ClientInfo`	*	List of all (or matching) ClientInfo objects.

5. Object Description

Schema

5.1 ClientInfo Object

The ClientInfo object represents the connection information of a party connected to a Hub.

Property	Type	Card.	Description
`party_id`	CiString(3)	1	CPO or eMSP ID of this party (following the 15118 ISO standard), as used in the credentials exchange.
`country_code`	CiString(2)	1	Country code of the country this party is operating in, as used in the credentials exchange.
`role`	Role	1	The role of the connected party.
`status`	ConnectionStatus	1	Status of the connection to the party.
`last_updated`	DateTime	1	Timestamp when this ClientInfo object was last updated.

Example ClientInfo Object

{
    "party_id": "ALL",
    "country_code": "NL",
    "role": "CPO",
    "status": "CONNECTED",
    "last_updated": "2019-06-25T14:30:37Z"
}

6. Data Types

Reference

6.1 ConnectionStatus enum

Defines the possible connection states of a party connected to a Hub.

Value	Description
`CONNECTED`	Party is connected.
`OFFLINE`	Party is currently not connected.
`PLANNED`	Connection to this party is planned, but has never been connected.
`SUSPENDED`	Party is no longer active, will never connect anymore.