Classify drops

File each drop in the right place in your system: a client's case file, a contract, a directory. The most reliable way is to tag the message when it is sent with a callback parameter, then read this tag in the manifest that your handler receives.

How it works

When sending a message, or creating an envelope, your application attaches an internal identifier: [{"Key":"CaseNumber","Value":"A-1042"}].
SESAR receives the copy of the message, or the reply to the envelope, with this identifier.
The manifest given to your handler contains it in CallBackParameter.
The handler validates the value and files the drop in the A-1042 folder. Without a valid value, the drop goes to a "To be sorted" folder.

Why a callback parameter

	Callback parameter	Subject, recipients, file names
Accuracy	The value set when sending comes back unchanged.	Free text, to be interpreted.
Personal information	An opaque identifier is enough.	Addresses, names and subject are personal information.
Consistency	Contextual keys give the same field names across the organization.	Varies with the sender.

Setting the parameter

Sending	Where	See
Message, with or without files	`CallBackParameters` of the send arguments	Notifications and callback parameters
Envelope	`CallBackParameters` of the envelope	Envelopes
Documents to sign	The same field as for a message	Notifications and callback parameters

Format. A JSON list of Key / Value pairs, with your organization's contextual keys as names: see Callback parameter format.
Envelopes. Their parameters are kept only if your organization uses SESAR: they come with the copy of each reply.
Confidentiality. This data is not confidential: Secure Exchanges, and anyone who reads the message with the SDK, can read it. Put only an internal identifier in it, never a name, an email address or a social insurance number.
On .NET Framework, the SDK embeds Newtonsoft.Json without exposing it: add the Newtonsoft.Json NuGet package to your project to use JsonConvert.

Drops that receive it

SESAR fills CallBackParameter when the sending had one:

Drop	`IsReply`	`CallBackParameter`
Copy of a message sent by a user of your organization	`false`	The parameters of the sending
Reply to an envelope	`true`	The parameters of the envelope
Sending without a callback parameter		Empty

The name differs on each side: CallBackParameters when sending, CallBackParameter in the manifest. The content is the same.

Reading and validating the value

The value comes from outside: your handler must use it only after validating it. The following example keeps only a case number in the expected format. It discards a value that is missing, unreadable, not a Key / Value list, or in an unexpected format:

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 ClassifyDrop
{
    // Your organization's contextual key for case files, and the format of its values: adapt them.
    private const string CaseKey = "CaseNumber";
    private static readonly Regex CaseFormat =
        new Regex(@"^[A-Z]-\d{4}$", RegexOptions.CultureInvariant, TimeSpan.FromMilliseconds(100));

    // Typed deserialization, with no type information taken from the text.
    private static readonly JsonSerializerSettings Reading =
        new JsonSerializerSettings { TypeNameHandling = TypeNameHandling.None, MaxDepth = 4 };

    /// <summary>
    /// Case number of the drop, or null when it is missing, unreadable or in an unexpected format:
    /// the drop then goes to "To be sorted".
    /// </summary>
    internal static string CaseNumber(StoreManifest manifest)
    {
        string raw = manifest?.CallBackParameter;
        if (string.IsNullOrWhiteSpace(raw))
        {
            return null;
        }

        List<CallBackParameter> parameters;
        try
        {
            parameters = JsonConvert.DeserializeObject<List<CallBackParameter>>(raw, Reading);
        }
        catch (JsonException)
        {
            return null; // not a Key / Value list: free text, or parameters that SESAR could not read
        }

        string value = parameters?.FirstOrDefault(p => p != null && p.Key == CaseKey)?.Value;
        if (value == null)
        {
            return null;
        }

        try
        {
            // The value comes from outside: only the expected format is used as a folder name.
            return CaseFormat.IsMatch(value) ? value : null;
        }
        catch (RegexMatchTimeoutException)
        {
            return null;
        }
    }
}

In the handler (see Create a handler):

public override async Task<IntegrationResult> ProcessAsync(StoreManifest manifest, WebhookContext context)
{
  string folder = ClassifyDrop.CaseNumber(manifest) ?? "to-be-sorted";
  // Put the files in this folder of your system. GetTrackingId(manifest) identifies the drop:
  // use it to discard a duplicate if SESAR sends the request again.
  ...
}

Before writing to the folder, also check that it exists in your system and that the drop may go there: a well-formed number is not necessarily this client's case file.

The "To be sorted" folder

Put every drop without a valid value there, and notify a person. Never infer the folder from the subject or the recipients.
Still answer with a success (IntegrationResult.Ok): the drop was received. A failure would make SESAR send the request again, while the value will always be missing. Keep failures for temporary errors, such as an unavailable target system.
Do not put personal information in folder or file names. This metadata is visible in your system, its logs and its search results, even when the content is protected.

Combining with the signature state

The manifest also carries two flags, described as follows in the SDK code. They can serve as a second classification axis:

Field	Description in the SDK
`ContainsSignsFiles`	The drop contains files to sign.
`ContainsFinalVersionSignedFiles`	The drop contains the final version of signed files.

Check their value on your own drops before relying on them. On a test server, the File system connector saves each manifest in clear text, so you can examine them; delete these files after the test, since they contain personal information.

Points to validate

Final signed version. Does the drop of the final version of a signed document keep the callback parameters of the original sending? Check it on a real drop before classifying signed documents this way.
Sendings without the SDK. Entering callback parameters from the Outlook add-in or from the web interface is not described here. Sendings without them go to "To be sorted".

Table of Contents