Bulk import
Généralités
Présentation
L'outil d'import massif est utilisé lorsque vous voulez effectuer une reprise de gros volumes de données existantes provenant d'un autre système, pour les injecter dans la base Any en implémentant votre programme Java. Ce processus a été conçu pour maximiser la vitesse d'import et nécessite une préparation préalable des données afin qu'elles soient compatibles avec la configuration cible (aspects et listes de données). L'outil ne permet que de créer de nouveaux documents : il ne peut pas être utilisé pour mettre à jour ou supprimer des données (voir la Sync API). L'import s'effectue via des messages postés dans une file d'attente gérée par le serveur de messages de Any. Attention : afin de ne pas saturer le serveur de messages avec les contenus binaires, le traitement des fichiers doit être effectué manuellement, via une copie des fichiers par les scripts fournis par l'outil ou par des dossiers partagés.
Conditions préalables
L'outil nécessite l'installation de Java 11 ou d'une version ultérieure sur l'ordinateur.
Installation
Pour installer l'outil de synchronisation, extrayez l'archive BulkImporter.zip dans un dossier.
Utilisation
Pour utiliser l'import massif, vous devez implémenter votre programme à l'aide des API et des exemples fournis dans le projet. Si vous voulez réaliser l'import massif via des fichiers CSV contenant vos métadonnées déjà prêtes, vous devez utiliser l'outil FileSystemImporter.
Configuration du serveur
Selon votre architecture, vous devrez configurer l'outil pour qu'il se connecte à Any. Les réglages s'effectuent dans le fichier settings.json, à l'intérieur du dossier config de l'archive décompressée.
Configuration sur site
Si vous disposez d'une installation sur site, vous devez configurer l'outil de synchronisation pour qu'il se connecte au serveur ActiveMQ de Any qui recevra les messages de synchronisation.
Dans le fichier settings.json, modifiez la partie mdb-messaging pour définir les valeurs en fonction de votre environnement. Un paramètre particulier est l'adresse jms-server-address, où les messages de synchronisation seront publiés.
"mdb-messaging": {
"jms_server_address": "tcp://<ActiveMQ Server Any>:61616",
[...]
Configuration du serveur de messages de Any (Messaging Server)
L'exécution des actions d'import de masse et des post-actions peut durer plusieurs heures, selon la complexité de vos applications et le nombre de contenus. Dans le fichier settings.json utilisé par le Messaging Server, vous devez désactiver le timeout avec le paramètre wireFormat.maxInactivityDuration=0.
"mdb-messaging": {
"jms_server_address": "tcp://<ActiveMQ Server Any>:61616?wireFormat.maxInactivityDuration=0",
[...]
Attention : ce fichier settings.json est différent de celui utilisé pour envoyer les contenus.
Projet Java d’import de masse
Préparation du projet
- Créez un nouveau projet Java dans votre IDE de développement.
- Ajoutez, en dépendances internes ou externes, tous les fichiers JAR fournis dans le dossier « lib ».
- Copiez le contenu du dossier « sources » fourni, en particulier le dossier « src/main/java », dans votre projet. Configurez ce dernier pour que le dossier « src/main/java » soit identifié comme dossier de sources.
- Ajoutez le dossier « src/test/resources » au CLASSPATH du projet.
- Ajoutez le dossier « config » au CLASSPATH du projet.
Ce projet montre l'utilisation de l'import de masse pour une configuration de démo. Vous devrez l'adapter à vos besoins et y ajouter la lecture de vos données pour pouvoir les injecter.
Préparation
Pour utiliser les API d'import de masse, vous devez référencer la configuration de votre application. Connectez-vous en administrateur dans Any et exportez la configuration complète de votre application depuis la section d'administration.
Initialisation de l'API
L'initialisation de l'API du serveur de messaging utilise le fichier settings.json disponible dans votre CLASSPATH. Référencez ce fichier dans votre CLASSPATH pour pouvoir l'utiliser.
IMessagingProvider messaging = MessagingProviderLoader.getMessagingProvider();
Pour utiliser les API d'import de masse, vous devez référencer la configuration de votre application. Celle-ci sert à préparer et à valider vos données avant l'envoi. Exportez la configuration complète de votre application et référencez-la dans votre projet, puis initialisez l'API permettant de lire la configuration de Any à partir de cette configuration.
// Loading configuration exported from Any to control the data mapping and aspects definitions
ConfigArchiveReader configReader = ConfigArchiveReader.getConfigArchiveReaderFromResources
("sample/config/Export-Config.zip",
Arrays.asList(Locale.FRENCH, Locale.ENGLISH));
La configuration peut être chargée via le classpath ou via un fichier externe.
Constitution du jeu de données
Création d'un objet
Pour envoyer vos données, vous devez constituer une liste d'objets AnyContent compatibles avec votre configuration.
Créez une nouvelle instance de AnyContent utilisant la configuration exportée, puis remplissez les données de base. L'initialisation prépare l'objet en lui assignant un ID interne unique et compatible avec Any.
Gestion des métadonnées
Pour remplir des métadonnées sans mapping, il suffit d'affecter la valeur en indiquant :
- le nom de l'aspect déclaré dans la configuration.
- le nom de la métadonnée.
IAnyContent obj = new AnyContent(configArchiveReader);
obj.setName("My name");
obj.setApplication("demo");
obj.setVersion("1.0", true);
obj.setCreationDate(new Date());
Pour remplir des données mappées, il suffit également d'affecter la valeur. La gestion automatique de la configuration se charge de formater les données afin qu'elles soient compréhensibles par le moteur de Any et associées à la liste de valeurs correspondante.
obj.setMetadata("standard", "title", "My title");
obj.setMetadata("standard", "subject", "My subject");
obj.setMetadata("standard", "status", "My status");
obj.setMetadata("standard", "keywords", Arrays.asList("Keyword 01", "Keyword 02"));
obj.setMetadata("standard", "authors", Arrays.asList("John Doe", "Jane Doe"));
Gestion des formats
Pour ajouter un format à votre objet, vous devez spécifier le chemin du fichier source. Ce chemin sera utilisé par Any comme fichier de secours s'il n'est pas trouvé dans le dossier des fichiers de Any (voir la section Stratégies de gestion des fichiers).
// Stocke le format avec le chemin futur du fichier comme source de copie ou de secours
obj.addFormat(fileUrl.toURI(), extension, extension, Files.size(fileUrl.toPath()), true);
Vous pouvez ajouter un ou plusieurs formats non primaires.
// A rendition is another format but not set as primary
obj.addFormat(fileUrlPdf.toURI(), "pdf", "pdf", Files.size(fileUrlPdf.toPath()), false);
Ajout à une room statique
Vous pouvez préparer votre document pour qu'il soit lié directement à une ou plusieurs rooms statiques (sans collection). Une fois importé, il sera directement disponible dans ces rooms.
Attention : l'ID de la room mentionnée et son application doivent être valides dans la base Any.
obj.addStaticRoom(roomId, application);
Gestion des versions
Les versions sont des contenus qui partagent le même ID de racine. Lorsque vous créez une nouvelle version à partir d'un contenu, vous pouvez hériter des données du père et spécifier si cette nouvelle version est la dernière.
IAnyContent contentv1 = new AnyContent(configReader);
contentv1.setName("Name of my content");
contentv1.setMetadata("standard", "title", "Title of my content");
contentv1.setVersion("1.0", false);
File file = new File("filev1.0.docx");
contentv1.addFormat(file.toURI(), "docx", "docx", Files.size(file.toPath()), true);
// Metadata are inherited, no need to set again name and title
IAnyContent contentv2 = contentv1.newVersion(true, "2.0", false);
file = new File("filev2.0.docx");
// New version does not have format, you need to set one
contentv2.addFormat(file.toURI(), "docx", "docx", Files.size(file.toPath()), true);
// Latest and current one
IAnyContent contentv3 = contentv1.newVersion(true, "3.0", true);
file = new File("filev3.0.docx");
contentv3.addFormat(file.toURI(), "docx", "docx", Files.size(file.toPath()), true);
Envoyer une liste de documents à importer
Une fois la liste des contenus construite, vous pouvez l'envoyer. Il est préférable de spécifier un nom de batch unique afin de pouvoir les distinguer dans Any.
Pour envoyer le message, il suffit de construire un nouveau message d'import en masse et de l'envoyer vers la file d'attente de type « BULK_IMPORT » définie dans les settings. Voir Files d'attente.
IMessageBulkImport msg = new MessageBulkImport();
// Set source, application and batch number/name
msg.setSource(sourceName);
msg.setApplication(application);
msg.setBatchNumber(batchNumber);
// set the list of contents to import
msg.setBulkContents(batchImport);
// Set copy file strategy
msg.setIsFileCopyOnConsume(false);
try {
LOG.debug("Start sending {} Any contents", batchImport.size());
messagingProvider.queue(messagingProvider.getQueueName(QueueType.BULK_IMPORT), msg);
LOG.debug("Contents sent : {} ({})", batchImport.size(), batchNumber);
}
catch (Exception e) {
LOG.error("Error while processing", e);
}
Le nombre de documents que vous pouvez envoyer dans chaque message dépend des performances de votre serveur, mais le moteur peut supporter au moins 2000 documents.
Remarque :
Si vous devez envoyer plusieurs versions d'un même document, il est nécessaire de les envoyer dans le même batch. Sinon, vous devez utiliser l'ID de racine de synchronisation pour les rattacher à l'arbre de versions. Cet ID de racine de synchronisation doit être identique sur toutes les versions.
Stratégies de gestion des fichiers
Les fichiers des contenus ne sont pas envoyés dans les messages d'import de masse : ils doivent être traités à part. Lorsque vous constituez votre jeu de données, vous devez spécifier le chemin du format. Ce chemin correspond à l'emplacement du fichier en dehors du système de fichiers de Any. Selon la stratégie choisie, il doit être accessible depuis les serveurs de messages et les instances de l'application web de Any.
Copie des fichiers directement dans Any
L'API d'import de masse permet de connaître à l'avance le futur emplacement de votre fichier dans le système de fichiers de Any. Vous pouvez copier directement vos fichiers à l'aide des scripts fournis ou du fichier CSV.
La copie des fichiers doit être faite avant de lancer le job de gestion des post-actions, afin que le contenu soit accessible par les actions « fulltext » et « conversion PDF ».
Intégration des fichiers au fur et à mesure
Cette stratégie permet d'intégrer les fichiers dans le système de fichiers de Any la première fois qu'ils seront modifiés. Lorsque le contenu est intégré dans Any, il conserve l'emplacement spécifié lors de la constitution du lot. Ce chemin sera utilisé comme chemin par défaut s'il n'est pas trouvé dans le système de fichiers de Any. Si Any tente de modifier un fichier (édition, nouvelle version, etc.), ce nouveau fichier sera intégré dans le système de fichiers de Any.
Cette option nécessite que vos fichiers soient accessibles depuis les serveurs de messages de Any et depuis les instances de l'application web de Any. Vous pouvez y parvenir en copiant vos fichiers, au moment de la constitution du jeu de données, dans un dossier partagé entre les serveurs. Sinon, vous pouvez aussi copier toute votre arborescence de fichiers sur les différents serveurs en conservant les mêmes chemins.
Copie à la consommation du message
Cette stratégie nécessite que le chemin spécifié lors de la constitution du jeu de données soit accessible par le serveur de messages de Any. Ce mode s'active dans le message d'import.
IMessageBulkImport msg = new MessageBulkImport();
// Set source, application and batch number/name
msg.setSource(sourceName);
msg.setApplication(application);
msg.setBatchNumber(batchNumber);
// set the list of contents to import
msg.setBulkContents(batchImport);
// Set copy file strategy
msg.setIsFileCopyOnConsume(true);
Dans ce cas, le fichier est intégré directement dans le système de fichiers de Any dès qu'il y est importé. Attention : cela impacte forcément un peu la rapidité d'import des contenus, puisqu'il faut copier les fichiers d'un dossier à un autre.
Copie en post-actions
Cette stratégie nécessite que le chemin spécifié lors de la constitution du jeu de données soit accessible par le serveur de messages de Any.
Ce mode est utilisable dans le job de post-actions via l'action copy_source_file ou move_source_file.
Dans ce cas, le fichier est intégré dans le système de fichiers de Any lors de l'exécution du job (voir la section Post-actions après un import de masse).
Post-actions après un import de masse
L'import massif a été conçu pour que vos documents soient accessibles et utilisables rapidement dans votre base documentaire. Après le traitement du lot, vos documents sont consultables (voir la section Stratégies de gestion des fichiers) et éventuellement disponibles dans une room (voir la section Ajout à une room statique), dans le respect des contraintes d'accessibilité à la room.
Pour finaliser l'import de vos documents, vous devez exécuter les actions suivantes :
- copier les fichiers sources (optionnel).
- synchroniser vos documents dans les rooms dynamiques.
- appliquer les ACL de restriction de visibilité.
- extraire le texte pour permettre la recherche par le contenu des fichiers.
- effectuer la conversion PDF.
Ces actions sont réalisables via le job JobBulkImportPostActions. Les traitements ont été optimisés pour gérer de gros volumes de données et peuvent être arrêtés puis repris à tout moment. Ce job permet aussi de suivre la progression des actions.
Actions
Copie ou déplacement de fichiers
ACTION : copy_source_file ou move_source_file
Selon la stratégie de gestion des fichiers choisie, vous pouvez copier ou déplacer vos fichiers dans le système de fichiers de Any via cette action.
Synchronisation des rooms dynamiques
ACTION : synchronize_dynamic_rooms
Cette action permet de placer vos contenus importés dans les rooms dynamiques. Si vos contenus ne sont que dans des rooms statiques, cette action n'est pas nécessaire : vous pouvez les placer directement lors de la constitution du lot.
Permission de visibilité
ACTION : acl
Cette action permet d'appliquer les permissions de visibilité configurées dans vos applications.
Extraction de texte
ACTION : fulltext
Cette action permet d'extraire le texte des fichiers pour activer la recherche plein texte. Cela peut prendre beaucoup de temps selon le volume de vos fichiers.
Conversion en PDF
ACTION : conversion_pdf
Cette action réalise les conversions PDF et l'ajout de vignettes. Cela peut prendre beaucoup de temps selon le volume de vos fichiers.
Finalisation
ACTION : mark_as_finished
Lorsque toutes vos actions sont terminées, vous pouvez marquer vos documents comme terminés afin que la prochaine exécution du job ne les traite plus. Cette action doit être placée à la fin.
Configuration du job
Éditez le job nommé JobBulkImportPostActions : vous pouvez accéder à ses différentes configurations.
Par défaut, les actions sont appliquées à tous les contenus importés massivement et non finalisés. Vous pouvez restreindre le périmètre d'application avec les paramètres suivants :
-
« filter » : prédicats permettant de filtrer les contenus sur lesquels appliquer les actions (ex. : « standard.status=Approved »).
-
« query » : une requête GQL complète permettant de filtrer les contenus sur lesquels appliquer les actions. Exemple :
select * from documents where standard.status='Approved' -
« batch » : permet de spécifier le nom du batch si vous voulez appliquer les actions uniquement aux contenus importés par ce batch. Par défaut, le job s'applique à tous les contenus non finalisés. Ce paramètre peut être utilisé seul ou combiné avec « query » et « filter ».
-
« actions » : liste des actions à appliquer dans l'ordre indiqué (voir la section Actions) (ex. : « [« copy_source_file », « fulltext »] »).
Si vos serveurs le permettent, vous pouvez améliorer les performances de traitement en contrôlant la taille des batchs d'écriture et le nombre de processus en parallèle, à l'aide des paramètres suivants :
- « nb_threads » (par défaut : 5) : nombre de processus en parallèle traitant les actions.
- « nb_threads_(action) » (par défaut : « nb_threads ») : nombre de processus en parallèle dédiés à une action spécifique (ex. : « nb_thread_fulltext » : 8).
Lancement et suivi des actions
Lancement et reprise
Une fois le job configuré, vous pouvez le lancer. Le champ « message » permet de suivre l'évolution du batch lorsque vous rafraîchissez le panneau.
Vous pouvez arrêter le job à tout moment. Dans ce cas, le traitement en cours s'arrête dès que possible. Pour relancer le job, vous devez attendre que l'arrêt soit notifié dans le message du job.
Vous pouvez ensuite relancer le job : le traitement reprend sur les contenus dont l'action en cours n'a pas encore été effectuée, puis se poursuit avec les actions suivantes.
Suivi
Les contenus importés de façon massive possèdent des métadonnées spécifiques que vous pouvez utiliser pour suivre leur évolution depuis Any :
- « sync.is_pending » (vrai/faux) : indique si le contenu est finalisé ou non.
- Vrai : le contenu a été importé mais n'est pas encore finalisé. Il sera traité par le job.
- Faux : le contenu a été finalisé. Il ne sera plus traité par le job.
- « sync.source » : le nom de la source spécifié lors de l'envoi.
- « sync.last_batch » : le nom du batch spécifié lors de l'envoi.
- « sync.post_actions_finished » : liste des actions déjà appliquées aux contenus.
Si vos contenus ont été importés avec un lien statique vers une room, vous pouvez suivre l'avancement des post-actions depuis la room concernée, en ajoutant les métadonnées ci-dessus dans les colonnes et les filtres.
Benchmark
Serveur
- CPU AMD Epyc 7371 - 16c/32t - 3.1 GHz/3.8 GHz
- RAM 128 Go ECC 2400 MHz
- Disques de données : 2×1.92 To SSD NVMe
Environnement
- OS : Ubuntu Server 22.04 LTS "Jammy Jellyfish"
- Ubuntu Desktop + Docker engine + Samba + divers outils
- Dockers :
- 3 dockers Elasticsearch (3 nœuds primaires) à partir des images ES 7.16.2
- 3 dockers Mongo (1 primaire + 2 secondaires) à partir des images Mongo 5.0.5
- 1 docker Kibana à partir de l’image Kibana ES 7.16.2
- 1 docker metrics connecté à Kibana et Elastic à partir d’une image Metric Beats 7.16.2
- 1 docker ActiveMQ 5.15 à partir d’une image modifiée de ActiveMQ 5.15.16
- 1 docker Any pour le Messaging Server et le Conversion Server à partir d'une image Apache Tomcat 8.5
- 1 docker Any pour la webapp et les vignettes à partir d’une image originale Tomcat 8.5
Ressources
- Mémoire disponible globale : 95 Go
- 32 CPUs assignés
- Pas de restriction de mémoire ou CPU par docker
- Swap de 4 Go par docker
- Partage des fichiers Any entre les différents dockers via un partage Samba sur le même serveur
Configuration Any
- 1 application « demo »
- 3 rooms dynamiques avec répartition aléatoire
- 1 room dynamique avec tous les documents
- 1 room statique « room 001 » assignée directement à la génération des données
- 1 permission de lister qui s'applique à environ 25 % des documents (répartition pseudo-aléatoire)
Configuration du serveur de messaging
- 5 processus dédiés à la file « bulk_import »
Batch
- Lot de 3000 documents aléatoires avec/sans versions et multiformats
- 1 million de contenus
- Taille totale des fichiers à copier : 154 Go
- 5 processus qui envoient les batchs de documents en parallèle
- Configuré pour ne pas copier le fichier à la consommation
Temps
| Étape | Moyenne (approx.) | Total (approx.) |
|---|---|---|
| 1 Mio disponibles dans la « room 001 » statique préconfigurée | 0.63 ms / contenu | 10.5 min |
Copie des fichiers (154 Go), action : copy_source_file | 12 ms / contenu | Env. 3 h |
Classement auto dans les 4 rooms, action : synchronize_dynamic_rooms | 1.26 ms / contenu | 21 min (1 room de 1M ≈ 12 min) |
ACL, application des restrictions de visibilité (env. 300 000 / 1 Mio), action : acl | 0.6 ms / contenu | 10 min |
Extraction fulltext, action : fulltext (20 processus) | 40 ms / contenu | Env. 11 h |
Conversion PDF (en local), action : conversion_pdf (20 processus) | 3 PDF / s | Env. 4 jours |
La performance pour le fulltext et la conversion PDF dépend forcément de la taille et de la nature des documents ainsi que du serveur de conversion.