Principe de l'échange de fichiers avec Cegid XRP Ultimate On Demand

   En mode On Premise, le produit Cegid XRP Ultimate est installé sur les serveurs de l'entreprise (client) qui l'utilise.
Les utilisateurs ont accès directement au serveur de traitements pour y déposer des fichiers nécessaires en entrée de traitements ou pour consulter des fichiers générés en sortie par les traitements du produit.

   Lorsque le produit Cegid XRP Ultimate est utilisé en mode On Demand, l'accès au serveur de traitements devient impossible.
Dans ce mode, les échanges de fichiers entre le client et Cegid XRP Ultimate se complexifient.

   Cegid File Exchange (CFE) est un composant commun technique d'échange de fichiers entre un produit Cegid en mode SaaS et un client Cegid (utilisateur du produit).

   Upload : Transfert du fichier du container de stockage du client vers Cegid XRP Ultimate. Le transfert peut être réalisé par le client ou toute autre personne ayant été autorisée par le client, par exemple, un partenaire.

   Download : Transfert du fichier de Cegid XRP Ultimate vers le container de stockage du client.

   Pour gérer ses fichiers, le client utilise Microsoft Azure Storage (solution de stockage Cloud).

   Container de stockage Microsoft Azure Storage (Block Storage) : Espace d'échange, pour le client, des fichiers en provenance ou à destination de Cegid XRP Ultimate. Le terme "Conteneur" est aussi employé.

   CFE permet donc l'échange de fichiers entre les containers de stockage de Microsoft Azure Storage et le serveur de traitements de Cegid XRP Ultimate.

   Cegid File Exchange (CFE) utilise le service Microsoft Azure Storage pour stocker les échanges de fichiers sous forme de "blob", dans un container dédié au client.
Ce stockage est temporaire. Les fichiers résultats des requêtes ont une durée de rétention de 30 jours. Ils sont automatiquement supprimés.

   Chaque client possède son propre container privé. Aucun container n'est public.

   Les accès sont octroyés au niveau du container client.
Les accès aux containers sont protégés par des "clés sas", générées par CFE. Une "clé sas" est une délégation d'autorisation, il s'agit d'un jeton d'accès, avec une durée de vie limitée.
https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview

   L'accès se fait en lecture et écriture avec une "clé sas" qui a une durée de vie de 24h.
Cette "clé sas" ne peut être obtenue que par un utilisateur client authentifié (ou une API Key Client) auprès de CFE, avec un compte Cegid (Cegidlife).

   Paramètres de sécurité relatifs au "blob storage"

   Le "blob storage" est configuré pour accepter les demandes émanant des connexions sécurisées uniquement, toutes les demandes provenant d'une connexion non sécurisée sont rejetées.
     "Chiffrement en transit" des données transportées (Https).
https://docs.microsoft.com/fr-fr/azure/storage/common/storage-require-secure-transfer

   Les données stockées dans le "blob storage" sont "chiffrées au repos", empêchant Microsoft (notre fournisseur) de pouvoir lire les données clients.

   https://docs.microsoft.com/fr-fr/azure/storage/common/storage-service-encryption
https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview

   La première chose à faire est d'obtenir une API Key.

   Cette API Key permet :
- de connecter le serveur de traitements de Cegid XRP Ultimate avec CFE ;
- d'automatiser la lecture/écriture de fichiers dans son container CFE.

   Une API Key représente un TENANT (code SIC Cegid) sur un Service (en l'occurrence, le service "CFE" auquel a souscrit le client Cegid).
Une API Key a une durée de vie infinie jusqu'à révocation (bouton "Poubelle" dans l'écran ci-dessous).
L'utilisateur doit avoir les droits "Administrateur" de Cegid Account pour pouvoir générer une API Key.

   Dans le menu "Catalogue de service", repérez le service "Cegid File Exchange" (en filtrant éventuellement sur le "libellé"), puis cliquez sur la clé présente dans la colonne de droite.

   Saisir le nom de l'API Key que vous souhaitez créer, puis cliquez sur le bouton "Générer".

   Grâce aux boutons "Copier", conservez précieusement ("Copier/Coller" dans un éditeur de texte par exemple) les deux données suivantes (visibles une seule fois) :
- identifiant de la clé d'API ;
- secret de la clé d'API.

   Pour connecter le serveur de traitements de Cegid XRP Ultimate avec CFE, il faut saisir cette clé dans la gestion GTPWD de l'interface utilisateur Cegid XRP Ultimate.

   GTFLP - Paramétrage des flux
Type de flux unique CFE (Cegid File Exchange).

   GTFLX - Flux
Référence les fonctionnalités du produit Cegid XRP Ultimate, en mode On Demand, utilisant le type de flux CFE.

   GTFLT - Association traitement-flux
Liste des traitements (avec échange de fichiers) nécessaires à la réalisation de la fonctionnalité (flux).
Automatiquement pré-paramétré.

   CTFLF - Fichiers des flux
Consultation par flux (fonctionnalité) des fichiers échangés.

   Microsoft Azure Storage permet :
- de déposer manuellement des fichiers dans un container référencé dans GTFLX ;
- de récupérer manuellement des fichiers générés par Cegid XRP Ultimate dans un container référencé dans GTFLX.

   L'accès au Storage Azure peut se faire avec l'outil graphique Microsoft Azure Storage Explorer à télécharger et à installer.

   Une fois le logiciel installé :

   - Ouvrir la boîte de connexion : icône

   - Sélectionner la ressource "Conteneur d'objets blob"

   - Sélectionner "URL de signature d'accès partagé (SAS)", puis "Suivant"

   - Entrer, par Copier/Coller du champ "URL" de la gestion des flux (GTFLX), les informations de connexion dans le champ "URL SAS du conteneur d'objets blob" ; puis, "Suivant"

   - Terminer par "Connexion"

Folder : Organisation des fichiers dans un conteneur.
Chaque flux de transfert (soit en entrée, soit en sortie) est représenté par un conteneur dans Microsoft Azure Storage. Le conteneur est défini par environnement, base de données et type de flux (GTFLP).

in : Les fichiers sont toujours à déposer ici. Tout fichier déposé dans le folder "in" (ou arborescence sous folder "in") sera pris par le système et transmis au serveur de traitements, tout en respectant l'arborescence.

out : Les fichiers en sortie sont toujours ici. Dès lors qu'un fichier a été créé par Cegid XRP Ultimate sur le serveur de traitements, un programme systématique le récupère, puis le dépose dans le folder "out" en respectant l'arborescence.

archive : Chaque fichier transféré vers le serveur de traitements est sauvegardé dans le folder "archive" pour une durée paramétrée. La durée de conservation, exprimée en jours, dépend du flux (GTFLX).
Les fichiers en entrée sont déplacés et ne restent jamais dans le folder "in".
Une fois traités, les fichiers sont déplacés dans le sous-folder "ok" de "archive". Cela permet d'avoir un historique.
De plus, si le fichier comporte des erreurs, il est déplacé dans le sous-folder "hs".
Possibilité de corriger les erreurs et de déposer à nouveau le fichier dans le folder "in".

   Si vous souhaitez déposer ou récupérer automatiquement un ou des fichiers dans un container CFE, il faudra :
- utiliser cet API Key sur votre serveur qui gère les flux entrant ou sortant de Cegid XRP Ultimate ;
- télécharger et installer l'outil Azcopy : AzCopy est un utilitaire de ligne de commande que vous pouvez utiliser pour copier des "blobs" ou des fichiers vers ou depuis un compte de stockage :

   https://learn.microsoft.com/fr-fr/azure/storage/common/storage-use-azcopy-v10#download-azcopy

   Voici un exemple d'un script powershell qui permet de copier des fichiers depuis un container CFE à l'aide l'outil AzCopy.
Cet outil génère une "clé sas" et lance la copie AzCopy.
Script azCopyCfe.ps1 ci-dessous.
Avant d'utiliser le script, il faut saisir le path de Azcopy ($azcopy), l'API Key ID ($ApiKeyId) et l'API Key Secret ($ApiKeySecret) généré depuis CegidLife.

   Exemple de copie du fichier C:\Users\xxxxxx\Downloads\qev_20221209143040.txt dans le container 99980016-dvtmsq-setting :
     .\azcopyCfe.ps1 in 99980016-dvtmsq-setting C:\Users\xxxxxx\Downloads\qev_20221209143040.txt

   Exemple de copie du fichier qev_20221209143040.txt du container 99980016-dvtmsq-setting dans le fichier C:\Users\xxxxxx\Downloads\qev_20221209143040.txt :
      .\azcopyCfe.ps1 out 99980016-dvtmsq-setting C:\Users\xxxxxx\Downloads\qev_20221209143040.txt

# =======================================================================
# ++TIT Generate Azure SAS Token and launch azcopy
# ++PRG
# ++MAJ J1.01 - D1.001 - AH   - 13.12.22 -
# =======================================================================

#
# Path of azcopy.exe
#
$azcopy=".\azcopy.exe"
#
# Api Key ID CegidLife
#
$ApiKeyId="xxxxxxxxxxxxxxxxxx"
#
# Api Key Secret CegidLife
#
$ApiKeySecret="xxxxxxxxxxxxxxxxxx"

#
# Debug
#
# set-executionpolicy unrestricted
$DebugPreference="Continue"
$DebugPreference="SilentlyContinue"

#
# URL CFE
#
$UrlCfe="https://commoncomponents.cegid.cloud"

#
# Blob Azure
#
$blobAzure="https://dat839900stai03cfe.blob.core.windows.net"

#
# Direction (in/out)
#
$inOrOut=$args[0]
#
# Container Name : SIC-ENV-FLUX
#
$containerName=$args[1]
#
# Filename with path
#
$fileName=$args[2]

Write-Host "Direction            : "$inOrOut
Write-Host "ContainerName : "$containerName
Write-Host "Filename            : "$fileName

#
# Syntaxe
#
function Get-Syntaxe() {

  write-host 'azcopyCfe <in|out> <containerName:sic-env-flux> <filename>'
  Exit 1

}
if (!$inOrOut -or !$containerName -or !$fileName) {
    Get-Syntaxe
}
if ($inOrOut -ne 'in' -and $inOrOut -ne 'out') {
    Get-Syntaxe
}

#
# Generate CFE access token (Valid : 1 min)
#
Try
{
    $Response = Invoke-WebRequest -Headers @{"api-key-secret" = $ApiKeySecret} -Method GET -Uri $UrlCfe/cfe/tokenprovider/token?api-key-id=$ApiKeyId
    Write-Debug($Response)
}
Catch
{
    $ErrorMessage = $_.Exception.Message
    Write-Output($ErrorMessage)
    Exit 1
}

$ContentJson = ConvertFrom-Json $Response.Content
$AccessToken = $ContentJson.accessToken
$TenantId = $ContentJson.tenantId

Write-Debug ("AccessToken : "+$AccessToken)
Write-Debug ("TenantId     : "+$TenantId)

#
# Generate CFE SAS token (Valid : 24 hours)
#
Try
{
    $Response=Invoke-WebRequest -Headers @{"Authorization" = "Bearer "+$AccessToken; "x-tenantid" = $TenantId} -Method GET -Uri $UrlCfe/cfe/storage/api/V1/getsastokenw/$containerName$minutes
    Write-Debug($Response)
}
Catch
{
    $ErrorMessage = $_.Exception.Message
    Write-Output($ErrorMessage)
    Exit 1
}

$ContentJson = ConvertFrom-Json $Response.Content
$blobServiceUri = $ContentJson.blobServiceUri
$containerName = $ContentJson.containerName
$sasToken = $ContentJson.sasToken

Write-Debug ("blobServiceUri : "+$blobServiceUri)
Write-Debug ("containerName   : "+$containerName)
Write-Debug ("sasToken        : "+$sasToken)

#
# Name of filename without path
#
$Name=(Split-Path -Path $fileName -Leaf)
Write-Debug ("Name            : "+$Name)

#
# Parameters with azcopy 'in'
#
if ($inOrOut -eq 'in') {
    $fileOri=$fileName
    $fileDes=$blobAzure+"/"+$containerName+"/in/"+$Name+$sasToken
    $fromTo="LocalBlob"
    $md5="--put-md5"
}

#
# Parameters with azcopy 'out'
#
if ($inOrOut -eq 'out') {
    $fileOri=$blobAzure+"/"+$containerName+"/out/"+$Name+$sasToken
    $fileDes=$fileName
    $fromTo="BlobLocal"
    $md5="--check-md5=FailIfDifferent"
}

Write-Debug ("File Origin    : "+$fileOri)
Write-Debug ("File Destin    : "+$fileDes)

#
# Azcopy
#
$cmdPath = $azcopy
$cmdArgList = @(
    "copy"
          $fileOri
          $fileDes
    "--overwrite=true"
    "--from-to="+$fromTo
    $md5
)

& $cmdPath $cmdArgList