STM.ICUCourriel.EAI — Spécification de l'état actuel (BizTalk)

---

Objectif

L'application BizTalk STM.ICUCourriel.EAI fournit une couche d'intégration pour l'envoi de courriels et le suivi des rejets (EAI = Enterprise Application Integration) pour la STM (Société de transport de Montréal). Ses responsabilités sont :

1. Envoi de courriels — Accepter les demandes d'envoi de courriels entrantes via un point de terminaison REST/HTTP, acheminer chaque message vers l'un des deux backends de livraison (Exchange Web Services / SMTP, ou SendGrid), et persister le résultat de la livraison dans une base de données SQL de suivi.
2. Réconciliation des rejets/suppressions — Sur un déclencheur planifié, interroger la base de données SQL de suivi pour les courriels envoyés par chaque canal et réconcilier les échecs de livraison (rebonds, blocages, rapports de spam, adresses invalides, NDR Exchange) dans cette base de données.

L'application est composée de deux assemblages BizTalk déployés comme une seule application BizTalk :

---

Systèmes externes

---

Points d'intégration / Endpoints

Emplacements de réception

Ports d'envoi

---

Flux de messages

1. EnvoyerCourriel (Coordinateur d'envoi de courriels)

Orchestration : STM.ICUCourriel.EAI.EnvoiCourriel.EnvoyerCourriel

Liaison de port BizTalk : MessageBox (liaison directe) — s'active sur tout message de type STM.ICUSchema.EAI.Schema.MessageUsager.Courriel arrivant du port de réception STM.ICUCourriel.EAI_EnvoiCourriel.

Déclencheur

POST HTTP entrant vers /icucourriel/api.svc/courriel portant une charge utile JSON désérialisée en MessageUsagerCourriel (STM.ICUSchema.EAI.Schema.MessageUsager.Courriel).

Étapes

1. Journalisation du début de traitement (DEBUT_TRAITEMENT_INFO).
2. Extraction de Source depuis la propriété de contexte du message STM.ICUSchema.EAI.Schema.Source.
3. Decide_FiltreValidation — appel de EnvoyerCourrielHelper.VerifierFiltreDestinataire(MessageUsagerCourriel) :

• True (le destinataire passe le filtre) :

1. Déterminer le service de livraison : Service = EnvoyerCourrielHelper.ObtenirServiceCourriel(Source) — retourne "SMTP" ou une autre valeur (p. ex. "SENDGRID").
2. Déterminer le nombre de lots : NbEnvoi = EnvoyerCourrielHelper.ObtenirNombreEnvoiParCourriel(MessageUsagerCourriel, Service).
3. Boucle IdxEnvoi de 1 à NbEnvoi :

• Construction du sous-message : MessageSousCourriel = EnvoyerCourrielHelper.ObtenirSousCourriel(MessageUsagerCourriel, IdxEnvoi, Service) (copie toutes les propriétés de contexte du message (*)).
• Decide_Service :
• Service == "SMTP" → appel EnvoyerEwsCourriel(MessageSousCourriel, out Statut, out ExtMessageId)
• sinon → appel EnvoyerSendGridCourriel(MessageSousCourriel, out ExtMessageId, out Statut, Source)
• Incrémentation de IdxEnvoi.
• False (destinataire filtré) :

1. Journalisation d'avertissement : "Impossible d'envoyer un courriel (Filtre)".
2. Génération d'un nouveau GUID comme ExtMessageId.
3. Affectation Statut = "Filtre", Service = "Aucun".
4. Appel SauvegarderTraitementCourriel(MessageUsagerCourriel, Service, ExtMessageId, Statut) pour persister l'enregistrement filtré.
5. Construction ResultatExecution = EnvoyerCourrielHelper.CreerResultatExecution(MessageUsagerCourriel, Statut).
6. Envoi ResultatExecution vers ResultatExecutionFiltrePort (liaison directe MessageBox → acheminé vers le port d'envoi FILE par filtre d'abonnement sur le type de message + medium = Courriel).
7. Journalisation de la fin de traitement (FIN_TRAITEMENT_INFO).

Points de décision / Gestion des erreurs

• L'orchestration elle-même ne contient pas de bloc scope/catch. Les exceptions non gérées se propagent au MessageBox BizTalk et résultent en une instance d'orchestration suspendue.
• Valeurs de Statut produites par cette orchestration : "Filtre" (lorsque filtré), ou la valeur retournée par les sous-orchestrations appelées ("Envoyé" ou "Echec").

Schémas de données référencés

• STM.ICUSchema.EAI.Schema.MessageUsager.Courriel — message canonique de courriel entrant (champ système source : STM.ICUSchema.EAI.Schema.Source)
• STM.ICUSchema.EAI.Schema.ResultatExecution — message de résultat d'exécution

---

2. EnvoyerEwsCourriel (Livraison Exchange / SMTP)

Orchestration : STM.ICUCourriel.EAI.EnvoiCourriel.EnvoyerEwsCourriel

Invocable : oui (appelée de façon synchrone depuis EnvoyerCourriel quand Service == "SMTP")

Paramètres en entrée : courriel (MessageUsager.Courriel) ; en sortie : Statut (string), MessageId (string)

Déclencheur

Appelée de façon synchrone depuis EnvoyerCourriel.

Étapes

1. Affectation Service = "SMTP".
2. Entrée dans une portée atomique synchronisée Scope_EnvoyerEwsCourriel :

• Construction de courrielEWS (type System.Xml.XmlDocument) par copie depuis courriel avec les propriétés de contexte.
• Envoi de courrielEWS vers SMTPPort → lié à STM.ICUCourriel.EAI_SMTP (adaptateur Static-DotNetSMTP). Il s'agit d'un envoi unidirectionnel ; BizTalk pilote la livraison SMTP réelle via le pipeline Snd_GenCourrielSMTP.
• Génération MessageId = EnvoyerCourrielHelper.ObtenriGuid().
• Affectation Statut = "Envoyé".
• Appel SauvegarderTraitementCourriel(courriel, Service, MessageId, Statut) — persiste l'enregistrement de succès.

1. Gestionnaire d'exception Catch_SMTPException (System.Exception) :

• Journalisation de l'erreur (SYSTEM_EXCEPTION_ERREUR, détail de l'exception).
• MessageId = courriel(STM.ICUSchema.EAI.Schema.IDMessage).
• Statut = "Echec".
• Appel SauvegarderTraitementCourriel(courriel, Service, MessageId, Statut) — persiste l'enregistrement d'échec.

Points de décision / Gestion des erreurs

• La portée atomique synchronisée encapsule toute la tentative de livraison.
• Sur toute System.Exception, le bloc catch enregistre le statut "Echec" et appelle SauvegarderTraitementCourriel ; l'orchestration retourne ensuite Statut = "Echec" à l'appelant.
• Note : la portée est synchronized (IsSynchronized=True), ce qui dans BizTalk fournit un accès exclusif à l'état partagé mais ne fournit pas de transactions de base de données.

Schémas de données référencés

• STM.ICUSchema.EAI.Schema.MessageUsager.Courriel
• System.Xml.XmlDocument (courrielEWS — XML brut envoyé à l'adaptateur SMTP)
• STM.ICUCourriel.EAI.EnvoiCourriel.Schema.TypedProcedure_dbo.SauvegarderTraitementCourriel (via la sous-orchestration SauvegarderTraitementCourriel)

---

3. EnvoyerSendGridCourriel (Livraison SendGrid)

Orchestration : STM.ICUCourriel.EAI.EnvoiCourriel.EnvoyerSendGridCourriel

Invocable : oui (appelée de façon synchrone depuis EnvoyerCourriel quand Service != "SMTP")

Paramètres en entrée : courriel (MessageUsager.Courriel), Source (string) ; en sortie : MessageId (string), Statut (string)

Déclencheur

Appelée de façon synchrone depuis EnvoyerCourriel.

Étapes

1. Affectation Service = "SENDGRID".
2. Entrée dans une portée atomique (non synchronisée) Scope_SendGridCourriel :

• Extraction de ReplyTo : si la propriété de contexte SMTP.From existe sur courriel, l'utiliser ; sinon chaîne vide.
• Construction de msgSendGridRequest (type SendGridCourrielSchema) :
• Corps : EnvoyerSendGridCourrielHelper.ObtenirSendGridMessage(courriel, Source, ReplyTo).
• En-tête de clé API : msgSendGridRequest(STM.WCFHttpHeaderBehavior.EAI.Schema.value) = EnvoyerSendGridCourrielHelper.ObtenirSendGridAPIKey().
• Envoi de msgSendGridRequest vers SendGridSendMailPort (opération SendMail, POST /mail/send).
• Réception de msgSendGridResponse (type System.Xml.XmlDocument) depuis SendGridSendMailPort.
• Extraction de MessageId depuis le contexte WCF.InboundHttpHeaders : EnvoyerSendGridCourrielHelper.ObtenirSendGridMessageId(msgSendGridResponse(WCF.InboundHttpHeaders)) — lit l'en-tête de réponse X-Message-Id.
• Journalisation "X-Message-Id:" + MessageId.
• Affectation Statut = "Envoyé".
• Appel SauvegarderTraitementCourriel(courriel, Service, MessageId, Statut).

1. Gestionnaire d'exception CatchException_SendGrid (System.Exception) :

• Journalisation de l'erreur.
• MessageId = courriel(STM.ICUSchema.EAI.Schema.IDMessage).
• Statut = "Echec".
• Appel SauvegarderTraitementCourriel(courriel, Service, MessageId, Statut).

Points de décision / Gestion des erreurs

• L'appel à l'API SendGrid est synchrone requête/réponse (SendGridSendMailPortType est requestresponse).
• La clé API SendGrid est récupérée à l'exécution depuis une méthode helper (ObtenirSendGridAPIKey()), non stockée comme propriété de contexte de message — le mécanisme réel de stockage du secret est opaque depuis le code d'orchestration.
• Le placeholder Authorization: Bearer setatruntime dans les HttpHeaders du port d'envoi indique que le jeton est injecté dans le contexte du message WCF par le comportement de point de terminaison STM.WCFHttpHeaderBehavior.EAI.Inspector en utilisant la valeur promue dans STM.WCFHttpHeaderBehavior.EAI.Schema.value.
• Nombre de réessais de liaison de port : 3, intervalle 5 s.

Schémas de données référencés

• STM.ICUSchema.EAI.Schema.MessageUsager.Courriel
• STM.ICUCourriel.EAI.EnvoiCourriel.Schema.SendGridCourrielSchema — Corps de l'API SendGrid v3 Mail Send :
• personalizations[].item (to, cc, bcc, substitutions)
• from (email, name)
• reply_to (email, name)
• subject
• content[] (type, value)
• attachments[] (content, filename)
• categories[]
• System.Xml.XmlDocument (réponse brute SendGrid)

---

4. SauvegarderTraitementCourriel (Persistance SQL — sous-orchestration partagée)

Orchestration : STM.ICUCourriel.EAI.EnvoiCourriel.SauvegarderTraitementCourriel

Appelée par : EnvoyerEwsCourriel, EnvoyerSendGridCourriel et EnvoyerCourriel (chemin filtre)

Cette orchestration est référencée dans tout le code, mais son fichier source .odx n'était pas inclus dans l'ensemble analysé. Son contrat est connu depuis le schéma et les sites d'appel :

• Entrée : courriel (MessageUsager.Courriel), Service (string), ExtMessageId/MessageId (string), Statut (string)
• Action SQL : TypedProcedure/dbo/SauvegarderTraitementCourriel
• Paramètres de procédure (de TypedProcedure.dbo.xsd) : courriels (ArrayOftypeCourriel), idMessage (max 100), enteteCourriel, source (max 100), externalMessageId (max 50), status (max 50), serviceCourriel (max 50), sujet
• Réponse : ReturnValue (int)
• Port d'envoi : STM.ICUCourriel.EAI_TraitementCourriel.WCF-SQL (unidirectionnel, livraison ordonnée)

---

5. TraiterRejets (Coordinateur de réconciliation des rejets)

Orchestration : STM.ICUCourriel.EAI.TraiteRejet.TraiterRejets

Liaison de port BizTalk : Réception depuis STM.ICUCourriel.EAI_Declencheur (adaptateur FILE).

Déclencheur

Arrivée de tout fichier *.xml dans ${RepertoireDeclenchement} (interrogé toutes les 60 secondes). Le contenu du fichier n'est pas consommé sémantiquement — il sert purement de déclencheur planificateur.

Étapes

1. Réception du message déclencheur msgDeclencheur (type System.Xml.XmlDocument).
2. Journalisation du début de traitement.
3. Construction de msgSelEAICourriel :

• Affectation cdInterface = "traiterRejets".
• Construction XML : .
• Remplissage du champ cdInterface.
• Capture dtExecution = System.DateTime.Now.

1. Envoi de msgSelEAICourriel vers selEAICourrielPort → STM.ICUCourriel.EAI_TraitementCourrielResponse.WCF-SQL, action TypedProcedure/dbo/selEAICourriel.
2. Réception de msgSelEAICourrielResponse — le jeu de résultats SQL des courriels en attente de réconciliation de rejets, filtré par cdInterface = "traiterRejets".
3. Exécution parallèle de 5 sous-orchestrations (toutes reçoivent msgSelEAICourrielResponse) :

• MettreAJourRejetServeurExchange — réconcilier les NDR Exchange
• MettreAJourBouncesSendGrid — récupérer les rebonds de l'API SendGrid et mettre à jour la BD
• MettreAJourBlocksSendGrid — récupérer les blocages de l'API SendGrid et mettre à jour la BD
• MettreAJourInvalidsSendGrid — récupérer les adresses invalides de l'API SendGrid et mettre à jour la BD
• MettreAJourSpamsSendGrid — récupérer les rapports de spam de l'API SendGrid et mettre à jour la BD

1. Construction de msgUpdEAICourriel :

• Construction XML : .
• Affectation cdInterface et dtDerniereExecution = dtExecution (l'horodatage capturé à l'étape 3).

1. Envoi de msgUpdEAICourriel vers updEAICourrielPort → STM.ICUCourriel.EAI_TraitementCourrielResponse.WCF-SQL, action TypedProcedure/dbo/updEAICourriel.
2. Réception de msgUpdEAICourrielResponse.
3. Journalisation de la fin de traitement.

Points de décision / Gestion des erreurs

• Aucun bloc scope/catch dans cette orchestration. Tout échec dans les branches parallèles ou les appels SQL suspend l'instance d'orchestration.
• Les 5 branches parallèles s'exécutent simultanément. BizTalk attend la complétion des 5 avant de passer à l'étape 7.

Schémas de données référencés

• STM.ICUCourriel.EAI.TraiteRejet.Schema.TypedProcedure_dbo.selEAICourriel — entrée de requête BD (champ cdInterface)
• STM.ICUCourriel.EAI.TraiteRejet.Schema.TypedProcedure_dbo.selEAICourrielResponse — jeu de résultats de requête BD (enregistrements de courriels en attente de réconciliation)
• STM.ICUCourriel.EAI.TraiteRejet.Schema.TypedProcedure_dbo.updEAICourriel — entrée de mise à jour BD (cdInterface, dtDerniereExecution)
• STM.ICUCourriel.EAI.TraiteRejet.Schema.TypedProcedure_dbo.updEAICourrielResponse

---

6. ObtenirTokenOAuth (Acquisition de jeton OAuth 2.0)

Orchestration : STM.ICUCourriel.EAI.TraiteRejet.ObtenirTokenOAuth

Invocable : oui (appelée depuis les sous-orchestrations de rejet qui interrogent Exchange Online)

Paramètres en sortie : token (string)

Déclencheur

Appelée de façon synchrone depuis les sous-orchestrations de réconciliation de rejets (spécifiquement MettreAJourRejetServeurExchange).

Étapes

1. Entrée dans une portée atomique Scope_OAuthToken :

• Construction de msgOAuthTokenRequest (type System.Xml.XmlDocument) :
• Corps depuis TraiterRejetsHelper.ObtenirTokenMessage().
• Promotion de la propriété de contexte tenantId : msgOAuthTokenRequest(STM.ICUCourriel.EAI.TraiteRejet.Schema.tenantId) = TraiterRejetsHelper.ObtenirTenantId().
• Envoi vers OAuthTokenPort → STM.ICUCourriel.EAI_OAuthToken.WCF-WebHttp, opération POST /{tenant-id}/oauth2/v2.0/token.
• La variable d'URL {tenant-id} est remplie au moment de l'envoi depuis la propriété de contexte tenantId promue (via BtsVariablePropertyMapping).
• Content-Type : application/x-www-form-urlencoded (pipeline Snd_wwwFormUrlEncoded).
• Réception de msgOAuthTokenResponse (type System.Xml.XmlDocument) — réponse de jeton JSON désérialisée par le pipeline Rcv_JsonToken.
• Extraction token = TraiterRejetsHelper.ExtraireAccessToken(msgOAuthTokenResponse).

1. Gestionnaire d'exception Catch_DeliveryFailureException (Microsoft.XLANGs.BaseTypes.DeliveryFailureException) :

• Journalisation de l'erreur ; affectation token = String.Empty.

1. Gestionnaire d'exception Catch_Exception (System.Exception) :

• Journalisation de l'erreur ; affectation token = String.Empty.

Points de décision / Gestion des erreurs

• DeliveryFailureException (échec de livraison BizTalk) et System.Exception (erreur générale) sont capturées. Dans les deux cas, token est mis à chaîne vide — les appelants reçoivent un jeton vide et sont censés le gérer, bien qu'aucune garde explicite en aval ne soit visible dans les orchestrations analysées.
• L'identifiant du locataire est récupéré dynamiquement via TraiterRejetsHelper.ObtenirTenantId() et promu comme propriété de contexte BizTalk. La valeur réelle n'est pas stockée dans les fichiers .odx.

Schémas de données référencés

• STM.ICUCourriel.EAI.TraiteRejet.Schema.ExchangeOnlinePropertySchema — schéma de propriété promue avec champ tenantId (xs:token), espace de noms https://STM.ICUCourriel.EAI.TraiteRejet.Schema.ExchangeOnlinePropertySchema
• System.Xml.XmlDocument (requête et réponse)

---

Problèmes connus et risques

1. Complexité du double backend de livraison sans stratégie de sélection claire

ObtenirServiceCourriel(Source) détermine si un message va vers EWS/SMTP ou SendGrid en fonction du champ Source. Cette logique de mappage réside entièrement dans une classe helper compilée (EnvoyerCourrielHelper) — elle n'est pas visible dans les schémas ou les orchestrations, créant une règle de routage opaque qui ne peut être modifiée sans redéployer l'assemblage.

2. La gestion de la clé API SendGrid est opaque

ObtenirSendGridAPIKey() est un appel de méthode helper sans surface de configuration visible. La clé est probablement stockée dans une application affiliée SSO BizTalk, un fichier de configuration ou une base de données. Il s'agit d'une lacune d'audit de sécurité.

3. Le jeton OAuth retourné comme chaîne vide en cas d'échec — pas de disjoncteur

Quand ObtenirTokenOAuth échoue, il retourne token = "". Il n'y a pas de garde dans les orchestrations appelantes pour sauter l'étape d'interrogation Exchange si le jeton est vide. Cela cause probablement une erreur HTTP 401 en aval contre l'API Exchange, résultant en une instance d'orchestration suspendue.

4. Aucune logique de réessai dans les orchestrations

Ni EnvoyerEwsCourriel ni EnvoyerSendGridCourriel ne réessaient en cas d'échec au niveau de l'orchestration. Le seul réessai disponible est le nombre de réessais du port d'envoi BizTalk (3 réessais, intervalle de 5 secondes pour SendGrid ; 3 réessais pour SMTP). Les instances en échec enregistrent simplement Statut = "Echec" sans escalade.

5. TraiterRejets n'a pas d'isolation d'erreur entre les branches parallèles

Les cinq branches parallèles dans TraiterRejets (Exchange, Bounces, Blocks, Invalids, Spam) ne partagent aucun try/catch. Un échec dans n'importe quelle branche fera suspendre l'instance complète de l'orchestration TraiterRejets, bloquant la mise à jour de l'horodatage updEAICourriel pour tous les canaux.

6. Le déclencheur basé sur fichier pour TraiterRejets est fragile

Le lot de rejets est déclenché par le dépôt de fichier dans ${RepertoireDeclenchement}. Il n'y a aucune garantie intégrée d'exécution unique, aucune lettre morte pour le fichier déclencheur, et aucun historique des fichiers déclencheurs.

7. Faute de frappe dans le code de production : ObtenriGuid() (et non ObtenirGuid())

Le nom de méthode ObtenriGuid (manque le second 'i' dans Obtenir) apparaît dans deux orchestrations (EnvoyerCourriel et EnvoyerEwsCourriel). Il s'agit d'une faute de frappe dans la classe helper compilée qui a été perpétuée en production.

8. ResultatExecution est écrit dans un répertoire du système de fichiers

Le message de résultat d'exécution est acheminé vers un port d'envoi FILE. Il s'agit d'un patron résiduel qui ne fournit aucune sémantique de file d'attente durable et dépend de la disponibilité du système de fichiers partagé.

9. La portée EWS est synchronisée (verrou exclusif), pas atomique avec rollback

Scope_EnvoyerEwsCourriel est synchronized, ce qui signifie qu'il utilise la portée synchronisée à longue durée de BizTalk. Cela ne fournit pas de rollback ACID ; cela ne fait que sérialiser l'accès aux objets partagés en mémoire. Dans un scénario multi-instance, cela ajoute de la contention sans fournir de sécurité transactionnelle.

10. La taille maximale de message sur le point de terminaison de réception est basse (206 536 octets)

L'emplacement de réception HTTP plafonne les messages à environ 202 Ko. Les courriels avec de grosses pièces jointes seraient rejetés au niveau de la couche de réception.

---

Dépendances

Dépendances d'exécution

Variables de configuration (paramétrées au déploiement)

---

Diagramme d'architecture

Le diagramme montre la topologie BizTalk complète pour STM.ICUCourriel.EAI. Les deux assemblages BizTalk (EnvoiCourriel et TraiteRejet) sont présentés comme des grappes d'orchestrations séparées.

graph LR
    subgraph InternalCallers["Appelants internes"]
        IC[Clients HTTP internes]
        FS_IN["Déclencheur système de fichiers\n${RepertoireDeclenchement}/*.xml"]
        SCHED["Adaptateur Schedule\npurge quotidienne 03:00"]
    end

    subgraph ReceiveLocations["Emplacements de réception"]
        RL1["EAI_EnvoiCourriel.WCF-WebHttp\n/icucourriel/api.svc POST /courriel\nAuth Basic · Rcv_Json · max 202 Ko"]
        RL2["EAI_Declencheur.FILE\n${RepertoireDeclenchement}/*.xml\ninterrogation 60s · lot 20"]
        RL3["EAI_PurgerTraitmentCourriel.Schedule\nAdaptateur Schedule · 03:00 quotidien"]
    end

    subgraph MessageBox["BizTalk MessageBox (pub/sub)"]
        MB[(MessageBox\nSQL Server)]
    end

    subgraph EnvoiCourrielAssembly["Assemblage : STM.ICUCourriel.EAI.EnvoiCourriel"]
        O1["EnvoyerCourriel\nFiltre → routage par Source\n→ boucle de lot"]
        O2["EnvoyerEwsCourriel\nLivraison SMTP\n(portée synchronisée)"]
        O3["EnvoyerSendGridCourriel\nLivraison SendGrid"]
        O4["SauvegarderTraitementCourriel\nHelper de persistance SQL"]
    end

    subgraph TraiteRejetAssembly["Assemblage : STM.ICUCourriel.EAI.TraiteRejet"]
        O5["TraiterRejets\nCoordinateur\n(fan-out parallèle × 5)"]
        O6["ObtenirTokenOAuth\nAcquisition de jeton Entra ID"]
        O7["MettreAJourRejetServeurExchange\nRéconciliation NDR Exchange"]
        O8["MettreAJourBouncesSendGrid"]
        O9["MettreAJourBlocksSendGrid"]
        O10["MettreAJourInvalidsSendGrid"]
        O11["MettreAJourSpamsSendGrid"]
    end

    subgraph SendPorts["Ports d'envoi"]
        SP1["EAI_SMTP\nStatic-DotNetSMTP\n${SMTPHostName}:${SMTPPort}"]
        SP2["EAI_SendGrid.WCF-WebHttp\n${UrlSendGrid}\nPOST /mail/send\nGET /suppression/*"]
        SP3["EAI_OAuthToken.WCF-WebHttp\nlogin.microsoftonline.com\nPOST /oauth2/v2.0/token"]
        SP4["EAI_TraitementCourriel.WCF-SQL\nSauvegarder / MettreAJour\n(unidirectionnel, ordonné)"]
        SP5["EAI_TraitementCourrielResponse.WCF-SQL\nMettreAJourStatus / selEAICourriel\nupdEAICourriel (bidirectionnel)"]
        SP6["EAI_ResultatExecution\nFILE · ${ResultatExecutionRepertoire}"]
    end

    subgraph ExternalSystems["Systèmes externes"]
        SMTP_SVC[Exchange Online\nEWS / SMTP]
        SG[SendGrid\nSaaS courriel]
        ENTRA[Microsoft Entra ID\noauth2/v2.0/token]
        SQL[(Base de données SQL ICU\n${IcuDbAdress})]
        FS_OUT[Système de fichiers\n${ResultatExecutionRepertoire}]
    end

    IC -->|POST /courriel JSON| RL1
    FS_IN -->|déclencheur *.xml| RL2
    SCHED -->|minuterie| RL3

    RL1 --> MB
    RL2 --> MB
    RL3 --> MB

    MB -->|MessageUsagerCourriel| O1
    MB -->|declencheur| O5

    O1 -->|Service=SMTP| O2
    O1 -->|Service!=SMTP| O3
    O1 -->|chemin Filtre| O4
    O2 -->|appel| O4
    O3 -->|appel| O4

    O5 -->|parallèle| O7
    O5 -->|parallèle| O8
    O5 -->|parallèle| O9
    O5 -->|parallèle| O10
    O5 -->|parallèle| O11
    O7 -->|appel| O6

    O2 --> SP1
    O3 --> SP2
    O6 --> SP3
    O8 --> SP2
    O9 --> SP2
    O10 --> SP2
    O11 --> SP2
    O4 --> SP4
    O5 --> SP5
    O1 --> SP6

    SP1 -->|SMTP/TLS| SMTP_SVC
    SP2 -->|HTTPS| SG
    SP3 -->|HTTPS| ENTRA
    SP4 -->|WCF-SQL| SQL
    SP5 -->|WCF-SQL| SQL
    SP6 --> FS_OUT
    RL3 -->|purge ADO| SQL

    style O6 fill:#f0ad4e,color:#000
    style SP6 fill:#ccc,color:#000

---

Diagramme de séquence

Cette séquence couvre le flux principal d'envoi de courriels (le chemin le plus complexe — envoi SendGrid multi-destinataires), suivi du déclenchement de la réconciliation des rejets.

sequenceDiagram
    autonumber
    actor Caller as Appelant interne
    participant RL as Emplacement de réception BizTalk<br/>(EAI_EnvoiCourriel)
    participant MB as BizTalk MessageBox
    participant EnvC as EnvoyerCourriel<br/>orchestration
    participant EnvSG as EnvoyerSendGridCourriel<br/>sous-orchestration
    participant EnvEWS as EnvoyerEwsCourriel<br/>sous-orchestration
    participant SaveDB as SauvegarderTraitementCourriel<br/>sous-orchestration
    participant SG as API SendGrid
    participant SMTP as Exchange / SMTP
    participant SQL as Base de données SQL ICU
    participant FS as Répertoire de résultats

    Caller->>RL: POST /icucourriel/api.svc/courriel (JSON, auth Basic)
    RL->>MB: Publication MessageUsagerCourriel (désérialisé)
    MB->>EnvC: Activation (liaison directe sur MessageUsager.Courriel)
    EnvC->>EnvC: ObtenirServiceCourriel(Source)\n→ "SMTP" ou "SENDGRID"
    EnvC->>EnvC: ObtenirNombreEnvoiParCourriel(message, Service)

    alt Destinataire filtré
        EnvC->>SaveDB: appel(Service=Aucun, Statut=Filtre)
        SaveDB->>SQL: exec SauvegarderTraitementCourriel
        EnvC->>MB: Publication ResultatExecution(Filtre)
        MB->>FS: Le port d'envoi FILE écrit le XML
    else Routage SMTP (par sous-message dans la boucle)
        loop IdxEnvoi 1..NbEnvoi
            EnvC->>EnvC: ObtenirSousCourriel(message, idx, SMTP)
            EnvC->>EnvEWS: appel(MessageSousCourriel)
            EnvEWS->>SMTP: Envoi via l'adaptateur Static-DotNetSMTP
            alt Succès
                EnvEWS->>SaveDB: appel(Statut=Envoyé, MessageId=nouveauGUID)
                SaveDB->>SQL: exec SauvegarderTraitementCourriel
            else System.Exception
                EnvEWS->>SaveDB: appel(Statut=Echec, MessageId=courriel.IDMessage)
                SaveDB->>SQL: exec SauvegarderTraitementCourriel
            end
        end
        EnvC->>MB: Publication ResultatExecution
        MB->>FS: Le port d'envoi FILE écrit le XML
    else Routage SendGrid (par sous-message dans la boucle)
        loop IdxEnvoi 1..NbEnvoi
            EnvC->>EnvC: ObtenirSousCourriel(message, idx, SENDGRID)
            EnvC->>EnvSG: appel(MessageSousCourriel, Source)
            EnvSG->>EnvSG: ObtenirSendGridAPIKey() → en-tête
            EnvSG->>SG: POST /mail/send {personalizations, from, subject, content}
            SG-->>EnvSG: 202 Accepted, en-tête X-Message-Id
            alt Succès
                EnvSG->>SaveDB: appel(Statut=Envoyé, MessageId=X-Message-Id)
                SaveDB->>SQL: exec SauvegarderTraitementCourriel
            else System.Exception
                EnvSG->>SaveDB: appel(Statut=Echec, MessageId=courriel.IDMessage)
                SaveDB->>SQL: exec SauvegarderTraitementCourriel
            end
        end
        EnvC->>MB: Publication ResultatExecution
        MB->>FS: Le port d'envoi FILE écrit le XML
    end

    Note over MB,SQL: La réconciliation des rejets s'exécute sur un déclencheur fichier séparé
    participant FT as Dépôt fichier déclencheur
    participant TR as TraiterRejets<br/>orchestration
    participant OA as ObtenirTokenOAuth<br/>sous-orchestration
    FT->>MB: Dépôt de fichier dans ${RepertoireDeclenchement}
    MB->>TR: Activation
    TR->>SQL: exec selEAICourriel(cdInterface=traiterRejets)
    SQL-->>TR: enregistrements de courriels en attente

    par 5 branches parallèles
        TR->>OA: appel (pour la branche Exchange)
        OA->>ENTRA as Entra ID: POST /oauth2/v2.0/token
        ENTRA-->>OA: access_token
        OA-->>TR: token
        TR->>SMTP: Requête NDR (API Exchange Graph)
    and
        TR->>SG: GET /suppression/bounces
    and
        TR->>SG: GET /suppression/blocks
    and
        TR->>SG: GET /suppression/invalid_emails
    and
        TR->>SG: GET /suppression/spam_reports
    end

    TR->>SQL: exec updEAICourriel(cdInterface, dtDerniereExecution)

---

Estimation de l'effort de migration

Effort total estimé : 22 jours-développeur (développeur unique ; ObtenirTokenOAuth peut être parallélisé avec TraiterRejets une fois l'échafaudage Durable Function en place).

---

Liste de vérification pour le développeur

Compléter ces étapes avant d'écrire tout code Azure pour cette intégration.

1. Récupération du code source

• ☐ Décompiler STM.ICUCourriel.EAI.Helper.dll avec ILSpy ou dnSpy. Exporter toutes les classes : EnvoyerCourrielHelper, EnvoyerSendGridCourrielHelper, TraiterRejetsHelper, AuthorizationManager, Logger. Il s'agit de l'élément à plus haut risque — toute la logique de routage, de filtrage et de récupération de clés réside ici.
• ☐ Depuis EnvoyerCourrielHelper, extraire et documenter la table de mappage ObtenirServiceCourriel(Source). C'est la règle qui décide SMTP vs SendGrid par source appelante. Elle ne peut pas être réimplémentée sans ces données.
• ☐ Depuis EnvoyerCourrielHelper, extraire ObtenirNombreEnvoiParCourriel — comprendre ce qui déclenche une boucle multi-sous-messages (est-ce le nombre de destinataires ? le nombre de pièces jointes ? autre chose ?).
• ☐ Depuis EnvoyerSendGridCourrielHelper, extraire ObtenirSendGridMessage pour comprendre comment le corps de la requête SendGrid v3 est construit à partir de MessageUsagerCourriel. Vérifier le mappage des champs personalizations, from, reply_to, attachments.
• ☐ Depuis TraiterRejetsHelper, extraire ObtenirTokenMessage, ObtenirTenantId, ExtraireAccessToken pour comprendre le corps de la requête de jeton OAuth (client_id, client_secret, scope). Ces valeurs doivent être migrées vers Key Vault.
• ☐ Décompiler STM.ICUCourriel.EAI.Helper.Securite.AuthorizationManager pour extraire la liste d'appelants autorisés. Cela devient l'audience JWT APIM ou la liste blanche de clés d'abonnement.

2. Extraction des identifiants et de la configuration

• ☐ Ouvrir l'outil d'administration SSO BizTalk. Lister toutes les applications affiliées pour STM.ICUCourriel. La clé API SendGrid y est stockée (ou dans un fichier de configuration — vérifier les deux). Extraire et stocker dans un classeur de secrets sécurisé.
• ☐ Récupérer toutes les valeurs des variables de déploiement : ${SMTPHostName}, ${SMTPPort}, ${UrlSendGrid}, ${IcuDbAdress}, ${IcuDbAdoAdress}, ${ResultatExecutionRepertoire}, ${RepertoireDeclenchement}. Les obtenir des scripts de déploiement BizTalk (.btdfproj ou fichiers de propriétés MSBuild).
• ☐ Auditer ${RepertoireDeclenchement} — compter combien de fichiers déclencheurs sont actuellement présents et s'ils sont en cours de traitement. Noter la cadence des dépôts de fichiers (manuel, planifié ou depuis un autre système). Cela détermine comment calibrer le remplacement par déclencheur minuterie.
• ☐ Auditer ${ResultatExecutionRepertoire} — déterminer si un système en aval lit les fichiers XML de résultats. Si oui, planifier un remplacement par callback Service Bus ou HTTP avant de décommissionner le port d'envoi FILE.

3. Base de données

• ☐ Se connecter à ${IcuDbAdress} et scripter toutes les procédures stockées : SauvegarderTraitementCourriel, MettreAJourTraitementCourriel, MettreAJourCourrielStatus, selEAICourriel, updEAICourriel, PurgerTraitementCourriel. Sauvegarder le DDL dans le contrôle de source.
• ☐ Inspecter la procédure stockée selEAICourriel : comprendre ce que retourne cdInterface = "traiterRejets" — noms et types de colonnes. Cela devient l'entrée de la Durable Function pour les 5 activités de rejet.
• ☐ Vérifier si SauvegarderTraitementCourriel est idempotent sur idMessage. Sinon, les sessions Service Bus (livraison ordonnée) sont obligatoires pour prévenir les écritures dupliquées.
• ☐ Confirmer avec l'équipe de base de données STM que updEAICourriel peut être appelé par activité (par type de rejet) plutôt qu'une seule fois à la fin, pour corriger le problème actuel d'horodatage tout-ou-rien.

4. Exchange Online

• ☐ Confirmer si l'adaptateur Static-DotNetSMTP achemine encore activement des courriels ou s'il a déjà été remplacé par SendGrid. Vérifier le mappage source ObtenirServiceCourriel pour toute source configurée comme "SMTP".
• ☐ Si Exchange est encore actif : travailler avec l'équipe d'administration Entra ID pour enregistrer une application avec la permission Graph Mail.Send (ou utiliser l'identité managée). Documenter la ou les boîtes aux lettres d'expéditeur utilisées par BizTalk.
• ☐ Clarifier le patron de réconciliation NDR Exchange dans MettreAJourRejetServeurExchange — interroge-t-il la boîte de réception d'une boîte aux lettres Exchange pour les messages rebondis, ou appelle-t-il un point de terminaison d'API Exchange ? Le code source BizTalk n'expose pas cela clairement ; nécessite la décompilation du helper de rejet.

5. Vérification opérationnelle

• ☐ Confirmer avec les opérations STM que l'échec indépendant des 5 branches parallèles de rejet dans TraiterRejets est acceptable. Dans BizTalk, un échec bloque le lot entier. Dans Azure, vous voudrez peut-être laisser les 4 autres branches continuer — il s'agit d'un changement de comportement nécessitant une approbation.
• ☐ Confirmer le calendrier de réconciliation des rejets : la cadence quotidienne à 03:00 est-elle correcte ? Devrait-elle être modifiée dans le remplacement Azure ?
• ☐ Examiner la faute de frappe ObtenriGuid() dans le code de production — confirmer que le GUID généré est véritablement aléatoire (équivalent UUID v4) pour que le code porté puisse utiliser Guid.NewGuid().ToString() sans problème de compatibilité de données.

6. Environnement de développement local

• ☐ Installer Azure Functions Core Tools v4, SDK .NET 8, extension Logic Apps pour VS Code, Azure CLI et Bicep CLI.
• ☐ Cloner le dépôt de migration. Créer une branche par orchestration (p. ex. feat/la-send-email, feat/fn-process-rejections).
• ☐ Provisionner une instance Azurite locale et un SQL Server local (ou Azure SQL de niveau développement) pour les tests d'intégration.
• ☐ Créer un fichier .env.local (ignoré par git) avec tous les placeholders d'identifiants extraits. Ne jamais committer de vrais secrets.