Le Data Manager est l’outil en ligne de commande de Cirrus Shield qui permet d’importer, mettre à jour ou supprimer des données en masse dans votre instance à partir de fichiers CSV. Il est destiné aux administrateurs et intégrateurs.
Ce guide explique comment installer, configurer et exécuter le Data Manager, comment construire vos fichiers source, et comment interpréter les erreurs renvoyées.
1. Contenu du package Data Manager
Le package Data Manager téléchargeable depuis votre environnement Cirrus Shield (menu Configuration → Intégration) contient les éléments suivants :
- •
datamanager.config— fichier de configuration générale (connexion, options d’exécution). - •
datamappings.config— fichier de correspondance entre les colonnes CSV et les champs Cirrus Shield. - •
privateKey.xml— clé privée utilisée pour le déchiffrement du mot de passe. - •Dossier
bin/Release/contenant :- ◦
CirrusShield.DataManager.exe— l’exécutable. - ◦
CirrusShield.DataManager.exe.config— configuration de l’exécutable. - ◦
CirrusShield.Security.dll— librairie de sécurité. - ◦Sous-dossier
Log/Verbose/— fichiers de journalisation générés à chaque exécution.
- ◦
Le package contient également l’outil EncryptDataManagerCirrusShieldUserPasswordEncryptionGUI.exe, utilisé pour chiffrer le mot de passe de connexion (voir § 4.2).
2. Vue d’ensemble : les étapes d’un import
L’exécution d’un import suit toujours la même séquence :
- 1.Préparer le ou les fichiers CSV source en respectant les formats de données attendus (§ 3).
- 2.Configurer
datamanager.configpour la connexion à votre instance etdatamappings.configpour la correspondance des champs (§ 4). - 3.Lancer
CirrusShield.DataManager.exe(double-clic ou ligne de commande). - 4.Vérifier les fichiers de résultats produits dans le dossier
Resultset les logs (§ 5).
3. Formats de données supportés
Les fichiers CSV doivent être encodés en UTF-8. Les valeurs doivent respecter les formats suivants selon le type du champ cible :
| Type | Format attendu |
|---|---|
| Booléen | 1 (vrai) ou 0 (faux), insensible à la casse. |
| Date | AAAA-MM-JJ (ex. 2017-01-15). |
| Date / Heure | AAAA-MM-JJ HH:MM:SS+TZ, où TZ est le fuseau horaire (ex. 2017-01-15 10:00:00+01). |
| Adresse e-mail valide. | |
| Nombre | nnnnnnnnnnnnnnnn.nn (point comme séparateur décimal). |
| Pourcentage | nnn.nn |
| Devise | Valeur numérique. |
| Texte | Chaîne libre. |
| Zone de texte | Chaîne libre, plusieurs lignes possibles. |
| Zone de texte (Rich) | HTML. |
| URL | URL valide. |
| Relation de recherche | Voir § 3.1. |
3.1 Champs Relation de recherche et Id Externe
Lorsque vous renseignez un champ Relation de recherche dans un CSV, vous pouvez désigner l’enregistrement parent par son Id Externe plutôt que par son Id Cirrus Shield interne. C’est généralement plus pratique lors d’un import depuis un système tiers, où vous connaissez déjà les identifiants externes mais pas ceux générés par Cirrus Shield.
L’Id Externe est un champ que vous désignez vous-même en cochant la propriété Identifiant externe lors de la création ou de la modification d’un champ dans Cirrus Shield.
Règle : un seul champ Id Externe peut être défini par objet. Dès qu’un champ Id Externe est défini sur un objet, toutes les relations de recherche pointant vers cet objet doivent être renseignées avec l’Id Externe, et non avec l’Id Cirrus Shield.
Exemple
On définit sur l’objet Utilisateur un champ personnalisé Id_Externe_Utilisateur (type Texte) avec la propriété Identifiant externe cochée. Deux utilisateurs existent :
| Nom | Id Cirrus Shield | Id_Externe_Utilisateur |
|---|---|---|
| Noémie Leroy | a1B2c3D4e5 | 123456 |
| Alice Robert | f6G7h8I9j0 | 789012 |
Pour importer des enregistrements de l’objet personnalisé Compte en attribuant chaque compte à son propriétaire, le CSV doit utiliser les valeurs de Id_Externe_Utilisateur :
| Nom_Compte | Id_Proprietaire |
|---|---|
| Compte 1 | 123456 |
| Compte 2 | 789012 |
Résultat : Compte 1 est attribué à Noémie Leroy, Compte 2 à Alice Robert.
Attention : si vous saisissez une valeur d’Id Externe inexistante (ex. 123457 au lieu de 123456), l’enregistrement ne sera pas créé.
4. Configuration
Le Data Manager s’appuie sur deux fichiers de configuration utilisés à chaque exécution :
- •
datamanager.config— définit l’instance Cirrus Shield cible, l’utilisateur de connexion et les options d’exécution. - •
datamappings.config— définit le ou les imports : fichier CSV source, objet cible, action et correspondance des champs.
4.1 Déclarer les chemins des fichiers de configuration
Dans CirrusShield.DataManager.exe.config (et CirrusShield.DataManager.vshost.exe.config en environnement de développement), renseignez le chemin absolu vers vos deux fichiers de configuration :
<appSettings> <add key="DataManagerConfig" value="C:\DataManager\datamanager.config" /> <add key="DataMappingsConfig" value="C:\DataManager\datamappings.config" /> </appSettings>
4.2 Fichier datamanager.config
Ce fichier définit la connexion à votre instance Cirrus Shield et le comportement général de l’outil. Les clés à renseigner :
| Clé | Rôle |
|---|---|
UserName | Identifiant de connexion (e-mail) de l’utilisateur Cirrus Shield qui exécute l’import. |
Password | Mot de passe chiffré de cet utilisateur (voir ci-dessous). |
HttpsCSInstance | URL HTTPS du Web Service SOAP Cirrus Shield. HTTPS est obligatoire en production. |
HttpCSInstance | URL HTTP, réservée aux environnements de test locaux. |
WebServiceProtocol | Protocole utilisé : http ou https. |
CSPrivateKey | Chemin absolu vers privateKey.xml. |
Proxy / ProxyUser / ProxyPwd | Paramètres de proxy si votre réseau en utilise un. Laisser vides sinon. |
CSVDelimiter | Séparateur des fichiers CSV : , ou ; |
Bulk | true pour activer le mode bulk (import par lots). |
BulkSize | Nombre d’enregistrements par lot. |
AutoExit | true pour fermer la fenêtre à la fin de l’exécution, false pour la laisser ouverte en attente d’une action. |
Chiffrer le mot de passe
La clé Password doit contenir le mot de passe chiffré, jamais en clair. Pour produire la valeur chiffrée :
- 1.Lancez
EncryptDataManagerCirrusShieldUserPasswordEncryptionGUI.exe, livré dans le package Data Manager. - 2.Saisissez votre mot de passe en clair.
- 3.Copiez la valeur chiffrée produite et collez-la dans la clé
Passworddu fichierdatamanager.config.
Exemple complet
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<appSettings>
<add key="UserName" value="nom.utilisateur@domaine.fr" />
<add key="Password" value="VALEUR_CHIFFREE_DU_MOT_DE_PASSE" />
<add key="HttpCSInstance" value="https://www.cirrus-shield.net" />
<add key="HttpsCSInstance" value="https://www.cirrus-shield.net" />
<add key="CSPrivateKey" value="C:\DataManager\privateKey.xml" />
<add key="Proxy" value="" />
<add key="ProxyUser" value="" />
<add key="ProxyPwd" value="" />
<add key="CSVDelimiter" value="," />
<add key="Bulk" value="true" />
<add key="BulkSize" value="100" />
<add key="AutoExit" value="true" />
<add key="WebServiceProtocol" value="https" />
</appSettings>
</configuration>
4.3 Fichier datamappings.config
Ce fichier définit, pour chaque CSV à importer, l’objet cible, l’action à exécuter et la correspondance entre les colonnes du CSV et les champs Cirrus Shield. Vous pouvez déclarer plusieurs blocs <map> pour exécuter plusieurs imports en une seule passe.
Exemple
<map>
<FilePath>C:\data\source\Policies.csv</FilePath>
<ObjectName>Policy</ObjectName>
<Action>Insert</Action>
<MatchingField>Policy_Number</MatchingField>
<Fields>
<Field Column="POLICY_NUMBER" APIColumn="Policy_Number" />
<Field Column="PRODUCT" APIColumn="Product" />
<Field Column="HOLDER_NUMBER" APIColumn="Holder_Number" />
<Field Column="HOLDER" APIColumn="Holder" />
<Field Column="INSURED_NUMBER" APIColumn="Insured_Number" />
<Field Column="INSURED" APIColumn="Insured" />
<Field Column="PAYER_NUMBER" APIColumn="Payer_Number" />
<Field Column="PAYER" APIColumn="Payer" />
<Field Column="TOTAL_PREMIUM" APIColumn="Total_Premium" />
<Field Column="NUMBER_OF_PAYMENTS" APIColumn="Number_of_Payments" />
<Field Column="COMMISSION" APIColumn="Commission" />
<Field Column="UNPAID_COMMISSION" APIColumn="Unpaid_Commission" />
<Field Column="ACCOUNT_VALUE_LIFE" APIColumn="Account_Value_Life" />
<Field Column="INSURANCE_TERM" APIColumn="Insurance_Term" />
<Field Column="PAYMENT_TERM" APIColumn="Payment_Term" />
<Field Column="POLICY_VALUE" APIColumn="Policy_Value" />
</Fields>
<ResultDirectory>C:\data\Results</ResultDirectory>
</map>
Balises supportées
| Balise | Rôle |
|---|---|
FilePath | Chemin absolu du fichier CSV source. |
ObjectName | Nom API de l’objet Cirrus Shield cible. |
Action | Insert, Update, Upsert ou Delete (voir § 4.4). |
MatchingField | Champ servant de clé unique pour les actions Update, Upsert et Delete. Doit être unique pour identifier de façon certaine l’enregistrement à mettre à jour ou supprimer. |
Fields | Liste des correspondances colonne CSV ↔ champ API. |
Field Column / APIColumn | Column = nom de la colonne dans le CSV. APIColumn = nom API du champ dans Cirrus Shield. |
ResultDirectory | Dossier où sera écrit le fichier de résultat (§ 5). |
4.4 Choix de l’action
Quatre actions sont disponibles. La structure du CSV et le contenu du bloc <Fields> diffèrent selon l’action.
Insert — Créer des enregistrements
Crée de nouveaux enregistrements. Champs système à fournir au minimum : le nom de l’enregistrement et l’Id du propriétaire (Id Cirrus Shield interne ou Id Externe de l’utilisateur s’il existe). Par défaut, les champs CreatedBy et ModifiedBy sont attribués à l’utilisateur déclaré dans datamanager.config.
Update — Mettre à jour des enregistrements existants
- •Indiquez dans
MatchingFieldun champ permettant d’identifier de façon unique l’enregistrement à mettre à jour. Si la clé n’est pas unique, plusieurs enregistrements partageant la même valeur seront tous mis à jour. - •Important : ne déclarez dans
<Fields>que les champs réellement à mettre à jour. Tout champ déclaré mais absent du CSV sera considéré comme vide et écrasera la valeur existante dans Cirrus Shield.
Upsert — Créer ou mettre à jour
Met à jour les enregistrements existants identifiés par MatchingField et crée ceux qui n’existent pas. Mêmes précautions que pour Update : si MatchingField n’est pas unique, tous les enregistrements correspondants seront mis à jour.
Delete — Supprimer des enregistrements
Le CSV ne doit contenir qu’une seule colonne, qui sert de critère de suppression :
- •Pour supprimer un enregistrement précis : utilisez un champ unique (ex. l’Id, ou un Id Externe).
- •Pour supprimer un ensemble d’enregistrements partageant une valeur commune (ex. tous les enregistrements où Numero = 1) : la colonne Numero avec la valeur 1 suffit.
5. Exécution et résultats
Une fois la configuration en place, double-cliquez sur CirrusShield.DataManager.exe pour lancer l’import.
Pour chaque fichier CSV traité, le Data Manager produit dans le dossier ResultDirectory un fichier nommé AAAAMMJJHHMMSS-nom_du_csv_original.csv. Ce fichier reprend toutes les colonnes du CSV source, augmentées de deux colonnes :
- •une colonne indiquant si l’action a réussi pour cet enregistrement,
- •une colonne contenant le message d’erreur le cas échéant.
Les logs détaillés sont écrits dans bin/Release/Log/Verbose/.
6. Dépannage : erreurs courantes
6.1 Erreurs en ligne de commande
« There is an error during the processing of the file »
Erreur affichée une fois par lot (BulkSize), pas par enregistrement. Si BulkSize=2000 et que 500 enregistrements sur 2000 échouent, vous verrez un seul message pour ce lot. Le lot suivant produira son propre message si lui aussi contient des erreurs. Consultez le fichier de résultat (§ 5) pour identifier précisément les enregistrements en erreur.
Erreur fatale due à un retour à la ligne dans un champ
Un caractère de retour à la ligne mal échappé dans une cellule du CSV peut provoquer une erreur système. Vérifiez que les valeurs multilignes sont entourées de guillemets doubles.
Erreur de connexion au Web Service
Peut survenir si la connexion entre le Data Manager et la base de données Cirrus Shield est interrompue, en particulier lorsque la base est hébergée sur un serveur distant. Vérifiez l’URL HttpsCSInstance, la connectivité réseau et les paramètres de proxy.
CSV introuvable
Si le fichier CSV référencé dans un bloc <map> n’existe pas, le Data Manager journalise l’incident dans Log/Verbose et passe au mapping suivant sans interrompre l’exécution.
6.2 Erreurs dans le fichier de résultat
Les erreurs spécifiques à un enregistrement apparaissent dans la colonne d’erreur du fichier de résultat :
| Message | Cause |
|---|---|
Error_MSG_Field_Required |
Valeur absente pour un champ obligatoire. |
Error_MSG_Value_entered_not_valid |
Valeur au format invalide pour le type du champ. Ex. : Date_of_Birth:Error_MSG_Value_entered_not_valid si la date n’est pas au format AAAA-MM-JJ ; Email:Error_MSG_Value_entered_not_valid si l’adresse e-mail est mal formée. |
This Record does not exist |
Action Update sur un enregistrement introuvable avec le MatchingField fourni. |
This record already exists |
Action Insert sur un enregistrement déjà présent. |
| Liste de sélection : valeur invalide | La valeur fournie dans le CSV n’existe pas dans la liste de choix définie côté Cirrus Shield. |
| Relation de recherche : enregistrement parent introuvable | Le champ Relation de recherche pointe vers un enregistrement (Id Externe ou Id Cirrus Shield) qui n’existe pas. L’enregistrement n’est pas inséré. |
Pour toute erreur persistante, contactez le support Cirrus Shield en joignant le fichier de résultat et un extrait des logs Verbose.