Importation via fichier CSV
Ce document détaille la procédure d'importation des référentiels via web service.
Les en-têtes obligatoires sont indiqués avec une étoile. Leur ordre de déclaration n'est pas important, mais l'ordre de déclaration dans les en-têtes doit ensuite être respecté dans les lignes de description. Les intitulés des en-têtes ne peuvent être modifiés. Certains peuvent être omis. Seront ici détaillés des en-têtes complets. Toute valeur supplémentaire ne sera pas prise en compte par le système et lancera une erreur.
Toutes les requêtes d'importation sont à réaliser en POST.
Un paramètre isReset est présent dans les requêtes. Ce paramètre, sert à déterminer si l'import est à réaliser avec remise à zéro de la base de données ou non. Les requêtes présentées ont ce paramètre à false. Le CSV est à renseigner dans le body de la requête POST.
> **Attention** : un import avec remise à zéro des données entraîne des conséquences sur d'autres tables, et est irréversible. Nous vous invitons à réaliser un dump de votre base avant d'initier cette action, afin d'être certain de ne pas perdre de données.
Après un import avec remise à zéro des champs, il sera nécessaire de faire des imports de référentiels dans un certain ordre afin que les relations dans la base soient effectives.
Les données des CSV sont séparées par des virgules ,. Les textes sont entre guillemets doubles "", les valeurs de tableau sont séparées par des points virgules ;.
La base de données de Maarch RM est une base de données relationnelle. Suite à une importation avec remise à zéro des données, il est important de respecter un ordre d'importation spécifique afin de correctement recréer les relations. L'ordre à respecter est détaillé plus bas dans cette documentation.
Import des référentiels d'organisations
POST /organization/organization/import?isReset=false
| orgName | otherOrgName | displayName* | legalClassification | businessType | description | orgTypeCode | orgRoleCodes | registrationNumber* | taxIdentifier | beginDate | endDate | parentOrgRegNumber | ownerOrgRegNumber | isOrgUnit | enabled |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Nom de l'organisation | Nom supplémentaire affiché de l'organisation | Nom affiché | Forme juridique | Nature de l'activité | Description | Type d'organisation | Rôles d'organisation | Identifiant de l'organisation | N° de TVA intraco | Date de début | Date de fin | Identifiant de l'organisation parente | Identifiant de l'organisation racine | Est une organisation (booléen) | Activé (booléen) |
Exemple de header complet avec une ligne de détail
orgName,otherOrgName,displayName,legalClassification,businessType,description,orgTypeCode,orgRoleCodes,registrationNumber,taxIdentifier,beginDate,endDate,parentOrgRegNumber,ownerOrgRegNumber,isOrgUnit,enabled
"Achats Groupe",,"Achats Groupe",,,,,,ACHAT,,,,DSG,ACME,1,1
La mise à jour des référentiels d'organisation met à jour la table organization ainsi que :
- les relations entre les comptes utilisateurs et les organisations/services ;
- les relations entre les comptes de service et les organisations/services ;
- les relations entre les profils d'archive et les organisations/services ;
- les relations entre les contacts et les organisations/services.
La valeur ownerOrgRegNumber devient obligatoire si la valeur isOrgUnit est à false.
L'ordre de déclaration des organisations dans le CSV est important. Une organisation parente DOIT être déclarée avant une organisation/service enfant sous peine d'engendrer une erreur.
Attention, dans le cas d'une mise à jour avec remise à zéro des référentiels, l'organisation de l'utilisateur/service responsable de l'action ne sera pas supprimée.
Import des référentiels de compte de service
POST /auth/serviceAccount/import?isReset=false
| accountName* | displayName* | emailAddress* | password | organizations | privileges | locked | enabled | ownerOrgRegNumber | isAdmin |
|---|---|---|---|---|---|---|---|---|---|
| Identifiant du compte | Nom affiché | Adresse mail | Mot de passe | Organisations de rattachement | Privilèges du compte de service | Verrouillé | Activé | Identifiant de l'organisation racine | Est administrateur |
Exemple d'en-tête complet avec une ligne de détail
accountName,displayName,emailAddress,password,organizations,privileges,locked,enabled,ownerOrgRegNumber,isAdmin
Systeme,Systeme,,RJpzB36bmR+iuz/aHN9Zl9PDn8tZEs4mzsz9OXNeNIrej2+v3UMzAsF3PSzDUlZ73kPvgqbQmZvza0eZO062uQu57Rdah9z3mdbTh6NBiiR8FQTnW6eVgQ==,GIC,*;audit/event/createChainjournal;batchProcessing/scheduling/updateProcess;lifeCycle/journal/createChainjournal;recordsmanagement/archivecompliance/readperiodic;recordsManagement/archives/deleteDisposablearchives;recordsManagement/archives/updateArchivesretentionrule;recordsManagement/archives/updateIndexfulltext,,1,ACME,
Les privilèges correspondent aux routes de privilège de Maarch RM. Les routes doivent correspondre à celles déclarées dans le fichier de configuration sous la variable servicePrivileges de la section [auth].
Le mot de passe correspond au jeton d'identification du service fourni lors de sa création. Ce jeton est encodé en base64 et "salé"" avec la clé secrète configuré au moment de l'installation de l'application.
Import des référentiels de compte utilisateur
POST /auth/userAccount/import?isReset=false
| accountName* | displayName* | emailAddress* | lastName | firstName | title | password* | roles | organizations | locked | enabled | ownerOrgRegNumber | isAdmin |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Identifiant | Nom affiché | Adresse mail | Nom de famille | prénom | Titre | Mot de passe | Tableau de rôles | Tableau des services/organisations d'appartenance | Verrouillé | Activé | Identifiant de l'organisation parente d'appartenance | Est administrateur |
Exemple de header complet avec une ligne de détail
accountName,displayName,emailAddress,lastName,firstName,title,password,roles,organizations,locked,enabled,ownerOrgRegNumber,isAdmin
aackermann,"Amanda ACKERMANN",support@maarch.fr,ACKERMANN,Amanda,Mme.,fffd2272074225feae229658e248b81529639e6199051abdeb49b6ed60adf13d,RESPONSABLE_ACTIVITE,FOUR,,1,ACME,
Les tableaux de rôles doivent reprendre les identifiants de rôles déja présents dans l'application
Le tableau des organisations/services d'appartenance doit comporter les registrationNumber des organisations/services
Le mot de passe doit être encodé en base64, et est facultatif. Une demande de modification à la première connexion de l'utilisateur sera automatiquement demandée.
Le CSV d'importation doit au moins avoir un administrateur. Un utilisateur doit être attaché à au moins un service (sauf s'il est administrateur).
Import des référentiels de profil d'archive
POST /recordsManagement/archivalProfile/import?isReset=false
| reference* | name | description | descriptionSchema | descriptionClass | retentionStartDate | retentionRuleCode | accessRuleCode | acceptUserIndex | acceptArchiveWithoutProfile | fileplanLevel | archiveDescriptions | childrenProfiles |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Identifiant | Nom | Description | Schéma de description | Classe de description | Date de référence de la règle de conservation | Identifiant de la règle de conservation | Identifiant de la règle de communicabilité | Autorise les index utilisateurs | Sans profil | Niveau dans le plan | Champs de description | Profils enfants |
Exemple de header complet avec une ligne de détail
reference,name,description,descriptionSchema,descriptionClass,retentionStartDate,retentionRuleCode,accessRuleCode,acceptUserIndex,acceptArchiveWithoutProfile,fileplanLevel,archiveDescriptions,childrenProfiles
COUA,"Courrier Administratif",,,,originatingDate,,,1,1,item,"[{""archivalProfileId"":""1"",""fieldName"":""org"",""required"":false,""position"":0,""descriptionField"":null,""isImmutable"":false,""isInList"":false,""isRetained"":false}]",
Import des référentiels de rôle
Cette fonctionnalité sera implémentée dans une future version. En attendant, les rôles ne peuvent être ni importés, ni exportés.
Import des référentiels de champs de description
POST /recordsManagement/descriptionField/import?isReset=false
| name* | label* | type* | default | minLength | maxLength | minValue | maxValue | enumeration | facets | pattern |
|---|---|---|---|---|---|---|---|---|---|---|
| Identifiant | Nom affiché | Type de variable | Valeur par défaut | Longueur minimale | Longueur maximale | Valeur minimale | Valeur maximale | Tableau des valeurs à sélectionner | Facette | Structure |
Exemple de header complet avec une ligne de détail
name,label,type,default,minLength,maxLength,minValue,maxValue,enumeration,facets,pattern
service,"Service Concerné",name,,,,,,"[""MARK"",""DSG"",""DSI"",""DAF""]",,
Pour les types de variables, les valeurs possibles sont :
- name -> Correspond à un mot-clé. Il peut avoir une valeur par défaut.
- Si un type énumération est désiré (i.e une liste déroulante), le champ énumération doit également être complété par un tableau comme dans l'exemple ci-dessus.
- Si une liste avec libellés est désirée , les champs "enumeration" et "facets" doivent être complétés. Le champ énumération est un tableau contenant les identifiants et le champ facets un objet json contenant les valeurs associés au champ énumération compris dans une valeur "enumNames". Par exemple dans le cas de deux couples prénom/nom, les valeurs à renseigner dans le CSV pour les champs enumeration et facets seront respectivement "["Bernard","Sharon","Nancy"]" et "{"enumNames": ["Blier", "Stone", "Nataly"]}".
- Si une liste placée dans un referentiel externe est désirée, le champ facets doit être renseigné avec la valeur suivante "{"ref": true}". Le champ name doit contenir le nom du CSV placé dans le dossier renseigné dans le point de configuration refDirectory. Pour plus d'information, veuillez vous référer à la documentation sur les données descriptives
- text
- date -> Si la date du jour est souhaité en tant que valeur par défaut, le champ default doit être rempli avec la valeur now. Si le format date désiré est celui avec une heure, le champ facets doit être complété par la valeur "{"format": "datetime"}"
- number
- boolean. La valeur par défaut, si désirée est à 1 si vrai, 0 si non.
Import des référentiels de règles de conservation
| code | duration | finalDisposition | description | label | implementationDate |
|---|---|---|---|---|---|
| Identifiant | Durée | Sort final | Description | Label | Date de mise en oeuvre |
Exemple de header complet avec une ligne de détail
code,duration,finalDisposition,description,label,implementationDate
BULPAI,P5Y,destruction,"Code du Travail, art. L3243-4 - Code de la Sécurité Sociale, art. L243-12","Bulletins de paie",
La durée est exprimée en intervalle de date php similaire à ceux exprimés dans la norme ISO 8601 (cf. https://www.php.net/manual/en/dateinterval.construct.php) Le sort final est soit Destruction (destruction), soit Conservation (preservation) La date de mise en oeuvre est au format YYYY-MM-DD.
Ordre des imports suite à une remise à zéro
Comme expliqué dans le préambule, lors d'un import des données avec remise à zéro, cela suppose que vous avez sauvegardé toutes vos données au préalable. La remise à zéro se faisant sur plusieurs tables, il est important de repasser tous les imports afin d'avoir un système fonctionnel. L'ordre de passage des référentiels afin d'avoir un système fonctionnel est le suivant :
- Règles de conservation
- Champs de description
- Profils d'archive
- Organisations
- Comptes de service
- Utilisateurs