OCPI – Guide superadmin du Management Portal

Ce guide accompagne le superadmin dans l'utilisation quotidienne du module OCPI Administration ajouté au Management Portal. Il complète :

• Vue d'ensemble OCPI — comprendre les rôles et les flux,
• Premier enregistrement Gireve — procédure d'onboarding,
• Manuel de déploiement — variables d'environnement & secrets,
• Logs & monitoring — débogage bas niveau.

Pré-requis : être connecté avec un compte portant le rôle Admin. L'item OCPI Administration n'apparaît dans la barre latérale que pour ces comptes.

---

1. Accéder au module

1. Se connecter au Management Portal avec un compte Admin.
2. Dans la barre latérale, cliquer sur OCPI Administration (icône réseau).
3. Le tableau de bord (/OcpiAdmin/Index) s'ouvre par défaut.

URL	Écran	Rôle
/OcpiAdmin	Tableau de bord & monitoring	Vue agrégée temps réel
/OcpiRegistry	Registry Gireve	Générer / enregistrer / vérifier le TOKEN_A et le handshake
/OcpiAdmin/Partners	Liste des partenaires	Admin EMSP / CPO / Hub
/OcpiAdmin/PartnerDetails/{id}	Détail partenaire	Endpoints + tokens + trafic
/OcpiAdmin/Credentials	Tokens OCPI	Inventaire / révocation
/OcpiAdmin/Endpoints	Endpoints déclarés	Recensement par module
/OcpiAdmin/Sessions	Sessions push	État des push vers Gireve
/OcpiAdmin/Cdrs	CDR	Suivi des CDR (facturation)
/OcpiAdmin/Inbound	Audit entrant	Toutes les requêtes reçues
/OcpiAdmin/Outbound	Outbox	File d'envoi + requeue/annulation
/OcpiAdmin/Commands	Journal des commandes	RESERVE_NOW, START_SESSION…

Chaque écran reprend les conventions visuelles du portail (filtres en haut, tableau Bootstrap, badges colorés selon le statut).

---

2. Tableau de bord

Le tableau de bord agrège les indicateurs critiques sur 24 heures :

KPI	Source	Seuil d'alerte
Partenaires actifs / total	ocpi.Partners	—
Requêtes entrantes (24h)	ocpi.InboundMessages	volume anormalement bas
Latence moyenne entrante	ocpi.InboundMessages.DurationMs	> 500 ms
Outbox en attente	ocpi.OutboundMessages (Pending)	> 100
Dead-letter	ocpi.OutboundMessages (DeadLetter=4)	> 0 ⇒ pastille jaune
Sessions actives	ocpi.Sessions (Pending/InFlight)	—
CDR en échec 24h	ocpi.Cdrs.PushStatus = Failed	> 0 ⇒ enquête

Deux graphiques :

• Volumétrie 7 jours (lignes inbound/outbound) pour repérer une chute soudaine.
• Inbound par module (camembert) pour comprendre qui parle à la gateway.

Pastille de santé

Une pastille de statut est affichée en haut à droite (Healthy / Degraded). Elle bascule à Degraded dès qu'un des compteurs critiques est non nul (dead-letter, CDR en échec). Le polling temps réel rafraîchit les compteurs toutes les 10 secondes via /OcpiAdmin/Snapshot.

Le tableau de bord ne remplace pas la sonde Kubernetes /health/ready du gateway. Il en est complémentaire : la sonde dit le service répond, le tableau de bord dit les flux métier fonctionnent.

---

3. Gérer les partenaires

3.1 Consulter

Liste filtrable par nom, party_id, code pays et statut. Pour chaque ligne :

• nombre d'endpoints déclarés,
• nombre de tokens actifs,
• compteur outbox en attente (lien direct vers la file),
• date du dernier appel entrant.

3.2 Détail partenaire

Sur la fiche détaillée, le superadmin voit :

• les endpoints OCPI retournés lors de l'échange /versions/2.2.1,
• les tokens (TOKEN_A/B/C) avec valeur masquée (4 premiers + 4 derniers caractères),
• les 25 dernières requêtes entrantes et 25 derniers envois.

3.3 (Dés)activer un partenaire

Bouton Activer / Désactiver en haut de la fiche.

• Désactiver : la gateway continue d'écrire les messages dans l'outbox mais le worker n'envoie plus rien à ce partenaire ; les requêtes inbound restent acceptées si le token reste valide (à révoquer séparément si nécessaire).
• Activer : reprend les envois en l'état (les messages en Pending partent au prochain tick du worker).

L'action est tracée par Serilog (OCPI partner toggled to {Active} by {User}).

---

4. Gérer les tokens OCPI

Sous OCPI > Tokens :

Type	Quand l'utiliser
TOKEN_A	Première poignée de main POST /credentials
TOKEN_B	Échange /versions pendant le handshake
TOKEN_C	Token actif pour tous les appels métier

Filtres : partenaire / direction (Inbound ou Outbound) / actif ou révoqué.

Révocation

Bouton ⛔ sur chaque ligne active. La révocation est immédiate :

• IsActive ⇒ false,
• RevokedDate ⇒ horodatage UTC,
• la prochaine requête utilisant ce token sera rejetée en 401 Unauthorized.

Important : révoquer ne supprime pas le token. La table conserve l'historique complet pour audit. Pour générer un nouveau token, suivre la procédure documentée dans Premier enregistrement Gireve.

La valeur en clair d'un token n'est jamais affichée par le portail. Pour la récupérer (rotation, support), utiliser le SecretManager / Key Vault défini dans le manuel de déploiement.

---

5. Surveiller les flux

5.1 Sessions OCPI (push CPO → EMSP)

L'écran Sessions liste l'état de chaque session ouverte/poussée vers Gireve :

Statut	Sens
Pending	En attente d'envoi par le worker
InFlight	Envoi en cours
Confirmed	Ack 2xx reçu de Gireve
Retrying	Erreur temporaire (5xx, timeout) — réessai planifié
DeadLetter	Échec définitif après N retries

Si un grand nombre de sessions reste en Pending plus de quelques minutes : vérifier que OcpiOutboundDispatcherService (côté Worker) tourne et que les credentials Outbound sont valides.

5.2 CDR (Charge Detail Records)

Les CDR sont immuables côté OCPI. L'écran CDR affiche le statut de push : Pending / Pushed / Failed. Un échec doit toujours être investigué (impact facturation). Les CDR en échec listent la dernière erreur HTTP / message.

5.3 Outbox (sortants)

Filtres : partenaire / module / statut. Actions disponibles :

• Replanifier (icône 🔄) : remet le message en Pending avec NextAttemptUtc = now. À utiliser après avoir corrigé une cause (ex. credential renouvelé).
• Annuler (icône ✖️) : passe le message en Cancelled. Définitif, à réserver aux messages obsolètes.

Toujours investiguer avant de replanifier en masse : un dead-letter signale souvent un problème côté partenaire (changement d'URL, token expiré).

5.4 Audit entrant

L'écran Inbound est l'équivalent d'un access log mais filtrable par module, code HTTP, partenaire, fenêtre temporelle (jusqu'à 7 jours).

• Filtre statusCode=401 ⇒ trouver les tokens cassés.
• Filtre statusCode>=500 ⇒ détecter un bug côté gateway.
• Filtre module=Commands ⇒ retrouver toutes les commandes RESERVE_NOW.

Le X-Correlation-ID est exposé pour faciliter le rapprochement avec les logs Serilog (Seq/ELK/Loki).

5.5 Commandes OCPI

L'écran Commandes récapitule les commandes reçues par la gateway et leur résultat (ACCEPTED / REJECTED / TIMEOUT) avec la durée de traitement.

---

6. Procédures fréquentes

6.1 Un partenaire ne reçoit plus rien

1. Ouvrir OCPI > Outbound, filtrer par partenaire.
2. Si la file est saturée en Retrying : examiner la dernière erreur.
3. Si l'erreur est 401 : aller dans Credentials, vérifier que le token Outbound est Actif. Si nécessaire, en générer un nouveau.
4. Une fois corrigé, replanifier les messages en Retrying/DeadLetter.

6.2 Onboarding d'un nouveau partenaire

Le module OCPI Administration n'effectue pas le handshake lui-même (c'est le rôle de la gateway). La procédure complète reste documentée dans Premier enregistrement Gireve. Le portail sert ensuite à vérifier que le partenaire est correctement enregistré :

1. Aller dans Partenaires : la nouvelle ligne doit apparaître Actif.
2. Ouvrir la fiche : la section Endpoints doit lister au minimum locations, sessions, cdrs, tariffs, tokens, commands.
3. La section Tokens doit lister un token TOKEN_C actif dans chaque sens.

6.3 Rotation d'un token

1. Aller dans Credentials, identifier le token actif courant.
2. Cliquer sur ⛔ pour le révoquer.
3. Suivre le handshake POST /credentials documenté dans Premier enregistrement Gireve pour obtenir un nouveau TOKEN_C.
4. Vérifier dans Inbound que les requêtes reprennent en 200 OK.

6.4 Vider la dead-letter

À ne faire qu'après avoir compris la cause racine. Sinon on remet une charge sans valeur dans la file.

1. OCPI > Outbound, filtre Status = DeadLetter.
2. Inspecter les LastError : grouper par cause.
3. Pour chaque famille :
   • Cause résolue ⇒ ▶️ Replanifier.
   • Cause obsolète (ex. session de test, partenaire désaffilié) ⇒ ✖️ Annuler.
4. Confirmer dans le tableau de bord que la pastille repasse à Healthy.

6.5 Demander à Gireve l'intégration de nouveaux opérateurs (eMI3 IDs)

Côté Gireve, chaque opérateur (CPO ou EMSP) à qui l'on veut être visible doit être ajouté explicitement à notre périmètre de roaming par l'équipe CTM. Pour cela, Gireve attend une liste d'eMI3 IDs.

Reponse CTM Gireve du 2026-05-19 : « Concernant votre question à propos de l'intégration des opérateurs, il faut nous communiquer la liste d'emi3-ids des opérateurs à ajouter. »

Decision en cours (PP-IOP, mai 2026) — mono-CPO

Perimetre actuel : uniquement FR*MSI (ChargeMSI).

FR*CSI (CPO sister) figure dans la cible commerciale mais n'est pas encore pris en charge par le code : OcpiOptions.PartyId est unique et les 4 mappers (Session, Location, Cdr, Tariff) emettent tous avec party_id=MSI. Demander à Gireve d'ouvrir FR*CSI aujourd'hui creerait un canal de roaming sans gateway derriere.

Ne pas inclure FR*CSI dans le mail à CTM Gireve tant que le multi-CPO n'a pas ete livre. Voir la roadmap ci-dessous.

Roadmap multi-CPO (Option 2)

Quand un second CPO devra etre exposé sous notre gateway, l'option retenue est le multi-CPO dans un seul gateway (et non un second deploiement) :

1. OcpiOptions expose LocalParties[] { CountryCode, PartyId, Role, BusinessDetails, TenantId } à la place du couple unique CountryCode/PartyId.
2. Une nouvelle colonne ChargePoint.OcpiPartyId (ou un mapping via ChargePoint.TenantID -> ocpi.LocalParties) route chaque borne vers sa party.
3. Les 4 mappers (Session, Location, Cdr, Tariff) consomment un ILocalPartyResolver.For(chargePoint) au lieu de _options.PartyId.
4. CredentialsService publie tous les roles[] dans la reponse au handshake POST /credentials (OCPI 2.2.1 le supporte nativement).
5. Une seule paire .crt/.key Gireve suffit (un seul FQDN expose), mais on declarera plusieurs roles dans l'enveloppe credentials.

Ouvrir un ticket de suivi OCPI-multi-cpo avant d'envoyer FR*CSI a Gireve.

Format eMI3 attendu

Un eMI3 ID identifie un acteur (party) sur deux composants :

Element	Source OCPI	Exemple
<CountryCode>	country_code (ISO-3166-1 alpha-2)	FR, DE, BE
<PartyID>	party_id (3 caracteres alphanumeriques)	MSI, GIR, ION
eMI3 PartyID complet	<CC>*<PID> (separateur *)	FR*MSI, DE*ION

ChargeMSI = FR*MSI. Gireve = FR*GIR.

Source de verite cote ChargeMSI

La liste des operateurs avec qui ChargeMSI souhaite interoperer est materialisee dans ocpi.Partners. Requete pour preparer le mail a Gireve :

SELECT
    CONCAT(CountryCode, '*', PartyId) AS Emi3Id,
    DisplayName,
    Role,
    IsActive,
    Environment
FROM ocpi.Partners
WHERE TenantID  = 'production'   -- ou 'staging'
  AND IsActive  = 1
  AND PartyId <> 'GIR'           -- Gireve lui-meme n'est pas un operateur a router
ORDER BY CountryCode, PartyId;

Sortie type :

Emi3Id    DisplayName             Role   IsActive  Environment
--------  ----------------------  -----  --------  -----------
DE*ION    IONITY                  EMSP   1         Production
FR*BOU    Bouygues Energies       EMSP   1         Production
FR*FRE    Freshmile               CPO    1         Production
...

Procedure d'envoi

1. Exporter la requete SQL ci-dessus (Management Portal -> OCPI > Partners -> bouton Exporter CSV, ou copier le resultat SSMS).
2. Filtrer : ne garder que les IsActive = 1 et exclure FR*GIR.
3. Verifier que chaque partenaire est bien valide cote ChargeMSI :
   • contrat commercial signe ;
   • Role coherent avec ce que Gireve doit router (EMSP -> visibilite de nos bornes ; CPO -> visibilite de leurs bornes pour nos utilisateurs).
4. Envoyer par mail a l'adresse CTM Gireve (ctm@gireve.com) en reponse au thread d'onboarding. Inclure :
   • notre eMI3 (FR*MSI) et l'environnement vise (PP-IOP ou Production) ;
   • le tableau d'eMI3 IDs des operateurs a ajouter ;
   • pour chaque ligne, la direction souhaitee : sortant (ChargeMSI vers l'operateur), entrant (l'operateur vers ChargeMSI), ou bidirectionnel.

Modele de mail (perimetre mono-CPO PP-IOP, mai 2026) :

A : ctm@gireve.com
Objet : ChargeMSI (FR*MSI) - Liste des operateurs a integrer - PP-IOP

Bonjour,

Suite a votre demande, voici la liste des eMI3 a ajouter sur notre
perimetre Pre-Production (PP-IOP).

Notre identite CPO :
  FR*MSI  ChargeMSI (CPO)

Operateurs (EMSPs / CPOs partenaires) :
  eMI3 ID   Role  Direction        Nom
  --------  ----  ---------------  --------------------------
  ... (a completer depuis ocpi.Partners)

Note : l'identite FR*CSI evoquee en interne sera ajoutee dans une
prochaine iteration, apres livraison du support multi-CPO cote gateway.
Ne pas l'activer dans cette demande.

Merci de nous confirmer l'activation cote hub.
Cordialement,

5. Tracer l'envoi dans le suivi onboarding (Chargemsi.Docs/articles/ocpi/) et attendre la confirmation Gireve avant de lancer un push de locations ou un test de tokens vers le nouvel operateur.

Verification apres activation Gireve

Une fois Gireve confirme l'ajout :

-- Cote Inbound : on doit voir au moins un PUT /tokens/{country}/{party}/...
-- pour chaque EMSP active recemment.
SELECT TOP 50 ReceivedUtc, PartyId, CountryCode, Path, StatusCode
FROM ocpi.InboundMessages
WHERE Path LIKE '/ocpi/2.2.1/tokens/%'
ORDER BY ReceivedUtc DESC;

-- Cote Outbound : verifier que les locations partent bien vers Gireve
SELECT TOP 20 Status, Module, LastError, CreatedUtc
FROM ocpi.OutboundMessages
ORDER BY CreatedUtc DESC;

Si rien n'arrive 24h apres l'activation, relancer Gireve avec le correlation_id de notre mail.

---

7. Auditabilité

Toutes les actions destructives ou de configuration tracent une ligne Serilog :

Action	Log
Activation/désactivation partenaire	OCPI partner {PartyId}/{Country} toggled to {Active} by {User}
Révocation de token	OCPI credential {Id} revoked by {User}
Requeue outbound	Outbound OCPI message {Id} requeued by {User}
Annulation outbound	Outbound OCPI message {Id} cancelled by {User}

Les logs sont propagés au sink configuré dans Program.cs (Serilog). Voir Logs & monitoring pour la configuration des sinks.

---

8. FAQ

Q. Pourquoi le module n'apparaît-il pas dans le menu ? R. Il est conditionné par User.IsInRole("Admin"). Vérifier dans Utilisateurs > Rôles que le compte porte bien le rôle Admin.

Q. Le tableau de bord est vide alors que la gateway tourne. R. La chaîne de connexion OcppSqlServerProd du Management Portal doit pointer sur la même base que la gateway. Sans ça, le portail lit un schéma ocpi vide.

Q. Puis-je créer un partenaire depuis le portail ? R. Non. La création se fait lors du handshake POST /credentials (gateway). Le portail n'expose que de la lecture, la (dés)activation et la révocation. C'est intentionnel : on évite d'introduire un canal d'écriture parallèle qui divergerait des règles OCPI 2.2.1.

Q. À quoi correspond la fenêtre temps réel ? R. Polling AJAX toutes les 10 s sur /OcpiAdmin/Snapshot. Charge négligeable (une requête de comptage par catégorie).