14. Module de collecte

14.1. Introduction

14.1.1. Documents de référence

Document	Date de la version
NF Z 44022 – MEDONA – Modélisation des données pour l’archivage	18/01/2014
Standard d’échange de données pour l’archivage – SEDA – v. 2.1	06/2018
Standard d’échange de données pour l’archivage – SEDA – v. 2.2	02/2022
Standard d’échange de données pour l’archivage – SEDA – v. 2.3	06/2024
Vitam – Structuration des Submission Information Package (SIP)
Vitam – Modèle de données
Vitam – Ontologie
Vitam – Schéma
Vitam – Profils d’archivage
Vitam – Profils d’unité archivistiques

14.1.2. Présentation du document

Le document présente les fonctionnalités associées à l’utilisation du module de collecte dans la solution logicielle Vitam.

Il s’articule autour des axes suivants :

une présentation du module de collecte ;
une présentation des mécanismes mis en œuvre dans la solution logicielle Vitam pour prendre en compte les opérations de collecte, en application du SEDA ;
des conseils de mise en œuvre.

Le présent document décrit les fonctionnalités qui sont offertes par la solution logicielle Vitam au terme de la version 8.1 (printemps 2025). Il a vocation à être amendé, complété et enrichi au fur et à mesure de la réalisation de la solution logicielle Vitam et des retours et commentaires formulés par les ministères porteurs et les partenaires du programme.

14.2. Présentation du module de collecte

14.2.1. Qu’est-ce que la collecte d’archives ?

La collecte d’archives désigne l’ensemble des opérations qui vont conduire au transfert d’un ensemble d’archives :

d’un service producteur à un service d’archives,
d’un service d’archives intermédiaires à un service d’archives définitives.

Un versement correspond à un ensemble d’archives faisant l’objet du transfert.

Le transfert matérialise l’opération visant à transférer la responsabilité de la conservation des archives d’un service à un autre.

La collecte d’archives peut intervenir à plusieurs occasions :

Un service producteur soumet un versement à un service d’archives ;
La collecte peut être à l’initiative d’un service d’archives, dans le cadre d’une campagne de collecte d’archives ;
Des règles de gestion associées à des archives arrivent à échéance et impliquent un transfert de responsabilité en termes de conservation de ces dernières et, de fait, un transfert vers un autre service d’archivage.

La manière de procéder au transfert d’archives est définie dans la norme NF Z 44-022 et dans sa déclinaison pour les acteurs du service public, le Standard d’échanges de données pour l’archivage (SEDA).

Le versement, pouvant également être nommé transfert ou transaction, s’effectue en deux temps :

la soumission d’un ensemble d’archives à verser en vue de :
- vérifier son contenu et, le cas échéant, procéder à des traitements (ex. suppression de documents, renommage, etc.) ;
- documenter et contextualiser le versement, par l’ajout d’informations sur le service producteur, son contenu, ses règles de gestion ;
après validation de l’ensemble d’archives candidates à l’archivage par les parties concernées, transfert des archives en vue d’en assurer leur conservation et transfert de la responsabilité liée à leur conservation.

Au préalable de versements, une politique ou stratégie de versement est définie par le service d’archives, en termes de rôles et responsabilités, mais aussi de contenu attendu. Elle est définie dans un contrat de versement, dont une partie est matérialisée dans un projet de versement et un contrat d’entrée.

14.2.2. Qu’est-ce que le module de collecte ?

La solution logicielle Vitam met à disposition un module de collecte en vue de recevoir des ensembles hétérogènes d’archives, de paramétrer leur réception, de procéder à des traitements sur ces archives et de les transférer pour conservation dans le système d’archivage électronique. Ce module :

constitue un service du back-office de la solution logicielle Vitam ;
est utilisé par l’APP « Collecte et préparation des versements » du front-office VitamUI.

Ce module intervient en amont du transfert (ou versement) d’archives dans la solution logicielle Vitam. Son installation, ainsi que son utilisation, sont optionnelles.

Positionnement du module de collecte en amont du versement

Il permet de :


Configurer des versements	Définir un projet de versement et paramétrer : - acteurs et références génériques, - un rattachement automatisé à une position dans l’arborescence, avec ou sans paramétrages de conditions de rattachement, - une clôture automatique après validation du versement, - le formatage des données entrantes.
(Pré-)Verser les archives	Collecter depuis l’extérieur un ensemble d’archives, caractérisées par des métadonnées et des fichiers numériques, et constituer : - des (pré-)versements (ou transactions) automatisés émanant d’un système d’information externe - des (pré-)versements (ou transactions) manuels et unitaires : a) constitués par exemple d’arborescences bureautiques ou de messageries, b) réalisés depuis des interfaces, notamment celles de l’APP « Collecte et préparation des versements » du front-office VitamUI.
Consulter les (pré-)versement	Consulter : - la liste des projets de versement et des (pré-)versements (ou transactions) en attente, - un projet de versement en particulier, c’est-à-dire sa description, les informations contextuelles et la position de rattachement dans le tenant de destination, - le contenu d’un (pré-)versement (ou transaction), c’est-à-dire la liste des archives associées, une unité archivistique en particulier et, le cas échéant, l’objet numérique associé.
Traiter les archives	Procéder à des traitements archivistiques tels que : - définition de métadonnées contextuelles, - identification de format, - calcul d’empreintes, - calcul du poids de l’objet numérique, - réorganisation d’arborescence, - ajout de dossiers et d’objets numériques, - mise à jour de métadonnées descriptives et de gestion, - suppression d’arborescences et/ou d’objets numériques, - tri, dédoublonnage (services non implémentés), - gestion de statuts (ex. réouverture d’un (pré-)versement en erreur), - suppression de projets et de (pré-)versements, - etc.
Transférer les archives	- Générer un SIP conforme au Standard d’échanges de données pour l’archivage (SEDA) et le transférer dans le système d’archivage électronique pour conservation. - Suppression automatisée d’un (pré-)versement

14.2.3. Pourquoi, quand et comment utiliser le module de collecte ?

Le module de collecte permet de :

faciliter, voire automatiser, les versements (ou transactions) d’archives, depuis un service externe vers la solution logicielle Vitam ;
le cas échéant, effectuer un contrôle supplémentaire sur les projets de versement et leur contenu, en vue de vérifier la qualité des données, en amont de leur transfert dans un système d’archivage électronique ;
enrichir les métadonnées (notamment par l’identification de formats, le calcul d’empreintes et du poids de l’objet numérique, ou encore la mise à jour des métadonnées descriptives et de gestion) ;
proposer un format pivot et générique pour les services externes souhaitant verser des archives au sein de la solution logicielle Vitam ;
améliorer l’interopérabilité entre les systèmes d’information.

L’utilisation du module de collecte peut être envisagée dans les cas suivants :

versements de flux applicatifs, afin de les automatiser ;
versements de dossiers ou de documents dits « sériels », obéissant strictement à des règles de nommage et de description uniformes (par exemple, des images numérisées par un service d’archives) ;
versements réguliers et récurrents d’un même type d’archives par différents services producteurs et donc répondant à la volonté de disposer d’une description homogène, y compris pour faciliter les recherches sur celles-ci ;
versements ponctuels d’archives hétérogènes, quel que soit leur type (bureautique, audiovisuel, etc.).

En outre, il peut être utilisé de manière différente en permettant de :

en faisant appel uniquement à ses services back-office et ses API, automatiser des flux de versements émanant de systèmes d’information ;
construire des interfaces, en appelant ses API permettant de générer un SIP, en vue de faciliter la saisie d’un bordereau de transfert et la préparation d’un versement ;
utiliser les interfaces de l’APP « Collecte et préparation des versements » du front-office VitamUI.

14.3. Mécanismes mis en œuvre dans la solution logicielle Vitam

La solution logicielle Vitam offre à un service d’archives plusieurs fonctionnalités lui permettant de collecter des archives au moyen du module de collecte :

la configuration des (pré-)versements (ou transactions) au moyen de la définition d’un projet de versement ;
leur (pré-)versement (ou collecte) dans le module ;
leur recherche et leur consultation ;
leur gestion et leur traitement ;
leur transfert vers les espaces de conservation pérennes de la solution logicielle Vitam.

14.3.1. Configuration

14.3.1.1. Définitions

Dans la solution logicielle Vitam, il est possible de configurer le versement de un à plusieurs SIP conforme(s) au Standard d’échanges des données pour l’archivage (SEDA) en initialisant un projet de versement au sein du module de collecte.

Un projet de versement est propre à chaque tenant de la solution logicielle Vitam.

Il permet de préconfigurer dans une base de données dédiée, sous forme d’enregistrements JSON, les informations relatives à :

des métadonnées correspondant à l’en-tête du message ArchiveTransfer (Base Collect > Collection Project),
le rattachement automatisé à :
- une position dans le tenant de destination,
- une à plusieurs position(s) en fonction de la définition de conditions à respecter dans le versement,
les métadonnées descriptives et de gestion attendues dans le cas d’un versement en lot d’archives,
la gestion automatisée des transactions,
la fréquence des transferts vers la solution logicielle Vitam, etc. (service non implémenté).

Les fonctionnalités ont été conçues et réalisées de manière à prendre en compte 1 à n transaction(s) pour un projet de versement.

Un projet de versement est modifiable.

Point d’attention :

La création et la modification d’un projet de versement dans le module de collecte ne sont pas journalisées dans le journal des opérations.
Il est recommandé d’avoir une seule transaction en cours d’alimentation pour un projet de versement.
Il n’est pas recommandé de modifier un projet de versement lorsqu’une transaction est en cours d’alimentation.

14.3.1.2. Création d’un projet de versement

14.3.1.2.1. Utilisation des API

L’envoi et l’enregistrement d’un projet de versement dans le module de collecte s’effectue au moyen d’une commande de création d’un projet de versement.

Point d’attention : la création d’un projet de versement est un prérequis à la création des transactions (ou versements).

Lors de la création d’un projet de versement sont envoyées :

les métadonnées correspondant aux informations dites d’en-tête du bordereau telles que l’identifiant du message ou le contrat d’entrée ;
le cas échéant, les paramètres suivants :
- position de rattachement et/ou paramètres de rattachement automatisés,
- gestion automatisée des transactions,
- transformation des données entrantes.

Un projet de versement peut comporter les éléments suivants[1] :

Champ	Description
Name	Intitulé du projet de versement (champ facultatif)[2].
ArchivalAgreement	Identifiant du contrat d’entrée utilisé pour réaliser l’entrée, destiné à alimenter le champ ArchivalAgreement du message ArchiveTransfer (champ facultatif).
MessageIdentifier	Identifiant du lot d’objets, utilisé pour identifier les versements, destiné à alimenter le champ MessageIdentifier du message ArchiveTransfer (champ facultatif).
Comment	Précisions sur la demande de transfert destiné à alimenter le champ Comment du message ArchiveTransfer (champ facultatif).
OriginatingAgencyIdentifier	Identifiant du service producteur, destiné à alimenter le champ OriginatingAgencyIdentifier du message ArchiveTransfer (champ facultatif).
SubmissionAgencyIdentifier	Identifiant du service versant, destiné à alimenter le champ SubmissionAgencyIdentifier du message ArchiveTransfer (champ facultatif).
ArchivalAgencyIdentifier	Identifiant du service d’archivage, destiné à alimenter le champ Identifier du bloc ArchivalAgency du message ArchiveTransfer (champ facultatif).
TransferringAgencyIdentifier	Identifiant du service de transfert, destiné à alimenter le champ Identifier du bloc TransferringAgency du message ArchiveTransfer (champ facultatif).
ArchivalProfile	Identifiant du profil d’archivage utilisé pour réaliser l’entrée, destiné à alimenter le champ ArchivalProfile du message ArchiveTransfer (champ facultatif).
UnitUp	Identifiant de l’unité archivistique à laquelle rattacher automatiquement la ou les unité(s) racine(s) des transactions associées au projet de versement (champ facultatif).
UnitUps	Liste de conditions permettant un rattachement automatisé de l’(des) unité(s) racine(s). A une métadonnée (MetadataKey) définissant une valeur spécifique (MetadataValue) peut être associée une unité archivistique de rattachement (UnitUp) (champs facultatifs).
AcquisitionInformation	Modalité d’entrée. Champ destiné à alimenter le champ AcquisitionInformation du message ArchiveTransfer (champ facultatif).
LegalStatus	Statut légal des archives, destiné à alimenter le champ LegalStatus du message ArchiveTransfer (champ facultatif). Si le champ est renseigné, les valeurs attendues sont : « Public Archive », « Private Archive », « Public and Private Archive ».
AutomaticIngest	Paramètre permettant d’automatiser l’envoi de transaction(s) vers la solution logicielle Vitam (champ facultatif).
TransformationRules	Paramètre permettant de lister des règles de transformation à opérer sur les données entrantes (champ facultatif).

Point d’attention : Au terme de la version 8.1 :

on ne peut pas inclure de règles de gestion dans un projet de versement ;
aucun contrôle n’est effectué avec les référentiels et unités archivistiques de rattachement présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de :
- veiller à inclure des références (ex. service producteur, contrat d’entrée, etc.) existant dans la solution, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.
la plupart des champs d’un projet de versement sont facultatifs. Néanmoins, il est recommandé d’indiquer un intitulé (Name) et les éléments obligatoires à la génération d’un SIP :
- le contrat d’entrée (champ ArchivalAgreement),
- l’identifiant du message (champ MessageIdentifier),
- le service producteur (champ OriginatingAgencyIdentifier),
- le service d’archivage (champ Identifier du bloc ArchivalAgency),
- le service responsable du transfert (champ Identifier du bloc TransferringAgency).

Exemple : requête de création d’un projet de versement

  POST {{url}}/collect-external/v1/projects
  accept: application/json
  content-type: application/json
  Content-Length: 401
  X-Tenant-Id: {{tenant}}
  
  {
   "Name": "Versements du SG",
   "ArchivalAgencyIdentifier": "Vitam",
   "TransferringAgencyIdentifier": "RATP",
   "OriginatingAgencyIdentifier": "RATP",
   "SubmissionAgencyIdentifier": "RATP",
   "MessageIdentifier": "20200131-000013",
   "ArchivalAgreement":"IC-000001",
   "Comment": "SG – bureautique",
   "UnitUp": "aeaqaaaaaehedmpfaay5gambwxsspviaaaba"
  }

Cette action provoque :

la création d’un enregistrement dans la base de données MongoDB, dans la collection « Project » (base Collect) ;
l’ajout des informations suivantes, associées à cet enregistrement :
- un statut (champ « Status ») dont la valeur est égale à « OPEN »,
- une date de création (champ « CreationDate ») dont la valeur est égale à la date de création de l’enregistrement,
- une date de dernière modification (champ « LastUpdate ») dont la valeur est égale à la date de création de l’enregistrement.

Exemple : enregistrement du projet de versement dans la collection « Project »

  {
   _id: 'aeeaaaaaaghj3m7nabjocamcdqvqqviaaaaq',
   Name: 'Versements du SG',
   Context: {
   ArchivalAgreement: 'IC-000001',
   MessageIdentifier: '20200131-000013',
   ArchivalAgencyIdentifier: 'Vitam',
   TransferirngAgencyIdentifier: 'RATP',
   OriginatingAgencyIdentifier: 'RATP',
   SubmissionAgencyIdentifier: 'RATP',
   Comment: 'SG - bureautique',
   UnitUp: 'aeaqaaaaaehedmpfaay5gambwxsspviaaaba'
   },
   CreationDate: '2022-08-23T09:05:52.242',
   LastUpdate: '2022-08-23T09:05:52.242',
   Status: 'OPEN',
   _tenant: 1
  }

Lors de cette action, non journalisée, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	Présence d’un champ inconnu dans la requête.

14.3.1.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de créer un projet de versement au moyen d’un wizard ou boîte de dialogue. Il peut s’agir d’un projet de versement pour :

un versement manuel. Ce projet de versement donne lieu au renseignement :
- d’un possible rattachement à un nœud d’arbre de positionnement ou de plan de classement,
- d’un possible rattachement automatique en fonction de conditions devant être respectées dans les unités racines envoyées dans le module de collecte,
- d’informations décrivant le versement (intitulé du message, description, service producteur et service versant),
- d’informations contextuelles (service d’archives et service responsable du transfert des archives, contrat d’entrée, profil d’archivage, modalité d’entrée, statut légal des versements).
La création du projet dans l’APP entraîne la création d’une unique transaction.
des versements de flux automatisé. Ce projet de versements donne lieu au renseignement :
- d’un possible rattachement à un nœud d’arbre de positionnement ou de plan de classement,
- d’un possible rattachement automatique en fonction de conditions devant être respectées dans les unités racines envoyées dans le module de collecte,
- d’un possible envoi automatique des transactions associées au projet après leur validation,
- d’un possible paramétrage de règles de transformations des données entrantes. Ce service passe par l’import d’un fichier au format JSLT,
- d’informations décrivant le versement (intitulé du message, description, service producteur et service versant),
- d’informations contextuelles (service d’archives et service responsable du transfert des archives, contrat d’entrée, profil d’archivage, modalité d’entrée, statut légal des versements).
La création du projet de versements de flux automatisé dans l’APP n’entraîne pas la création de transaction.

L’APP « Collecte et préparation des versements » permet également de :

rechercher un projet de versement,
accéder à la liste des projets de versement,
accéder au détail d’un projet de versement en particulier,
modifier un projet de versement.

Point d’attention : Au terme de la version 8.1 :

l’intitulé saisi dans le wizard ou boîte de dialogue incrémente à la fois l’identifiant du message (MessageIdentifier) et l’intitulé du projet (Name) ;
on ne peut pas inclure de règles de gestion dans un projet de versement ;
aucun contrôle n’est effectué avec les référentiels présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de :
- veiller à inclure des références (ex. service producteur, contrat d’entrée, etc.) existant dans le tenant (coffre), de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.
il n’est pas possible de modifier les paramétrages liés au rattachement automatique ou via conditions depuis les interfaces. De fait, il est recommandé de veiller à ne pas faire d’erreurs lors de la saisie des informations.
Au terme de la version 8.1, le paramétrage permettant de définir des règles de transformation n’est pas accessible depuis les interfaces. De fait, il est recommandé de veiller à ne pas faire d’erreurs lors de la saisie des informations.

14.3.1.3. Accès

14.3.1.3.1. Utilisation des API

La solution logicielle Vitam permet de :

accéder à la liste des projets de versement créés sur un tenant donné ;
consulter les informations d’un projet en particulier sur un tenant donné ;
rechercher un à plusieurs projets de versement par rapport à certains critères (recherche approchante) :
- un intitulé,
- un identifiant du message,
- un service producteur ;
rechercher les projets de versement d’un service producteur en particulier.

Exemple : requête en vue d’obtenir l’ensemble des projets de versement disponibles sur un tenant donné

  @tenant = 1
  
  GET {{url}}/collect-external/v1/projects
  accept: application/json
  X-Tenant-Id: {{tenant}}

Exemple : requête en vue d’obtenir les informations relatives à un projet donné dont l’identifiant est « aeeaaaaaaghpmborabjyyambxjekiyyaaaaq »* *sur un tenant donné.

  @project-id = **aeeaaaaaaghpmborabjyyambxjekiyyaaaaq**
  @tenant = 1
  
  GET {{url}}/collect-external/v1/projects/{{project-id}}
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}

Exemple : requête en vue d’obtenir les projets de versement dont l’intitulé et/ou le service producteur contient le terme « Versement » sur un tenant donné.

  @tenant = 1
  
  GET {{url}}/collect-external/v1/projects
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143
  
  {
   "$query":"Versement"
  }

Exemple : requête en vue d’obtenir les projets de versement dont le service producteur est égal à « Vitam » sur un tenant donné.

  @tenant = 1
  
  GET {{url-collect}}/collect-external/v1/projects
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143

 {
   "originatingAgencies": ["Vitam"]
 }

Point d’attention : En résultats, la solution logicielle renvoie systématiquement l’ensemble des métadonnées relatives au(x) projet(s) de versement. Au terme de la version 8.1, il n’est pas possible de récupérer une sélection de métadonnées.

14.3.1.3.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet d’accéder à la liste des projets de versement préalablement créés et de les rechercher au moyen de :

leur intitulé (champ MessageIdentifier),
leur service versant (champ SubmissionAgencyIdentifier).

Point d’attention : La recherche est approchante.

Exemple : champ de recherche dans l’APP « Collecte et préparation des versements »

Par ailleurs, pour un projet donné, il est possible de :

consulter son détail ;
consulter les transactions associées ;
consulter les archives associées.

L’accès aux projets de versement peut être restreint via l’utilisation d’un contrat d’accès. Ainsi, un utilisateur du front-office VitamUI devant accéder aux projets de versement d’un service en particulier pourra ne voir que ceux-là si son profil utilisateur est associé à un contrat d’accès lui permettant d’accéder uniquement aux archives de ce service.

Point d’attention : Au terme de la version 8.1, ce filtre n’est disponible que depuis le front-office VitamUI.

14.3.1.4. Modification d’un projet de versement

14.3.1.4.1. Utilisation des API

La solution logicielle Vitam permet de modifier un projet de versement, et plus précisément de :

modifier ses métadonnées,
lui ajouter des métadonnées,
supprimer des métadonnées.

Exemple : requête en vue de modifier des métadonnées d’un projet de versement dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @tenant = 1
  
  PUT {{url}}/collect-external/v1/projects/
  accept: application/json
  content-type: application/json
  Content-Length: 401
  X-Tenant-Id: {{tenant}}
  
  {
    "#id": "**aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq**",
    "ArchivalAgencyIdentifier": "Vitam",
    "TransferringAgencyIdentifier": "RATP",
    "OriginatingAgencyIdentifier": "RATP",
    "SubmissionAgencyIdentifier": "RATP",
    "MessageIdentifier": "20200131-000006",
    "ArchivalAgreement":"IC-000001",
    "Comment": "Bulletins de salaire - Janvier 2020"
  }

Points d’attention :

Le service de mise à jour d’un projet de versement fonctionne en mode « annule et remplace ».
La plupart des champs d’une transaction étant facultatifs, il est recommandé d’indiquer les éléments obligatoires à la génération d’un SIP :
- le contrat d’entrée (champ « ArchivalAgreement »),
- l’identifiant du message (champ « MessageIdentifier),
- le service producteur (champ « OriginatingAgencyIdentifier »),
- le service d’archivage (champ « ArchivalAgencyIdentifier »),
- le service responsable du transfert (« TransferringAgencyIdentifier »)
Au terme de la version 8.1 :
- le module de collecte permet de modifier un rattachement ainsi que les conditions de rattachement. Néanmoins, il n’est pas recommandé de les modifier si une transaction contenant des archives a été créée, car la modification n’est pas répercutée dans cette transaction ;
- ce service ne vérifie pas le caractère obligatoire d’un champ. Il est fortement recommandé de veiller à ne pas supprimer un champ obligatoire, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- on ne peut pas ajouter de règles de gestion dans un projet de versement ;
- aucun contrôle n’est effectué avec les référentiels et unités archivistiques de rattachement présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de :
  - veiller à inclure des références (ex. service producteur, contrat d’entrée, etc.) existant dans la solution, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
  - ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.

Cette action, non journalisée, provoque la mise à jour du projet.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	Présence d’un champ inconnu dans la requête. Le projet n’existe pas.

14.3.1.4.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de modifier un projet de versement, avec, le cas échéant, la(les) transaction(s) associée(s) si elle(s) a(ont) un statut égal à « OPEN ».

Point d’attention : Au terme de la version 8.1, il n’est pas possible, depuis les interfaces, de modifier :

les paramètres de rattachement ;
les conditions de rattachement ;
la gestion automatique des transactions ;
les règles de transformation.

14.3.1.5. Suppression d’un projet de versement

14.3.1.5.1. Utilisation des API

La solution logicielle Vitam permet de supprimer un projet de versement.

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé un projet de versement et le signaler dans l’API, pour une suppression de projet.

Exemple : requête en vue de supprimer un projet de versement dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @project-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
  DELETE {{url}}/collect-external/v1/projects/{{project-id}}
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}

Cette action provoque la suppression de l’enregistrement dans la base de données MongoDB, dans la collection « Project » (base Collect). Si le projet de versement est associé à une transaction qui, elle-même contient des archives (unités archivistiques, objets techniques), l’ensemble des archives sont supprimées de la base de données et des offres de stockage :

les unités archivistiques sont supprimées de la collection « Unit » (base MetadataCollect) ;
les groupes d’objets techniques sont supprimées de la collection « ObjectGroup » (base MetadataCollect).
les objets sont supprimés des offres de stockage.

Lors de cette action, non journalisée, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	Le projet n’existe pas. Le projet n’est pas reconnu dans la requête.

14.3.1.5.2. Utilisation dans VitamUI

Au terme de la version 8.1, il n’est pas possible de supprimer un projet de versement depuis l’APP « Collecte et préparation des versements » du front-office VitamUI.

14.3.2. Versement

14.3.2.1. Définitions

Dans la solution logicielle Vitam, il est possible de préparer le versement d’un SIP conforme au Standard d’échanges des données pour l’archivage (SEDA) au moyen du module de collecte.

Ce module est propre à chaque tenant de la solution logicielle Vitam.

Il permet de recevoir dans un espace de stockage et des bases de données dédiés :

sous forme d’enregistrements JSON les informations relatives à :
- des métadonnées correspondant à l’en-tête du message ArchiveTransfer (Base Collect, Collection « Transaction »),
- des métadonnées descriptives et de gestion associées à des unités archivistiques (Base MetadataCollect, Collection « Unit »),
- le cas échéant, des métadonnées techniques (Base MetadataCollect, Collection « ObjectGroup »),
les objets associés.

À l’étape d’ajout des objets, la solution logicielle Vitam réalise une mise à jour des métadonnées techniques, qui inclut :

un calcul d’empreinte de l’objet,
un calcul du poids de l’objet (exprimé en octets),
une identification de format.

L’envoi des métadonnées et des objets peut s’effectuer de deux manières :

en mode « unitaire » : pour chaque type de métadonnées et pour chaque objet à collecter, le module de collecte reçoit une requête d’envoi ;
en mode « lot » : pour un ensemble d’unités archivistiques et d’objets, le module de collecte reçoit une unique requête lui faisant parvenir l’ensemble.

Les fonctionnalités ont été conçues et réalisées de manière à prendre en compte :

1 à n unités archivistiques pour une transaction, correspondant à un ensemble de métadonnées d’en-tête,
0 à n parents pour les unités archivistiques,
1 groupe d’objets techniques par unité archivistique,
1 objet binaire pour une version d’usage de l’objet pour un groupe d’objets techniques donné.

Point d’attention : Le versement des métadonnées et des objets dans le module de collecte n’est pas journalisé dans le journal des opérations.

14.3.2.2. Création d’une transaction

14.3.2.2.1. Utilisation des API

À un projet de versement peu(ven)t être associée(s) 1 à n transaction(s) (ou versement(s)).

Dans la transaction sont :

héritées des métadonnées correspondant aux informations dites d’en-tête préalablement définies dans le projet de versement, si elles ne sont pas définies dans la transaction ;
envoyées les métadonnées correspondant aux informations dites d’en-tête du bordereau telles que l’identifiant du message, qui sont spécifiques à la transaction.

Point d’attention :

En prérequis à la création d’une transaction, il faut avoir au préalable créé un projet de versement et le signaler dans l’API.
La création d’une transaction est un prérequis à l’ajout d’archives en mode « unitaire » ou en mode « lot ».

La transaction peut comporter les éléments suivants[3] :

Champ	Description
Name	Intitulé de la transaction (champ facultatif).
ArchivalAgreement	Identifiant du contrat d’entrée utilisé pour réaliser l’entrée, destiné à alimenter le champ ArchivalAgreement du message ArchiveTransfer (champ facultatif).
MessageIdentifier	Identifiant du lot d’objets, utilisé pour identifier les versements, destiné à alimenter le champ MessageIdentifier du message ArchiveTransfer (champ facultatif).
Comment	Précisions sur la demande de transfert, destinées à alimenter le champ Comment du message ArchiveTransfer (champ facultatif).
OriginatingAgencyIdentifier	Identifiant du service producteur, destiné à alimenter le champ OriginatingAgencyIdentifier du message ArchiveTransfer (champ facultatif).
SubmissionAgencyIdentifier	Identifiant du service versant, destiné à alimenter le champ SubmissionAgencyIdentifier du message ArchiveTransfer (champ facultatif). S’il est absent ou vide à l’initialisation de la transaction, alors la valeur contenue dans le champ OriginatingAgencyIdentifier est reportée dans ce champ.
ArchivalAgencyIdentifier	Identifiant du service d’archivage, destiné à alimenter le champ ArchivalAgencyIdentifier du message ArchiveTransfer (champ facultatif).
TransferringAgencyIdentifier	Identifiant du service de transfert, destiné à alimenter le champ TransferringAgencyIdentifier du message ArchiveTransfer (champ facultatif).
ArchivalProfile	Identifiant du profil d’archivage utilisé pour réaliser l’entrée, destiné à alimenter le champ ArchivalProfile du message ArchiveTransfer (champ facultatif).
AcquisitionInformation	Modalité d’entrée. Champ destiné à alimenter le champ AcquisitionInformation du message ArchiveTransfer (champ facultatif).
LegalStatus	Statut légal des archives, destiné à alimenter le champ LegalStatus du message ArchiveTransfer (champ facultatif). Si le champ est renseigné, les valeurs attendues sont : « Public Archive », « Private Archive » ou « Public and Private Archive ».

Point d’attention : Au terme de la version 8.1 :

on ne peut pas inclure de règles de gestion dans la partie transactionnelle ;
aucun contrôle n’est effectué avec les référentiels et unités archivistiques de rattachement présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de :
- veiller à inclure des références (ex. service producteur, contrat d’entrée, etc.) existant dans la solution, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés ;
- renseigner les valeurs attendues par le SEDA pour le statut légal des archives, à savoir : « Public Archive », « PrivateArchive » ou « Public and Private Archive ».
la plupart des champs d’une transaction sont facultatifs. Néanmoins, il est recommandé d’indiquer les éléments obligatoires à la génération d’un SIP, soit dans le projet de versement, soit dans la transaction :
- le contrat d’entrée (champ « ArchivalAgreement »),
- l’identifiant du message (champ « MessageIdentifier),
- le service producteur (champ « OriginatingAgencyIdentifier »),
- le service d’archivage (champ « ArchivalAgencyIdentifier »),
- le service responsable du transfert (« TransferringAgencyIdentifier »)
s’ils ne sont pas renseignés dans la transaction, les champs suivants peuvent être hérités du projet de versement s’ils y ont été renseignés :
- le contrat d’entrée (champ « ArchivalAgreement »),
- l’identifiant du message (champ « MessageIdentifier »),
- les précisions sur la demande de transfert (« Comment »),
- le service producteur (champ « OriginatingAgencyIdentifier »),
- le service versant (champ « SubmissionAgencyIdentifier »),
- le service d’archivage (champ « ArchivalAgencyIdentifier »),
- le service responsable du transfert (« TransferringAgencyIdentifier »),
- le profil d’archivage (« ArchivalProfile »),
- le statut légal des archives (« LegalStatus »),
- les modalités d’entrée (« AcquisitionInformation »).

Exemple : requête de création d’une transaction pour le projet de versement préalablement créé dont l’identifiant est aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq.

  @project-id = **aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq**
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/projects/{{project-id}}/transactions
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  
  {
    "ArchivalAgencyIdentifier": "Vitam",
    "TransferringAgencyIdentifier": "AN",
    "OriginatingAgencyIdentifier": "MICHEL_MERCIER",
    "SubmissionAgencyIdentifier": "MICHEL_MERCIER",
    "MessageIdentifier": "20220302-000005",
    "ArchivalAgreement":"IC-000001",
    "Comment": "Archives bureautiques du cabinet de Michel Mercier"
  }

Cette action provoque la création d’un enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect).

À cet enregistrement, est associé :

un statut (champ « Status ») dont la valeur est égale à « OPEN »,
l’identifiant du projet de versement à l’origine de la création de la transaction (champ « ProjectId »),
une date de création (champ « CreationDate ») dont la valeur est égale à la date de création de l’enregistrement,
une date de dernière modification (champ « LastUpdate ») dont la valeur est égale à la date de création de l’enregistrement.

Exemple : enregistrement de la transaction dans la collection « Transaction »

{
    "_id": "aeeaaaaaacecwapyabsgsamwiiin6eaaaaaq",
    "Name: "Archives bureautiques du cabinet de Michel Mercier",
    "Context: {
        "AcquisitionInformation": "Versement",
        "LegalStatus": "Private Archive",
		"ArchivalAgencyIdentifier": "Vitam",
    	"TransferringAgencyIdentifier": "AN",
    	"OriginatingAgencyIdentifier": "MICHEL_MERCIER",
    	"SubmissionAgencyIdentifier": "MICHEL_MERCIER",
    	"MessageIdentifier": "20220302-000005",
    	"ArchivalAgreement":"IC-000001",
    	"Comment": "Archives bureautiques du cabinet de Michel Mercier"
    },
    "Status": "OPEN",
    "CreationDate": "2025-04-17T04:45:24.115",
    "LastUpdate": "2025-04-17T04:45:24.296",
    "ProjectId": "aeaaaaaaaaecwapyabsgsamwiiin35iaaaaq",
    "_tenant": 0,
    "_v": 1
}

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Présence d’un champ inconnu dans la requête. - Le projet associé à la transaction n’existe pas.

14.3.2.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam ne permet pas à l’utilisateur de créer une transaction.

Néanmoins, La création d’un projet de versement manuel entraîne la création d’une unique transaction qui hérite des informations saisies dans le projet :

description du versement (intitulé du message, description, service producteur et service versant),
contexte du versement (service d’archives et service responsable du transfert des archives, contrat d’entrée, profil d’archivage, modalité d’entrée, statut légal des versements).

Point d’attention : La création du projet de versement de flux automatisé dans l’APP n’entraîne pas la création de transaction.

14.3.2.3. Alimentation d’une transaction en mode « unitaire »

L’envoi et l’enregistrement des archives dans le module de collecte s’effectue au moyen de trois commandes distinctes :

création unitaire des unités archivistiques,
création unitaire des groupes d’objets techniques,
ajout des objets.

Points d’attention :

En prérequis à la création d’une unité archivistique, il faut avoir au préalable créé une transaction et le signaler dans l’API.
L’ordre d’utilisation des API doit être respecté en vue d’enregistrer avec succès l’ensemble des métadonnées et objets constituant un versement (ou transaction).

14.3.2.3.1. Envoi d’unités archivistiques

14.3.2.3.1.1. Utilisation des API

À une transaction peu(ven)t être associée(s) 1 à n unité(s) archivistique(s).

Chaque unité archivistique :

doit définir un titre (Title) et un niveau de description (DescriptionLevel), qui sont des éléments rendus obligatoires en entrée de la solution logicielle Vitam ;
peut inclure :
- des règles de gestion ;
- des métadonnées descriptives supplémentaires ;
- un lien vers une unité archivistique de niveau supérieur.

Points d’attention :

En prérequis à la création d’une unité archivistique, il faut avoir au préalable créé une transaction et la signaler dans l’API. En outre, la transaction associée doit avoir un statut « OPEN »[5] ;
Au terme de la version 8.1, aucun contrôle n’est effectué avec les référentiels présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de veiller à :
- inclure les métadonnées obligatoires attendues par la solution logicielle Vitam, à savoir un titre (Title) et un niveau de description (DescriptionLevel) ;
- inclure des règles de gestion existant dans la solution, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- veiller au bon nommage des éléments (ou vocabulaires internes), tout en respectant leurs caractéristiques (s’il s’agit d’une chaîne de caractères, d’une date, etc.), et à leur insertion dans l’ontologie, s’il s’agit de vocabulaires externes ;
- ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.

Exemple : requête de création d’une unité archivistique pour la transaction préalablement créée dont l’identifiant est aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq.

  @transaction-id = **aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq**
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/transactions/{{transaction-id}}/units
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  {
      "DescriptionLevel": "RecordGrp",
      "Title": "Discours du ministre",
      "#management": {
        "AccessRule": {
              "Rules": [
                  {
                      "Rule": "ACC-00001",
                      "StartDate": "2000-01-01"
                  }
              ]
          }
        }
  }

Points d’attention :

L’élément #management doit toujours être présent dans la requête, même si aucune règle de gestion n’est définie pour une unité archivistique donnée ;

Exemple : requête de création d’une unité archivistique qui ne définit pas de règle de gestion.

  POST  {{url}}/collect-external/v1/transactions/{{transaction-id}}/units
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  {
      "DescriptionLevel": "RecordGrp",
      "Title": "Discours de Michel Mercier",
      **"#management": {
      }**
  }

Pour associer une unité archivistique à une autre unité archivistique, de niveau supérieur, il est recommandé de :
- créer en premier lieu l’unité archivistique de niveau supérieur et de récupérer son identifiant technique,
- ajouter parmi les métadonnées de l’unité archivistique de niveau inférieur le paramètre #unitups avec pour valeur l’identifiant de(s) unité(s) archivistique(s) de niveau supérieur.

Exemple : requête de création d’une unité archivistique incluant un rattachement à une unité archivistique de niveau supérieur.

  POST  {{url}}/collect-external/v1/transactions/{{transaction-id}}/units
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  {
      "DescriptionLevel": "Item",
      "Title": "Discours prononcé à l'occasion de l'audition devant la commission des lois relative à la proposition de loi constitutionnelle relative à la fonction de représentation par le Sénat des collectivités locales",
      "TransactedDate":"2010-12-08",
      **"#unitups": ["aeeaaaaaaghiyso4ablmyal74smvqcqaaaaq"]**,
      "#management": {
      }
  }

Cette action provoque la création d’un enregistrement dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect)[6]. À cet enregistrement, sont associés :

l’identifiant de la transaction (_opi),
l’identifiant du service producteur (_sp et _sps).

Le cas échéant, l’action provoque également :

- si le projet de versement déclarait un rattachement unique, la création d'une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base *MetadataCollect[^10]*). Sont enregistrés automatiquement :
  -   un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  -   un intitulé (Title) dont la valeur est « STATIC_ATTACHEMENT »,
  -   l'identifiant de l'unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation);
- si le projet de versement déclarait un rattachement par clé / valeur, la création d'une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base *MetadataCollect[^10]*). Sont enregistrés automatiquement :
  -   un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  -   un intitulé (Title) dont la valeur est « DYNAMIC_ATTACHEMENT »,
  -   l'identifiant de l'unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation).

Exemple : enregistrement d’une unité archivistique dans la collection « Unit » de la base « MetadataCollect ».

  {
   "_id": "aeeaaaaaaghdvam4abgoyambfxvoaoiaaaaq",
   "DescriptionLevel": "RecordGrp",
   "Title": "Discours du ministre",
   "_mgt": {
   "AccessRule": {
   "Rules": [
   {
   "Rule": "ACC-00001",
   "StartDate": "2000-01-01"
   }
   ]
   }
   },
   "_opi": "aeeaaaaaaghdvam4abgoyambfxnhd6aaaaaq",
   "_unitType": "INGEST",
   "_up": [],
   "_us": [],
   "_graph": [],
   "_sps": ["MICHEL_MERCIER"],
   "_sp": ["MICHEL_MERCIER"],
   "_uds": {},
   "_min": 1,
   "_max": 1,
   "_glpd": "2022-06-04T08:52:56.689",
   "_acd": "2022-06-04T08:52:56.689",
   "_aud": "2022-06-04T08:52:56.689",
   "_v": 0,
   "_av": 0,
   "_tenant": 1
  }

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- L’unité archivistique n’a pas été associée à une transaction ; - La transaction associée à l’unité archivistique n’existe pas ; - La transaction associée à l’unité archivistique a été clôturée; - L’unité archivistique n’est pas conforme au profil d’unité archivistique qu’elle déclare.

14.3.2.3.1.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam ne permet pas à l’utilisateur d’utiliser ce mode pour alimenter une transaction.

14.3.2.3.2. Envoi des métadonnées techniques

14.3.2.3.2.1. Utilisation des API

À une unité archivistique donnée peut être associé un groupe d’objets techniques, dans lequel on peut ajouter unitairement une version d’objet d’un usage particulier.

Il est possible d’associer plusieurs usages à un groupe d’objets techniques :

original numérique (BinaryMaster),
original physique (PhysicalMaster),
copie numérique (Dissemination),
vignette (Thumbnail),
texte brut (TextContent).

Point d’attention :

En prérequis à la création de métadonnées techniques, il faut avoir au préalable créé :
- une transaction et la signaler dans l’API. En outre, la transaction associée doit avoir un statut « OPEN »[7] ;
- une unité archivistique et la signaler dans l’API.
À cette étape, il n’est pas nécessaire d’envoyer les métadonnées correspondant à l’empreinte d’un fichier numérique, à l’identification de son format ou à son poids, dans la mesure où ce type de métadonnées est calculé lors de l’envoi du fichier numérique dans le module de collecte ;
Au terme de la version 8.1, il n’est pas possible de modifier les informations envoyées dans le module de collecte. De fait, il est fortement recommandé de veiller au bon nommage des éléments (ou vocabulaires internes), tout en respectant leurs caractéristiques (s’il s’agit d’une chaîne de caractères, d’une date, etc.), et à leur insertion dans l’ontologie, s’il s’agit de vocabulaires externes.
Par ailleurs, certains contrôles, disponibles au moment du transfert dans la solution logicielle Vitam n’ont pas été implémentés. Il est fortement recommandé de ne créer dans le module de collecte que des versions initiales d’objet numérique pour un usage donné.

Exemple : requête d’association d’un groupe d’objets techniques, et plus exactement une version initiale d’un original numérique, à une unité archivistique dont l’identifiant est aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq.

  @transaction-id = aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq
  @unit-id = **aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq**
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/units/{{unit-id}}/objects/**BinaryMaster/1**
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  {
    "FileInfo": {
      "Filename": "Test01.jpeg"
    }
  }

Cette action provoque la création d’un enregistrement dans la base de données MongoDB, dans la collection « ObjectGroup » (base MetadataCollect[8]). À cet enregistrement, sont associés :

l’identifiant de la transaction (_opi),
l’identifiant du service producteur (_sp).

Exemple : enregistrement des métadonnées techniques dans la collection « ObjectGroup » de la base « MetadataCollect ».

  {
   "_id": "aeeaaaaaaghdvam4abgoyambfxzdbviaaaaq",
   "_tenant": 1,
   "FileInfo": {
   "Filename": "Test01.jpeg"
   },
   "_nbc": 2,
   "_opi": "aeeaaaaaaghdvam4abgoyambfxnhd6aaaaaq",
   "_sp": "MICHEL_MERCIER",
   "_qualifiers": [
   {
   "qualifier": "BinaryMaster",
   "_nbc": 1,
   "versions": [
   {
   "_id": "aeeaaaaaaghdvam4abgoyambfxzdbvyaaaaq",
   "DataObjectVersion": "BinaryMaster_1",
   "FileInfo": {
   "Filename": "Test01.jpeg"
   },
   "Size": 0
   }
   ]
   }
   ],
   "_v": 1,
   "_av": 1,
   "_acd": "2023-01-02T12:01:34.629",
   "_aud": "2023-01-02T12:01:34.629"
  }

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- L’ unité archivistique n’existe pas ou est erronée ; - L’objet technique n’a pas été associé à une unité archivistique ; - La requête renvoie une deuxième fois une demande de création d’un usage d’objet ayant déjà été versé dans le module de collecte ; - La transaction associée a été clôturée.

14.3.2.3.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam ne permet pas à l’utilisateur d’utiliser ce mode pour alimenter une transaction.

14.3.2.3.3. Envoi des objets

14.3.2.3.3.1. Utilisation des API

À une unité archivistique associée à un groupe d’objets techniques et pour un usage et une version d’objet donné, on peut ajouter unitairement un objet numérique.

Point d’attention :

En prérequis à l’envoi d’un objet, il faut avoir au préalable créé :
- une transaction et la signaler dans l’API. En outre, la transaction associée doit avoir un statut « OPEN »[9] ;
- une unité archivistique et la signaler dans l’API.

Exemple : requête d’association d’un fichier numérique, et plus exactement une version initiale d’un original numérique, à une unité archivistique dont l’identifiant est aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq.

  @transaction-id = aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq
  @unit-id = **aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq**
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/units/{{unit-id}}/objects/**BinaryMaster/1/binary**
  Accept: application/json
  Content-Type: application/octet-stream
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  < /MichelMercier/Discours/Test01.jpeg

Cette action provoque :

l’enregistrement de l’objet numérique sur les offres de stockage.
la mise à jour des métadonnées techniques de l’objet avec, calculés lors de l’envoi de l’objet numérique :
- ajout de l’empreinte d’un fichier numérique,
- ajout de l’identification de son format,
- mise à jour de son poids exprimé en octets.

Exemple : ajout de l’empreinte du fichier et de son identification de format et mise à jour du poids dans la collection « ObjectGroup » de la base « MetadataCollect ».

  {
   "_id": "aeeaaaaaaghdvam4abgoyambfxzdbviaaaaq",
   "_tenant": 1,
   "FileInfo": {
   "Filename": "Test01.jpeg"
   },
   "_nbc": 2,
   "_opi": "aeeaaaaaaghdvam4abgoyambfxnhd6aaaaaq",
   "_sp": "MICHEL_MERCIER",
   "_qualifiers": [
   {
   "qualifier": "BinaryMaster",
   "_nbc": 1,
   "versions": [
   {
   "_id": "aeeaaaaaaghdvam4abgoyambfxzdbvyaaaaq",
   "DataObjectVersion": "BinaryMaster_1",
   **"FormatIdentification": {**
   "FormatLitteral": "JPEG File Interchange Format",
   "MimeType": "image/jpeg",
   "FormatId": "fmt/43"
  ** }**,
   "FileInfo": {
   "Filename": "Test01.jpeg"
   },
   ** "Size": 7702,**
   "Uri": "Content/Test01.jpeg",
   "MessageDigest": "0e0cec05a1d72ee5610eaa5afbc904c012d190037cbc827d08272102cdecf0226efcad122b86e7699f767c661c9f3702379b8c2cb01c4f492f69deb200661bb9",
   "Algorithm": "SHA-512"
   }
   ]
   }
   ],
   "_v": 1,
   "_av": 1,
   "_acd": '"023-01-02T12:01:34.629",
   "_aud": "2023-01-02T12:01:34.965"
  }

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- L’ unité archivistique n’existe pas ou est erronée ; - Le groupe d’objets techniques n’existe pas ; - La transaction associée a été clôturée.

Point d’attention : Certains contrôles, disponibles au moment du transfert dans la solution logicielle Vitam n’ont pas été implémentés. Il est fortement recommandé de ne pas envoyer dans le module de collecte plusieurs objets numériques pour un usage et une version donnée.

14.3.2.3.3.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam ne permet pas à l’utilisateur d’utiliser ce mode pour alimenter une transaction.

14.3.2.4. Alimentation d’une transaction en mode « lot »

L’envoi et l’enregistrement des données dans le module de collecte peut s’effectuer en lot au moyen d’une commande pouvant fonctionner de deux façons :

envoi sous forme de fichier .zip d’une arborescence bureautique,
envoi sous forme de fichier .zip d’une arborescence bureautique et d’un fichier annexe intitulé « metadata.csv » ou « metadata.jsonl » référençant des métadonnées descriptives et de gestion.

Point d’attention : Pour ces deux envois, la commande est unique. Seule l’association d’un fichier annexe « metadata.csv » ou « metadata.jsonl », optionnelle, diffère.

14.3.2.4.1. Envoi d’une arborescence bureautique

14.3.2.4.1.1. Utilisation des API

Pour une transaction donnée, est envoyée une arborescence bureautique sous forme de fichier .zip.

Point d’attention : En prérequis à l’envoi d’une arborescence bureautique, il faut avoir au préalable créé une transaction et le signaler dans l’API.

Exemple : requête d’envoi d’une arborescence bureautique stream.zip pour la transaction préalablement créée dont l’identifiant est aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq.

  @transaction-id = **aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq**
  @tenant = 1
  
  POST {{url}}/collect-external/v1/transactions/{{transaction-id}}/upload
  Accept: application/json
  Content-Type: application/zip
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}
  
  < /path_tozip/**stream.zip**

Cette action provoque :

la création des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement[11] :
- un niveau de description (DescriptionLevel) dont la valeur est :
  - « RecordGrp » pour une unité archivistique référençant un répertoire,
  - « Item » pour une unité archivistique référençant un objet numérique ;
- un intitulé (Title), correspondant au nom d’un répertoire ou d’un objet binaire présent dans l’arborescence bureautique.
À chaque enregistrement, est associé :
```
-   l’identifiant de la transaction (_opi),
-   l'identifiant du service producteur (_sp et _sps);
```
la création de métadonnées techniques dans la base de données MongoDB, dans la collection « ObjectGroup » (base MetadataCollect[12]) ;

À chaque enregistrement, est associé :
```
-   l’identifiant de la transaction (_opi),
-   l'identifiant du service producteur (_sp);
```
l’enregistrement des objets numériques sur les offres de stockage.
la mise à jour des métadonnées techniques de l’objet avec, calculés lors de l’envoi du fichier numérique :
- ajout de l’empreinte d’un fichier numérique,
- ajout de l’identification de son format,
- mise à jour de son poids exprimé en octets.
le cas échéant :
- si le projet de versement déclarait un rattachement unique, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « STATIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation);
- si le projet de versement déclarait un rattachement par clé / valeur, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « DYNAMIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation).

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Le fichier .zip n’a pas été téléchargé pour cause de nom erroné ou de chemin introuvable. - La transaction n’existe pas ou est erronée. -
La transaction a été clôturée.

Elle n’est pas journalisée dans le journal des opérations.

Point d’attention :

Aucun fichier ne doit avoir un poids équivalent à 0 octet.
Au terme de la V.8.1, il est recommandé que les noms de répertoires et de fichiers ne contiennent ni caractère accentué, ni virgule, ni apostrophe, ni parenthèse, ni espace, ni élément de ponctuation, ou tout autre caractère spécial. Ne sont à privilégier que l’underscore et le tiret comme séparateurs. Néanmoins, s’ils en contiennent et si l’arborescence bureautique émane d’un environnement Windows, il est recommandé d’utiliser l’outil Winzip pour la zipper, afin d’éviter des problèmes d’encodage.

14.3.2.4.1.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de verser une arborescence bureautique, le cas échéant accompagnée d’un fichier « metatadata.csv », lors de la création d’un projet de versement manuel au moyen d’un wizard ou boîte de dialogue.

Le détail du projet de versement, ainsi que les archives qui lui sont associées sont par ailleurs accessibles depuis l’APP.

14.3.2.4.2. Envoi d’une arborescence bureautique avec fichier .csv

14.3.2.4.2.1. Utilisation des API

Pour une transaction donnée peut être envoyé sous forme de zip en plus d’une arborescence bureautique[13] un fichier .csv contenant des métadonnées détaillant unitairement les unités archivistiques.

Le fichier .csv, obligatoirement intitulé « metadata.csv », est composé de x colonnes[14] :

File : chemin relatif des fichiers numériques ou des répertoires à partir de l’emplacement où est enregistré le fichier .csv (colonne obligatoire) ;
ObjectFiles : chemin relatif des fichiers numériques dont certains peuvent être rattachés à des répertoires déclarés dans la colonne File (colonne facultative) ;
DescriptionLevel : niveau de description de l’unité archivistique (colonne facultative) ;
Title : intitulé de l’unité archivistique (colonne facultative) ;
toute colonne correspondant à une métadonnée du standard SEDA (colonnes facultatives) ;
le cas échéant, toute colonne correspondant à une métadonnée externe du standard SEDA (colonnes facultatives).

Exemple : contenu d’un fichier « metadata.csv ».

  "File";"Content.DescriptionLevel";"Content.Title";"Content.FilePlanPosition";"Content.ArchivalAgencyArchiveUnitIdentifier";"Content.Description";"Content.CustodialHistory.CustodialHistoryItem.0";"Content.CustodialHistory.CustodialHistoryItem.1";"Content.CustodialHistory.CustodialHistoryItem.2";"Content.DocumentType";"Content.Language";"Content.DescriptionLanguage";"Content.Version";"Content.Tag.0";"Content.Tag.1";"Content.Tag.2";"Content.Tag.3";"Content.Tag.4";"Content.Keyword.0.KeywordContent";"Content.Keyword.0.KeywordType";"Content.Keyword.1.KeywordContent";"Content.Keyword.1.KeywordType";"Content.Keyword.2.KeywordContent";"Content.Keyword.2.KeywordType";"Content.Keyword.3.KeywordContent";"Content.Keyword.3.KeywordType";"Content.Keyword.4.KeywordContent";"Content.Keyword.4.KeywordType";"Content.Coverage.Spatial.0";"Content.Coverage.Spatial.1";"Content.Coverage.Spatial.2";"Content.Coverage.Spatial.3";"Content.Coverage.Temporal";"Content.Coverage.Juridictional.0";"Content.Coverage.Juridictional.1";"Content.Coverage.Juridictional.2";"Content.Coverage.Juridictional.3";"Content.OriginatingAgency.Identifier";"Content.SubmissionAgency.Identifier";"Content.StartDate";"Content.EndDate";"Management.AccessRule.Rule";"Management.AccessRule.StartDate"
  "AU1/27juillet1888/5FI6/_5FI6/_16";"RecordGrp";"Brantes. Combe de la Mure.";"instrument_recherche/5FI6/5FI6_16";"5 Fi 6/16";"Dim. 18x24 cm.";;;;;"fre";"fre";"Original";"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;;"Combe de la Mure (Brantes, Vaucluse, France)";"geogname";"Brantes (Vaucluse, France)";"geogname";;;;;;;"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;1888;"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;;;;"1888-12-30T00:00:00";"ACC-00001";"1888-12-30"
  "AU1/27juillet1888";"RecordGrp";"Clichés du 27 juillet 1888";;;;;;;;"fre";"fre";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Exemple : contenu d’un fichier « metadata.csv » décrivant un contexte de signature détachée.

  "File";"ObjectFiles";"Content.DescriptionLevel";"Content.Title";"Content.Description";"Content.DocumentType";"Content.Tag";"Content.EndDate";"Content.SigningInformation.SigningRole.0";"Content.SigningInformation.SigningRole.1";"Content.SigningInformation.SigningRole.2";"Content.SigningInformation.SignatureDescription.0.Signer.FullName";"Content.SigningInformation.SignatureDescription.0.Signer.SigningTime";"Content.SigningInformation.TimestampingInformation.TimeStamp";"Content.SigningInformation.AdditionalProof.0.AdditionalProofInformation.0";"Content.SigningInformation.AdditionalProof.0.AdditionalProofInformation.1";"Management.AppraisalRule.Rule";"Management.AppraisalRule.StartDate";"Management.AppraisalRule.FinalAction";"Management.AccessRule.Rule";"Management.AccessRule.StartDate"
  "**Parapheur**";"Parapheur/20230615_note_Vu AB.pdf";"Item";"20230615_note_Vu AB.pdf";"Parapheur créé par Al Capone. Note";"Document signé";"Note";"2023-06-15";"SignedDocument";"Signature";"Timestamp";"Al Capone";"2023-06-15T11:18:12";"2023-06-15T11:18:12";"EvidenceRecords";"Report";"APP-00003";"2023-06-15";"Keep";"ACC-00020";"2023-06-15"
  "Parapheur/aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf";"**Parapheur/aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf**";"Item";"aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf";;"Fichier de preuve";;;"AdditionalProof";;;;;;;;;;;;
  "Parapheur/report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf";"**Parapheur/report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf**";"Item";"report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf";;"Rapport";;;"AdditionalProof";;;;;;;;;;;;```

Exemple : contenu d’un fichier « metadata.csv » déclarant un rattachement.

  "File";"Content.DescriptionLevel";"Content.Title";**"Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataName**";"**Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue**"
  "Discours hors parlement";"RecordGrp";"Discours hors parlement";"**ArchivalAgencyArchiveUnitIdentifier**";"**20130456/3**"
  "Discours hors parlement/Discours d'inauguration";"RecordGrp";"Discours d’inauguration";;
  "Discours hors parlement/Discours d'inauguration/Inauguration de Notre-Dame.odt";"Item";"Inauguration de Notre-Dame";;

Points d’attention :

la colonne File doit toujours être placée en première position ;
une première ligne d’en-tête donnant le nom des colonnes doit être présente, chaque ligne décrivant ensuite une unité archivistique ;
le séparateur entre les colonnes est le point-virgule, le séparateur de texte les guillemets doubles et l’encodage est « UTF-8 » ;
le fichier .csv ne référence que des métadonnées propres aux unités archivistiques (métadonnées descriptives et de gestion). Il ne supporte pas les métadonnées techniques propres aux fichiers numériques ;
seul un objet peut être associé à un enregistrement. Ce format d’import ne permet pas de facto de gérer l’import de groupe d’objets techniques disposant de plusieurs objets aux usages différents devant être référencés par la même unité archivistique.
le fichier .csv à importer doit se trouver dans le même répertoire que le répertoire correspondant à la racine de la structure arborescente de fichiers à importer.
chaque répertoire et objet numérique devant contenir des métadonnées particulières doit être référencé dans le fichier .csv ;
si le fichier .csv déclare un rattachement à une unité archivistique, il doit matérialiser cette unité archivistique par une ligne dédiée correspondant à un dossier dans l’arborescence bureautique. Dans cette ligne :
- Ne devront être renseignées que les informations suivantes :
  - DescriptionLevel,
  - Title,
  - UpdateOperation.ArchiveUnitIdentifierKey.MetadataName et Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue OU UpdateOperation.SystemId.
- Un rattachement ne peut être déclaré que dans un répertoire racine.
concernant le nommage des colonnes :
- pour les colonnes correspondant à des champs du standard SEDA, l’intitulé de la colonne doit correspondre à celui du champ dans le standard SEDA, précédé de « Management. » s’il s’agit d’une métadonnée de gestion (ex. « Management.AccessRule.Rule » pour une règle de communicabilité) ou de « Content » s’il s’agit d’une métadonnée descriptive (ex. « Content.DocumentType ») ;
- pour les colonnes correspondant à des métadonnées externes au standard SEDA, l’intitulé de la colonne doit correspondre à celui du champ, précédé de « Content. » ;
- quand le schéma XML du standard SEDA propose une structure complexe de balises (par exemple pour décrire un auteur via l’objet XML <Writer> qui contient plusieurs balises XML comme FullName ou BirthName), il convient d’intituler la colonne de la manière suivante : Content.Writer.FullName ou Content.Writer.BirthName ;
- quand un champ ou un objet XML est multivalué dans le standard SEDA (et qu’il est possible d’en décrire plusieurs dans le bordereau comme c’est le cas pour l’objet Writer par exemple), il convient de numéroter la colonne de la manière suivante : Content.Writer.0.FullName, Content.Writer.1.FullName ;
concernant le contenu des colonnes :
- la colonne File :
  - ne doit pas comprendre d’espace avant ou après les « / » ;
  - doit correspondre à un chemin tel que décrit par l’explorateur de fichiers (avec des « / ») ;
- la colonne DescriptionLevel ne doit comprendre que les valeurs autorisées par le standard SEDA : Collection, Fonds, Series, SubSeries, RecordGrp, File, Item ;
- les colonnes correspondant à des champs Date dans le standard SEDA doivent être formatées conformément à la norme ISO 8601 (AAAA-MM-JJ) ;
- les références à des règles de gestion et à des profils d’unité archivistique doivent se conformer aux identifiants de règles présents dans le SAE.
Aucun fichier ne doit avoir un poids équivalent à 0 octet.
Les dates de début (Content.StartDate) doivent être antérieures aux dates de fin (Content.EndDate).
Au terme de la V.8.1, il est recommandé que les noms de répertoires et de fichiers ne contiennent ni caractère accentué, ni virgule, ni apostrophe, ni parenthèse, ni espace, ni élément de ponctuation, ou tout autre caractère spécial. Ne sont à privilégier que l’underscore et le tiret comme séparateurs.

Néanmoins, s’ils en contiennent et si l’arborescence bureautique émane d’un environnement Windows, il est recommandé d’utiliser l’outil Winzip pour la zipper, afin d’éviter des problèmes d’encodage.

L’import du fichier .zip incluant un fichier .csv et une arborescence bureautique provoque :

la création des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[15]). Sont enregistrées automatiquement les valeurs portées dans le fichier .csv si l’enregistrement ne contient pas d’erreur.

À chaque enregistrement, est associé :
- s’il n’a pas été défini dans le fichier .csv, un niveau de description (DescriptionLevel) dont la valeur est :
  - « RecordGrp » pour une unité archivistique référençant un répertoire,
  - « Item » pour une unité archivistique référençant un objet numérique ;
- l’identifiant de la transaction (_opi) ;
- un identifiant de batch (_batchId) ;
- la localisation initiale du dossier ou du fichier dans l’arborescence (_uploadPath),
- l’identifiant du service producteur (_sp et _sps) ;
la création de métadonnées techniques dans la base de données MongoDB, dans la collection « ObjectGroup » (base MetadataCollect[16]).

À chaque enregistrement, est associé :
- l’identifiant de la transaction (_opi) ;
- un identifiant de batch (_batchId) ;
- l’identifiant du service producteur (_sp) ;
l’enregistrement des objets numériques sur les offres de stockage.
la mise à jour des métadonnées techniques de l’objet avec :
- ajout de l’empreinte d’un fichier numérique,
- ajout de l’identification de son format,
- mise à jour de son poids exprimé en octets, calculés lors de l’envoi du fichier numérique ;
le cas échéant :
- si le projet de versement déclarait un rattachement unique, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « STATIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation);
- si le projet de versement déclarait un rattachement par clé / valeur, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « DYNAMIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation).

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Le fichier .zip n’a pas été téléchargé pour cause de nom erroné ou de chemin introuvable ; - Le fichier .csv contient au moins une erreur ; - La transaction n’existe pas ou est erronée ; - La transaction est clôturée.

Cette action n’est pas journalisée dans le journal des opérations.

Point d’attention :**

Au terme de la V.8.1, le module de collecte peut :
- bloquer l’import de l’arborescence bureautique accompagnée d’un fichier .csv si ce dernier comporte les erreurs suivantes :
  - il ne contient pas au moins la colonne obligatoire File ;
  - au moins un fichier référencé dans le fichier .csv n’est pas présent dans l’arborescence bureautique,
  - il ne contient aucune information ;
  - il ne contient pas de séparateurs de champs ;
  - il contient des virgules, des espaces, des pipes comme séparateurs de champs ;
  - le fichier contient des simples guillemets comme séparateurs de texte ;
  - etc.
    L’API peut :
    - soit renvoyer une seule erreur, si cette erreur est bloquante,
    - soit renvoyer jusqu’à 20 erreurs, si ces erreurs sont cumulables. L’arborescence bureautique ne sera pas importée.
- ne pas bloquer l’import de l’arborescence bureautique accompagnée d’un fichier CSV si ce dernier comporte les erreurs suivantes :
  - il dispose d’un champ dont le contenu est mal formaté (ex. ReceivedDate écrite en chaîne de caractères) ; Une erreur est alors renvoyée par l’API, le contenu du fichier .csv sera ignoré et seule l’arborescence bureautique sera téléchargée selon le comportement décrit dans la sous-section précédente.
Aucun contrôle n’est effectué entre le nombre de répertoires et d’objets binaires présents dans l’arborescence bureautique et les éléments décrits dans le fichier .csv. Il est recommandé de veiller à ne pas ajouter de niveaux intermédiaires dans l’arborescence bureautique non référencés dans le fichier .csv, car ils seront automatiquement créés dans le module de collecte selon le comportement décrit dans la sous-section précédente.

14.3.2.4.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de verser une arborescence bureautique, le cas échéant accompagnée d’un fichier « metadata.csv », lors de la création d’un projet de versement manuel au moyen d’un wizard ou boîte de dialogue.

Le détail du projet de versement, ainsi que les archives qui lui sont associées sont par ailleurs accessibles depuis l’APP.

Point d’attention :

Si un fichier « metadata.csv » est associé à une arborescence bureautique, il faut d’abord télécharger cette dernière dans le wizard ou boîte de dialogue, puis faire de même avec le fichier « metadata.csv » ;
Si le nom du fichier .csv est erroné, l’interface VitamUI l’interprétera comme un fichier numérique à collecter au même titre que l’arborescence bureautique associée ;
Au terme de la V.8.1, l’APP « Collecte et préparation des versements » ne renvoie pas d’erreurs lors de l’import de l’arborescence bureautique accompagnée d’un fichier .csv si ce dernier comporte des erreurs.

14.3.2.4.3. Envoi d’une arborescence bureautique avec fichier .jsonl

14.3.2.4.3.1. Utilisation des API

Pour une transaction donnée peut être envoyé sous forme de zip en plus d’une arborescence bureautique[13] un fichier .jsonl contenant des métadonnées détaillant unitairement les unités archivistiques.

Le fichier .jsonl, obligatoirement intitulé « metadata.jsonl », est composé des informations suivantes :

File : chemin relatif des fichiers numériques ou des répertoires à partir de l’emplacement où est enregistré le fichier .jsonl (champ obligatoire) ;
Selector : liste de conditions permettant l’enregistrement des métadonnées dans une unité archivistique correspond à ces conditions (champ obligatoire) ;
ObjectFiles : chemin relatif des fichiers numériques dont certains peuvent être rattachés à des répertoires déclarés dans le champ File (champ facultatif) ;
UnitContent : bloc dans lequel sont insérées les métadonnées descriptives et de gestion d’une unité archivistique (champ obligatoire), dont :
- DescriptionLevel : niveau de description de l’unité archivistique (champ facultatif) ;
- Title : intitulé de l’unité archivistique (champ facultatif) ;
- tout champ correspondant à un champ du standard SEDA (champs facultatifs) ;
- le cas échéant, tout champ correspondant à une métadonnée externe du standard SEDA (champs facultatifs).

Exemple : contenu d’un fichier « metadata.jsonl ».

{ "File": "File", "UnitContent": { "DescriptionLevel": "Collection", "Title": "File", "Description": "Ceci est un versement de bulletins de paie", "StartDate": "2023-01-01", "EndDate": "2023-01-31", "Tag": [ "Paie", "Bulletin" ] } }
{ "File": "File/BP_123456_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123456_20230131.pdf", "OriginatingSystemId": [ "BP_123456_20230131" ], "Agent": [ { "FirstName": "DUPONT", "BirthName": "Charles", "Identifier": [ "123456" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00001", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } }
{ "File": "File/BP_123463_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123463_20230131.pdf", "OriginatingSystemId": [ "BP_123463_20230131" ], "Agent": [ { "FirstName": "DUPOND", "BirthName": "Victor", "Identifier": [ "123463" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00002", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } }
{ "File": "File/BP_123464_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123464_20230131.pdf", "OriginatingSystemId": [ "BP_123464_20230131" ], "Agent": [ { "FirstName": "CHARLES", "BirthName": "Ray", "Identifier": [ "123464" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00002", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } } 

Exemple : contenu d’un fichier « metadata.jsonl » décrivant un contexte de signature détachée.

{ "File" : "My Root Folder", "ObjectFiles": "SomeFile.xml", "UnitContent": { "Title": "My Root Folder (with attached SomeFile.xml)" } }
{ "File" : "My Root Folder/MyFile1.txt", "ObjectFiles": null, "UnitContent": { "Title": "My Root Folder/MyFile1.txt" } }
{ "File" : "My Root Folder/MyFile2.txt", "ObjectFiles": "My Root Folder/MyFile2.txt", "UnitContent": { "Title": "My Root Folder/MyFile2.txt" } }
{ "File" : "My Root Folder/SubFolder", "ObjectFiles": "My Root Folder/SubFolder/MyFile3.txt", "UnitContent": { "Title": "My Root Folder/SubFolder (with attached MyFile3.txt)" } }
{ "Selector" : { "#uploadPath" : "Yet Another Folder" }, "ObjectFiles": "My Root Folder/SubFolder/MyFile4.txt", "UnitContent": { "Title": "Yet Another Folder (with attached MyFile4.txt)" } }

Exemple : contenu d’un fichier « metadata.jsonl » déclarant un rattachement.

{ "File": "Discours hors parlement", "UnitContent": { "DescriptionLevel": "RecordGrp", "Title": "Discours hors parlement", "#management": { "UpdateOperation": { "ArchiveUnitIdentifierKey" : { "MetadataName" : "ArchivalAgencyArchiveUnitIdentifier", "MetadataValue" : "20130456/3"} }  } } }
{ "File": "Discours hors parlement/Discours d'inauguration", "UnitContent": { "DescriptionLevel": "RecordGrp", "Title": "Discours d’inauguration" } }
{ "File": "Discours hors parlement/Discours d'inauguration/Inauguration de Notre-Dame.odt", "UnitContent": { "DescriptionLevel": "Item", "Title": "Inauguration de Notre-Dame" } }
 

Points d’attention :

le fichier .jsonl doit toujours contenir un champ File ou un champ Selector. Celui-ci doit toujours être placée en première position ;
les métadonnées pouvant être utilisées comme conditions dans le champ Selector doivent des éléments simples de type string, boolean, long ou double.
le fichier .jsonl ne référence que des métadonnées propres aux unités archivistiques (métadonnées descriptives et de gestion). Il ne supporte pas les métadonnées techniques propres aux fichiers numériques ;
seul un objet peut être associé à un enregistrement. Ce format d’import ne permet pas de facto de gérer l’import de groupe d’objets techniques disposant de plusieurs objets aux usages différents devant être référencés par la même unité archivistique.
le fichier .jsonl à importer doit se trouver dans le même répertoire que le répertoire correspondant à la racine de la structure arborescente de fichiers à importer.
chaque répertoire et objet numérique devant contenir des métadonnées particulières doit être référencé dans le fichier .jsonl ;
si le fichier .jsonl déclare un rattachement à une unité archivistique, il doit matérialiser cette unité archivistique par une ligne dédiée correspondant à un dossier dans l’arborescence bureautique. Dans cette ligne :
- Ne devront être renseignées que les informations suivantes :
  - DescriptionLevel,
  - Title,
  - UpdateOperation.ArchiveUnitIdentifierKey.MetadataName et Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue OU UpdateOperation.SystemId.
- Un rattachement ne peut être déclaré que dans un répertoire racine.
le nommage des champs et leur structuration en JSON doivent se conformer au modèle de données de la solution logicielle Vitam.
concernant le contenu des champs :
- la colonne File :
  - ne doit pas comprendre d’espace avant ou après les « / » ;
  - doit correspondre à un chemin tel que décrit par l’explorateur de fichiers (avec des « / ») ;
- le champ DescriptionLevel ne doit comprendre que les valeurs autorisées par le standard SEDA : Collection, Fonds, Series, SubSeries, RecordGrp, File, Item ;
- les champs correspondant à des champs Date dans le standard SEDA doivent être formatés conformément à la norme ISO 8601 (AAAA-MM-JJ) ;
- les références à des règles de gestion et à des profils d’unité archivistique doivent se conformer aux identifiants de règles présents dans le SAE
Aucun fichier ne doit avoir un poids équivalent à 0 octet.
Les dates de début (Content.StartDate) doivent être antérieures aux dates de fin (Content.EndDate).
Au terme de la V.8.1, il est recommandé que les noms de répertoires et de fichiers ne contiennent ni caractère accentué, ni virgule, ni apostrophe, ni parenthèse, ni espace, ni élément de ponctuation, ou tout autre caractère spécial. Ne sont à privilégier que l’underscore et le tiret comme séparateurs.

Néanmoins, s’ils en contiennent et si l’arborescence bureautique émane d’un environnement Windows, il est recommandé d’utiliser l’outil Winzip pour la zipper, afin d’éviter des problèmes d’encodage.

L’import du fichier .zip incluant un fichier .jsonl et une arborescence bureautique provoque :

la création des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[15]). Sont enregistrées automatiquement les valeurs portées dans le fichier .jsonl si l’enregistrement ne contient pas d’erreur.

À chaque enregistrement, est associé :
- s’il n’a pas été défini dans le fichier .csv, un niveau de description (DescriptionLevel) dont la valeur est :
  - « RecordGrp » pour une unité archivistique référençant un répertoire,
  - « Item » pour une unité archivistique référençant un objet numérique ;
- l’identifiant de la transaction (_opi) ;
- un identifiant de batch (_batchId) ;
- la localisation initiale du dossier ou du fichier dans l’arborescence (_uploadPath),
- l’identifiant du service producteur (_sp et _sps) ;
la création de métadonnées techniques dans la base de données MongoDB, dans la collection « ObjectGroup » (base MetadataCollect[16]).

À chaque enregistrement, est associé :
- l’identifiant de la transaction (_opi) ;
- un identifiant de batch (_batchId) ;
- l’identifiant du service producteur (_sp) ;
l’enregistrement des objets numériques sur les offres de stockage.
la mise à jour des métadonnées techniques de l’objet avec :
- ajout de l’empreinte d’un fichier numérique,
- ajout de l’identification de son format,
- mise à jour de son poids exprimé en octets, calculés lors de l’envoi du fichier numérique ;
le cas échéant :
- si le projet de versement déclarait un rattachement unique, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « STATIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation);
- si le projet de versement déclarait un rattachement par clé / valeur, la création d’une unité archivistique dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement :
  - un niveau de description (DescriptionLevel) dont la valeur est « Series »,
  - un intitulé (Title) dont la valeur est « DYNAMIC_ATTACHEMENT »,
  - l’identifiant de l’unité archivistique de rattachement (champ SystemId inclus dans un bloc UpdateOperation).

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Le fichier .zip n’a pas été téléchargé pour cause de nom erroné ou de chemin introuvable ; - Le fichier .jsonl contient au moins une erreur ; - La transaction n’existe pas ou est erronée ; - La transaction est clôturée.

Cette action n’est pas journalisée dans le journal des opérations.

Point d’attention :

Au terme de la V.8.1, le module de collecte peut :
- bloquer l’import de l’arborescence bureautique accompagnée d’un fichier .jsonl si ce dernier comporte les erreurs suivantes :
  - il ne contient pas au moins le champ obligatoire File ;
  - au moins un bloc UnitContent ne contient aucune information ;
  - au moins un fichier référencé dans le fichier .jsonl n’est pas présent dans l’arborescence bureautique,
  - il ne contient aucune information ;
  - une date de fin de règle a été intégrée dans le fichier .jsonl ;
  - il dispose d’un champ dont le contenu est mal formaté (ex. ReceivedDate écrite en chaîne de caractères) ;
  - etc.
    L’API peut :
    - soit renvoyer une seule erreur, si cette erreur est bloquante,
    - soit renvoyer jusqu’à 20 erreurs, si ces erreurs sont cumulables. L’arborescence bureautique ne sera pas importée.
Aucun contrôle n’est effectué entre le nombre de répertoires et d’objets binaires présents dans l’arborescence bureautique et les éléments décrits dans le fichier .jsonl. Il est recommandé de veiller à ne pas ajouter de niveaux intermédiaires dans l’arborescence bureautique non référencés dans le fichier .jsonl, car ils seront automatiquement créés dans le module de collecte selon le comportement décrit dans la sous-section précédente.

14.3.2.4.3.2. Utilisation dans VitamUI

Il n’est pas possible d’envoyer une arborescence bureautique avec un fichier .jsonl de métadonnées depuis l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam.

14.3.3. Accès

14.3.3.1. Définitions

Après versement d’archives dans le module de collecte, il est possible de rechercher et de consulter :

les informations ayant trait au versement,
les archives associées à un versement.

Cette recherche et consultation est propre à chaque tenant de la solution logicielle Vitam.

14.3.3.2. Accès aux informations du versement

14.3.3.2.1. Utilisation des API

Pour un projet donné, la solution logicielle Vitam permet de :

accéder à la liste des transactions associées créées sur un tenant donné,
consulter les informations d’une transaction en particulier sur un tenant donné.

Exemple : requête en vue d’obtenir l’ensemble des transactions d’un projet de versement disponibles sur un tenant donné

  @tenant = 1
  @project-id = aeeaaaaaaghpmborabjyyambxjekiyyaaaaq
  
  GET {{url}}/collect-external/v1/projects/{{project-id}}/transactions
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}

Cette action peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Un paramètre (identifiant du projet) contient une mauvais valeur. - Le projet associé à la transaction n’existe pas.

Exemple : requête en vue d’obtenir les informations relatives à une transaction donnée dont l’identifiant est « aeeaaaaaaghpmborabjyyambxjekiyyaaabcdef » sur un tenant donné

  @tenant = 1
  @transaction-id = *aeeaaaaaaghpmborabjyyambxjekiyyaaabcdef*
  
  GET {{url}}/collect-external/v1/transactions/{{transaction-id}}
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  
  {
  }

Cette action peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Un paramètre (identifiant de la transaction) contient une mauvais valeur. - La transaction n’existe pas.

Point d’attention :

En résultats, la solution logicielle renvoie systématiquement l’ensemble des métadonnées relatives au(x) transaction(s). Au terme de la version 8.1, il n’est pas possible de récupérer une sélection de métadonnées.
Si la transaction a été envoyée dans la solution logicielle Vitam, l’API renverra également l’identifiant de l’opération de versement (champ « VitamOperationId »).

14.3.3.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet à l’utilisateur de consulter :

la liste des transactions associées à un projet de versement. Au terme de la version 8.1, elle ne permet pas de consulter le détail des informations d’une transaction.
les archives associées à une transaction donnée.

L’accès aux transactions d’un projet de versement peut être restreint via l’utilisation d’un contrat d’accès. Ainsi, un utilisateur du front-office VitamUI devant accéder aux projets de versement d’un service en particulier, et à ses transactions, pourra ne voir que ceux-là si son profil utilisateur est associé à un contrat d’accès lui permettant d’accéder uniquement aux archives de ce service.

Point d’attention : Au terme de la version 8.1, ce filtre n’est disponible que depuis le front-office VitamUI.

14.3.3.3. Accès aux unités archivistiques

14.3.3.3.1. Utilisation des API

L’utilisateur peut rechercher :

une unité archivistique en particulier et accéder à son détail,
une unité archivistique pour une transaction donnée.

Il est possible de :

limiter le nombre de résultats retournés au moyen d’un seuil de requête ;
obtenir :
- une liste de résultats, incluant l’ensemble des métadonnées des unités archivistiques ou une sélection,
- le nombre exact de résultats, s’il dépasse les 10 000 unités d’archives, au moyen d’un paramétrage de la plate-forme.
- un résultat par facettes (nombre d’occurrences pour une métadonnée donnée).

Point d’attention : le seuil de résultats supporté par le moteur d’indexation Elastic Search est de 10 000 unités archivistiques. Il est de fait recommandé d’utiliser des requêtes ne dépassant pas les 10 000 résultats.

Exemple : requête en vue d’obtenir l’unité archivistique dont l’identifiant est « aeeaaaaaaceezldyaamscambcvdf6zyaaaaq »

  @tenant = 1
  @unit-id= ***aeeaaaaaaceezldyaamscambcvdf6zyaaaaq***
  GET {{url}}/collect-external/v1/units/{{unit-id}}
  
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143
  
  {
  }

Exemple : requête en vue d’obtenir les unités archivistiques de la transaction dont l’identifiant est « aeeaaaaaaceezldyaamscambcvdf6zyaaaaq »

  @tenant = 1
  @transaction-id=* **aeeaaaaaaceezldyaamscambcvdf6zyaaaaq***
  
  GET {{url}}/collect-external/v1/transactions/{{transaction-id}}/units
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143
  {
   "$roots": [],
   "$query": [ {
   "$eq": {
   "#unitType": "INGEST"
   }
   }],
   "$filter": {},
   "$projection": {}
  }

Exemple : requête en vue d’obtenir les unités archivistiques de la transaction dont l’identifiant est « aeeaaaaaaceezldyaamscambcvdf6zyaaaaq » et ayant pour tout ou partie du champ Title la valeur « Bulletin »

  @tenant = 1
  @transaction-id=* **aeeaaaaaaceezldyaamscambcvdf6zyaaaaq***
  
  GET {{url}}/collect-external/v1/transactions/{{transaction-id}}/units
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143
  
  {
   "$roots": [],
   "$query": [ { "$match": { "Title": "Bulletin" } } ],
   "$filter": {},
   "$projection": {}
  }

14.3.3.3.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet d’accéder aux unités archivistiques d’une transaction.

Ce service est disponible :

depuis la page permettant de visualiser l’ensemble des projets de versement,
depuis la page permettant de visualiser l’ensemble des transactions (ou versements)

Ces deux accès mènent à une page permettant de :

visualiser l’ensemble des unités archivistiques d’une transaction,
rechercher dans cette liste selon de nombreux critères de recherche,
consulter les métadonnées d’une unité archivistique en particulier.

14.3.3.4. Accès aux groupes d’objets techniques

14.3.3.4.1. Utilisation des API

L’utilisateur peut récupérer :

les métadonnées techniques d’un groupe d’objets techniques donné,
l’objet numérique associé à une unité archivistique donnée.

Exemple : requête en vue d’obtenir le groupe d’objets techniques dont l’identifiant est « aeeaaaaaaceezldyaamscambcvdf6zyaaaaq »

  @tenant = 1
  @got-id= ***aeeaaaaaaceezldyaamscambcvdf6zyaaaaq***
  
  GET {{url}}/collect-external/v1/objects/{{got-id}}
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  Content-Length: 143
  
  {
  }

Exemple : requête en vue d’obtenir l’objet technique d’usage « BinaryMaster » et de version « 1 » associé à l’unité archivistique dont l’identifiant est « aeeaaaaaaceezldyaamscambcvdf6zyaaaaq »

  
  @tenant = 1
  @unit-id=* **aeeaaaaaaceezldyaamscambcvdf6zyaaaaq***
  
  GET {{url}}/collect-external/v1/units/{{unit-id}}/objects/BinaryMaster/1/binary
  Accept: application/json
  Content-Type: application/octet-stream
  X-Tenant-Id: {{tenant}}
  
  {
  }

14.3.3.4.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office Vitam UI fournie avec la solution logicielle Vitam permet d’accéder aux métadonnées techniques d’un groupe d’objets techniques ainsi qu’aux différents usages et versions d’un objet technique.

Ce service est disponible depuis la page permettant de visualiser l’ensemble des unités archivistiques d’une transaction au sein de l’onglet « Objet » du panneau latéral d’une unité archivistique. Il est également possible d’y télécharger les différents objets techniques.

14.3.4. Gestion des transactions

14.3.4.1. Définitions

Le module de collecte a vocation à permettre d’effectuer un certain nombre de traitement en amont du versement au niveau de la transaction.

Au terme de la V8.1, il est possible de réaliser les actions suivantes :

modification des informations relatives à l’en-tête du versement,
suppression d’une transaction et de son contenu,
abandon d’une transaction et de son contenu,
réouverture d’une transaction (ou versement),
clôture et validation de la transaction (ou versement),
transfert de la transaction (ou versement) depuis le module de collecte vers le back-office de la solution logicielle Vitam sous la forme d’un SIP conforme au SEDA 2.2.,
si le transfert est en succès ou en avertissement, suppression automatique des archives qui sont associées à la transaction.

Ces actions sont propres à chaque tenant de la solution logicielle Vitam.

Elles ne sont pas journalisées dans le journal des opérations. Seule l’opération de transfert des archives sous la forme d’un SIP, envoyée par le module de collecte, est tracée dans le journal des opérations (opération de type « INGEST »).

Point d’attention : L’ordre d’utilisation des API doit être respecté, notamment en vue de transférer avec succès l’ensemble des métadonnées et objets constituant un versement vers la solution logicielle Vitam pour conservation.

14.3.4.2. Modification d’une transaction

14.3.4.2.1. Utilisation des API

La solution logicielle Vitam permet de modifier une transaction, et plus précisément de :

modifier ses métadonnées,
lui ajouter des métadonnées,
supprimer des métadonnées.

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé :

un projet de versement ;
une transaction.

Exemple : requête en vue de modifier des métadonnées d’une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq » et dont le projet de versement associé a l’identifiant « aeaaaaaaaaecafogaeyu2amw2sbvtmaaaaaq »

  @tenant = 1
  
  PUT {{url}}/collect-external/v1/transactions
  accept: application/json
  content-type: application/json
  Content-Length: 401
  X-Tenant-Id: {{tenant}}
  
  {
   "#id": "**aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq**",
   "ArchivalAgencyIdentifier": "Vitam",
   "TransferringAgencyIdentifier": "RATP",
   "OriginatingAgencyIdentifier": "RATP",
   "SubmissionAgencyIdentifier": "RATP",
   "MessageIdentifier": "20200131-000001",
   "ArchivalAgreement":"IC-000001",
   "Comment": "RH - bulletins de salaire (février 2020)",
   "AcquisitionInformation":"Versement",
   "LegalStatus":"Public Archive",
   "ProjectId":"**aeaaaaaaaaecafogaeyu2amw2sbvtmaaaaaq**"
  }

Points d’attention :

Le service de mise à jour d’une transaction fonctionne en mode « annule et remplace ».
La plupart des champs d’une transaction étant facultatifs, il est recommandé d’indiquer les éléments obligatoires à la génération d’un SIP :
- le contrat d’entrée (champ « ArchivalAgreement »),
- l’identifiant du message (champ « MessageIdentifier),
- le service producteur (champ « OriginatingAgencyIdentifier »),
- le service d’archivage (champ « ArchivalAgencyIdentifier »),
- le service responsable du transfert (« TransferringAgencyIdentifier »)
Au terme de la version 8.1 :
- ce service ne vérifie pas le caractère obligatoire d’un champ. Il est fortement recommandé de veiller à ne pas supprimer un champ obligatoire, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
- on ne peut pas ajouter de règles de gestion dans une transaction ;
- aucun contrôle n’est effectué avec les référentiels et unités archivistiques de rattachement présents dans la solution logicielle Vitam. De fait, il est fortement recommandé de :
  - veiller à inclure des références (ex. service producteur, contrat d’entrée, etc.) existant dans la solution, de manière à éviter de possibles échecs lors des étapes de contrôles des données référentielles du processus d’entrée (opération « INGEST ») ;
  - ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.

Cette action provoque la mise à jour de la transaction.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Présence d’un champ inconnu dans la requête ; - La transaction n’existe pas.

14.3.4.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de modifier uniquement les informations de description et de contexte d’une transaction.

Ce service est disponible depuis la modification d’un projet de versement dans son panneau latéral uniquement si le choix est fait dans la pop-in s’affichant lors de l’enregistrement des modifications de les appliquer à la transaction en cours (ou versement en édition).

14.3.4.3. Suppression d’une transaction

14.3.4.3.1. Utilisation des API

La solution logicielle Vitam permet de supprimer une transaction.

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API.

Exemple : requête en vue de supprimer une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
  DELETE {{url}}/collect-external/v1/transactions/{{transaction-id}}
  accept: application/json
  content-type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}
 

Ces actions provoquent :

la suppression de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect).
si la transaction contient des archives (unités archivistiques, objets techniques), la suppression de l’ensemble des données associées à cette transaction de la base de données et des offres de stockage :
- les unités archivistiques sont supprimées de la collection « Unit » (base MetadataCollect) ;
- les groupes d’objets techniques sont supprimés de la collection « ObjectGroup » (base MetadataCollect).
- les objets sont supprimés des offres de stockage.

Mais le projet de versement ne sera pas supprimé.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- La transaction n’existe pas. - La transaction n’est pas reconnue dans la requête.

14.3.4.3.2. Utilisation dans VitamUI

Il n’est pas possible de supprimer une transaction depuis l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam.

14.3.4.4. Abandon d’une transaction

14.3.4.4.1. Utilisation des API

La solution logicielle Vitam permet également d’abandonner une transaction[58].

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API.

Exemple : requête en vue d’abandonner une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
  PUT {{url}}/collect-external/v1/transactions/{{transaction-id}}/abort
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  
  {}

Cette action provoque :

la modification de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect) : la valeur du champ « Status » devient « ABORTED » ;
la purge des données associées à la transaction, enregistrées dans les collections « Unit » et « ObjectGroup » (base MetadataCollect) et sur les offres de stockage, passé un certain délai configurable par tenant (60 minutes par défaut)[19].

Point d’attention :

Une transaction peut être abandonnée uniquement lorsque son statut est égal à « OPEN », « READY », « ACK_KO », « KO ».

Si elle a un statut égal à « SENDING », « SENT », « ACK_OK », « ACK_WARNING », elle ne peut pas l’être[58].
La différence avec l’action de suppression est que l’abandon :
- ne purge pas les archives directement, mais de manière automatisée, passé un certain délai ;
- ne supprime pas la transaction ;
- donne lieu à une mise à jour du statut de la transaction.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- La transaction n’existe pas. - La transaction n’est pas reconnue dans la requête. - La transaction a un statut égal à « SENDING », « SENT », « ACK_OK », « ACK_WARNING ».

14.3.4.4.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet d’abandonner une transaction. Son statut passe alors à « Abandonné »[58].

Ce service est disponible depuis la page permettant de visualiser l’ensemble des transactions (ou versements) via un bouton « Abandonner » présent dans les boutons d’actions secondaires.

Point d’attention: Le bouton est inactif quand la transaction a un statut « Préparation et envoi du SIP » (« SENDING »), « Envoyé, en cours de traitement du SAE » (« SENT »), « Versé avec succès » (« ACK_OK »), « Versé en avertissement » (« ACK_WARNING »).

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Abandon d’une transaction
Administrateur	oui
Archiviste	non
Service producteur	non

14.3.4.5. Réouverture d’une transaction

14.3.4.5.1. Utilisation des API

La solution logicielle Vitam permet également de rouvrir (ou rééditer) une transaction[58].

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API.

Exemple : requête en vue de réouvrir une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
  PUT {{url}}/collect-external/v1/transactions/aeeaaaaabohhxsvcaaxnqamfooffxkqaaaaq/reopen
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}
  
  {}

Cette action provoque la modification de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect) : la valeur du champ « Status » devient « OPEN ».

Dès lors, il est à nouveau possible de :

associer à la transaction rouverte des unités archivistiques, ainsi que des groupes d’objets techniques et des objets numériques ;
modifier, réorganiser et supprimer des unités archivistiques.

Point d’attention :

Une transaction peut être rouverte uniquement lorsque son statut est égal à « READY », « ACK_KO », « KO ».
Si elle a un statut égal à « OPEN », « SENDING », « SENT », « ACK_OK », « ACK_WARNING », « ABORTED », elle ne peut pas l’être.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- La transaction n’existe pas. - La transaction n’est pas reconnue dans la requête. - La transaction a un statut égal à « OPEN », « SENDING », « SENT », « ACK_OK », « ACK_WARNING », « ABORTED ».

14.3.4.5.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de rouvrir ou éditer une transaction[58]. Son statut passe alors à « Ouvert en édition ».

Ce service est disponible depuis la page permettant de visualiser l’ensemble des transactions (ou versements) d’un projet via un bouton « Editer » présent dans les boutons d’actions secondaires.

Point d’attention: Le bouton est inactif quand la transaction a un statut « Ouvert en édition » (« OPEN »), « Préparation et envoi du SIP » (« SENDING »), « Envoyé, en cours de traitement du SAE » (« SENT »), « Versé avec succès » (« ACK_OK »), « Versé en avertissement » (« ACK_WARNING »), « Abandonné » (« ABORTED »).

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Réouverture de transaction
Administrateur	oui
Archiviste	oui
Service producteur	non

14.3.4.6. Validation d’une transaction

14.3.4.6.1. Utilisation des API

La solution logicielle permet de clôturer une transaction[58], une fois l’ensemble des archives liées à cette transaction envoyées dans cette dernière et ne nécessitant plus de traitements.

Points d’attention :

Cette action est un prérequis à l’envoi d’un SIP depuis le module de collecte vers la solution logicielle Vitam.
Il faut avoir au préalable créé une transaction et la signaler dans l’API.

Exemple : requête de clôture

  @transaction-id = **aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq**
  @unit-id = aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/transactions/**{{transaction-id}}**/close
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  {}

Cette action provoque la modification de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect) :

la valeur du champ « Status » est désormais « READY » ;
si le paramètre « AutomaticIngest » présent dans le projet de versement associé à la transaction a une valeur « true », la valeur du champ « Status » est désormais « SENDING » et/ou « SENT », car la transaction est directement clôturée et envoyée dans la solution logicielle Vitam.

Exemple : enregistrement de la transaction dans la collection « Transaction »

  {
   "_id": "aeeaaaaaaghdvam4abgoyambfxnhd6aaaaaq",
   "Status": "READY",
   "Context": {
   "ArchivalAgreement": "IC-000001",
   "MessageIdentifier": "20220302-000005",
   "ArchivalAgencyIdentifier": "Vitam",
   "TransferringAgencyIdentifier": "AN",
   "OriginatingAgencyIdentifier": "MICHEL_MERCIER",
   "SubmissionAgencyIdentifier": "MICHEL_MERCIER",
   "Comment": "Versement du service producteur : Cabinet de Michel Mercier"
   },
   "CreationDate": "2022-10-15T15:50:06.153",
   "LastUpdate": "2022-11-15T15:50:06.153",
   "ProjectId": "aeaaaaaaaaha7iacabzrsamepp45blyaaaaq",
   "_tenant": 1
  }

Dès lors, si la transaction a un statut « READY », il n’est plus possible de :

associer à cette transaction des unités archivistiques, ainsi que des groupes d’objets techniques et des objets numériques ;
modifier, réorganiser et supprimer des unités archivistiques.

Point d’attention :

Une transaction peut être validée uniquement lorsque son statut est égal à « OPEN ».
Si elle a un statut égal à « SENDING », « SENT », « ACK_OK », « ACK_WARNING », « ACK_KO », « ABORTED », « KO », elle ne peut pas l’être.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- La transaction associée n’existe pas ; - La transaction associée a déjà été clôturée.

Point d’attention : S’il s’avère nécessaire de modifier le contenu d’une transaction ayant un statut « READY », il est toujours possible à ce stade la rouvrir[21].

14.3.4.6.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam utilise l’API de clôture pour valider une transaction (ou versement).

Ce service est disponible :

depuis la page permettant de visualiser l’ensemble des archives d’un projet de versement, où il est possible de :
- « Valider » un versement, action correspondant à la clôture du versement ;
depuis la page permettant de visualiser l’ensemble des transactions (ou versements) associées à un projet de versement, où il est possible de :
- « Valider » un versement, action correspondant à la clôture du versement[58].

Point d’attention : Le bouton est :

actif quand la transaction a un statut « Ouvert en édition » (« OPEN »),
inactif quand la transaction a un statut « Préparation et envoi du SIP » (« SENDING »), « Envoyé, en cours de traitement du SAE » (« SENT »), « Versé avec succès » (« ACK_OK »), « Versé en avertissement » (« ACK_WARNING »), « Echec du versement » (« ACK_KO »), « Erreur technique » (« KO »), « Abandonné » (« ABORTED »).

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Validation d’une transaction
Administrateur	oui
Archiviste	oui
Service producteur	oui

14.3.4.7. Envoi d’une transaction

14.3.4.7.1. Utilisation des API

Pour une transaction donnée, une fois celle-ci clôturée, le module de collecte permet de générer un SIP et de le transférer au moyen d’une opération de type « INGEST »[58].

Point d’attention :

En prérequis à l’envoi du SIP, il faut avoir au préalable clôturé la transaction (son statut doit être égal à « READY ») et signaler cette dernière dans l’API.
Cette action peut être automatisée si le paramètre « AutomaticIngest » présent dans le projet de versement associé à la transaction a une valeur « true ». Dès lors, dès validation de la transaction, la transaction est directement clôturée et envoyée dans la solution logicielle Vitam.

Exemple : requête d’envoi du SIP vers la solution logicielle Vitam pour conservation

  @transaction-id = **aeeaaaaaaghiyso4ablmyal74slqwtqaaaaq**
  @unit-id = aeeaaaaaaghiyso4ablmyal74sndwiqaaaaq
  @tenant = 1
  
  POST  {{url}}/collect-external/v1/transactions/{{**transaction-id**}}/send
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: ContratTNR
  
  {
  }

Cette action provoque[58] :

si elle est en erreur technique :
- la modification de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect) : la valeur du champ « Status » est « KO » ;
si elle est conforme :
- l’initialisation d’une opération de type « INGEST »,
- la modification de l’enregistrement dans la base de données MongoDB, dans la collection « Transaction » (base Collect) :
  - la valeur du champ « Status » est :
    - « SENDING » tant que l’opération de type « INGEST » n’a pas été initialisée par la solution logicielle Vitam,
    - « SENT » quand l’opération de type « INGEST » est en cours ;
  - un champ correspondant à l’identifiant de l’opération d’entrée est ajouté (VitamOperationId).Une fois l’opération de type « INGEST » terminée, le statut est :
    - si l’opération est en succès, la valeur du champ « Status » est désormais « ACK_OK » ; si l’opération est en avertissement, la valeur du champ « Status » est « ACK_WARNING » ;
    - si l’opération est en erreur, la valeur du champ « Status » est « ACK_KO ».

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- La transaction associée n’existe pas ; - La transaction associée n’a pas été clôturée ; - La transaction ne contient pas d’archives associées (unités archivistiques et groupes d’objets techniques).

Point d’attention : Au terme de la version 8.1, les archives transférées avec succès ou en avertissement (statut égal à « ACK_OK » et « ACK_WARNING ») pour archivage sont purgées du module de collecte passé un certain délai configurable par tenant (60 minutes par défaut)[22].

14.3.4.7.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam utilise l’API de génération d’un SIP pour envoi dans la solution logicielle Vitam.

Ce service est disponible :

depuis la page permettant de visualiser l’ensemble des archives d’un projet de versement, où il est possible de :
- « Verser » un versement, action correspondant à l’envoi du SIP.
depuis la page permettant de visualiser l’ensemble des transactions (ou versements) associées à un projet de versement, où il est possible de :
- « Verser » un versement, action correspondant à l’envoi du SIP[58].

Point d’attention : Le bouton est :

actif quand la transaction a un statut « Validé » (« READY »),
inactif quand la transaction a un statut « Ouvert en édition » (« OPEN »), « Préparation et envoi du SIP » (« SENDING »), « Envoyé, en cours de traitement du SAE » (« SENT »), « Versé avec succès » (« ACK_OK »), « Versé en avertissement » (« ACK_WARNING »), « Echec du versement » (« ACK_KO »), « Erreur technique » (« KO »), « Abandonné » (« ABORTED »).

Cette action entraîne la purge des archives passé un certain délai, si le résultat est un versement en succès ou en avertissement.

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Validation d’une transaction
Administrateur	oui
Archiviste	oui
Service producteur	non

14.3.5. Gestion des archives

14.3.5.1. Définitions

Le module de collecte a vocation à permettre d’effectuer un certain nombre de traitements sur les archives en amont du versement.

Au terme de la V8.1, il est possible de réaliser les actions suivantes :

modification,
ajout d’une à plusieurs unités archivistiques sous une unité archivistique,
réorganisation d’arborescences,
suppression.

Ces actions sont propres à chaque tenant de la solution logicielle Vitam.

Sont journalisées dans le journal des opérations :

réorganisation d’arborescences,
suppression. Ne sont pas journalisées dans le journal des opérations :
modification,
ajout d’une à plusieurs unités archivistiques sous une unité archivistique.

14.3.5.2. Modification des métadonnées

La solution logicielle Vitam permet de modifier des unités archivistiques par :

une mise à jour unitaire en masse de métadonnées,
import d’un fichier au format .csv,
import d’un fichier au format .jsonl.

14.3.5.2.1. Modification unitaire en masse

14.3.5.2.1.1. Utilisation des API

La solution logicielle Vitam permet de mettre à jour unitairement plusieurs unités archivistiques. Pour chacune d’entre elles, elle permet plus précisément de :

modifier des métadonnées descriptives,
ajouter des métadonnées descriptives,
supprimer des métadonnées descriptives.

Points d’attention :

En prérequis à la mise à jour unitaire en masse des unités archivistiques, il faut avoir au préalable créé une transaction et le signaler dans l’API ;
Il n’est pas possible d’ajouter une unité archivistique lors de cette action de mise à jour ;
Il n’est pas possible de mettre à jour des règles de gestion lors de cette action de mise à jour.

Exemple : requête en vue de modifier un titre pour une unité archivistique dont l’identifiant d’agent est « 123456 », de supprimer une date d’envoi et d’ajouter une description pour une unité archivistique dont l’identifiant d’agent est « 123457 »

@transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*

POST {{url}}/collect-external/v1/transactions/{{transaction-id}}/units/bulk
Accept: application/json
Content-Type: application/json
X-Tenant-Id: {{tenant}}

{
  "threshold": 10,
  "queries": [
    {
      "$query": [
        { "$eq": { "Agent.Identifier": "123456" } }
      ],
      "$action": [
        { "$set": { "Title": "Nouveau titre" } }
      ]
    },
    {
      "$query": [
        { "$eq": { "Agent.Identifier": "123457" } }
      ],
      "$action": [
        { "$unset": [ "SentDate" ] },
        { "$set": { "Description": "Description mise à jour" } }
      ]
    }
  ]
}

Cette action provoque la mise à jour des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[18]).

Points d’attention : L’API est synchrone et bloquante. L’action de mise à jour peut donc prendre quelques instants avant d’être effective.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Le seuil de requête est dépassé. - Plusieurs unités archivistiques ont été trouvées. - Aucune unité archivistique n’a été trouvée. - Le format de la métadonnées à modifier n’est pas conforme au type d’indexation défini dans l’ontologie.

Points d’attention :

L’échec ne concerne pas l’action en général, mais est spécifique à une unité archivistique en particulier.
La requête utilise le langage de requête DSL de type mise à jour unitaire de masse (BULK UPDATE) de la solution logicielle Vitam en entrée.
Le nombre de requêtes unitaires doit rester raisonnable, idéalement pas plus de 1000 par appel. Il est limité à un seuil maximum de 100 000 unités archivistiques par défaut. Ce seuil peut être redéfini dans la requête via le paramètre de seuil (threshold).

Elle n’est pas journalisée dans le journal des opérations.

14.3.5.2.1.2. Utilisation dans VitamUI

Depuis l’APP « Collecte et préparation des versements », le service de « modification unitaire en masse » est utilisé pour une modification unitaire. Il n’est pas disponible pour effectuer une modification de masse depuis cette APP.

14.3.5.2.2. Modification par import de fichier .csv

14.3.5.2.2.1. Utilisation des API

La solution logicielle permet de modifier des métadonnées descriptives et de gestion au moyen de l’import d’un fichier au format .csv. Il est plus précisement possible de :

modifier des métadonnées descriptives et/ou de gestion,
ajouter des métadonnées descriptives et/ou de gestion.

Points d’attention :

En prérequis à la mise à jour des unités archivistiques, il faut avoir au préalable créé :
- une transaction et le signaler dans l’API ;
- les unités archivistiques qui sont référencées dans le fichier .csv ;
Il n’est pas possible de :
- supprimer une métadonnée avec ce mode ;
- ajouter une unité archivistique lors de cette action de mise à jour.

Exemple : requête en vue de modifier des métadonnées d’unités archivistiques associées à une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id = aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq
  
  PUT {{url}}/collect-external/v1/transactions/{{**transaction-id**}}/units/metadata/csv
  Accept: application/json
  Content-Type: application/octet-stream
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}
  
  < /path_tozip/stream.csv

Pour une transaction donnée, peut être envoyé un fichier .csv contenant des métadonnées détaillant unitairement tout ou partie des unités archivistiques préalablement envoyées.

Le fichier .csv est composé de x colonnes[17] :

File : chemin relatif à partir de l’emplacement où est positionnée l’unité archivistique faisant l’objet de la modification. Il s’agit d’une concaténation des intitulés des différentes unités archivistiques (colonne obligatoire) ;
toute colonne correspondant à un champ du standard SEDA et nécessitant une modification et/ou un ajout de métadonnées (colonnes facultatives) ;
le cas échéant, toute colonne correspondant à une métadonnée externe du standard SEDA et nécessitant une modification et/ou un ajout de métadonnées (colonnes facultatives).

Points d’attention :

le fichier .csv n’est pas obligatoirement intitulé « metadata.csv » ;
l’ordre des premières colonnes ne doit pas être modifié ;
une première ligne d’en-tête donnant le nom des colonnes doit être présente, chaque ligne décrivant ensuite une unité archivistique ;
le séparateur entre les colonnes est le point-virgule, le séparateur de texte les guillemets doubles et l’encodage est « UTF-8 » ;
le fichier .csv ne référence que des métadonnées propres aux unités archivistiques (métadonnées descriptives et de gestion).
concernant le nommage des colonnes :
- pour les colonnes correspondant à des champs du standard SEDA, l’intitulé de la colonne doit correspondre à celui du champ dans le standard SEDA, précédé de « Management. » s’il s’agit d’une métadonnée de gestion (ex. « Management.AccessRule.Rule » pour une règle de communicabilité) ou de « Content. » s’il s’agit d’une métadonnée descriptive (ex. « Content.DocumentType ») ;
- pour les colonnes correspondant à des métadonnées externes au standard SEDA, l’intitulé de la colonne doit correspondre à celui du champ, précédé de « Content. » ;
- quand le schéma XML du standard SEDA propose une structure complexe de balises (par exemple pour décrire un auteur via l’objet XML Writer; qui contient plusieurs balises XML comme FullName ou BirthName), il convient d’intituler la colonne de la manière suivante : Content.Writer.FullName ou Content.Writer.BirthName ;
- quand un champ ou un objet XML est multivalué dans le standard SEDA (et qu’il est possible d’en décrire plusieurs dans le bordereau comme c’est le cas pour l’objet Writer par exemple), il convient de numéroter la colonne de la manière suivante : Content.Writer.0.FullName, Content.Writer.1.FullName ;
concernant le contenu des colonnes :
- la colonne File :
  - indique la position de l’unité archivistique dans l’arborescence de la transaction, depuis l’unité archivistique racine jusqu’à l’unité archivistique décrite. Il s’agit là d’une concaténation des intitulés des différentes unités archivistiques.
  - ne doit pas comprendre d’espace avant ou après les « / » ;
  - doit correspondre à un chemin tel que décrit par l’explorateur de fichiers (avec des « / ») ;
- la colonne DescriptionLevel, si elle est présente, ne doit comprendre que les valeurs autorisées par le standard SEDA : Collection, Fonds, Series, SubSeries, RecordGrp, File, Item ;
- les colonnes correspondant à des champs Date dans le standard SEDA doivent être formatées conformément à la norme ISO 8601 (AAAA-MM-JJ) ;
- les références à des règles de gestion doivent se conformer aux identifiants de règles présents dans le SAE ;
- les dates de début (Content.StartDate) doivent être antérieures aux dates de fin (Content.EndDate).

Exemple : fichier .csv de mise à jour des métadonnées (ajout ou modification des dates de début et de fin pour les unités archivistiques intitulées « AU1 » et « AU2 »)

  File;Content.DescriptionLevel;Content.Title;Content.StartDate;Content.EndDate
  "content/AU1";"Item";"AU1";"1970-06-03";"1980-06-03"
  "content/AU2";"Item";"AU2";"1970-06-03";"1980-06-03"
  "content/AU3";"Item";"AU3";"";""
  "content/AU4";"Item";"AU4";"";""

Cette action provoque la mise à jour des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[18]). Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Avertissement	Le formatage du fichier .csv contient au moins une erreur (ex. date mal formatée, valeur attendue erronée, date de début postérieure à la date de fin, etc.)
Échec	- Le fichier .csv n’est pas au format .csv. - Le fichier .csv contient des erreurs dans la colonne File. - Action non réalisée pour cause de nom erroné ou de chemin introuvable dans la requête. - La transaction n’existe pas ou est erronée. - La transaction a un statut « READY », « SENDING », « SEND », « ACK_OK », « ACK_WARNING », « ACK_KO », « KO », « ABORTED ».

Elle n’est pas journalisée dans le journal des opérations.

Point d’attention : Au terme de la V.8.1, le module de collecte peut :

-  bloquer la mise à jour si le fichier .csv dernier comporte les erreurs suivantes :
   -   il ne contient pas au moins la colonne obligatoire File ;
   -   au moins un fichier référencé dans le fichier .csv n'est pas présent dans l'arborescence bureautique,
   -   il ne contient aucune information ;
   -   il ne contient pas de séparateurs de champs ;
   -   il contient des virgules, des espaces, des pipes comme séparateurs de champs ;
   -   le fichier contient des simples guillemets comme séparateurs de texte ;
   -   etc.
   L'API peut :
       - soit renvoyer une seule erreur, si cette erreur est bloquante,
	   - soit renvoyer jusqu'à 20 erreurs, si ces erreurs sont cumulables.

-  ne pas bloquer la mise à jour si le fichier .csv dernier comporte les erreurs suivantes :
   -   il dispose d’un champ dont le contenu est mal formaté (ex. ReceivedDate écrite en chaîne de caractères) ;
Une erreur est alors renvoyée par l’API, le contenu du fichier .csv sera ignoré.

Il ne permet pas de :
- supprimer une métadonnée avec ce mode de mise à jour par envoi de fichier .csv ;
- ajouter un rattachement à une unité archivistique (UpdateOperation).

14.3.5.2.2.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de modifier tout ou partie des unités archivistiques d’une transaction au moyen de l’import d’un fichier .csv.

Ce service est disponible depuis la page permettant de visualiser l’ensemble des archives d’un projet de versement, où il est possible de « Mettre à jour les métadonnées ».

Point d’attention: Le bouton est :

actif quand la transaction a un statut « Ouvert en édition » (« OPEN »),
inactif quand la transaction a un statut « Validé » (« READY »), « Préparation et envoi du SIP » (« SENDING »), « Envoyé, en cours de traitement du SAE » (« SENT »), « Versé avec succès » (« ACK_OK »), « Versé en avertissement » (« ACK_WARNING »), « Echec du versement » (« ACK_KO »), « Erreur technique » (« KO »), « Abandonné » (« ABORTED »).

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Validation d’une transaction
Administrateur	oui
Archiviste	oui
Service producteur	non

14.3.5.2.3. Modification par import de fichier .jsonl

14.3.5.2.3.1. Utilisation des API

La solution logicielle permet de modifier des métadonnées descriptives et de gestion au moyen de l’import d’un fichier au format .jsonl. Il est plus précisement possible de :

modifier des métadonnées descriptives et/ou de gestion,
ajouter des métadonnées descriptives et/ou de gestion.

Points d’attention :

En prérequis à la mise à jour des unités archivistiques, il faut avoir au préalable créé :
- une transaction et le signaler dans l’API ;
- les unités archivistiques qui sont référencées dans le fichier .jsonl ;
Il n’est pas possible de :
- supprimer une métadonnée avec ce mode ;
- ajouter une unité archivistique lors de cette action de mise à jour.

Exemple : requête en vue de modifier des métadonnées d’unités archivistiques associées à une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id = aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq
  
  PUT {{url}}/collect-external/v1/transactions/{{**transaction-id**}}/units/metadata/jsonl
  Accept: application/json
  Content-Type: application/octet-stream
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}
  
  < /path_tozip/stream.jsonl

Pour une transaction donnée, peut être envoyé un fichier .jsonl contenant des métadonnées détaillant unitairement tout ou partie des unités archivistiques préalablement envoyées.

Le fichier .jsonl, obligatoirement intitulé « metadata.jsonl », est composé de :

File : chemin relatif à partir de l’emplacement où est positionnée l’unité archivistique faisant l’objet de la modification. Il s’agit d’une concaténation des intitulés des différentes unités archivistiques (champ obligatoire) ;
Selector : liste de conditions permettant l’enregistrement des métadonnées dans une unité archivistique correspond à ces conditions (champ obligatoire) ;
UnitContent : bloc dans lequel sont insérées les métadonnées descriptives et de gestion d’une unité archivistique nécessitant d’être modifiée (champ obligatoire), dont :
- DescriptionLevel : niveau de description de l’unité archivistique (champ facultatif) ;
- Title : intitulé de l’unité archivistique (champ facultatif) ;
- tout champ correspondant à un champ du standard SEDA et nécessitant une modification et/ou un ajout de métadonnées (champs facultatifs) ;
- le cas échéant, tout champ correspondant à un champ externe au standard SEDA et nécessitant une modification et/ou un ajout de métadonnées (champs facultatifs).

Points d’attention :

le fichier .jsonl n’est pas obligatoirement intitulé « metadata.jsonl » ;
le fichier .jsonl doit toujours contenir un champ File ou un champ Selector. Celui-ci doit toujours être placée en première position ;
les métadonnées pouvant être utilisées comme conditions dans le champ Selector doivent des éléments simples de type string, boolean, long ou double.
le fichier .jsonl ne référence que des métadonnées propres aux unités archivistiques (métadonnées descriptives et de gestion). Il ne supporte pas les métadonnées techniques propres aux fichiers numériques ;
le nommage des champs et leur structuration en JSON doivent se conformer au modèle de données de la solution logicielle Vitam.
concernant le contenu des champs :
- le champ File :
  - ne doit pas comprendre d’espace avant ou après les « / » ;
  - doit correspondre à un chemin tel que décrit par l’explorateur de fichiers (avec des « / ») ;
- le champ DescriptionLevel ne doit comprendre que les valeurs autorisées par le standard SEDA : Collection, Fonds, Series, SubSeries, RecordGrp, File, Item ;
- les champs correspondant à des champs Date dans le standard SEDA doivent être formatés conformément à la norme ISO 8601 (AAAA-MM-JJ) ;
- les références à des règles de gestion et à des profils d’unité archivistique doivent se conformer aux identifiants de règles présents dans le SAE
Les dates de début (Content.StartDate) doivent être antérieures aux dates de fin (Content.EndDate).

Exemple : fichier .jsonl de mise à jour des métadonnées

{"Selector": {"#uploadPath": "File","#tenant": 1},"UnitContent": { "DescriptionLevel": "Series", "Title": "File", "Description": "Modification de la description", "StartDate": "2023-01-01", "EndDate": "2023-01-31", "Tag": ["Paie"] } }
{"Selector": {"DescriptionLevel":"Item","OriginatingSystemId":"BP_123456_20230131","#tenant": 8},"UnitContent":{ "DescriptionLevel": "Item", "Title": "BP_123456_20230131.pdf", "OriginatingSystemId": ["BP_123456_20230131"], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire","Bulletin de paie", "tot"], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00001", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } }}

Cette action provoque la mise à jour des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[18]). Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Avertissement	Le formatage du fichier .jsonl contient au moins une erreur (ex. date mal formatée, valeur attendue erronée, date de début postérieure à la date de fin, etc.)
Échec	- Le fichier .jsonl n’est pas au format .jsonl. - Le fichier .jsonl contient des erreurs dans la colonne File ou Selector. - Action non réalisée pour cause de nom erroné ou de chemin introuvable dans la requête. - La transaction n’existe pas ou est erronée. La transaction a un statut « READY », « SENDING », « SEND », « ACK_OK », « ACK_WARNING », « ACK_KO », « KO », « ABORTED ».

Elle n’est pas journalisée dans le journal des opérations.

Point d’attention : Au terme de la V.8.1, le module de collecte peut :

-  bloquer la mise à jour si le fichier .jsonl dernier comporte les erreurs suivantes :
   -   il ne contient pas au moins le champ obligatoire File ou Selector ;
   -   au moins un bloc UnitContent ne contient aucune information ;
   -   au moins un fichier référencé dans le fichier .jsonl n'est pas présent dans l'arborescence bureautique,
   -   il ne contient aucune information ;
   -   une date de fin de règle a été intégrée dans le fichier .jsonl ;
   -   il dispose d’un champ dont le contenu est mal formaté (ex. ReceivedDate écrite en chaîne de caractères) ;
   -   etc.
   L'API peut :
       - soit renvoyer une seule erreur, si cette erreur est bloquante,
	   - soit renvoyer jusqu'à 20 erreurs, si ces erreurs sont cumulables.

-  ne pas bloquer la mise à jour si le fichier .jsonl dernier comporte les erreurs suivantes :
   -   il dispose d’un champ dont le contenu est mal formaté (ex. ReceivedDate écrite en chaîne de caractères) ;
Une erreur est alors renvoyée par l’API, le contenu du fichier .jsonl sera ignoré partiellement.

Il ne permet pas de :
- supprimer une métadonnée avec ce mode de mise à jour par envoi de fichier .jsonl ;
- ajouter un rattachement à une unité archivistique (UpdateOperation).

14.3.5.2.3.2. Utilisation dans VitamUI

Il n’est pas possible de mettre à jour des unités archivistiques au moyen d’un import de fichier .jsonl depuis l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam.

14.3.5.3. Réorganisation des arborescences

14.3.5.3.1. Utilisation des API

La solution logicielle Vitam permet de modifier l’organisation de l’arborescence des unités archivistiques d’une transaction. Il est possible de :

rattacher une unité archivistique à une unité archivistique, en respectant l’organisation hiérarchique de l’information,
modifier un rattachement préexistant,
ajouter un rattachement,
supprimer un lien hiérarchique entre une unité archivistique et une autre, ce qui signifie qu’on peut supprimer un sous-niveau d’un niveau de description parent.

Point d’attention :

En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API.
A noter qu’au terme de la version 8.1, il n’est pas possible de modifier la(les) position(s) de rattachement de la transaction, qu’elle(s) soi(en)t statique ou dynamique(s).

Exemple : requête en vue de déplacer l’unité d’archives dont l’identifiant est « aeaqaaaaaeecohy6ab4heamu7jl5epqaaaba »

@transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
POST {{url-collect}}/collect-external/v1/transactions/{{transaction-id}}/reclassification
Accept: application/json
Content-Type: application/json
X-Tenant-Id: {{tenant}}

[
  {
    "$roots": [],
    "$query": [{ "$eq": { "#id": "aeaqaaaaaeecohy6ab4heamu7jl5epqaaaba" } }],
    "$action": [
      {
        "$pull": {
          "#unitups": [ "aeaqaaaaaeecohy6ab4heamu7jl5epqaaaaq" ]
        },
        "$add": {
          "#unitups": [ "aeaqaaaaaeecohy6ab4heamu7jl5ejqaaaaq" ]
        }
      }
    ]
  }
]

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	Action non réalisée : - L’unité archivistique de destination semble inexistante ou inaccessible, - L’unité archivistique à déplacer semble inexistante dans la transaction.

Elle est journalisée dans le journal des opérations (COLLECT_RECLASSIFICATION).

14.3.5.3.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet dans la page de consultation des archives d’un projet de versement de :

modifier un rattachement préexistant,
ajouter un rattachement,
supprimer un lien hiérarchique entre une unité archivistique et une autre.

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Suppression d’archives
Administrateur	oui
Archiviste	oui
Service producteur	non

14.3.5.4. Ajout d’archives

14.3.5.4.1. Utilisation des API

La solution logicielle Vitam permet d’ajouter des unités archivistiques à une transaction donnée.

Point d’attention :

En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API.
Le(s) document(s) ajouté(s) doivent être compressé(s) au format .zip.

Exemple : requête en vue d’ajouter une ou plusieurs unité(s) archivistique(s) à une transaction dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
POST {{url}}/collect-external/v1/transactions/{{transaction-id}}/upload
Accept: application/json
Content-Type: application/zip
X-Tenant-Id: {{tenant}}
X-Access-Contract-Id: {{access-contract}}
*X-Attachement-Id : guid-de-au-cible*

< C:/Users/doc_a_ajouter.zip

Cette action provoque :

la création des unités archivistiques dans la base de données MongoDB, dans la collection « Unit » (base MetadataCollect[10]). Sont enregistrés automatiquement[11] :

- un niveau de description (DescriptionLevel) dont la valeur est :

- « RecordGrp » pour une unité archivistique référençant un répertoire, - « Item » pour une unité archivistique référençant un objet numérique ;

- un intitulé (Title), correspondant au nom d’un répertoire ou d’un objet binaire présent dans l’arborescence bureautique.

À chaque enregistrement, sont associés : - l’identifiant de la transaction (_opi) ; - un identifiant de batch (_batchId) ; - la localisation initiale du dossier ou du fichier dans l’arborescence (_uploadPath), - l’identifiant du service producteur (_sp et _sps) ;

la création de métadonnées techniques dans la base de données MongoDB, dans la collection « ObjectGroup » (base MetadataCollect[12]) ;

À chaque enregistrement, sont associés : - l’identifiant de la transaction (_opi) ; - un identifiant de batch (_batchId) ; - l’identifiant du service producteur (_sp) ;

l’enregistrement des objets numériques sur les offres de stockage.
la mise à jour des métadonnées techniques de l’objet avec, calculés lors de l’envoi du fichier numérique :

- ajout de l’empreinte d’un fichier numérique, - ajout de l’identification de son format, - mise à jour de son poids exprimé en octets.

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Échec	- Le fichier .zip n’a pas été téléchargé pour cause de nom erroné ou de chemin introuvable. - La transaction n’existe pas ou est erronée. - La transaction a été clôturée. - L’identifiant technique de la position cible est erroné.

Elle n’est pas journalisée dans le journal des opérations.

Point d’attention :

Aucun fichier ne doit avoir un poids équivalent à 0 octet.
Au terme de la V.8.1, il est recommandé que les noms de répertoires et de fichiers ne contiennent ni caractère accentué, ni virgule, ni apostrophe, ni parenthèse, ni espace, ni élément de ponctuation, ou tout autre caractère spécial. Ne sont à privilégier que l’underscore et le tiret comme séparateurs. Néanmoins, s’ils en contiennent et si l’arborescence bureautique émane d’un environnement Windows, il est recommandé d’utiliser l’outil Winzip pour la zipper, afin d’éviter des problèmes d’encodage.

14.3.5.4.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet d’ajouter des archives supplémentaires dans une transaction, en choisissant sa position cible dans l’arborescence, au moyen d’un wizard ou boîte de dialogue contenant une fenêtre d’upload.

14.3.5.5. Suppression d’archives

14.3.5.5.1. Utilisation des API

La solution logicielle Vitam permet de supprimer une à plusieurs unités archivistiques d’une transaction donnée.

Point d’attention : En prérequis à cette action, il faut avoir au préalable créé une transaction et le signaler dans l’API, pour une suppression d’unités archivistiques.

Exemple : requête en vue de supprimer l’unité d’archives dont l’identifiant est « aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq »

  @transaction-id= *aeeaaaaaachj3m7nabjocamcdqr2rqaaaaaq*
  
  POST {{url-collect}}/collect-external/v1/transactions/{{transaction-id}}/deletion/action
  Accept: application/json
  Content-Type: application/json
  X-Tenant-Id: {{tenant}}
  X-Access-Contract-Id: {{access-contract}}

{
  "dslRequest": {
    "$roots": [],
    "$query": [
      {
      "$eq": {
            "#id": "aeeaaaaaagecohy6ab4heamu6wrl5hiaaaaq"
          }
        }
    ],
    "$threshold": 10
  }
}

Cette action provoque la suppression :

-   des unités archivistiques de la collection « Unit » (base *MetadataCollect*) ;
-   des groupes d’objets techniques de la collection « ObjectGroup » (base *MetadataCollect*).
-   des objets des offres de stockage ;

Lors de cette action, l’opération peut aboutir aux résultats suivants :

Statut	Motifs
Succès	Action réalisée sans rencontrer de problèmes particuliers.
Avertissement	Au moins une des unités archivistiques ne peut pas être supprimée car elle(s) a(ont) des enfants (NON_DESTROYABLE_HAS_CHILD_UNITS).
Échec	Le seuil de requête est dépassé.

Elle est journalisée dans le journal des opérations (COLLECT_DELETION).

14.3.5.5.2. Utilisation dans VitamUI

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam permet de supprimer une à plusieurs unités archivistiques d’une transaction et, de fait, les objets numériques associés.

Des droits utilisateurs sont par ailleurs définis :

Profil utilisateur	Suppression d’archives
Administrateur	oui
Archiviste	oui
Service producteur	non

Les opérations de suppression sont journalisées et leur résultat accessible depuis l’APP « Journal des opérations ».

14.4. Conseils de mise en œuvre

À l’issue de cette phase de réalisation de fonctionnalités concernant le module de collecte, l’équipe du programme Vitam est en mesure de fournir plusieurs recommandations de mise en œuvre.

14.4.1. Comment formaliser les données dans les API du module de collecte ?

Il est possible de verser séparément dans le module de collecte selon un formalisme spécifique au format JSON :

les métadonnées correspondant à l’en-tête du message ArchiveTransfer,
les métadonnées décrivant les unités archivistiques,
les métadonnées techniques.

Chaque appel API[23] permettant de verser ces métadonnées inclut une liste d’éléments, clés ou vocabulaires que l’on souhaite intégrer dans le module de collecte.

Si ces éléments doivent respecter le formalisme attendu par le SEDA et l’ontologie de la solution logicielle Vitam (s’il s’agit d’une chaîne de caractères, d’une date, d’un élément répétable, etc.), il n’est pas nécessaire de les ordonnancer comme le demande le SEDA.

Si certains éléments, issus du SEDA et/ou du système externe, ne doivent pas être envoyés, il n’est pas nécessaire de les référencer dans les différents appels API[24].

Certains contrôles, disponibles au moment du transfert dans la solution logicielle Vitam n’ont pas été implémentés. Il est fortement recommandé de ne pas envoyer dans le module de collecte des éléments sans valeurs, en particulier ceux qui sont obligatoires et doivent nécessairement être renseignés.

14.4.1.1. Généralités

Dans un enregistrement JSON, un élément (ou vocabulaire) est désigné par son nom.

Exemple : l’élément suivant se nomme Description.

  "Description": "Ceci est une description"

Point d’attention :

Si un élément (ou vocabulaire), présent dans un enregistrement, n’existe pas dans l’ontologie, Il est fortement recommandé de l’avoir préalablement créé dans le référentiel[25].
Les vocabulaires issus du SEDA sont nommés de la même manière qu’ils le sont dans le standard (ex. l’élément « Tag » défini dans le SEDA est référencé sous ce nom dans l’ontologie et doit être indiqué comme tel).
Il existe néanmoins quelques exceptions à cette règle :
- le bloc Management doit être déclaré sous le nom #management. La modélisation des catégories de règle de gestion attend :
  - un sous-bloc « Rules » pouvant contenir 0 à n règles de gestion, non défini par le SEDA,
  - un sous-bloc « Inheritance » pouvant bloquer des règles de gestion, non défini par le SEDA. Ce sous-bloc peut également contenir l’élément « PreventRulesId » correspondant au champ « RefNonRuleId » du SEDA.
- si le bloc Event porte le nom « Event », ses sous-blocs doivent être renommés pour se conformer à l’ontologie :
  - « EventIdentifier » en « evId »,
  - « EventTypeCode » en « evTypeProc »,
  - « EventType » en « evType »,
  - « EventDateTime » en « evDateTime »,
  - « EventDetail » en « evTypeDetail »,
  - « Outcome » en « outcome »,
  - « OutcomeDetail » en « outDetail »,
  - « OutcomeDetailMessage » en « outMessg »,
  - « EventDetailData » en « evDetData ».
- les éléments Title et Description, s’ils contiennent des attributs, seront intitulés « Title_ » et « Description_ » et devront définir des propriétés[26].

14.4.1.2. Types

L’élément (ou vocabulaire) est associé à un type particulier[27]. On distingue plusieurs types JSON possibles :

« string » : texte ;
« number » : nombre, entier ou décimal ;
« integer » : nombre entier ;
« boolean » : booléen dont la valeur est « true » ou false ;
« object » : objet ;
« array » : liste ou tableau de valeurs textuelles.

Il doit alors être cohérent avec celui du vocabulaire tel qu’il est déclaré dans l’ontologie[28] :

Type d’indexation dans l’ontologie	Type correspondant dans un profil d’unité archivistique Vocabulaire interne	Type correspondant dans un profil d’unité archivistique Vocabulaire externe	Commentaires
TEXT	string ou [string]	[string]
KEYWORD	string ou [string]	[string]
DATE	string ou [string] + pattern date	[string] + pattern date
LONG	number ou integer [number] ou [integer]	[number] ou [integer]
DOUBLE	number ou [number]	[number]
BOOLEAN	boolean ou [boolean]	[boolean]
GEO_POINT	string	[string]	L’équipe Vitam n’a pas investigué sur les usages de ce type d’indexation
ENUM	[string] + pattern énumératif	[string] + pattern énumératif	L’équipe Vitam n’a pas investigué sur les usages de ce type d’indexation

Par analogie au SEDA et au langage XML, il convient de prêter attention aux éléments suivants :

sera qualifié en objet (« object ») un élément contenant des sous-éléments, par exemple : Management, Writer, Keyword ;
sera qualifié en tableau (ou « array ») :
- un élément répétable, tel que Tag ou OriginatingAgencyArchiveUnitIdentifier,
- un vocabulaire externe ;
certains éléments du SEDA (PreventInheritance, NeedAuthorization, NeedReassessingAuthorization) doivent contenir un booléen.

On trouvera essentiellement les types suivants :

pour les informations d’en-tête : les éléments sont uniquement de type « string » ou « array » ;
pour une unité archivistique :
- pour les vocabulaires internes, propres au SEDA, les principaux types rencontrés sont : « string », « array » et « object », auxquels s’ajoute un unique « boolean » et un unique « integer »[29].
- quant aux vocabulaires externes, ajoutés pour répondre à des besoins et transferts spécifiques, il faut les identifier systématiquement comme des « array » (ou tableaux), c’est-à-dire des éléments répétables. Ces tableaux peuvent inclure ensuite un type particulier de chaînes : texte, entier, décimal ou booléen.
Pour un groupe d’objets techniques:
- pour les vocabulaires internes, propres au SEDA, les principaux types rencontrés sont : « string », « array » et « object », auxquels s’ajoutent quelques « integer » ou « number ».

Les éléments de type « array » et « object » ont une structuration plus complexe qu’un type simple :

un type simple se définit par un nom, auquel est associé une seule valeur. Ce type est associé à un élément dont la cardinalité est 0-1 ou 1-1.

Exemple : les vocabulaires Description, GpsAltitude et NeedAuthorization sont des éléments simples. Attendant un entier, Size est caractérisé par un item de type « integer », tandis que NeedAuthorization est de type « boolean ».

  "Description": "Ceci est une description"
  "GpsAltitude": 390
  "NeedAuthorization": true

un élément de type « array » peut contenir une liste ou un tableau de valeurs ou d’objets. Ce type est associé à un élément dont la cardinalité est 0-n ou 1-n.

Exemple : les vocabulaires externes NomDuCapitaine, AgeDuCapitaine et le vocabulaire interne Tag sont dotés d’un type « array » dans l’enregistrement d’une unité archivistique. Attendant un entier, AgeDuCapitaine est caractérisé par un item de type « integer ».

  "NomDuCapitaine" : ["Capitaine Fracasse"],
  "AgeDuCapitaine" : [1],
  "Tag" : ["Marine", "Capitaine Fracasse"]

un élément de type « object » définit des sous-éléments. Ce type peut être associé à un tableau de sous-éléments (ex. « RegisteredAgent »).

Exemple :

  "RegisteredAgent": [{
   **"FirstName": "description",**
   "FullName": "description",
   "BirthName": "description"
   }]
  "BirthPlace": {
   **"Geogname": "Toronto [Ontario]",**
   "Address": "123 my Street",
   "PostalCode": "CD255",
   "City": "Toronto",
   "Region": "Ontario",
   "Country": "Canada"
   }

Enfin, en fonction du type d’indexation, les valeurs doivent être enregistrées

soit entre guillemets (string)
soit sans guillemets (integer, number, boolean).

Exemple : les vocabulaires Title, Size et NeedReassessingAuthorization sont des éléments simples : le premier est un string, le second un integer et le dernier un boolean.

  "Title": "Ceci est une description"
  "Size": 390
  "NeedReassessingAuthorization": false

14.4.1.3. Cas particulier

Les éléments « Title » et « Description », s’ils définissent un attribut ou sont répétables, doivent prendre la forme d’objet.

"Title_": {
     "fr": "Ceci est un titre en français",
     "en": "This is a title in English"
}
"Description_": {
     "fr": "Ceci est une description en français",
     "en": "This is a content in English"
}

Le bloc définissant les règles de gestion contient également des particularités. Il doit être déclaré sous le nom #management. La modélisation des catégories de règle de gestion attend :

un sous-bloc « Rules » pouvant contenir 0 à n règles de gestion,
un sous-bloc « Inheritance » pouvant bloquer des règles de gestion[30].

Exemple : Le bloc AppraisalRule déclare deux règles différentes dans le sous-bloc Rules, « APP-00001 » et « APP-00002 », et définit un blocage sur la catégorie de règle avec le sous-bloc PreventInheritance.

  "#management": {
   "AppraisalRule": {
   "Rules": [ {
   "Rule": "APP-00001",
   "StartDate": "2015-01-01",
   "EndDate": "2095-01-01"
   },
   {
   "Rule": "APP-00002"
   } ],
   "Inheritance": {
   "PreventInheritance": true,
   "PreventRulesId": []
   },
   "FinalAction": "Keep"
  }

14.4.2. Comment sont gérés les statuts d’une transaction ?

Le module de collecte attribue un certain nombre de statuts à une transaction. Ces statuts sont générés à la suite d’une action :

Actions disponibles	Statut correspondant dans le front-office	Statut correspondant dans le back-office	Modification possible ?	Abandon possible ?	Purge automatique ?
Créer la transaction	Ouvert en édition	OPEN	OUI	OUI
Clôturer / Valider	Validé	READY		OUI
Verser / Envoyer	Préparation et envoi du SIP	SENDING
Verser / Envoyer	Envoyé, en cours de traitement du SAE	SENT
Verser / Envoyer	Versé en succès	ACK_OK			OUI
Verser / Envoyer	Versé	ACK_WARNING			OUI
Verser / Envoyer	Échec du versement	ACK_KO		OUI
Verser / Envoyer	Erreur technique	KO		OUI
Éditer / Rouvrir	Ouvert en édition	OPEN	OUI
Abandonner	Abandonné	ABORTED			OUI

Ces services sont disponibles depuis l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam :

depuis la page permettant de visualiser l’ensemble des archives d’un projet de versement, où il est possible de :
- « Valider » un versement, action correspondant à la clôture du versement,
- « Verser » un versement, action correspondant à l’envoi du SIP.
depuis la page permettant de visualiser l’ensemble des transactions (ou versements) associées à un projet de versement, où il est possible de :
- « Accéder aux archives »,
- « Valider » un versement, action correspondant à la clôture du versement,
- « Verser » un versement, action correspondant à l’envoi du SIP,
- « Editer » un versement, action correspondant à la réouverture du versement en vue, notamment, de le modifier,
- « Abandonner » un versement, action correspondant à l’abandon du versement,

Certaines de ces actions entraînent la purge des archives passé un certain délai. Il s’agit des actions suivantes :

« Abandonner »
« Verser », si le résultat de cette action est un versement en succès ou en avertissement.

14.4.3. Comment paramétrer un versement ?

La solution logicielle Vitam permet de paramétrer des versements au moyen de la définition d’un projet de versement. Dans ce dernier, il est possible de :

définir des métadonnées d’en-tête qui seront héritées dans chacune des transactions qui seront associées au projet de versement et qui, de fait, ne nécessiteront pas d’être envoyées lors de la création d’une transaction. Peuvent être héritées les métadonnées suivantes :
- un intitulé (Name) ;
- des éléments obligatoires à la génération d’un SIP :
  - le contrat d’entrée (champ « ArchivalAgreement »),
  - l’identifiant du message (champ « MessageIdentifier),
  - le service producteur (champ « OriginatingAgencyIdentifier »),
  - le service d’archivage (champ « ArchivalAgencyIdentifier »),
  - le service responsable du transfert (« TransferringAgencyIdentifier »)
- des éléments facultatifs à la génération d’un SIP :
  - les modalités d’acquisition (« AcquisitionInformation »),
  - le statut légal des archives (« LegalStatus »),
  - le profil d’archivage (« ArchivalProfile »).

Points d’attention : Dans le cas d’un flux automatisé, à l’exception de l’intitulé (« Name ») et de l’identifiant du message (« MessageIdentifier »), qui seront la plupart du temps spécifiques à chaque transaction, il est recommandé de spécifier dans le projet de versement les autres métadonnées, qui ont un caractère plus générique.

définir des rattachements automatiques pour la(les) transaction(s) associée(s) au projet de versement :
- rattachement à une unité archivistique déjà conservée dans la solution logicielle Vitam (« UnitUp ») ;
- rattachement à des unités archivistiques déjà conservées dans la solution par la définition de conditions (« UnitUps »), à savoir une métadonnée (« MetadataKey »), une valeur (« MetadataValue ») et une position de rattachement (« UnitUp »). Si l’(les) unité(s) archivistique(s) racine(s) comporte(nt) la métadonnée et la valeur définies, alors elle(s) ira(ont) se rattacher à l’unité archivistique de rattachement associée ;
Ces deux paramètres peuvent être utilisés séparément ou ensemble. S’ils sont utilisés ensemble, alors, le module de collecte proposera un rattachement automatique des unités archivistiques racines suivant les conditions définies dans le projet de versement. Si elles ne remplissent pas les conditions, alors elles seront rattachées à l’unité archivistique de rattachement par défaut (« UnitUp »)[53].
paramétrer l’envoi automatique du SIP dans la solution logicielle Vitam dès la validation de la transaction (AutomaticIngest).
ajouter des règles de transformation exprimées dans un format JSLT[54].

14.4.4. Quels sont les rattachements possibles ?

On peut déclarer des règles de rattachement de plusieurs manières dans le module de collecte. Ces règles peuvent être cumulables en fonction de leur utilisation.

Dans un projet de versement, il est possible de déclarer :

une position unique de rattachement (champ UnitUp) ou « rattachement statique »,
une à plusieurs position(s) de rattachement en fonction de la définition de conditions à respecter dans le versement (champ UnitUps) ou « rattachement dynamique ». Ces deux paramètres sont cumulables.

Les règles appliquées sont les suivantes :

si un projet définit ces deux paramètres et si une unité archivistique entrante répond à une condition par clé/valeur,
elle sera rattachée à la position déclarée dans la condition de rattachement dynamique,
la règle de rattachement statique ne sera pas pris en compte, car ce sont les règles de rattachement dynamique qui l’emportent ;
si un projet définit ces deux paramètres et si une unité archivistique entrante ne répond à aucune condition par clé/valeur,
elle sera rattachée à la position de rattachement statique,
elle ne sera rattachée à aucune position de rattachement dynamique.
si un projet définit plusieurs conditions de rattachement dynamique et si une unité archivistique entrante a des correspondances avec plusieurs conditions,
elle sera rattachée à plusieurs positions de rattachement.
si un projet définit plusieurs conditions de rattachement dynamique mais pas de rattachement statique et si une unité archivistique entrante n’a aucune correspondance avec ces conditions,
elle ne sera rattachée à aucune position de rattachement.

Point d’attention: Les règles de rattachement statique et dynamique ne sont pas cumulables dans l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam.

Pour un projet de versement manuel, on ne peut définir qu’un rattachement statique,
Pour un projet de versement automatique, on peut :
soit définir un rattachement statique,
soit définir un rattachement dynamique. Mais on ne peut pas définir les deux paramètres dans un même projet de versement.

Il est également possible de déclarer des rattachements lors de l”import d’une arborescence bureautique associée à un fichier .jsonl ou .csv. Il est alors nécessaire de :

ajouter un répertoire matérialisant l’unité archivistique dans laquelle on souhaite rattacher l’arborescence bureautique,
déclarer ce répertoire dans le fichier .jsonl ou .csv accompagnant l’arborescence bureautique. Ne devront être renseignées que les informations suivantes : - File, - DescriptionLevel, - Title, - UpdateOperation.ArchiveUnitIdentifierKey.MetadataName et Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue OU UpdateOperation.SystemId.

Point d’attention :

Un rattachement ne peut être déclaré que dans un répertoire racine.
UpdateOperation.ArchiveUnitIdentifierKey.MetadataName et UpdateOperation.SystemId ne sont pas cumulables. Pour une unité archivistique, on ne peut renseigner que l’un ou l’autre, mais pas les deux en même temps.
Si on a employé UpdateOperation.ArchiveUnitIdentifierKey.MetadataName, il faut nécessairement déclarer UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue et inversement.
Si le projet de versement associé à la transaction déclare un rattachement statique et/ou un rattachement dynamique et et si le fichier .jsonl ou .csv associé à l’arborescence bureautique déclare un rattachement, alors les règles de rattachement déclarées dans le projet de versement ne seront pas appliquées. Dans cette arborescence, si une unité archivistique racine ne déclare pas de rattachement, alors le rattachement statique et/ou dynamique s’appliquera.
Un rattachement ne peut être ajouté lors d’une mise à jour des métadonnées, notamment par envoi de fichier .jsonl ou .csv.

Par ailleurs, un rattachement peut être :

ajouté suite à l’utilisation d’une transformation paramétrée dans un projet de versement via des commandes JSLT. Si le projet déclare en plus un rattachement statique et/ou dynamique, ce dernier ne sera pas appliqué. Le module de collecte exécute en priorité les transformations de rattachement exprimées en JSLT.
supprimé suite à l’utilisation d’une transformation paramétrée dans un projet de versement.
- Si le projet déclare un rattachement statique et/ou dynamique, ce dernier pourra être appliqué, suivant les règles définies plus haut.
- Si les conditions de rattachement définies dans les ordres de transformation JSLT ne sont pas réunies et si le projet déclare un rattachement statique et/ou dynamique, ce dernier pourra être appliqué, suivant les règles définies plus haut.

Enfin, il est possible d”ajouter des répertoires dans une transaction.

Si ces répertoires sont accompagnés d’un fichier .jsonl ou .csv, celui-ci ne peut contenir des informations de rattachement.
S’il en contient, l’ajout des répertoires sera en échec.

14.4.5. Comment paramétrer des règles de transformation ?

La solution logicielle Vitam permet d’agir sur les métadonnées des archives versées au moyen d’une configuration au format JSLT paramétrée dans un projet de versement (TransformationRules). Dans cette configuration, il est possible de demander :

l’ajout de métadonnées descriptives ou de gestion de manière systématique, le cas échéant en fonction de critères à définir ;
la suppression de métadonnées,
la modification de métadonnées en fonction de critères à définir ;
la transformation de métadonnées en des métadonnées conformes au SEDA ;
la modification de valeurs renseignées dans les métadonnées afin de les nettoyer (ex. ajout de majuscule, suppression d’espaces, etc.).

Le but d’un fichier au format JSLT est de transformer du JSON[55]. Son application est toujours évaluée par rapport à une entrée, appelée « le nœud de contexte ». Le résultat peut être un objet, un nombre, une chaîne de caractères, une valeur nulle (« null »), etc., exprimé au format JSON, format dans lequel sont transformées les métadonnées une fois importées dans le module de collecte[56].

Prenons l’entrée suivante :

Exemple : Fiche matricule d’Albert Dupont (enregistrement JSON)

{
  "Title" : "Albert Dupont",
 "DocumentType" : "Fiche matricule",
  "Coverage" : {"Temporal" : ["XXème siècle","1ère guerre mondiale","1914-1918"],"Spatial" : ["France","Verdun"},
  "ID-ARK" : "mon-domaine/12345/eaferzebn13bac"
  "#management": {
        "AccessRule": {
                "Rules": [
                    {
                        "Rule": "ACC-00001",
                        "StartDate": "2007-09-25"
                    }
                ]
            }
    }

}

Exemple : Fiche matricule d’Albert Dupont (fichier .csv)

"File","Content.Title";"Content.DocumentType";"Content.Coverage.Temporal.0";"Content.Coverage.Temporal.1";"Content.Coverage.Temporal.2";"Content.Coverage.Spatial.0";"Content.Coverage.Spatial.1";"Content.ID-ARK";"Management.AccessRule.Rule";"Management.StartDate.Rule"
"eaferzebn13bac.pf","Albert Dupont";"Fiche matricule";"XXème siècle";"1ère guerre mondiale";"1914-1918";"France";"Verdun";"Content.ID-ARK";"ACC-00001";"2007-09-25"

14.4.5.1. Absence d’actions sur les données entrantes

Si l’on souhaite uniquement ajouter des métadonnées, sans agir sur les données entrantes, il faudra déclarer les métadonnées et les valeurs à ajouter, suivies de l’expression « * : . ».

*Exemple : Ajout d’un Tag dont la valeur est « Fiche matricule » en plus des autres métadonnées entrantes.

{
    "Tag": "Fiche matricule",
    *: .
}

Exemple : Ajout d’une règle de diffusion dont la règle est DISS-00001 et la date de début 2007-09-25 en plus de la règle de communicabilité déjà présente dans les données entrantes.

{
    "#management": {
        "DisseminaRule": {
                "Rules": [
                    {
                        "Rule": "DISS-00001",
                        "StartDate": "2007-09-25"
                    }
                ]
            },
        *: .
    },
    *: .
}

Point d’attention : L’expression « * : . » est présente à deux endroits :

dans le bloc #management car il peut y avoir d’autres règles de gestion dans les données entrantes,
dans le nœud courant afin de récupérer la globalité des informations.

14.4.5.2. Actions sur les données entrantes

Si l’on souhaite agir sur les données entrantes, il faudra nommer la métadonnée en la préfixant d’un point (ex. .DocumentType). On parlera alors de « clé ». Voici quelques règles en fonction de la métadonnée concernée :

Type d’élément	Nommage possible de la clé	Résultat obtenu en sortie	Commentaires
Élément « feuille »	.DocumentType	« Fiche matricule » Soit la(les) valeur(s) de la métadonnée DocumentType
Élément englobant	.Coverage	« Temporal » : [« XXème siècle », »1ère guerre mondiale », »1914-1918 »], »Spatial » : [« France », »Verdun »]. Soit la(les) métadonnée(s) englobée(s) et leur(s) valeur(s)
Élément englobé	.Coverage.Temporal	[« XXème siècle », »1ère guerre mondiale », »1914-1918 »] Soit la(les) valeur(s) de la métadonnée Temporal.
Élément avec caractères spéciaux	. »ID-ARK »	« mon-domaine/12345/eaferzebn13bac » Soit la(les) valeur(s) de la métadonnée ID-ARK	Si une des clés à utiliser contient des caractères spéciaux, il est nécessaire de mettre son nom entre guillemets, sans quoi la clé ne fonctionnera pas.
Éléments factorisés	.Coverage	[.Temporal, .Spatial]	[ « XXème siècle », « 1ère guerre mondiale », « 1914-1918 » ], [ « France » ]
Elément variabilisé	let varDocumentType = .DocumentType Usage : $varDocumentType	« Fiche matricule »	Il est possible de définir des variables pour découper des expressions complexes ou éviter de recalculer plusieurs fois la même chose.

On pourra insérer des expressions dans un nouvel objet au moyen de l’appel à ces clés. En d’autres termes, on peut, par exemple, ajouter une métadonnée dans laquelle on insérera les valeurs d’une clé passée en paramètre.

Point d’attention : Si une expression produit null, {} ou [], la clé est omise.

Exemple : Ajout d’un Tag dont la valeur sera égale à la valeur de la métadonnée DocumentType en plus des autres métadonnées entrantes.

{
    "Tag": .DocumentType,
    *: .
}

Il est également possible de vouloir conserver l’ensemble des valeurs du fichier à l’exception de certaines, dans ce cas on utilisera l’expression « * - ValeurExclue : . ».

Exemple : Ajout d’un Tag dont la valeur sera égale à la valeur de la métadonnée DocumentType et exclusion de la métadonnée DocumentType.

{
    "Tag": .DocumentType,
     * - DocumentType : .
}

Il est possible d’intervenir sur les données entrantes de manière à agir sur la sortie via :

l”indexation en tableau avec le paramètre [index]. Ainsi, .Coverage.Temporal[0] donnerait « XXème siècle » en utilisant l’exemple général d’entrée du début de ce document. On peut également découper des tableaux. Par exemple, .Coverage.Temporal[1 : 3] donnera [« XXème siècle », « 1914-1918 »]. Le premier indice est donc inclusif et que le dernier est exclusif. Par ailleurs, le compte de l’index commence toujours à 0. Les indices négatifs sont autorisés pour référencer les éléments en partant de la fin du tableau. Ainsi, [-1] renverrait le dernier élément du tableau. Cela fonctionne aussi avec le découpage : pour supprimer le premier et le dernier élément, il faut écrire [1 : -1]. Ce mode permet de sélectionner les données à extraire.
les fonctions intégrées proposées par JSLT qui permettent de transformer les données[57].

Exemple : Passage en majuscules des valeurs de la métadonnée Title et remplacement de la valeur de la métadonnée DocumentType (« Registre matricule » devient « Fiche matricule »).

{
"Title":trim(uppercase(.Title)),
"DocumenType": replace(.DocumentType,"Registre matricule","Fiche matricule")
}

de nouvelles fonctions, qu’il faut déclarer en amont des expressions de transformation du fichier JSLT. La syntaxe est la suivante : def Nomfonction(paramètre(s)) Il est possible d’utiliser des variables préalablement définies au sein de la définition d’une fonction. Les fonctions peuvent également s’appeler elles-mêmes et appeler d’autres fonctions déjà définies.

Point d’attention : Si deux fonctions différentes utilisent le même nom, seule la dernière fonction définie sera prise en compte.

des opérateurs.

Type	Opérateur
Mathématiques	+ : addition. Il sert également à la concaténation de chaînes de caractères, tableaux et objets.
Comparaisons	> : supérieur à < : inférieur à ≥ : supérieur ou égal à ≤ : inférieur ou égal à != : différent de == : égal à
Boléens	and, or, not(etc.)

Dans le fichier .jslt, on peut introduire :

des expressions conditionnelles telles que : if () else . L’expression if retourne toujours une valeur et ne fait rien d’autre. La partie else peut être omise, auquel cas l’expression if retournera null si la condition est fausse. Les valeurs false, null, {} et [] sont évaluées comme false.

Exemple : Ajout d’un champ Tag récupérant la valeur du champ DocumenType si le champ DocumentType est présent et contient une valeur dans les données entrantes.

if (.DocumentType)
  {
    "Tag" : [.DocumentType]
  }
else
  { 
    "Tag" : ["Registre matricule"]
  }

*Résultat :*
-   Si le champ DocumentType est présent et contient une valeur dans les données entrantes :

{
  "Tag" : [ "Registre matricule" ]
}

-   S'il n'y a aucun résultat, la transformation ajoutera le champ Tag et la valeur "Registre matricule" :

{
  "Tag" : [ "Registre matricule" ]
}

Points d’attention :

Ecrire if(.DocumentType!=null) est équivalent à utiliser if(.DocumentType).
Dans l’exemple ci-dessus, utiliser des conditions permet non seulement de transformer les métadonnées entrantes (DocumentType devient Tag), mais aussi d’uniformiser les saisies de valeurs quand on sait que certaines métadonnées ne sont pas systématiquement renseignées.
des boucles telles que : [for () ]. L’expression for permet de parcourir un tableau et de transformer chaque élément en appliquant une expression. L’expression entre parenthèses est comprise comme un tableau sur lequel on boucle. Pour chaque élément du tableau, la seconde expression est évaluée.

Exemple : Ajout d’un champ Tag récupérant les valeurs du champ Temporal que l’on souhaite transformer en majuscules.

{"Tag" : [for (.Coverage.Temporal) trim(uppercase(.))]}

Une boucle peut être aussi utilisée pour : 
-   transformer les valeurs d’un tableau de nombres à chaînes de caractères en utilisant la fonction string(.), 
-   transformer un tableau en objet.

14.4.6. Quels sont les profils utilisateurs possibles ?

L’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam propose trois profils utilisateurs :

administrateur,
archiviste,
service producteur.

Chacun d’eux a la possibilité d’agir sur cette APP à des degrés différents :

Profil utilisateur	Administrateur	Archiviste	Service producteur
Créer une transaction	oui	oui	oui
Valider une transaction	oui	oui	oui
Verser une transaction	oui	oui	non
Ajouter des archives	oui	oui	oui
Réorganiser des arborescences	oui	oui	non
Supprimer des archives	oui	oui	non
Modifier unitairement des archives	oui	oui	oui
Modifier des archives par import de fichier .csv	oui	oui	non

Par ailleurs, il est possible de restreintre d’accès aux projets et aux transactions via l’utilisation d’un contrat d’accès. Ainsi, un utilisateur du front-office VitamUI devant accéder aux projets de versement d’un service en particulier, et à ses transactions, pourra ne voir que ceux-là si son profil utilisateur est associé à un contrat d’accès lui permettant d’accéder uniquement aux archives de ce service.

14.4.7. Quels sont les services disponibles ?

Le module de collecte met à disposition des services :

via les API
depuis l’APP « Collecte et préparation des versements » du front-office VitamUI fournie avec la solution logicielle Vitam.

Voici un tableau récapitulatif des services disponibles, mettant en évidence les nouveautés des deux dernières versions publiées de la solution logicielle Vitam :

—	APP Collecte	Back module de collecte
Configurer des versements	Crée N projets de versement : - Pour des versements manuels - Pour des versements de flux automatisés	Crée N projets de versement : - Pour des versements manuels - Pour des versements de flux automatisés
(Pré-)Verser les archives	- Crée automatiquement 1 transaction associée (mode lot ou unitaire) pour 1 projet de versement manuel préalablement créé. - Ne crée pas de transaction associée à un projet de versement automatique. - Ajouts a posteriori possibles d’archives (mode lot) - version 8.1	- Crée N transactions associées avec ses archives (mode lot ou unitaire). - Ajouts a posteriori possibles d’archives (mode lot - version 8.1 - ou unitaire)
Consulter les (pré-)versement(s)	- Liste les projets de versement - Recherche dans les projets de versement - Affichage du détail d’un projet de versement - Liste les transactions associées à un projet - Liste les archives d’une transaction - Recherche simple / avancée / arborescence dans les archives d’une transaction - Affichage du détail d’une unité (métadonnées descriptives et de gestion, métadonnées techniques) - Téléchargement de l’objet numérique	- Liste les projets de versement - Recherche dans les projets de versement - Affichage du détail d’un projet de versement - Liste les transactions associées à un projet - Affichage du détail d’une transaction - Liste les archives d’une transaction - Recherche simple / avancée / arborescence dans les archives d’une transaction - Affichage du détail d’une unité (métadonnées descriptives et de gestion, métadonnées techniques) - Téléchargement de l’objet numérique
Traiter les archives	- définition et mise à jour de métadonnées contextuelles, - identification de format, - calcul d’empreintes, - calcul du poids de l’objet numérique, - mise à jour de métadonnées descriptives et de gestion (par import de fichier .csv), - mise à jour unitaire de métadonnées descriptives, - suppression d’archives - version 8.1, - réorganisation d’archives - version 8.1, - gestion de statuts (ex. réouverture ou abandon d’un (pré-)versement)	- définition et mise à jour de métadonnées contextuelles, - identification de format, - calcul d’empreintes, - calcul du poids de l’objet numérique, - mise à jour de métadonnées descriptives et de gestion (par import de fichier .csv et .jsonl), - mise à jour unitaire en masse de métadonnées descriptives et de gestion, - suppression d’archives - version 8.1, - réorganisation d’archives - version 8.1, - gestion de statuts (ex. réouverture ou abandon d’un (pré-)versement), - suppression unitaire d’un (pré-versement) et d’un projet de versement
Transférer les archives	- Générer un SIP - Suppression automatique	- Générer un SIP - Suppression automatique
Gestion des droits	- Trois groupes de profils : administrateur, archiviste, service producteur - version 8.0, - Possibilité de filtrage des accès aux projets par service producteur - version 8.0.

14.5. Annexe 1 : Exemples de données entrantes

*Nota bene *: les cas présentés ci-dessous sont des exemples fictifs.

14.5.1. Métadonnées d’en-tête

{
  "ArchivalAgencyIdentifier": "Vitam",
  "TransferringAgencyIdentifier": "AN",
  "OriginatingAgencyIdentifier": "MICHEL_MERCIER",
  "SubmissionAgencyIdentifier": "MICHEL_MERCIER",
  "MessageIdentifier": "20220302-000005",
  "ArchivalAgreement":"IC-000001",
  "Comment": "Versement du service producteur : Cabinet de Michel Mercier"
}

14.5.2. Création unitaire d’archives

14.5.2.1. Unités archivistiques

{
    "DescriptionLevel": "RecordGrp",
    "Title": "Discours de Michel Mercier",
    "#management": {
      "AccessRule": {
            "Rules": [
                {
                    "Rule": "ACC-00001",
                    "StartDate": "2000-01-01"
                }
            ]
        }
      }
}

14.5.2.2. Objets

{
  "FileInfo": {
    "Filename": "MonFichier.txt"
  }
}

14.5.3. Création d’archives en lot avec fichier .jsonl

Exemple 1 : contenu d’un fichier « metadata.jsonl ».

{ "File": "File", "UnitContent": { "DescriptionLevel": "Collection", "Title": "File", "Description": "Ceci est un versement de bulletins de paie", "StartDate": "2023-01-01", "EndDate": "2023-01-31", "Tag": [ "Paie", "Bulletin" ] } }
{ "File": "File/BP_123456_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123456_20230131.pdf", "OriginatingSystemId": [ "BP_123456_20230131" ], "Agent": [ { "FirstName": "DUPONT", "BirthName": "Charles", "Identifier": [ "123456" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00001", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } }
{ "File": "File/BP_123463_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123463_20230131.pdf", "OriginatingSystemId": [ "BP_123463_20230131" ], "Agent": [ { "FirstName": "DUPOND", "BirthName": "Victor", "Identifier": [ "123463" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00002", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } }
{ "File": "File/BP_123464_20230131.pdf", "UnitContent": { "DescriptionLevel": "Item", "Title": "BP_123464_20230131.pdf", "OriginatingSystemId": [ "BP_123464_20230131" ], "Agent": [ { "FirstName": "CHARLES", "BirthName": "Ray", "Identifier": [ "123464" ] } ], "SentDate": "2023-01-31", "AcquiredDate": "2023-01-20", "Tag": [ "Salaire" ], "#management": { "AppraisalRule": { "Rules": [ { "Rule": "APP-00002", "StartDate": "2023-01-20" } ], "FinalAction": "Destroy" }, "AccessRule": { "Rules": [ { "Rule": "ACC-00016", "StartDate": "2023-01-20" } ] } } } } 

Exemple 2 : contenu d’un fichier « metadata.jsonl » décrivant un contexte de signature détachée.

{ "File" : "My Root Folder", "ObjectFiles": "SomeFile.xml", "UnitContent": { "Title": "My Root Folder (with attached SomeFile.xml)" } }
{ "File" : "My Root Folder/MyFile1.txt", "ObjectFiles": null, "UnitContent": { "Title": "My Root Folder/MyFile1.txt" } }
{ "File" : "My Root Folder/MyFile2.txt", "ObjectFiles": "My Root Folder/MyFile2.txt", "UnitContent": { "Title": "My Root Folder/MyFile2.txt" } }
{ "File" : "My Root Folder/SubFolder", "ObjectFiles": "My Root Folder/SubFolder/MyFile3.txt", "UnitContent": { "Title": "My Root Folder/SubFolder (with attached MyFile3.txt)" } }
{ "Selector" : { "#uploadPath" : "Yet Another Folder" }, "ObjectFiles": "My Root Folder/SubFolder/MyFile4.txt", "UnitContent": { "Title": "Yet Another Folder (with attached MyFile4.txt)" } }

Exemple 3 : contenu d’un fichier « metadata.jsonl » déclarant un rattachement.

{ "File": "Discours hors parlement", "UnitContent": { "DescriptionLevel": "RecordGrp", "Title": "Discours hors parlement", "#management": { "UpdateOperation": { "ArchiveUnitIdentifierKey" : { "MetadataName" : "ArchivalAgencyArchiveUnitIdentifier", "MetadataValue" : "20130456/3"} }  } } }
{ "File": "Discours hors parlement/Discours d'inauguration", "UnitContent": { "DescriptionLevel": "RecordGrp", "Title": "Discours d’inauguration" } }
{ "File": "Discours hors parlement/Discours d'inauguration/Inauguration de Notre-Dame.odt", "UnitContent": { "DescriptionLevel": "Item", "Title": "Inauguration de Notre-Dame" } }
 

14.5.4. Création d’archives en lot avec fichier .csv

Exemple 1 : contenu d’un fichier « metadata.csv ».

  "File";"Content.DescriptionLevel";"Content.Title";"Content.FilePlanPosition";"Content.ArchivalAgencyArchiveUnitIdentifier";"Content.Description";"Content.CustodialHistory.CustodialHistoryItem.0";"Content.CustodialHistory.CustodialHistoryItem.1";"Content.CustodialHistory.CustodialHistoryItem.2";"Content.DocumentType";"Content.Language";"Content.DescriptionLanguage";"Content.Version";"Content.Tag.0";"Content.Tag.1";"Content.Tag.2";"Content.Tag.3";"Content.Tag.4";"Content.Keyword.0.KeywordContent";"Content.Keyword.0.KeywordType";"Content.Keyword.1.KeywordContent";"Content.Keyword.1.KeywordType";"Content.Keyword.2.KeywordContent";"Content.Keyword.2.KeywordType";"Content.Keyword.3.KeywordContent";"Content.Keyword.3.KeywordType";"Content.Keyword.4.KeywordContent";"Content.Keyword.4.KeywordType";"Content.Coverage.Spatial.0";"Content.Coverage.Spatial.1";"Content.Coverage.Spatial.2";"Content.Coverage.Spatial.3";"Content.Coverage.Temporal";"Content.Coverage.Juridictional.0";"Content.Coverage.Juridictional.1";"Content.Coverage.Juridictional.2";"Content.Coverage.Juridictional.3";"Content.OriginatingAgency.Identifier";"Content.SubmissionAgency.Identifier";"Content.StartDate";"Content.EndDate";"Management.AccessRule.Rule";"Management.AccessRule.StartDate"
  "AU1/27juillet1888/5FI6_/5FI6_16";"RecordGrp";"Brantes. Combe de la Mure.";"instrument_recherche/5FI6/5FI6_16";"5 Fi 6/16";"Dim. 18x24 cm.";;;;;"fre";"fre";"Original";"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;;"Combe de la Mure (Brantes, Vaucluse, France)";"geogname";"Brantes (Vaucluse, France)";"geogname";;;;;;;"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;1888;"Combe de la Mure (Brantes, Vaucluse, France)";"Brantes (Vaucluse, France)";;;;;;"1888-12-30T00:00:00";"ACC-00001";"1888-12-30"
  "AU1/27juillet1888";"RecordGrp";"Clichés du 27 juillet 1888";;;;;;;;"fre";"fre";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Exemple 2 : contenu d’un fichier « metadata.csv » décrivant un contexte de signature détachée.

  "File";"ObjectFiles";"Content.DescriptionLevel";"Content.Title";"Content.Description";"Content.DocumentType";"Content.Tag";"Content.EndDate";"Content.SigningInformation.SigningRole.0";"Content.SigningInformation.SigningRole.1";"Content.SigningInformation.SigningRole.2";"Content.SigningInformation.SignatureDescription.0.Signer.FullName";"Content.SigningInformation.SignatureDescription.0.Signer.SigningTime";"Content.SigningInformation.TimestampingInformation.TimeStamp";"Content.SigningInformation.AdditionalProof.0.AdditionalProofInformation.0";"Content.SigningInformation.AdditionalProof.0.AdditionalProofInformation.1";"Management.AppraisalRule.Rule";"Management.AppraisalRule.StartDate";"Management.AppraisalRule.FinalAction";"Management.AccessRule.Rule";"Management.AccessRule.StartDate"
  "**Parapheur**";"Parapheur/20230615_note_Vu AB.pdf";"Item";"20230615_note_Vu AB.pdf";"Parapheur créé par Al Capone. Note";"Document signé";"Note";"2023-06-15";"SignedDocument";"Signature";"Timestamp";"Al Capone";"2023-06-15T11:18:12";"2023-06-15T11:18:12";"EvidenceRecords";"Report";"APP-00003";"2023-06-15";"Keep";"ACC-00020";"2023-06-15"
  "Parapheur/aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf";"**Parapheur/aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf**";"Item";"aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq-evidenceRecord.pdf";;"Fichier de preuve";;;"AdditionalProof";;;;;;;;;;;;
  "Parapheur/report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf";"**Parapheur/report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf**";"Item";"report_aeaaaaaaaaecb7ovabhryamreeao2oyaaaaq.pdf";;"Rapport";;;"AdditionalProof";;;;;;;;;;;;```

Exemple 3 : contenu d’un fichier « metadata.csv » déclarant un rattachement.

  "File";"Content.DescriptionLevel";"Content.Title";**"Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataName**";"**Management.UpdateOperation.ArchiveUnitIdentifierKey.MetadataValue**"
  "Discours hors parlement";"RecordGrp";"Discours hors parlement";"**ArchivalAgencyArchiveUnitIdentifier**";"**20130456/3**"
  "Discours hors parlement/Discours d'inauguration";"RecordGrp";"Discours d’inauguration";;
  "Discours hors parlement/Discours d'inauguration/Inauguration de Notre-Dame.odt";"Item";"Inauguration de Notre-Dame";;

14.6. Annexe 2 : Types JSON

Pour les éléments propres au SEDA, le tableau suivant précise les types de certains d’entre eux :

Métadonnées d’en-tête :

	obligatoire	string
ArchivalAgreement	x	x
MessageIdentifier	x	x
Comment		x[31]
OriginatingAgencyIdentifier	x	x
SubmissionAgencyIdentifier		x
ArchivalAgencyIdentifier	x	x
TransferringAgencyIdentifier	x	x
ArchivalProfile		x
AcquisitionInformation		x

Métadonnées descriptives et de gestion d’une unité archivistique :

	obligatoire	string	number	boolean	object	array
ArchiveUnitProfile		x
#management[32]	x				x
AccessRule					x
AppraisalRule					x
StorageRule					x
ReuseRule					x
ClassificationRule					x
HoldRule					x
Rules					x	x
Rule		x
StartDate		x[33]
EndDate		x[34]
FinalAction[35]		x
Inheritance					x
PreventInheritance				x
PreventRulesId						x[36]
HoldEndDate		x[37]
HoldOwner		x
HoldReason		x
HoldReassessingDate		x[38]
PreventRearrangement				x
ClassificationOwner		x
ClassificationReassessingDate		x[39]
NeedReassessingAuthorization				x
ClassificationLevel		x
ClassificationAudience		x
Logbook						x
NeedAuthorization				x
DescriptionLevel	x	x
Title	x	x				x
Title_					x
FilePlanPosition		x				x
SystemId		x				x
OriginatingSystemId		x				x
ArchivalAgencyArchiveUnitIdentifier		x				x
OriginatingAgencyArchiveUnitIdentifier		x				x
TransferringAgencyArchiveUnitIdentifier		x				x
Description		x				x
Description_					x
CustodialHistory					x
CustodialHistoryItem		x				x
Type		x
DocumentType		x
Language		x[40]				x
DescriptionLanguage		x[41]
Status		x
Version		x
Tag		x				x
Keyword					x	x
KeywordContent		x
KeywordReference		x
KeywordType		x
Coverage					x
Spatial		x				x
Temporal		x				x
Juridictional		x				x
OriginatingAgency					x
SubmissionAgency					x
Identifier		x
AuthorizedAgent					x	x
Writer					x	x
Addressee					x	x
Recipient					x	x
Transmitter					x	x
Sender					x	x
FirstName		x
BirthName		x
FullName		x
GivenName		x
Gender		x
BirthDate		x[42]
DeathDate		x[43]
BirthPlace					x
DeathPlace					x
Geogname		x
Address		x
PostalCode		x
City		x
Region		x
Country		x
Nationality		x
Corpname		x
Identifier		x
Function		x
Activity		x
Position		x
Role		x
Mandate		x
RelatedObjectReference					x
IsVersionOf					x
Replaces					x
Requires					x
IsPartOf					x
References					x
ArchiveUnitRefId		x
DataObjectReference					x
DataObjectReferenceId		x
DataObjectGroupReferenceId		x
RepositoryArchiveUnitPID		x
RepositoryObjectPID		x
CreatedDate		x
TransactedDate		x
AcquiredDate		x
SentDate		x
ReceivedDate		x
RegisteredDate		x
StartDate		x
EndDate		x
Event					x
evId[44]		x
evTypeProc[45]		x
evType[46]		x
EvDateTime[47]		x
evTypeDetail[48]		x
outcome[49]		x
outDetail[50]		x
outMessg[51]		x
evDetData[52]		x
Signature					x
Signer					x
Validator					x
ValidationTime		x
MasterData		x
ReferencedObject					x
SignedObjectId		x
SignedObjectDigest		x
Gps					x
GpsVersionId		x
GpsAltitude			x
GpsAltitudeRef		x
GpsLatitude		x
GpsLongitude		x
GpsLongitudeRef		x
GpsDateStamp		x

14.7. Annexe 3 : Liste des points d’API

	Description	Permission	Verbe	EndPoint
project	Création d’un projet de versement	project:create	POST	/collect-external/v1/projects/
	Récupère la liste des projets de versement	project:read	GET	/collect-external/v1/projects/
	Récupère un projet de versement	project:id:read	GET	/collect-external/v1/projects/{projectId}/
	Récupère la liste des projets de versement par critère de recherche	project:query:read	GET	project:query:read
	Mise à jour d’un projet de versement	project:update	PUT	/collect-external/v1/projects
	Supprime un projet de versement	project:id:delete	DELETE	/collect-external/v1/projects/{projectId}/
	Verser une archive arborescente ZIP à un projet de versement automatique sans transaction	project:id:zip:create	POST	/collect-external/v1/projects/{projectId}/upload/
	Récupérer la liste des transactions du projet	project:id:transactions	GET	/collect-external/v1/projects/{projectId}/transactions/
transaction	Création de la transaction	transaction:create	POST	/collect-external/v1/projects/{projectId}/transactions/
	Mise à jour d’une transaction	transaction:update	PUT	/collect-external/v1/transactions/
	Récupère une transaction	transaction:id:read	GET	/collect-external/v1/transactions/{transactionId}/
	Clôture de la transaction	transaction:close	POST	/collect-external/v1/transactions/{transactionId}/close/
	Envoi de la transaction	transaction:send	POST	/collect-external/v1/transactions/{transactionId}/send/
	Abandonner une transaction	transaction:abort	PUT	/collect-external/v1/transactions/{transactionId}/abort/
	Rouvrir une transaction	transaction:reopen	PUT	/collect-external/v1/transactions/{transactionId}/reopen/
	Charge les binaires en lot	transaction:zip:create	POST	/collect-external/v1/transactions/{transactionId}/upload/
	Crée une unité archivistique	transaction:unit:create	POST	/collect-external/v1/transactions/{transactionId}/units/
	Récupère toutes les unités archivistiques	transaction:unit:read	GET	/collect-external/v1/transactions/{transactionId}/units/
	Supprime une transaction	transaction:id:delete	DELETE	/collect-external/v1/transactions/{transactionId}/
units	Crée ou modifie un groupe d’objets techniques	transaction:object:upsert	POST	/collect-external/v1/units/{unitId}/objects/{usage}/{version}/
	Insère ou modifie un objet binaire	transaction:binary:upsert	POST	/collect-external/v1/units/{unitId}/objects/{usage}/{version}/binary/
	Récupère une unité archivistique	transaction:unit:id:read	GET	/collect-external/v1/units/{{unit-id}}/
	Mettre à jour les unités archivistiques	transaction:id:units:update	PUT	/collect-external/v1/transactions/{transactionId}/units/
	Télécharge un usage/version du binaire d’un groupe d’objets techniques	transaction:binary:read	GET	/collect-external/v1/units/{unitId}/objects/{usage}/{version}/binary/
	Réorganisation des arborescences	transaction:reclassification	POST	/collect-external/v1/transactions/{transactionId}/reclassification
	Supprime des archives	transaction:deletion:action	POST	/collect-external/v1/transactions/{transactionId}/deletion
	Elimine des archives	transaction:elimination:action	POST	/collect-external/v1/transactions/{transactionId}/elimination/action
objects	Récupère un groupe d’objets techniques	transaction:object:read	GET	/collect-external/v1/objects/{gotId}/

14.8. Annexe 4 : Exemples de transformations JSLT

*Nota bene *: les cas présentés ci-dessous sont des exemples fictifs.

14.8.1. Exemple 1

On souhaite transformer les métadonnées du fichier .csv suivant :

File;Content.NomDocument;Content.Description;Content.Cote;Content.DateDerniereModif;Content.SortFinal
"file1.txt";"Title 1";description title 1;"1 M 59";"2007-06-17";"Destroy"
"file2.txt";"Title 2";description title 2;"1 M 60";"2007-03-02";"Keep"
"file3.txt";"Title 3";description title 3;"1 M 61";"2022-07-12";"Keep"
"file4.txt";"Title 4";description title 4;"1 M 62";"2011-11-27";"Destroy"

Un enregistrement (correspondant à une ligne du fichier .csv) exprimé en JSON correspond à :

{
    "NomDocument": "Title 1",
    "Description": "description title 1",
    "DescriptionLevel": "Item",
    "Cote": ["1 M 59"],
    "DateDerniereModif":["2007-06-17"],
    "SortFinal":["Destroy"]
}

En sachant qu’on souhaite :

ajouter systématiquement une métadonnée DescriptionLevel avec « Item » comme valeur,
créer une métadonnée ArchivalAgencyArchiveUnitIdentifier reprenant les valeurs de la métadonnée Cote,
créer une métadonnée Title reprenant les valeurs de la métadonnée NomDocument,
ajouter des règles de gestion :
- règle de communicabilité avec « ACC-00001 » pour règle et les valeurs de la métadonnée DateDerniereModif pour date de début (StartDate),
- une DUA avec pour sort final les valeurs de la métadonnée SortFinal
ne pas reprendre les contenus des colonnes NomDocument, Cote, DateDerniereModif, SortFinal,
récupérere le contenu de la métadonnée Description,

les commandes JSLT prendront la forme suivante :

{
	"Title": .NomDocument,
    "ArchivalAgencyArchiveUnitIdentifier": .Cote,
    "#management": {
        "AccessRule" : [
            "Rules":[
                {
                    "Rule":"ACC-00001",
                    "StartDate":.DateDerniereModif
                }
            ]
        ],
        "AppraisalRule":[
            "FinalAction":.SortFinal
        ]
    },
    * - NomDocument, Cote, DateDerniereModif, SortFinal : .
}

Le résultat obtenu sera le suivant :

{
    "Title" : "Title 1",
    "ArchivalAgencyArchiveUnitIdentifier" : "1 M 59",
    "#management" : {
      "AccessRule" : [ {
        "Rule" : "ACC-00001",
        "StartDate" : "2007-06-17"
      } ],
	  "AppraisaRule" : [ {
      },"FinalAction" : "Destroy" ] 
    },
    "Description" : "description title 1",
    "DescriptionLevel" : "Item"
  }

14.8.2. Exemple 2

On souhaite transformer les métadonnées du fichier .csv suivant :

File;Content.Title;Content.Description;Content.StartDate;Content.ArchivalAgencyArchiveUnitIdentifier;Content.Tag;Management.AppraisalRule.FinalAction
"dossier/file1.txt";"Title 1";"description title 1";"2007-06-17";"1 M 59";"facture";"Destroy"
"dossier/file2.txt";"Title 2";"description title 2";"2007-03-02";"1 M 60";"mail";"Keep"
"dossier/file3.txt";"Title 3";"description title 3";"2022-07-12";"1 M 61";"dossierRH";"Keep"
"dossier/file4.txt";"Title 4";"description title 4";"2011-11-27";"1 M 62";"dossierRH";"Keep"
"dossier";"Dossier";"description dossier";"2003-04-13";;;"Destroy"

Un enregistrement (correspondant à une ligne du fichier .csv) exprimé en JSON correspond à :

{
    "#management": {
      "AppraisalRule": {
        "FinalAction": "Destroy"
      }
    },
    "Title": "Title 1",
    "Description": "description title 1",
    "StartDate":"2007-06-17",
    "DescriptionLevel": "Item",
    "ArchivalAgencyArchiveUnitIdentifier": "1 M 59",
    "Tag":["facture"]
  }

En sachant qu’on souhaite :

ajouter une DUA en fonction des tags,
utiliser la StartDate pour la Startdate de la DUA,

les commandes JSLT prendront la forme suivante :

{
    "#management": {
        "AppraisalRule" : if (.Tag == ["facture"]) {
            "Rules":[
                {
                    "Rule":"APP-00001",
                    "StartDate":.StartDate
                }
            ],
            *: .
        } else if (.Tag == ["mail"])
        {
            "Rules":[
                {
                    "Rule":"APP-00002",
                    "StartDate":.StartDate
                }
            ],
            *: .
        } else if (.Tag == ["dossierRH"]){
            "Rules":[
                {
                    "Rule":"APP-00003",
                    "StartDate":.StartDate
                }
            ],
            *: .
        } else {
            *: .
        },
        *: .
    },
    * - StartDate: . 
}

Le résultat obtenu sera le suivant :

{
    "#management" : {
      "AppraisalRule" : {
        "Rules" : [ {
          "Rule" : "APP-00001",
          "StartDate" : "2007-06-17"
        } ],
        "FinalAction" : "Destroy"
      }
    },
    "Title" : "Title 1",
    "Description" : "description title 1",
    "DescriptionLevel" : "Item",
    "ArchivalAgencyArchiveUnitIdentifier" : "1 M 59",
    "Tag":["facture"]
  }

14.8.3. Exemple 3

On souhaite transformer les métadonnées du fichier .csv suivant :

File;Content.Title;Content.Description;Content.ArchivalAgencyArchiveUnitIdentifier;Content.Addressee.0.FirstName;Content.Addressee.0.BirthName;Content.Addressee.0.BirthDate;Content.Addressee.1.FirstName;Content.Addressee.1.BirthName;Content.Addressee.1.BirthDate;Management.AppraisalRule.Rule;Management.AppraisalRule.StartDate;Management.AppraisalRule.FinalAction
"dossier/file1.txt";" Title 1 ";"description title 1";"1 M 59";Albert;Dupont;2000-06-17;Béré;Nice;"1998-09-17";"APP-00001";"2007-06-17";"Destroy"
"dossier/file2.txt";" Title 2 ";"description title 2";"1 M 60";Marc;Aurèle;1987-07-11;Marc;Antoine;"1990-06-14";"APP-00001";"2007-03-02";"Keep"
"dossier/file3.txt";" Title 3 ";"description title 3";"1 M 61";Sarah;Bernardt;2001-10-10;Edmond;Rostand;"2007-04-19";"APP-00003";"2022-07-12";"Keep"
"dossier/file4.txt";" Title 4 ";"description title 4";"1 M 62";Marc;Aurèle;2000-01-31;Jules;César;"2000-10-14";APP-00002";"2011-11-27";"Keep"
"dossier";"Dossier";"description dossier";;;;;;;;"APP-00002";"2003-04-13";"Destroy"

Un enregistrement (correspondant à une ligne du fichier .csv) exprimé en JSON correspond à :

{
    "#management": {
      "AppraisalRule": {
        "Rules": [
          {
            "Rule": "APP-00001",
            "StartDate": "17/06/2007"
          }
        ],
        "FinalAction": "Destroy"
      }
    },
    "Title": "Title 1",
    "Description": "description title 1",
    "DescriptionLevel": "Item",
    "ArchivalAgencyArchiveUnitIdentifier": "1 M 59",
    "Addressee": [
      {
        "FirstName": "Albert",
        "BirthName": "Dupont",
        "BirthDate": "2000-10-14"
      },
      {
        "FirstName": "Béré",
        "BirthName": "Nice",
        "BirthDate": "1998-09-17"
      }
    ]
  }

En sachant qu’on souhaite :

modifier la cote de l’ensemble des unités archivistiques en la remplaçant par une empreinte calculée à partir des titres,
mettre les titres en majuscules et enlever les espaces vides présents,
remplacer le mot « title » présent dans la métadonnée Description par « titre »,
ne pas reprendre les contenus des métadonnées ArchivalAgencyArchiveUnitIdentifier, Description puisqu’elles ont été traitées spécifiquement dans des commandes,

les commandes JSLT prendront la forme suivante :

{
    "ArchivalAgencyArchiveUnitIdentifier":sha256-hex(.Title),
    "Title":trim(uppercase(.Title)),
    "Description": replace(.Description,"title","titre"),
    *- ArchivalAgencyArchiveUnitIdentifier, Description: .
}

Le résultat obtenu sera le suivant :

{
    "ArchivalAgencyArchiveUnitIdentifier" : "ab03af41c2940e7584b62df48a964db37cd0202137fc60a9e782d16d4cc03843",
    "Title" : "TITLE 1",
    "#management" : {
      "AppraisalRule" : {
        "Rules" : [ {
          "Rule" : "APP-00001",
          "StartDate" : "17/06/2007"
        } ],
        "FinalAction" : "Destroy"
      }
    },
    "Description" : "description titre 1",
    "DescriptionLevel" : "Item",
    "Addressee" : [ {
      "FirstName" : "Marc",
      "BirthName" : "Aurèle",
      "BirthDate" : "2000-10-14"
    }, {
      "FirstName" : "Béré",
      "BirthName" : "Nice",
      "BirthDate" : "1998-09-17"
    } ]
  }

14.8.4. Exemple 4

Voici un exemple complexe de commandes JSLT contenant des variables et des expressions conditionnelles appelant ces variables :

let hasAppraisal = ."#management".AppraisalRule != null
let existingAppraisalRules = ."#management".AppraisalRule.Rules
let existingAppraisalFinalAction = ."#management".AppraisalRule.FinalAction

let appraisalRuleToAdd = if      (contains(.DOSSIER[0].nomTypeDossier[0], ["DP", "PC", "PA", "PD", "DT"])) "XXX"
                         else if (contains(.DOSSIER[0].nomTypeDossier[0], [ "CUa", "CUb"]))                "YYY"
                         else                                                                              null

let appraisalRuleStartDate = if ( contains(.TYPE_DOSSIER[0], [ "CUa", "CUb"]) ) .terrains[0].dtDecisionDossierCU[0]
                             else                                               .decisionsUrba[0].dtDecisionUrba[0]

let appraisalFinalAction = if        (contains(.DOSSIER[0].nomTypeDossier[0], ["CUa", "CUb"]) and contains(.DOSSIER[0].nomEtatsOuSousEtatsGenera[0], [ "Rejet", "Refus"] ))    "Destroy"
                           else if   (contains(.DOSSIER[0].nomTypeDossier[0], ["CUa", "CUb"]) and contains(.DOSSIER[0].nomEtatsOuSousEtatsGenera[0], [ "Accord ", "Sursis"] )) "Keep"
                           else                                                                                                                                                 null
        
{
    "#management": {
        // Only set AppraisalRule if existing field (rule, properties and/or inheritance) OR new rule to set
        "AppraisalRule": if ($hasAppraisal or $appraisalRuleToAdd != null) {
            // Add new rule to existing ones
            "Rules": if ($appraisalRuleToAdd != null)     [ { "Rule": $appraisalRuleToAdd, "StartDate": $appraisalRuleStartDate } ] + $existingAppraisalRules
                else if ($existingAppraisalRules != null) $existingAppraisalRules
                else                                      [],
            // Final action is required, if no value found set "Keep"
            "FinalAction": if($appraisalFinalAction != null)               $appraisalFinalAction 
                           else if ($existingAppraisalFinalAction != null) $existingAppraisalFinalAction
                           else                                            "Keep",
            * : .
        } else {},
        * : .
    },
    * : .
}

14.9. Annexe 5 : Liste de fonctions JSLT

*Nota bene *: les cas présentés ne sont pas exhaustifs et sont issus de la documentation disponible sur le site suivant : https://github.com/schibsted/jslt/blob/master/functions.md.

14.9.1. Fonctions générales

contains(element, sequence) -> boolean oui

Renvoie « true » si element est contenu dans sequence, sinon renvoie « false ». sequence peut être un tableau, une chaîne de caractères ou un objet :

Si sequence est un tableau, element doit être un élément de ce tableau.
Si sequence est une chaîne de caractères, element est converti en chaîne et doit être une sous-chaîne de sequence. Si element est « null », le résultat est « false ».
Si sequence est un objet, element est converti en chaîne et doit être une clé de l’objet.

Exemples :

-   contains(null, [1, 2, 3])      => false  
-   contains(1, [1, 2, 3])         => true  
-   contains(0, [1, 2, 3])         => false  
-   contains("no", {"no" : false}) => true  
-   contains(1, {"1" : false})     => true  
-   contains("ab", "abc")          => true

size(sequence) -> integer

Renvoie le nombre d’éléments dans sequence, qui peut être un tableau, un objet ou une chaîne de caractères. Si sequence est « null », la fonction renvoie « null ».

Exemples :

-   size([1, 2, 3]) => 3  
-   size({"1" : 3}) => 1  
-   size("abcdef")  => 6  
-   size(null)      => null

error(message)

Interrompt la transformation avec une erreur et affiche le message donné en paramètre.

Exemple :

if (not(is-array(.things)))  
  error("'things' is not an array")

fallback(arg1, arg2, …) -> value

Renvoie le premier argument qui a une valeur, c’est-à-dire le premier qui n’est ni « null », ni un tableau vide « [] », ni un objet vide « {} ».

Exemples :

-   fallback(.not_existing_key, .another_not_existing, 1)  => 1  
-   fallback(null, [], {}, "value")                        => "value"

min(arg1, arg2) -> value

Renvoie l’argument le plus petit selon la comparaison. Si un des arguments est « null », le résultat est « null ».

Exemple :

-   min(10, 1)    -> 1  
-   min("a", "b") -> "a"  
-   min(10, null) -> null

max(arg1, arg2) -> value

Renvoie l’argument le plus grand selon la comparaison. Si un des arguments est « null », le résultat est « null ».

Exemple :

-   max(10, 1)    -> 10  
-   max("a", "b") -> "b"  
-   max(10, null) -> null  

14.9.2. Fonctions string

is-string(object) -> boolean

Renvoie « true » si l’argument est une chaîne de caractères, sinon renvoie « false ».

Exemples :

-   is-string(null)    => false  
-   is-string("hello") => true  
-   is-string(123)     => false  
-   is-string([])      => false  

string(object, fallback?) -> string

Convertit l’argument en chaîne de caractères si cela est possible.

Les nombres, booléens et objets sont convertis en chaînes de caractères.
« null » renvoie « null ».
Tout autre type provoque une erreur, sauf si un fallback est spécifié.

Exemples :

-   string(123)     => "123"  
-   string(true)    => "true"  
-   string(null)    => null  
-   string([1, 2])  => error  
-   string([1, 2], "fallback") => "fallback"  *

test(input, regexp) -> boolean

Cette fonction renvoie « true » si et seulement si l’entrée correspond à l’expression régulière (regexp). Elle renvoie « true » si l’expression correspond uniquement à une partie de la chaîne, sauf si les ancres ^ et $ sont utilisées. Si l’entrée est « null », la fonction retourne « false ».

Exemples :

-   test("123", "\d+") => Erreur (\d n'est pas un code d'échappement connu)
-   test("123", "\d+") => true
-   test("abc123", "\d+") => true (une correspondance partielle suffit)
-   test("abc123", "^\d+$") => false

capture(input, regexp) -> object

Si l’entrée correspond à l’expression régulière (regexp), la fonction retourne un objet contenant une clé pour chaque groupe nommé dans l’expression. Si l’entrée est « null », la fonction retourne « null ». Si l’expression ne correspond pas, un objet vide est retourné.

Par exemple, étant donné l’entrée suivante :

{"schema" : "http://schemas.schibsted.io/thing/pulse-simple.json#1.json"}

la fonction capture() peut être utilisée avec l’expression régulière suivante :

capture(.schema, "http://(?<host>[^/]+)/(?<rest>.+)")

Les deux groupes nommés (host et rest) correspondent à différentes parties de la chaîne, donc la sortie contiendra une clé pour chaque groupe nommé :

{
  "host" : "schemas.schibsted.io",
  "rest" : "thing/pulse-simple.json#1.json"
}

split(string, separator) -> array

Cette fonction divise la chaîne en un tableau de sous-chaînes en utilisant separator. Si separator est une chaîne vide « « , la chaîne est divisée caractère par caractère.

Exemples :

-   split("a,b,c", ",")  => ["a", "b", "c"]  
-   split("hello", "")   => ["h", "e", "l", "l", "o"]  
-   split("one|two", "|") => ["one", "two"]

join(array, separator) -> string

Cette fonction concatène les éléments du tableau en une seule chaîne de caractères, séparés par separator. Si array est vide, une chaîne vide est renvoyée.

Exemples :

-   join(["a", "b", "c"], ",")  => "a,b,c"  
-   join(["one", "two"], "|")   => "one|two"  
-   join([], ",")               => ""  

lowercase(string) -> string

Convertit la chaîne de caractères en minuscules. Si l’argument est « null », il est retourné tel quel.

Exemples :

-   lowercase("HELLO") => "hello"  
-   lowercase(null)    => null  

Point d’attention: les fonctions lowercase() et uppercase() ne comprennent que les caractères ASCII.

uppercase(string) -> string

Convertit la chaîne en majuscules. Si l’argument est null, il est retourné tel quel.

Exemples :

-   uppercase("hello") => "HELLO"  
-   uppercase(null)    => null

Point d’attention: les fonctions lowercase() et uppercase() ne comprennent que les caractères ASCII.

sha256-hex(string) -> string

Cette fonction génère une chaîne de caractères contenant la représentation hexadécimale du hachage SHA256 de la chaîne d’entrée.

Exemples :

-   sha256-hex("foo") => "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
-   sha256-hex("42") => "73475cb40a568e8da8a045ced110137e159f890ac4da883b6b17dc651b3a8049"
-   sha256-hex(42) => "73475cb40a568e8da8a045ced110137e159f890ac4da883b6b17dc651b3a8049"
-   sha256-hex(null) => null

starts-with(tested, prefix) -> boolean

Renvoie « true » si et seulement si la chaîne testée commence par le préfixe (prefix).

Exemples :

-   starts-with("prohibition", "pro") => true
-   starts-with("prohibition", "pre") => false
-   starts-with(null, "pre") => false

ends-with(tested, suffix) -> boolean

Renvoie « true » si et seulement si la chaîne testée se termine par le suffixe (suffix).

Exemples :

-   ends-with("prohibition", "pro") => false
-   ends-with("prohibition", "ion") => true
-   ends-with(null, "ion") => false

from-json(string, fallback?) -> value

Cette fonction analyse la chaîne de caractères donnée (string) en tant que JSON et retourne le résultat. Ainsi, analyser « 22 » retournera 22. Si la chaîne est « null », la fonction retournera « null ». Si l’argument facultatif fallback n’est pas spécifié, les erreurs d’analyse JSON provoqueront une erreur. Si cet argument est précisé, cette valeur sera retournée en cas d’échec de l’analyse JSON.

Exemples :

-   from-json("[1,2]") => [1, 2]
-   from-json("[1,2", "BAD") => "BAD"
-   from-json("[1,2") => erreur
-   from-json(null) => null

to-json(value) -> string

Cette fonction est l’inverse de from-json. Il prend donc une valeur JSON et la sérialise sous forme de chaîne de caractères.

Exemples :

-   to-json([1,2]) => "[1, 2]"
-   to-json(1) => "1"
-   to-json("foo") => ""foo""
-   to-json(null) => "null"

replace(value, regexp, out) -> string

Cette fonction remplace chaque sous-chaîne de value correspondant à l’expression régulière regexp par out. Si value n’est pas une chaîne, elle est convertie en chaîne, sauf si elle est « null ». regexp et out doivent être des chaînes de caractères.

Point d’attention: regexp ne peut être une chaîne vide.

Exemples :

-   replace("abc def ghi", " ", "-") => "abc-def-ghi"
-   replace("abc def ghi", "\s+", "-") => "abc-def-ghi"
-   replace(null, "\s+", "-") => null
-   replace(" whoah", "^\s+", "") => "whoah"
-   replace("abc def ghi", "[a-z]", "x") => "xxx xxx xxx"
-   replace("abc def ghi", "[a-z]+", "x") => "x x x"

trim(string) -> string

Cette fonction supprime les espaces au début et à la fin de la chaîne. Si l’argument est « null », il est retourné tel quel. Les autres valeurs non textuelles sont converties en chaînes de caractères.

Exemples :

-   trim("  hello  ") => "hello"
-   trim(null)       => null
-   trim("abc \t\r\n") => "abc"

uuid(long, long) -> string

Cette fonction génère une chaîne UUID formatée avec des tirets.

Exemples :

-   uuid() => "b02c39c0-6f8f-4250-97cd-78500af36e27"
-   uuid(123sh4567890, 1234567890) => "00000000-4996-102d-8000-0000499602d2"
-   uuid(0, 0) => "00000000-0000-1000-8000-000000000000"
-   uuid(null, null) => "00000000-0000-0000-0000-000000000000"

14.9.3. Fonctions date

now() -> double

Cette fonction retourne le nombre de secondes écoulées depuis minuit, le 1er janvier 1970 UTC dans le fuseau horaire UTC. Les millisecondes sont renvoyées sous forme de décimales du nombre.

Exemples :

-   now() -> 1.529677371698E9
-   round(now()) -> 1529677391

parse-time(time, format, fallback?) -> double

Analyse la date/heure en utilisant le format spécifié (au format date/heure de Java) et retourne le nombre de secondes écoulées depuis l’époque dans le fuseau horaire UTC. Si aucun fuseau horaire n’est spécifié dans la chaîne de date/heure, le fuseau horaire par défaut est UTC.

Si le paramètre fallback n’est pas spécifié, la fonction génère une erreur si time est du mauvais type ou ne correspond pas au format.
Si fallback est spécifié, cette valeur sera retournée à la place.

Exemples :

-   parse-time("2018-05-30T11:46:37Z", "yyyy-MM-dd'T'HH:mm:ssX") => 1.527680797E9
-   parse-time("2018-05-30T11:46:37", "yyyy-MM-dd'T'HH:mm:ssX") => error
-   parse-time("2018-05-30T11:46:37", "yyyy-MM-dd'T'HH:mm:ssX", null) => null
-   parse-time(null, "yyyy-MM-dd'T'HH:mm:ssX") => null

format-time(timestamp, format, timezone?) -> string

Cette fonction formate timestamp (le nombre de secondes écoulées depuis l’époque) en utilisant le format spécifié et retourne la chaîne formatée. Le fuseau horaire par défaut est UTC, mais il peut être remplacé en utilisant l’argument timezone.

Exemples :

-   format-time(1529677391, "yyyy-MM-dd'T'HH:mm:ss") => "2018-06-22T14:23:11"
-   format-time(0, "yyyy-MM-dd") => "1970-01-01"
-   format-time(null, "yyyy-MM-dd") => null

14.9.4. Fonctions booléen

boolean(value) -> boolean

Cette fonction convertit la valeur d’entrée en un booléen. Tout est considéré comme « true », sauf « null », [], {}, « « , « false » et 0.

Exemples :

-   boolean(null) => false
-   boolean("") => false
-   boolean(" ") => true
-   boolean(0) => false
-   boolean(1) => true
-   boolean(true) => true
-   boolean(false) => false
-   boolean([]) => false
-   boolean([1]) => true

not(boolean) -> boolean

Cette fonction retourne la valeur booléenne opposée au paramètre. L’entrée est automatiquement convertie en booléen, donc not(null) retournera « true ».

Exemples :

-   not(null) => true
-   not("") => true
-   not(" ") => false
-   not(0) => true
-   not(1) => false
-   not(true) => false
-   not(false) => true
-   not([]) => true
-   not([1]) => false

is-boolean(value) -> boolean

Renvoie « true » si et seulement si la valeur est un booléen.

Exemples :

-   is-boolean(null) => false
-   is-boolean(true) => true
-   is-boolean(false) => true
-   is-boolean("") => false
-   is-boolean(" ") => false

14.9.5. Fonctions numériques

is-number(object) -> boolean

Renvoie « true » si l’argument object est un nombre, sinon renvoie « false ».

Exemples :

-   is-number(null) => false  
-   is-number(1)    => true  
-   is-number(1.0)  => true  
-   is-number("1")  => false

is-integer(object) -> boolean

Renvoie « true » si l’argument object est un entier, sinon renvoie « false ».

Exemples :

-   is-integer(null) => false  
-   is-integer(1)    => true  
-   is-integer(1.0)  => false  
-   is-integer("1")  => false

is-decimal(object) -> boolean

Renvoie « true » si l’argument object est un nombre à virgule flottante, sinon renvoie « false ». Dans ce contexte, « 1.0 » est considéré comme un nombre à virgule flottante et « 1 » ne l’est pas.

Exemples :

-   is-decimal(null) => false  
-   is-decimal(1)    => false  
-   is-decimal(1.0)  => true  
-   is-decimal("1.0")  => false

number(object, fallback?) -> integer|float

Convertit l’argument object en nombre si cela est possible.

Les entiers et les nombres décimaux sont retournés tels quels.
Les chaînes de caractères sont converties en nombres.
« null » renvoie « null ».
Tout autre type provoque une erreur, sauf si un fallback est spécifié.

Exemples :

-   number(23)      => 23  
-   number("23")    => 23  
-   number("023")   => 23  
-   number(23.0)    => 23.0  
-   number(".23")   =>  0.23  
-   number("-.23")  => -0.23  
-   number(null)    => null  
-   number("ab")    => error  
-   number("ab", 0) => 0

round(float) -> integer

Arrondit l’argument à l’entier le plus proche. Les entiers et « null » sont retournés tels quels. Tout autre type provoque une erreur.

Exemples :

-   round(1)    => 1  
-   round(1.0)  => 1  
-   round(1.51) => 2  
-   round(null) => null

floor(float) -> integer

Arrondit l’argument à l’entier inférieur ou égal.

Exemples :

-   floor(1)    => 1  
-   floor(1.0)  => 1  
-   floor(1.51) => 1  
-   floor(null) => null

ceiling(float) -> integer

Arrondit l’argument à l’entier supérieur ou égal.

Exemples :

-   ceiling(1)    => 1  
-   ceiling(1.0)  => 1  
-   ceiling(1.51) => 2  
-   ceiling(null) => null

random() -> float

Renvoie un nombre aléatoire entre 0.0 et 1.0.

Exemple :

random() => 0.24712712424

sum(array) -> number

Renvoie la somme des nombres d’un tableau. Le paramètre doit obligatoirement être un tableau constitué uniquement de nombres.

Exemples :

-   sum([1,2,3])    => 6
-   sum([1])        => 1 
-   sum([1.0, 2.0]) => 3.0
-   sum([])         => 0
-   sum(null)       => null

mod(a,d) -> integer

Renvoie a modulo d. Cette fonction est l’équivalent de l’opérateur % de la plupart des langages de programmation. Son comportement est néanmoins différent pour les nombres négatifs. Il renvoie un résultat compris entre 0 et abs(d). Mathématiquement, la fonction est définie de la façon suivante :

a = d * floor(a / d) + mod(a, d)

Exemples :

-   mod(10, 2)    => 0
-   mod(10, 3)    => 1
-   mod(10, 4)    => 2
-   mod(-10, 3)   => 2
-   mod(-10, -3)  => 2
-   mod(10, -3)   => 1
-   mod(null, 2)  => null
-   mod(10, null) => null
-   mod(10.5, 2)  => error
-   mod(10, 2.1)  => error
-   mod(10, "2")  => error

hash-int(object) -> int

Renvoie une empreinte pour un object donné. L’empreinte est constituée uniquement de chiffres.

Point d’attention: Dans des environnements différents, il est possible que, pour un même objet, l’empreinte retournée soit différente.

Exemples :

-   hash-int("test") => 3556808
-   hash-int("") => 310
-   hash-int({}) => 8
-   hash-int([]) => 1
-   hash-int([1,2]) => 8928
-   hash-int([2,1]) => 9858
-   hash-int([1,2]) != hash-int([2,1]) => true
-   hash-int(1) => 248
-   hash-int(null) => 6
-   hash-int({"a":1,"b":2}) => 10519540
-   hash-int({"b":2,"a":1}) => 10519540
-   hash-int({"a":1,"b":2}) == hash-int({"b":2,"a":1}) => true

14.9.6. Fonctions objet

is-object(value) -> boolean

Renvoie « true » si et seulement si la valeur est un objet.

Exemples :

-   is-object(null) => false
-   is-object({}) => true
-   is-object([]) => false
-   is-object("") => false

get-key(object, key, fallback?) -> value

Fait la même chose que .key sur un objet, à la différence que la clé peut être dynamique. Autrement dit, elle peut provenir d’une variable, être recherchée dans des données d’entrée, etc. Si la clé n’existe pas :

« null » est retourné si l’argument de secours (fallback) n’est pas fourni,
si fallback est spécifié, cette valeur sera retournéee.

Exemple : Fonction retournant la valeur « Norway ».

let lookup = {  
  "no" : "Norway",  
  "se" : "Sweden"  
}  

get-key($lookup, "no")

Exemple : Fonction utilisant une valeur de secours et retournant la valeur « »

let lookup = {  
  "no" : "Norway",  
  "se" : "Sweden"  
}  

get-key($lookup, "dk", "<unknown>") 

14.9.7. Fonctions tableau (array)

array(value) -> array

Cette fonction convertit la valeur d’entrée en un tableau. Les nombres, les booléens et les chaînes de caractères ne peuvent pas être convertis en tableau. Les objets sont convertis en tableaux sous la forme suivante :

[  
  {"key" : première clé, "value" : première valeur},  
  {"key" : deuxième clé, "value" : deuxième valeur},  
  {"key" : troisième clé, "value" : troisième valeur},  
  ...  
]

Exemples :

-   array(null) => null
-   array([1, 2]) => [1, 2]
-   array("123") => error
-   array({"a": 1, "b": 2}) =>  
  	[  
    		{"key" : "a", "value" : 1},  
    		{"key" : "b", "value" : 2}  
 	 ]

is-array(value) -> boolean

Cette fonction renvoie « true » si et seulement si la valeur est un tableau.

Exemples :

-   is-array(null) => false
-   is-array([1, 2]) => true
-   is-array("123") => false

flatten(array) -> array

Aplatit un tableau contenant d’autres tableaux de manière à ce que chaque valeur à l’intérieur d’un sous-tableau soit directement contenue dans le tableau de sortie. Tous les sous-tableaux à n’importe quel niveau d’imbrication sont aplatis, mais les objets et autres valeurs restent inchangés.

Exemples :

-   flatten([[1,2], [3,4]]) => [1,2,3,4]
-   flatten([1, 2, 3, 4]) => [1,2,3,4]
-   flatten([1, [2, [3, [4, []]]]]) => [1,2,3,4]
-   flatten(null) => null

all(array) -> boolean

Cette fonction renvoie « true » si et seulement si tous les éléments du tableau sont évalués comme vrais.

Exemples :

-   all([true, true, true]) => true
-   all([true, true, false]) => false
-   all(null) => null
-   all([]) => true
-   all("") => error

any(array) -> boolean

Cette fonction renvoie « true » si et seulement si au moins un élément du tableau est évalué comme vrai.

Exemples :

-   any([false, false, false]) => false
-   any([false, false, true]) => true
-   any(null) => null
-   any([]) => false
-   any("") => error

zip(array1, array2) -> array

Fusionne les deux tableaux en un nouveau tableau constitué de tableaux à deux éléments. Le premier tableau à deux éléments contient le premier élément de array1 et le premier élément de array2, le second contient les deuxièmes éléments, et ainsi de suite. Une erreur est renvoyée si les deux tableaux ont des longueurs différentes.

Exemples :

-   zip(["a", "b", "c"], [1, 2, 3]) => [["a", 1], ["b", 2], ["c", 3]]
-   zip(["a", "b", "c"], null) => null
-   zip(null, [1, 2, 3]) => null
-   zip([], []) => []
-   zip([1], []) => error

zip-with-index(array) -> array

Cette fonction transforme un tableau en un nouveau tableau où chaque élément du tableau d’entrée est mappé à un objet sous la forme {« value » : <élément du tableau>, « index » : <index de l’élément>}.

Exemples :

-   zip-with-index(["a", "b", "c"]) => [  
          {"value" : "a", "index" : 0},  
          {"value" : "b", "index" : 1},  
          {"value" : "c", "index" : 2}  
      ]  
-   zip-with-index([]) => []
-   zip-with-index(null) => null
-   zip-with-index("abc") => error

index-of(array, value) -> integer

Cette fonction retourne l’index de value dans array, ou « -1 » si la valeur ne peut pas être trouvée.

Exemples :

-   index-of([], 1) => -1
-   index-of([0, 1, 2], 1) => 1
-   index-of([0, 1, 2, null], null) => 3
-   index-of([0, 1, 2], null) => -1
-   index-of(null, 1) => null
-   index-of(1, 1) => error

14.9.8. Autres fonctions

parse-url(url) -> object

Cette fonction analyse l’URL et renvoie un objet avec les clés [scheme, userinfo, host, port, path, query, parameters, fragment].

Exemples :

-   parse-url("http://example.com").scheme => "http"
-   parse-url("http://example.com").host => "example.com"
-   parse-url("http://example.com").path => null
-   parse-url("http://example.com/").path = "/"
-   parse-url("https://www.example.com/?aa=1&aa=2&bb=&cc").query =>  "aa=1&aa=2&bb=&cc"
-   parse-url("https://www.example.com/?aa=1&aa=2&bb=&cc").parameters.aa =>  ["1", "2"]
-   parse-url("https://www.example.com/?aa=1&aa=2&bb=&cc").parameters.bb =>  [null]
-   parse-url("https://www.example.com/?aa=1&aa=2&bb=&cc").parameters.cc =>  [null]
-   parse-url("ftp://username:password@host.com/").userinfo => "username:password"
-   parse-url("https://example.com:8443").port => 8443