L'application tags permet d'associer des étiquettes colorées aux documents pour les classer, filtrer et retrouver rapidement. Un tag est un libellé + une couleur RGB, attaché à un ou plusieurs documents via une relation many-to-many.
Emplacement : mayan/apps/tags/
| Champ | Type | Description |
|---|---|---|
label |
CharField(128), unique | Nom du tag — doit être unique dans tout le système |
color |
CharField(7) | Couleur au format CSS hexadécimal #RRGGBB |
documents |
ManyToManyField → Document | Documents portant ce tag |
La relation entre tags et documents est une ManyToMany directe (sans modèle intermédiaire). Un tag peut être attaché à autant de documents que souhaité, et un document peut porter autant de tags que nécessaire.
label est unique dans tout le système — deux tags ne peuvent pas avoir le même nomcolor accepte uniquement le format #RRGGBB (7 caractères, ex: #FF5733, #3498DB)tag.attach_to(document, user) # Attache le tag au document (+ événement)
tag.remove_from(document, user) # Retire le tag du document (+ événement)
tag.get_document_count(user) # Nombre de documents (filtré par ACL)
tag.get_documents(user, permission) # QuerySet des documents (filtré par ACL)
tag.get_preview_widget() # Widget HTML de prévisualisation colorée
Création (tag_create)
→ event_tag_created
Modification label ou couleur (tag_edit)
→ event_tag_edited
→ Réindexation de tous les documents du tag (si index utilise tags__label)
Attachement à un document (tags/attach)
→ event_tag_attached (cible: document, action_object: tag)
Retrait d'un document (tags/remove)
→ event_tag_removed (cible: document, action_object: tag)
Suppression du tag (tag_delete)
→ event_tag_removed pour chaque document associé (via handler pre_delete)
→ Le tag est retiré proprement de tous ses documents avant suppression
| Permission | Description | Portée ACL |
|---|---|---|
permission_tag_view |
Voir les tags | Tag, Document |
permission_tag_create |
Créer de nouveaux tags | Vue (global) |
permission_tag_edit |
Modifier label et couleur | Tag |
permission_tag_delete |
Supprimer des tags | Tag |
permission_tag_attach |
Attacher des tags à des documents | Tag, Document |
permission_tag_remove |
Retirer des tags de documents | Tag, Document |
Les tags ont leur propre système ACL, indépendant des documents. Pour attacher un tag à un document, l'utilisateur a besoin de permission_tag_attach sur le tag (pas seulement sur le document).
| Rôle | Permissions recommandées |
|---|---|
| Lecteur | permission_tag_view |
| Collaborateur | permission_tag_view, permission_tag_attach, permission_tag_remove |
| Gestionnaire | Toutes les permissions tags |
| Administrateur | Toutes les permissions tags + gestion ACL |
| Action | URL |
|---|---|
| Liste de tous les tags | /tags/ |
| Créer un tag | /tags/create/ |
| Modifier un tag | /tags/{id}/edit/ |
| Supprimer un tag | /tags/{id}/delete/ |
| Documents portant ce tag | /tags/{id}/documents/ |
| Supprimer plusieurs tags | /tags/multiple/delete/ |
| Action | URL |
|---|---|
| Voir les tags d'un document | /documents/{id}/tags/ |
| Attacher un ou plusieurs tags | /documents/{id}/tags/multiple/attach/ |
| Retirer un ou plusieurs tags | /documents/{id}/tags/multiple/remove/ |
| Attacher à plusieurs documents | /documents/multiple/tags/multiple/attach/ |
| Retirer de plusieurs documents | /documents/multiple/tags/multiple/remove/ |
Les formulaires d'attachement et de retrait utilisent Select2 avec affichage des couleurs pour faciliter la sélection.
Si l'utilisateur a permission_tag_attach et qu'il existe des tags, une étape optionnelle "Select tags" s'affiche dans l'assistant d'upload. Les tags sélectionnés sont attachés automatiquement au document après son traitement.
L'app tags fournit deux actions utilisables dans les workflows :
AttachTagAction)Dans un état de workflow, ajouter une action de type "Attach tag" et sélectionner un ou plusieurs tags. Quand la transition vers cet état se produit, les tags sélectionnés sont automatiquement attachés au document.
Configuration :
Attach tagCas d'usage : Attacher automatiquement le tag #Approuvé quand un document passe à l'état "Approuvé" dans un workflow de validation.
RemoveTagAction)Identique mais retire les tags sélectionnés du document lors de la transition.
Cas d'usage : Retirer le tag #En attente quand le document quitte l'état "En attente".
Dans la recherche avancée (/search/advanced/documents.document/) :
| Champ | Description |
|---|---|
tags__label |
Libellé du tag |
tags__color |
Couleur du tag (ex: #FF5733) |
tags__id |
ID base de données du tag |
# Trouver tous les documents avec le tag "Urgent"
GET /api/v4/search/advanced/documents.document/?tags__label=Urgent
# Trouver tous les documents avec un tag rouge
GET /api/v4/search/advanced/documents.document/?tags__color=%23FF0000
Les tags ont leur propre modèle de recherche (tags.tag) :
| Champ indexé | Description |
|---|---|
label |
Libellé du tag |
color |
Couleur |
documents__label |
Libellé des documents associés |
documents__document_type__label |
Type des documents associés |
documents__description |
Description des documents associés |
documents__uuid |
UUID des documents associés |
GET /api/v4/search/tags.tag/?q=urgent
Les tags sont accessibles dans les expressions de nœuds d'index :
{% for tag in document.tags.all %}{{ tag.label }} {% endfor %}
Base URL : /api/v4/
| Méthode | Endpoint | Permission | Description |
|---|---|---|---|
GET |
/tags/ |
permission_tag_view |
Lister tous les tags |
POST |
/tags/ |
permission_tag_create |
Créer un tag |
GET |
/tags/{id}/ |
permission_tag_view |
Détail d'un tag |
PATCH |
/tags/{id}/ |
permission_tag_edit |
Modifier label/couleur |
PUT |
/tags/{id}/ |
permission_tag_edit |
Remplacer label/couleur |
DELETE |
/tags/{id}/ |
permission_tag_delete |
Supprimer un tag |
GET |
/tags/{id}/documents/ |
permission_tag_view + permission_document_view |
Documents portant ce tag |
GET |
/documents/{id}/tags/ |
permission_tag_view |
Tags d'un document |
POST |
/documents/{id}/tags/attach/ |
permission_tag_attach |
Attacher un tag |
POST |
/documents/{id}/tags/remove/ |
permission_tag_remove |
Retirer un tag |
{
"id": 5,
"label": "Urgent",
"color": "#FF0000",
"url": "https://mayan.example.com/api/v4/tags/5/",
"documents_url": "https://mayan.example.com/api/v4/tags/5/documents/"
}
TOKEN="votre_token"
BASE="https://mayan.example.com/api/v4"
# Lister tous les tags
curl -H "Authorization: Token $TOKEN" $BASE/tags/
# Créer un tag
curl -X POST $BASE/tags/ \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "Urgent", "color": "#FF0000"}'
# Modifier la couleur d'un tag
curl -X PATCH $BASE/tags/5/ \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{"color": "#E74C3C"}'
# Tags d'un document
curl -H "Authorization: Token $TOKEN" $BASE/documents/42/tags/
# Attacher un tag à un document
curl -X POST $BASE/documents/42/tags/attach/ \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{"tag": 5}'
# Retirer un tag d'un document
curl -X POST $BASE/documents/42/tags/remove/ \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{"tag": 5}'
# Documents portant un tag
curl -H "Authorization: Token $TOKEN" $BASE/tags/5/documents/
# Supprimer un tag
curl -X DELETE $BASE/tags/5/ \
-H "Authorization: Token $TOKEN"
import requests
BASE = "https://mayan.example.com/api/v4"
HEADERS = {"Authorization": "Token votre_token"}
# Créer un tag
tag = requests.post(f"{BASE}/tags/", headers=HEADERS, json={
"label": "À réviser",
"color": "#F39C12"
}).json()
tag_id = tag["id"]
# Attacher à plusieurs documents
for doc_id in [42, 43, 44]:
requests.post(f"{BASE}/documents/{doc_id}/tags/attach/",
headers=HEADERS, json={"tag": tag_id})
# Lister tous les documents d'un tag
docs = requests.get(f"{BASE}/tags/{tag_id}/documents/", headers=HEADERS).json()
for doc in docs["results"]:
print(doc["id"], doc["label"])
# Retirer un tag de tous ses documents
all_docs = docs["results"]
for doc in all_docs:
requests.post(f"{BASE}/documents/{doc['id']}/tags/remove/",
headers=HEADERS, json={"tag": tag_id})
Dans la liste des documents, cocher plusieurs documents puis utiliser le menu Actions → Attach tags.
Même principe avec Actions → Remove tags.
Dans la liste des tags, cocher plusieurs tags puis Actions → Delete.
Lors de la suppression d'un tag, Mayan retire proprement ce tag de tous ses documents avant suppression, en déclenchant un événement
event_tag_removedpour chaque retrait.
Deux tags ne peuvent pas avoir le même libellé. Si tu tentes de créer un tag avec un label existant, l'API retourne une erreur 400 Bad Request avec le détail du champ.
Quand un tag est modifié (label ou couleur), Mayan réindexe automatiquement tous les documents associés à ce tag dans le moteur de recherche. Ce comportement est géré par le handler handler_index_document via le signal post_save de Tag.
La suppression d'un tag déclenche un handler pre_delete qui retire le tag de chaque document associé avant la suppression effective. Cela garantit que les événements de retrait sont bien enregistrés dans le journal d'activité.
Un utilisateur peut voir un document sans voir ses tags, et vice-versa. Les permissions tags sont gérées indépendamment des permissions document. Pour attacher un tag, l'utilisateur doit avoir permission_tag_attach sur le tag spécifique, pas seulement sur le document.
| Besoin | Action |
|---|---|
| Créer un tag | Administration → Tags → Create |
| Couleur d'un tag | Format #RRGGBB (ex: #3498DB) |
| Attacher à un document | Vue document → Tags → Attach tags |
| Attacher via workflow | Action "Attach tag" dans un état de workflow |
| Chercher par tag | Recherche avancée → champ tags__label |
| Voir tous les documents d'un tag | /tags/{id}/documents/ |
| Retirer de tous les documents | Supprimer le tag (retrait automatique) |
| Opérations en lot | Sélection multiple dans la liste → Actions |