path: root/docs/fr/administrateur-applicatif.md

Administration applicative
==========================

Auteur

:   Étienne Loks

Date

:   2023-11-16

Copyright

:   CC-BY 3.0

------------------------------------------------------------------------

::: {#interface-administrateur}
La configuration d\'Ishtar se fait essentiellement par le biais de «
l\'interface d\'administration ». Cette interface propose une vue brute
des tables en base de données. Même si cette interface propose une
ergonomie simple et pratique, utiliser cette interface peut nécessiter
d\'avoir connaissance de notions de base d\'une base de données pour
pouvoir opérer des choix pertinents.
:::

L\'interface d\'administration nécessite d\'avoir un compte
administrateur pour y accéder. Les utilisateurs disposant de ce droit
ont une icône « roue dentée » sur la barre de menu à l\'extrémité
droite. Sauf configuration spécifique, cette interface est aussi
disponible via l\'adresse « <https://monsite-ishtar.net/admin/> »
(ajouter [/admin/]{.title-ref} à l\'adresse de base).

L\'interface d\'administration présente la liste des différentes tables
par ordre alphabétique regroupées par application.

::: {.warning}
::: {.title}
Warning
:::

Pour des questions de performance, Ishtar utilise intensément un système
de cache. Il arrive parfois que celui-ci tarde à se mettre à jour. Il
peut arriver que des modifications en administration prennent plusieurs
minutes à être prises en compte.
:::

Listes de types
---------------

Ishtar fournit par défaut des données pour chaque liste de choix.
Chacune de ces listes est paramétrable en administration.

Dans les pages d\'administration, les listes de types se retrouvent sous
les dénominations « Types de \... », rangées par application :

-   **Ishtar - Commun** : contient les listes de types transversales
    utilisées par plusieurs types d\'éléments ;
-   **Ishtar - Opération** : contient les listes de types concernant les
    opérations et les entités archéologiques/sites ;
-   **Ishtar - Unités d\'enregistrement** : contient les listes de types
    relatives aux Unités d\'enregistrement et aux datations ;
-   **Ishtar - Mobilier** : contient les listes de types relatives au
    mobilier et aux traitements ;
-   **Ishtar - Lieu de conservation** : contient les listes de types
    relatives aux lieux de conservation et aux contenants ;
-   **Ishtar - Dossier** : contient les listes de types relatives aux
    dossiers administratifs.

Dans Ishtar, chaque type est défini au minimum par les champs suivants :

-   **Dénomination**
-   **Identifiant textuel** : L\'identifiant textuel est une version
    standardisée du nom. Il ne contient que des lettres en minuscules
    non accentuées, des nombres et des tirets (-). Chaque identifiant
    textuel doit être unique dans la liste de types. Ces identifiants
    sont des clés permettant les échanges entre bases de données et pour
    des traductions. Ces identifiants peuvent être utilisés dans le code
    source de l\'application. Une fois créés il ne faut a priori pas
    changer ces identifiants textuels.
-   **Commentaire** : Le contenu du commentaire est affiché dans l\'aide
    en ligne sur les formulaires.
-   **Disponibilité** : Décocher ce champ rend indisponible ce type dans
    les formulaires, sans détruire l\'information pour ce qui est déjà
    présent en base ; l\'information est toujours visible dans les
    fiches.
-   **Ordre** : Dans les listes les champs sont ordonnés par ce numéro
    d\'ordre et en cas d\'égalité par ordre alphabétique.

Certains types permettent de mettre en place une hiérarchie. Pour cela
le champ **parent** est disponible. Pour chaque type enfant, ce champ
est renseigné avec le type parent adéquat.

Certains types disposent aussi d\'autres champs spécifiques ; ceux-ci
sont explicites ou disposent d\'une aide en ligne.

::: {.note}
::: {.title}
Note
:::

Pour travailler sur ces listes de types ou les transmettre à des tiers,
la possibilité est offerte d\'exporter ces listes de types via
l\'interface d\'administration. On sélectionne les éléments à exporter
(ou tous les éléments) puis on utilise l\'action « Exporter les éléments
sélectionnés en fichier CSV ». Le fichier peut alors être édité dans un
tableur. Pour une mise à jour, il est important de ne pas modifier les
identifiants textuels qui sont la clé de rapprochement pour le
ré-import. L\'action d\'import est disponible en haut à droite : «
Import depuis un CSV ».
:::

Champs personnalisés {#champ-personnalises}
--------------------

Ishtar propose un certain nombre de champs standards et génériques
permettant de disposer dès le départ d\'une base solide et aussi pour
assurer un certain degré d\'inter-opérabilité entre les différentes
installations d\'Ishtar. Néanmoins nul ne peut prétendre à
l\'exhaustivité et, notamment dans le cadre d\'une utilisation d\'Ishtar
axée recherche, le besoin se fera probablement sentir d\'ajouter des
champs.

Dans Ishtar ces champs sont appelés : **Champs personnalisés**. Le
format JSON étant utilisé pour stocker ces données, le nom **Données
JSON** est aussi utilisé.

Ajouter un champ personnalisé se fait via l\'interface d\'administration
au niveau de la rubrique : *Ishtar - Commun › Données JSON - Champs*.

Les différentes données à rentrer sont :

-   **Nom** : Ce nom sera repris dans les formulaires et la fiche.
-   **Type de contenu** : Le type d\'objet auquel sera rattaché le
    champ - Opération, Site, Unité d\'Enregistrement, Mobilier, \...
-   **Clé** : Valeur de la clé dans le format JSON. Cette clé ne doit
    impérativement comporter que des lettres minuscules, sans accent et
    des tirets bas « \_ » (ne pas commencer la clé par le tiret bas et
    ne pas mettre plusieurs tirets bas d\'affilée dans la clé de base).
    On peut structurer les données personnalisée de manière
    hiérarchique. Pour les clés hiérarchiques on utilise « \_\_ » entre
    les sections. Par exemple pour la clé « ma\_sousclef » dans la
    catégorie « ma\_categorie », la clé sera notée :
    *ma\_categorie\_\_ma\_sousclef*.
-   **Type** : Les types de données disponibles sont les suivants :
    -   Texte,
    -   Texte long : le composant de saisie sera une zone de texte,
    -   Entier : nombre entier positif ou négatif,
    -   Nombre à virgule,
    -   Booléen : case à cocher - Vrai ou Faux,
    -   Date : un composant permettant le choix de date depuis un
        calendrier est proposé,
    -   Choix : un composant en autocomplétion sur les valeurs
        existantes est proposé. L\'utilisateur a la possibilité de
        rentrer librement de nouvelles valeurs.
-   **Ordre** : Le numéro saisi permet d\'ordonner par défaut ce champ
    par rapport aux autres champs.
-   **Section** : La section correspond à un titre de section pour
    présenter ce champ sur la fiche et permettre des regroupements.
-   **Utiliser dans les index de recherche** : Si cette case est cochée,
    la recherche libre indexera le contenu de ce champ.
-   **Afficher** : Si cette case n\'est pas cochée, ce champ ne sera pas
    affiché sur la fiche.

Sauf si un champ personnalisé est uniquement destiné à des données
importées et à un affichage sur la fiche, un champ personnalisé sera
dans la plupart des cas intégré à un
`formulaire personnalisé <formulaire-personnalise>`{.interpreted-text
role="ref"}.

Formulaires personnalisés {#formulaire-personnalise}
-------------------------

La plupart des formulaires peuvent être personnalisés dans Ishtar,
notamment tous les formulaires de création/modification ainsi que les
formulaires de recherche. À ce jour, il n\'est pas encore possible
d\'ajouter de nouveaux formulaires.

Les formulaires personnalisés permettent deux choses : soustraire de
l\'affichage du formulaire les champs disponibles par défaut et ajouter
des champs JSON dans le formulaire. Chaque formulaire personnalisé peut
être mis à disposition pour tous ou seulement certains utilisateurs.

La configuration de ces champs se fait en administration via : *Ishtar -
Commun › Formulaires personnalisés*.

La création se fait en deux temps, d\'abord un paramétrage des champs de
base puis une définition des champs à exclure et des champs JSON à
ajouter.

Le paramétrage de base demande les champs suivants :

-   **Nom** : le nom correspondant au formulaire personnalisé. Ce nom ne
    sera visible qu\'en administration mais pour s\'y retrouver, il doit
    à la fois reprendre le nom du formulaire ainsi que le contexte pour
    lequel il a été défini. Par exemple : « Mobilier - 020 - Général -
    Tout utilisateur » ou « Mobilier - 030 - Conservation - Saisie
    terrain ».
-   **Formulaire** : le formulaire à personnaliser. Le nom utilisé
    permet d\'identifier assez simplement le formulaire correspondant,
    car il correspond dans l\'ordre (séparé par des tirets) au :
    -   type d\'objet concerné (par exemple : « Mobilier »),
    -   éventuellement, le numéro d\'ordre dans les formulaires
        successifs,
    -   nom du formulaire.
-   **À qui s\'applique ce formulaire**, cela peut être au choix :
    -   à tous les utilisateurs,
    -   à certains utilisateurs en particulier,
    -   à certains types d\'utilisateurs.

Une fois ce paramétrage de base enregistré, la configuration précise du
formulaire peut se faire :

-   **champs à exclure** : chaque champ de base présent dans le
    formulaire actuel peut être sélectionné dans la liste pour être
    écarté de la saisie.
-   **champs JSON** : tous les champs JSON préalablement paramétrés
    concernant l\'élément courant (mobilier, OA\...) peuvent être
    sélectionnés. La dénomination permet éventuellement de surcharger le
    nom par défaut du champ JSON. L\'ordre permet de placer le champ
    dans le formulaire. L\'aide permet éventuellement d\'ajouter un
    texte pour aider à la saisie.

::: {.warning}
::: {.title}
Warning
:::

Sur les formulaires de création, il est impératif de ne pas exclure des
champs obligatoires sans quoi la création devient impossible.
:::

::: {.note}
::: {.title}
Note
:::

En tant qu\'administrateur, en modifiant son profil depuis les pages
d\'administration (*Ishtar - Commun › Profils d\'utilisateurs*) et en
cochant « Afficher les numéros des champs », les numéros des champs
actuels des formulaires s\'affichent sur l\'interface, cela permet ainsi
de placer plus aisément les champs personnalisés.
:::

Gestion des permissions
-----------------------

### Gestion des comptes {#gestion-comptes}

Dans Ishtar, un compte doit être associé à une personne. Si la personne
n\'existe pas dans la base, il faut l\'ajouter via l\'interface
principale d\'Ishtar : *Annuaire › Personne › Ajout*.

Ensuite on crée un compte associé à cette personne, toujours via
l\'interface d\'Ishtar : *Administration › Compte › Ajout/modification*.
Dans les différents panneaux, il est demandé : l\'identifiant du compte,
le courriel rattaché, le mot de passe puis le type de profil.

Les types de profil définiront les types de permissions auxquelles aura
accès l\'utilisateur. Sur ces types de profil, des zones peuvent être
définies afin de permettre des règles de rattachement spécifique (cf.
`permissions dans Ishtar<permissions-ishtar>`{.interpreted-text
role="ref"}).

Cette interface de création de compte permet aussi de modifier le mot de
passe de comptes existants.

### Permissions dans Ishtar {#permissions-ishtar}

Les permissions dans Ishtar sont essentiellement gérées par « Type de
profil ». Chaque compte a un ou plusieurs « types de profil » associés à
son compte. Chaque type de profil donne accès à des actions et des accès
sur des types d\'objets.

La création/configuration d\'un type de profil se fait via : *Ishtar -
Commun › Types de profil* :

-   **dénomination** : ce champ doit être explicite, car il va être
    retrouvé au niveau de l\'interface utilisateur.
-   **identifiant textuel** : rempli selon les règles habituelles des
    identifiants textuels.
-   **groupes** : listes des groupes auxquels le profil est rattaché.

Chaque groupe correspond à un type de permission pour un élément précis
de la base de données :

-   droit de lecture ;
-   droit d\'ajout ;
-   droit de modification/suppression.

Chacun de ces droits est décliné en deux modalités :

-   droits sur tous les éléments ;
-   droit sur les éléments rattachés.

Un élément est dit « rattaché » à une personne en fonction de règles
précises spécifiées dans
l\'`annexe 1 - détail des permissions <annexe-1-permission-action>`{.interpreted-text
role="ref"}. La notion de rattachement permet de spécifier finement les
permissions pour des personnes qui sont directement associées à
l\'élément. Par exemple cela permet donner les droits de modification du
mobilier d\'une opération au responsable scientifique de cette
opération.

En pratique, globalement, les groupes de droits permettent d\'accéder à
certaines actions :

-   le droit de lecture permet une ouverture de la fiche correspondant à
    l\'élément ;
-   le droit d\'ajout permet d\'accéder aux actions d\'ajout d\'un
    nouvel élément ;
-   le droit de modification/suppression permet d\'accéder aux actions
    concernant la modification/suppression des éléments.

Dans le détail, il y a certaines données, actions qui sont accessibles
en fonction d\'appartenance à des groupes en particulier. Tout cela est
détaillé dans
l\'`annexe 1 - détail des permissions <annexe-1-permission-action>`{.interpreted-text
role="ref"}.

::: {.note}
::: {.title}
Note
:::

La page *Ishtar - Commun › Résumés des types de profil* permet
d\'accéder à un tableau qui reprend et rend explicites toutes les
permissions associées aux types de profil.
:::

### Permissions dans les pages d\'administration

Les permissions des pages d\'administration sont gérées différemment.
Elles utilisent le système de permission du framework Django, framework
(cadre de développement logiciel) utilisé par Ishtar. Une fois le compte
créé, les droits se spécifient dans les pages d\'administration :
*Authentification et autorisation › Utilisateurs*.

L\'ouverture de l\'accès aux pages d\'administration se fait en cochant
le « Statut équipe ». Si l\'on souhaite n\'ouvrir l\'accès qu\'à
certaines pages spécifiques, on ajoute les « Permissions de
l\'utilisateur » correspondant aux tables que l\'on souhaite ouvrir, si
l\'on souhaite ouvrir l\'accès à toutes les tables, il suffit de cocher
le « Statut super-utilisateur ».

Patrons de documents
--------------------

### Principes de base

Ishtar propose une génération automatisée de document. Depuis un patron
au format LibreOffice (ODT), les données relatives à un élément (acte
administratif, mobilier\...) remplacent les variables du patron pour
obtenir le document désiré.

On crée le patron au format ODT avec un contenu adapté, puis depuis
l\'interface d\'administration, sous l\'entrée *Ishtar - Commun ›
Patrons de document › Document de référence*, on créé un patron de
document avec ce fichier ODT associé au type d\'élément pour lequel il
est destiné.

Le document peut alors être généré depuis n\'importe quelle fiche de
l\'élément concerné (en haut à droite sous « Documents »).

### Un premier patron

Pour créer un patron, la première étape est de récupérer toutes les
variables disponibles pour l\'élément à partir duquel on veut générer un
document. Il existe pour cela un [document de
référence](https://gitlab.com/iggdrasil/ishtar/raw/main/archaeological_operations/tests/document_reference.odt)
que l\'on peut attacher à l\'élément pour lequel on souhaite éditer un
nouveau document.

::: {.note}
::: {.title}
Note
:::

En cas d\'indisponibilité du lien pour ce document, ce document est très
simple et peut être recréé facilement, il suffit d\'insérer :
`{{VALUES}}` dans un document ODT vide et de sauvegarder le document.
:::

Depuis *Ishtar - Commun › Patrons de document › Document de référence*,
on ajoute un nouveau patron de document : « Document de référence »
auquel on associe le document de référence téléchargé et le type
d\'élément pour lequel on souhaite créer un patron de document.

Ensuite, il faut récupérer un document de référence généré depuis la
fiche d\'un élément contenant tous les champs que l\'on souhaite
exploiter.

On ouvre ce document sous LibreOffice. Le document produit contient une
liste de clé avec la valeur associée concernant l\'élément que l\'on a
choisi.

Les différentes clés vont permettre de constituer un patron répondant à
ce qui est attendu. Pour cela reprendre un exemple du document que l\'on
souhaite générer (toujours au format ODT) et remplacer chaque occurence
d\'une valeur par la clé en reprenant la
`syntaxe Jinja <formules-syntaxe-jinja>`{.interpreted-text role="ref"}
(Jinja est le nom de la bibliothèque utilisée). Une fois quelques
substitutions faites, on peut l\'enregistrer et créer le patron dans
l\'interface d\'administration Ishtar. Ce premier patron est alors
disponible depuis la fiche des éléments.

Configuration du profil d\'instance Ishtar {#configuration-instance-ishtar}
------------------------------------------

*En cours de rédaction\...*

### Identifiants et index personnalisés

Pour chaque type d\'élément principal, il est possible de configurer le
profil Ishtar pour personnaliser :

-   l\'identifiant externe : c\'est un identifiant textuel unique dans
    la base qui permet de faire des rapprochements de manière non
    ambiguë. Il est souvent utilisé pour les imports. Par exemple, un
    identifiant externe pour les unités d\'enregistrement peut être
    \"code patriarche de l\'opération-identifiant de l\'unité
    d\'enregistrement\" ou alors \"code patriarche de
    l\'opération-section parcelle-numéro parcelle-identifiant de
    l\'unité d\'enregistrement\". Des identifiants externes sont
    paramétrés par défaut pour chaque type d\'élément principale. Note :
    l\'identifiant externe de l\'opération est toujours le code
    patriarche et n\'est pas paramétrable.
-   l\'identifiant complet (optionnel) : cet identifiant est un
    identifiant de gestion paramétrable. Cet identifiant peut par
    exemple se distinguer de l\'identifiant externe pour incorporer des
    codes matières.
-   clés pour index personnalisé : un index personnalisé peut être
    défini en fonction d\'une ou plusieurs clés reprenant les champs.
    Par exemple une clé opération peut être utilisée pour générer un
    index numérotant de 1 à n le mobilier sur une opération.

Pour définir identifiant externes et identifiant complet, on utilise des
formules. Deux types de syntaxes sont utilisées : une
`syntaxe simple <formules-syntaxe-simple>`{.interpreted-text role="ref"}
et une `syntaxe Jinja <formules-syntaxe-jinja>`{.interpreted-text
role="ref"} (nom de la bibliothèque utilisée). Ces deux syntaxes
utilisent des variables relatives à l\'élément. L\'utilisation de ces
variables est explicitée dans
l\'`annexe technique 3 - variables <annexe-technique-3-variables>`{.interpreted-text
role="ref"}.

Formules
--------

### Syntaxe simple {#formules-syntaxe-simple}

Cette syntaxe permet d\'utiliser directement les variables en utilisant
la notation accolade simple `{}`. Par exemple : :

    OA-{code_patriarche}

Cette notation se traduira ainsi par des rendus comme :
[OA-061234]{.title-ref} ou [OA-44789]{.title-ref}.

### Syntaxe Jinja {#formules-syntaxe-jinja}

Cette syntaxe permet de faire de faire des substitutions de manière plus
fine qu\'avec la syntaxe simple. Cette syntaxe est utilisée
systématiquement pour les patrons de document, un sous-ensemble de cette
syntaxe (variables et structures conditionnelles) peut-être utilisée
optionnellement pour les identifiants personnalisés.

#### Variables

L\'accès aux [variables \<annexe-technique-3-variables\>]{.title-ref} se
fait par la notation double accolade `{{ }}`. Ainsi par exemple, pour
accéder aux variables [nom\_de\_ma\_clef\_1]{.title-ref} et
[nom\_de\_ma\_clef\_2]{.title-ref} : :

    Je, soussigné, {{nom_de_ma_clef_1}}, vous accorde un prêt de {{nom_ma_clef_2}}.

#### Conditions

Des structures conditionnelles peuvent être mises en place. Cela permet
notamment de tester si une valeur a été renseignée et de permettre de
contextualiser l\'affichage en fonction de cela. Exemple : :

    Ce traitement sous
    {% if responsable %}la responsabilité de {{responsable}}
    {% else %}une responsabilité à définir
    {% endif %} se tiendra...

Les structures conditionnelles se structurent autour des mots clés `if`,
`else` et `endif`. On utilise `{%` et `%}` autour de ces mots clés. La
section `else` est facultative.

#### Parcours de liste

Certaines clés peuvent parfois renvoyer à des listes d\'éléments, chacun
ayant des attributs. On peut alors parcourir cette liste d\'élément de
cette manière : :

    {% for element in liste_elements %}
       {{element.nom}} - {{element.prenom}}
    {% endfor %}

Cela se structure autour des mots clés `for`, `in` et `endfor`. Au lieu
de doubles accolades, `{%` et `%}` encadrent ces mots clés.

Journalisation RGPD
-------------------

Conformément aux [recommandations de la
CNIL](https://www.cnil.fr/fr/la-cnil-publie-une-recommandation-relative-aux-mesures-de-journalisation),
une journalisation des actions relatives aux traitements, au sens RGPD,
de données personnelles est possible dans Ishtar.

La journalisation consiste à assurer la traçabilité des actions opérées
sur des données personnelles. La traçabilité est assurée en enregistrant
:

-   l\'identifiant utilisateur qui réalise le traitement,
-   la date et l'heure de l'accès,
-   l\'adresse IP de connexion,
-   l\'information si cette IP est « routable » (i.e l\'IP est routable
    si la connexion vient d\'Internet sinon la connexion vient du réseau
    interne au serveur),
-   le type de traitement,
-   des liens vers les personnes concernées par le traitement.

Si une personne est supprimée de la base de données, nom et prénom de
cette personne sont sauvegardées dans une table intermédiaire le temps
que des données de journalisation concernant cette personne existent.

Les types de traitements identifiés sont :

-   consultation de l\'annuaire (listing de personnes),
-   export de l\'annuaire,
-   consultation de la notice personne,
-   export de la notice personne,
-   création de personne (formulaire ou import),
-   modification de personne (formulaire, import ou fusion),
-   suppression de fiche personne.

::: {.note}
::: {.title}
Note
:::

Cette journalisation n\'est destinée qu\'à des seules fins
d'investigation en cas d'incident, d'intrusion dans les systèmes
informatiques ou de détournement d'usage des traitements de données par
les personnes habilitées. Tout autre usage n\'est a priori pas légitime
et relève d\'une infraction au règlement RGPD.
:::

Cette journalisation est désactivée par défaut. Elle peut être activée
par l\'administrateur serveur (paramètre [GDPR\_LOGGING]{.title-ref} à
[True]{.title-ref} dans le fichier [local\_settings.py]{.title-ref}).

La durée de conservation des données de journalisation est fixée à 6
mois (durée minimale préconisée par la CNIL). Cette durée peut être
changée par l\'administrateur serveur (paramètre
[GDPR\_RETENTION\_PERIOD]{.title-ref} dans le fichier
[local\_settings.py]{.title-ref}) mais il convient de rester dans le
cadre légal (sauf exception la durée de conservation ne peut excéder un
an). Au-delà de la durée paramétrée les données sont supprimées
automatiquement (un script vérifie quotidiennement la péremption des
données).

Ces données sont accessibles en consultation uniquement (la suppression
et la modification ne sont pas possible) via l\'interface
d\'administrateur aux utilisateurs : statut « super utilisateur » ou
dans le groupe « Administrateur RGPD » (et disposant du statut équipe :
cf. `gestion des comptes <gestion-comptes>`{.interpreted-text
role="ref"} ). Un export de ces données en CSV est possible pour
analyse. Le cas échéant, l\'administrateur RGPD doit prendre des mesures
organisationnelles afin de garantir une détruction de cet export une
fois que celui-ci a été exploité.

::: {.note}
::: {.title}
Note
:::

Si des utilisateurs disposent d\'un statut « super utilisateur » mais ne
sont pas administrateur RGPD, il est nécessaire de leur retirer ce
statut pour leur donner le groupe « administrateur technique ».
:::

Lors du contrôle de ces données, une attention particulière sera portée
sur les lignes ne disposant pas de l\'information de l\'utilisateur
et/ou de l\'adresse IP associée et/ou si l\'adresse IP est non routable.
Il peut s\'agir d\'entrées relatives à, dans le cas le plus courant, un
script de maintenance, à un dysfonctionnement ou alors, dans le pire des
cas, d\'une compromission de la base de données. Remontez l\'information
au plus vite au référent administration système.