Comment diagnostiquer et corriger les erreurs fréquentes lors d'un import de référentiels (ETL) ?

Contexte

Les erreurs d'import de référentiels (ETL) se produisent lorsque des champs obligatoires sont vides ou que des identifiants référencés n'existent pas encore dans quarksUp. Ce guide aborde les messages d'erreur les plus fréquents rencontrés lors d'imports de référentiels (CSP, Départements, Niveaux, Services, Emplois, Entités, Employés).

Messages d'erreur fréquents et leurs causes

« Le champ RepositoryReference est obligatoire » / « RepositoryExternalID est obligatoire » / « RepositoryLabel est obligatoire »

Ces champs sont requis dans tous les fichiers de référentiels génériques. Vérifiez que les colonnes suivantes sont bien renseignées dans votre fichier :

• RepositoryReference : code interne du référentiel
• RepositoryExternalID : identifiant externe unique
• RepositoryLabel : libellé affiché

« Le champ RepositoryForeignKey est obligatoire »

Ce message apparaît lorsqu'un élément de référentiel dépend d'un parent (ex. : un service doit être rattaché à un département). Vérifiez que la colonne Parent (ExtID) est correctement renseignée pour chaque enregistrement.

« DuplicateKey : JobDataReference »

Ce message signifie que l'emploi que vous tentez d'importer existe déjà avec cet identifiant. Vérifiez si des colonnes comme « Code pôle » ou « Code département » sont vides pour les nouvelles lignes : cela peut générer un conflit de clé.

« Dans Structure, l'External ID XXX n'existe pas »

L'élément référencé (Etablissement, Pôle, etc.) n'existe pas encore dans quarksUp. Importez d'abord les éléments parents (sociétés, établissements, pôles) avant les éléments enfants (services, employés).

« Dans Job, l'externalId XXX n'existe pas »

Ce message signifie que l'emploi (Job) référencé par la colonne « Emploi (Ext ID) » de votre fichier d'import n'existe pas encore dans le référentiel Emplois de quarksUp. L'externalId indiqué dans le message correspond à l'identifiant externe attendu pour cet emploi. Pour corriger :

1. Vérifiez dans le référentiel Emplois si un emploi porte déjà cet identifiant externe (ExtID) ; si non, il doit être créé (manuellement ou par import du référentiel Emplois) avant de pouvoir être référencé dans le fichier en erreur.
2. Si l'emploi existe mais sous un ExtID différent, corrigez la colonne « Emploi (Ext ID) » de votre fichier pour qu'elle corresponde à l'identifiant réellement utilisé dans quarksUp.
3. Respectez l'ordre d'import recommandé ci-dessous : les emplois doivent être importés avant les fichiers qui les référencent (ex. fiches employés).

« Le DirectoryEmployeeDataExternalID XXX n'existe pas »

L'employé référencé (comme manager, par exemple) n'est pas encore créé dans quarksUp. Importez les employés avant d'importer les liens hiérarchiques (managers).

Ordre recommandé pour les imports

Pour éviter les erreurs de référence manquante, respectez cet ordre d'import :

1. Référentiels génériques (CSP, Niveaux, Indices, Contrats)
2. Structure organisationnelle (Sociétés > Etablissements > Pôles > Départements > Services)
3. Postes / Emplois
4. Employés
5. Informations complémentaires (managers, données personnelles)

Bon à savoir

Après chaque import, consultez le rapport d'import dans quarksUp (ETL > Historique des imports) pour identifier les lignes en erreur et les corriger avant le prochain envoi. Pour les éléments nouvellement créés dans quarksUp (nouvelle catégorie, nouveau service, nouvel emploi...), assurez-vous de répercuter ces ajouts (et leur ExtID exact) dans vos fichiers sources d'import.