Outils de correspondance de fichiers
Qu’est-ce qu’un outil de correspondance de fichiers ?
Mappage de fichiers est l’un des trois types d’outils du générateur d’outils REDA AI. Il convient lorsque :
- Des CSV de même structure sont traités régulièrement, par exemple un export hebdomadaire d’un autre système.
- Vous souhaitez une correspondance prévisible, que l’agent ne peut pas modifier à l’exécution.
- Vous ne souhaitez pas écrire de code Apex.
- La destination est un seul objet Salesforce, pour créer des enregistrements ou modifier ceux existants à partir d’une clé.
La correspondance est définie lors de la création de l’outil. À l’exécution, l’agent choisit uniquement le fichier à importer. Il ne peut modifier ni la correspondance, ni l’objet cible, ni l’opération de création ou de mise à jour. Le fonctionnement reste ainsi maîtrisable, même pour des utilisateurs moins expérimentés.
Fonctionnement d’un outil de correspondance
-
Paramètres fixés à la conception
Vous définissez l’objet cible, l’opération de création ou de mise à jour, la correspondance entre colonnes et champs et, pour les mises à jour, la clé de rapprochement. La plateforme conserve ces paramètres dans une définition d’outil en métadonnées personnalisées.
-
Une entrée minimale pour l’agent
Le modèle ne voit qu’un seul paramètre d’entrée : l’identifiant ContentVersion du CSV à importer. Tout le reste est fixé.
-
L’utilisateur charge le fichier
Un utilisateur charge ou référence un CSV dans la conversation. L’agent reconnaît le fichier attendu par l’outil et propose l’import.
-
Confirmation de l’action
Ces outils écrivent dans Salesforce et appartiennent donc à la catégorie Action. Sur le canal interne, l’agent affiche une carte de confirmation avant l’exécution, sauf si Actions de fichiers à exécution automati est activé. Les autres canaux suivent leurs propres règles de confirmation.
-
Exécution
Les petits imports sont exécutés directement et renvoient un résultat dans le même tour. Les imports plus volumineux sont confiés à un traitement par lot asynchrone.
-
Résultats par ligne
Les imports autorisent les réussites partielles. Les lignes valides sont enregistrées ; les lignes en échec sont signalées avec leur motif. L’utilisateur reçoit un résumé des créations, mises à jour et échecs.
Configuration à la conception
Créez l’outil dans le générateur d’outils. Après avoir choisi la carte Mappage de fichiers, renseignez quatre blocs de configuration :
| Bloc | Configuration |
|---|---|
| Objet cible | L’objet Salesforce dans lequel écrire les lignes. Il peut être standard ou personnalisé, sous réserve des droits de l’utilisateur d’exécution. |
| Opération | create insère de nouveaux enregistrements. Avec update, une clé Salesforce Id désigne un enregistrement existant. Pour une clé externe, vérifiez aussi le chemin de traitement : l’exécution directe recherche une correspondance, tandis que le traitement par lot peut insérer les lignes sans correspondance. |
| Colonne CSV → Champ Salesforce | Pour chaque colonne CSV à charger, indiquez le nom API du champ cible. Les colonnes sans correspondance sont ignorées. Les en-têtes sont sensibles à la casse et leurs espaces de début et de fin sont supprimés. |
| Clé du match, mise à jour uniquement | Le champ servant à retrouver l’enregistrement de chaque ligne ; le libellé « Clé du match » désigne cette clé de rapprochement. Choisissez Salesforce Id si le CSV contient les identifiants des enregistrements, ou External Id / unique field et indiquez le champ cible auquel comparer la valeur du CSV. |
Le générateur IA peut remplir ces quatre blocs à partir d’un exemple de CSV et d’une courte description du résultat attendu. Vérifiez ensuite la correspondance générée et modifiez-la avant d’enregistrer.
Consultez Configurer les outils pour la procédure complète : cartes de type, panneau d’impact en direct et verrouillage de la catégorie.
Comportement à l’exécution
Ce que voit l’agent
L’agent reçoit un outil dont l’unique entrée est l’identifiant ContentVersion du CSV. La correspondance, l’objet cible et l’opération ne sont pas exposés au modèle ; l’agent ne peut donc pas improviser des modifications du contrat d’import.
Exécution directe ou par lot
Les petits fichiers sont traités dans le même tour, avec un résumé immédiat. Les plus volumineux sont transmis à un traitement par lot asynchrone. L’agent indique alors que l’import a commencé et que les résultats seront consultables dans l’enregistrement d’action planifiée créé.
Réussite partielle
Les imports ne fonctionnent pas en mode tout ou rien. Une ligne qui échoue à une validation, enfreint une règle de doublons ou cible un enregistrement non modifiable par l’utilisateur est signalée en erreur ; le reste du fichier continue à être chargé. Le résumé indique les nombres de réussites et d’échecs, ainsi que les premiers motifs d’erreur.
Mises à jour et rapprochement
Pour une opération update, la plateforme recherche les enregistrements existants avec la clé de rapprochement :
- Salesforce Id : la colonne CSV contient l’identifiant de 15 ou 18 caractères, utilisé directement.
- External Id / unique field : la plateforme interroge l’objet cible pour trouver les enregistrements dont le champ choisi correspond à la valeur CSV. Tout champ unique convient ; un véritable champ d’identifiant externe n’est pas obligatoire.
Avec une clé externe, l’exécution directe signale les lignes introuvables ; le traitement par lot peut au contraire les insérer. Le rejet des correspondances multiples n’est pas garanti sur tous les chemins. Utilisez une clé réellement unique et testez les cas sans correspondance, avec doublon et avec un fichier volumineux avant tout import.
Sécurité et gouvernance
- La sécurité au niveau des champs s’applique. Les imports s’exécutent en mode utilisateur. Un champ non modifiable échoue lors de l’écriture et est signalé comme erreur de ligne.
- La correspondance est réservée à l’administrateur. L’agent ne peut changer ni la correspondance, ni l’objet cible, ni l’opération. Un administrateur doit modifier la définition de l’outil.
- Confirmation par défaut sur le canal interne. Les outils de correspondance affichent une carte avant l’exécution, sauf si Actions de fichiers à exécution automati est activé. Les canaux externes et API suivent les règles de confirmation propres à leur canal.
- Piste d’audit. Les exécutions directes sont enregistrées dans la conversation et ses messages. Les traitements par lot créent aussi une action planifiée et un rapport d’erreurs par ligne.
Quand choisir la correspondance de fichiers
| Pour… | Utilisez |
|---|---|
| Poser des questions ponctuelles sur un CSV sans l’importer | Le traitement conversationnel avec les outils intégrés : consultez Traitement des documents |
| Charger les lignes CSV dans un seul objet avec une correspondance stable | Un outil de correspondance de fichiers, décrit ici |
| Extraire des données d’un PDF ou d’une image, les rapprocher d’enregistrements existants, écrire dans plusieurs objets ou appeler un système externe | Un outil Apex avec traitement de fichiers : consultez Outils de classe Apex |
| Exécuter une requête SOQL paramétrée comme outil | Un outil de modèle SOQL : consultez Outils de modèle SOQL |
Bonnes pratiques
Associez uniquement les colonnes utiles. Limitez le CSV aux colonnes utilisées par l’import. L’agent traite aussi son contenu ; un fichier plus léger coûte moins cher et améliore la précision.
Choisissez la clé la plus simple qui convient. Un identifiant Salesforce est le plus fiable. Utilisez un champ externe ou unique uniquement si le système source ne fournit pas d’identifiants Salesforce.
Validez d’abord sur un petit fichier. Testez 5 à 10 lignes avant d’utiliser un fichier de production. Les erreurs se diagnostiquent plus facilement sur un faible volume.
Choisissez l’exécution automatique de manière réfléchie. Ces outils écrivent dans Salesforce. Sur le canal interne, conservez la confirmation par défaut, sauf si l’agent est réservé à un usage interne et que la structure des fichiers est bien maîtrisée.
Expliquez le fonctionnement dans le nom de l’outil. Le nom et la description doivent rendre l’objet cible et l’opération évidents pour les futurs administrateurs. Préférez « Importer des comptes — Création » à « Outil d’import 1 ».
Questions fréquentes
Non. Chaque outil de correspondance cible un seul objet. Pour charger des enregistrements liés dans plusieurs objets à partir d’un même fichier, utilisez un outil Apex avec traitement de fichiers.
La ligne est ignorée et signalée en erreur ; les autres sont traitées. L’agent renvoie les nombres de lignes réussies et en échec, avec les premiers motifs d’erreur.
Non. La correspondance appartient à la définition de l’outil. Seul un administrateur qui la modifie peut changer les champs, l’objet cible, l’opération ou la clé de rapprochement.
Oui. Les imports s’exécutent en mode utilisateur avec ses autorisations. Les champs qu’il ne peut pas modifier échouent à l’écriture et sont signalés comme erreurs de ligne.
Les paramètres de la plateforme appliqués aux fichiers chargés s’appliquent aussi ici : Taille maximale du fichier (Mo) et Nombre maximal de caractères CSV. Au-delà du seuil d’exécution directe, l’import est automatiquement exécuté par lots, en plusieurs blocs, plutôt que de façon synchrone.
L’agent utilise le fichier chargé ou référencé dans la conversation. Un nom et une description d’outil explicites l’aident à choisir le bon fichier lorsque plusieurs sont disponibles.
Prochaines étapes
Consultez Traitement des documents pour comprendre le parcours des fichiers dans REDA AI, ou Outils de classe Apex si vos imports dépassent les possibilités de la correspondance déclarative.