Classer les dépôts

Ranger chaque dépôt au bon endroit de votre système : le dossier d'un client, un contrat, un répertoire. Le moyen le plus fiable est d'étiqueter le message dès son envoi avec un paramètre de rappel, puis de lire cette étiquette dans le manifeste que reçoit votre gestionnaire.

Le principe

À l'envoi d'un message, ou à la création d'une enveloppe, votre application joint un identifiant interne : [{"Key":"NoDossier","Value":"A-1042"}].
SESAR reçoit la copie du message, ou la réponse à l'enveloppe, avec cet identifiant.
Le manifeste remis à votre gestionnaire le contient dans CallBackParameter.
Le gestionnaire valide la valeur et range le dépôt dans le dossier A-1042. Sans valeur valide, le dépôt va dans un dossier « À classer ».

Pourquoi un paramètre de rappel

	Paramètre de rappel	Objet, destinataires, noms de fichiers
Exactitude	La valeur posée à l'envoi revient telle quelle.	Texte libre, à interpréter.
Renseignements personnels	Un identifiant opaque suffit.	Adresses, noms et objet sont des renseignements personnels.
Cohérence	Les clés contextuelles donnent les mêmes noms de champ à toute l'organisation.	Varie selon la personne qui envoie.

Poser le paramètre

Envoi	Où	Voir
Message, avec ou sans fichiers	`CallBackParameters` des arguments d'envoi	Avis et paramètres de rappel
Enveloppe	`CallBackParameters` de l'enveloppe	Enveloppes
Documents à signer	Le même champ que pour un message	Avis et paramètres de rappel

Le format. Une liste JSON de paires Key / Value, et comme noms, les clés contextuelles de votre organisation : voir Format des paramètres de rappel.
Les enveloppes. Leurs paramètres ne sont conservés que si votre organisation utilise SESAR : ils accompagnent la copie de chaque réponse.
La confidentialité. Ces données ne sont pas confidentielles : Secure Exchanges et quiconque lit le message avec le SDK peuvent les lire. N'y mettez qu'un identifiant interne, jamais de nom, de courriel ni de numéro d'assurance sociale.
En .NET Framework, le SDK embarque Newtonsoft.Json sans l'exposer : ajoutez le paquet NuGet Newtonsoft.Json à votre projet pour utiliser JsonConvert.

Les dépôts qui le reçoivent

SESAR remplit CallBackParameter quand l'envoi en avait un :

Dépôt	`IsReply`	`CallBackParameter`
Copie d'un message envoyé par un utilisateur de votre organisation	`false`	Les paramètres de l'envoi
Réponse à une enveloppe	`true`	Les paramètres de l'enveloppe
Envoi sans paramètre de rappel		Vide

Le nom diffère selon le côté : CallBackParameters à l'envoi, CallBackParameter dans le manifeste. Le contenu est le même.

Lire et valider la valeur

La valeur vient de l'extérieur : votre gestionnaire ne doit s'en servir qu'après l'avoir validée. L'exemple suivant ne retient qu'un numéro de dossier au format attendu. Il écarte une valeur absente, illisible, d'une autre forme qu'une liste Key / Value, ou d'un format inattendu :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using Newtonsoft.Json;
using SecureExchangesSDK.Models.Messenging;
using SecureExchangesSDK.Models.Transport;

internal static class ClasserDepot
{
    // La clé contextuelle de votre organisation pour les dossiers, et le format de ses valeurs : à adapter.
    private const string CleDossier = "NoDossier";
    private static readonly Regex FormatDossier =
        new Regex(@"^[A-Z]-\d{4}$", RegexOptions.CultureInvariant, TimeSpan.FromMilliseconds(100));

    // Désérialisation typée, sans information de type venue du texte.
    private static readonly JsonSerializerSettings Lecture =
        new JsonSerializerSettings { TypeNameHandling = TypeNameHandling.None, MaxDepth = 4 };

    /// <summary>
    /// Numéro de dossier du dépôt, ou null s'il est absent, illisible ou d'un format inattendu :
    /// le dépôt va alors dans « À classer ».
    /// </summary>
    internal static string NumeroDossier(StoreManifest manifest)
    {
        string brut = manifest?.CallBackParameter;
        if (string.IsNullOrWhiteSpace(brut))
        {
            return null;
        }

        List<CallBackParameter> parametres;
        try
        {
            parametres = JsonConvert.DeserializeObject<List<CallBackParameter>>(brut, Lecture);
        }
        catch (JsonException)
        {
            return null; // pas une liste Key / Value : chaîne libre, ou paramètres que SESAR n'a pas pu lire
        }

        string valeur = parametres?.FirstOrDefault(p => p != null && p.Key == CleDossier)?.Value;
        if (valeur == null)
        {
            return null;
        }

        try
        {
            // La valeur vient de l'extérieur : seul le format attendu sert de nom de dossier.
            return FormatDossier.IsMatch(valeur) ? valeur : null;
        }
        catch (RegexMatchTimeoutException)
        {
            return null;
        }
    }
}

Dans le gestionnaire (voir Créer un gestionnaire) :

public override async Task<IntegrationResult> ProcessAsync(StoreManifest manifest, WebhookContext context)
{
  string dossier = ClasserDepot.NumeroDossier(manifest) ?? "A-classer";
  // Déposez les fichiers dans ce dossier de votre système. GetTrackingId(manifest) identifie
  // le dépôt : il sert à écarter un doublon si SESAR renvoie la requête.
  ...
}

Avant d'écrire dans le dossier, vérifiez aussi qu'il existe dans votre système et que le dépôt peut y aller : un numéro bien formé n'est pas forcément un dossier de ce client.

Le dossier « À classer »

Rangez-y tout dépôt sans valeur valide, et prévenez une personne. Ne déduisez jamais le dossier de l'objet ou des destinataires.
Répondez quand même par une réussite (IntegrationResult.Ok) : le dépôt est bien reçu. Un échec ferait renvoyer la requête par SESAR, alors que la valeur manquera toujours. Réservez l'échec aux erreurs passagères, comme un système cible indisponible.
Ne mettez pas de renseignements personnels dans les noms de dossiers ou de fichiers. Ces métadonnées sont visibles dans votre système, ses journaux et ses résultats de recherche, même quand le contenu est protégé.

Combiner avec l'état de la signature

Le manifeste porte aussi deux indicateurs, décrits ainsi dans le code du SDK. Ils peuvent servir de second axe de classement :

Champ	Description dans le SDK
`ContainsSignsFiles`	Le dépôt contient des fichiers à signer.
`ContainsFinalVersionSignedFiles`	Le dépôt contient la version finale de fichiers signés.

Vérifiez leur valeur sur vos propres dépôts avant de vous y fier. Sur un serveur de test, le connecteur Système de fichiers enregistre chaque manifeste en clair, ce qui permet de les examiner ; supprimez ces fichiers après l'essai, car ils contiennent des renseignements personnels.

Points à valider

Version finale signée. Le dépôt de la version finale d'un document signé garde-t-il les paramètres de rappel de l'envoi d'origine ? Vérifiez-le sur un dépôt réel avant de classer les documents signés par ce moyen.
Envois sans le SDK. La saisie de paramètres de rappel depuis le module Outlook ou depuis l'interface web n'est pas décrite ici. Les envois qui en sont dépourvus arrivent dans « À classer ».

Table of Contents