# Configuration Moodle pour SAM

[← Exports](05-exports.md) | [Accueil](README.md)

---

## Prérequis

- Moodle **3.9+** (recommandé : 4.x)
- Accès **administrateur** au site Moodle
- Les **Web Services** activés sur Moodle

---

## Étape 1 : Activer les Web Services

1. Connectez-vous en tant qu'**administrateur** sur Moodle
2. Allez dans **Administration du site** → **Fonctions avancées**
3. Cochez **Activer les services web**
4. Cliquez sur **Enregistrer**

---

## Étape 2 : Activer le protocole REST

1. Allez dans **Administration du site** → **Plugins** → **Services web** → **Gérer les protocoles**
2. Activez **REST protocol** (cliquez sur l'icône œil pour l'activer)

---

## Étape 3 : Créer un rôle dédié (recommandé)

Pour des raisons de sécurité, créez un rôle spécifique pour l'API SAM.

1. Allez dans **Administration du site** → **Utilisateurs** → **Permissions** → **Définir les rôles**
2. Cliquez sur **Ajouter un nouveau rôle**
3. Configurez :
   - **Nom court** : `sam_api`
   - **Nom complet** : `SAM API Service`
   - **Type de contexte** : Système
4. Accordez les **capacités** suivantes :

### Capacités requises

| Capacité | Description |
|----------|-------------|
| `moodle/site:accessallgroups` | Accès à tous les groupes |
| `moodle/user:viewdetails` | Voir les détails des utilisateurs |
| `moodle/user:viewhiddendetails` | Voir les détails masqués |
| `moodle/user:create` | Créer des utilisateurs |
| `moodle/user:update` | Modifier des utilisateurs |
| `moodle/cohort:view` | Voir les cohortes |
| `moodle/cohort:manage` | Gérer les cohortes |
| `moodle/course:view` | Voir les cours |
| `moodle/course:viewhiddencourses` | Voir les cours masqués |
| `moodle/course:viewparticipants` | Voir les participants d'un cours |
| `moodle/completion:view` | Voir les données de complétion |
| `mod/quiz:viewreports` | Voir les rapports de quiz |
| `mod/quiz:grade` | Voir les notes des quiz |
| `webservice/rest:use` | Utiliser le protocole REST |

5. Cliquez sur **Créer ce rôle**

---

## Étape 4 : Créer un utilisateur de service

1. Allez dans **Administration du site** → **Utilisateurs** → **Comptes** → **Ajouter un utilisateur**
2. Créez un utilisateur dédié :
   - **Nom d'utilisateur** : `sam_service`
   - **Mot de passe** : (générez un mot de passe fort)
   - **Prénom** : `SAM`
   - **Nom** : `Service API`
   - **Email** : `sam-api@votre-domaine.com`
3. Cliquez sur **Créer utilisateur**

### Attribuer le rôle à l'utilisateur

1. Allez dans **Administration du site** → **Utilisateurs** → **Permissions** → **Attribution des rôles système**
2. Sélectionnez le rôle **SAM API Service**
3. Ajoutez l'utilisateur `sam_service`

---

## Étape 5 : Créer le service externe

1. Allez dans **Administration du site** → **Plugins** → **Services web** → **Services externes**
2. Cliquez sur **Ajouter**
3. Configurez :
   - **Nom** : `SAM - Suivi des Apprenants Moodle`
   - **Nom court** : `sam_api`
   - **Activé** : Oui
   - **Utilisateurs autorisés** : Seulement les utilisateurs autorisés
4. Cliquez sur **Ajouter un service**

---

## Étape 6 : Ajouter les fonctions au service

1. Cliquez sur **Fonctions** à côté du service créé
2. Ajoutez les **18 fonctions** suivantes :

### Fonctions système (1)

| Fonction | Description |
|----------|-------------|
| `core_webservice_get_site_info` | Vérifier la connexion et infos du site |

### Fonctions utilisateurs (3)

| Fonction | Description |
|----------|-------------|
| `core_user_get_users` | Lister/rechercher les utilisateurs |
| `core_user_create_users` | Créer des utilisateurs |
| `core_user_update_users` | Modifier des utilisateurs |

### Fonctions cohortes (6)

| Fonction | Description |
|----------|-------------|
| `core_cohort_get_cohorts` | Lister les cohortes |
| `core_cohort_create_cohorts` | Créer des cohortes |
| `core_cohort_update_cohorts` | Modifier des cohortes |
| `core_cohort_delete_cohorts` | Supprimer des cohortes |
| `core_cohort_add_cohort_members` | Ajouter des membres |
| `core_cohort_delete_cohort_members` | Retirer des membres |

### Fonctions cours (2)

| Fonction | Description |
|----------|-------------|
| `core_course_get_courses` | Lister les cours |
| `core_course_get_contents` | Sections et activités d'un cours |

### Fonctions inscriptions et progression (4)

| Fonction | Description |
|----------|-------------|
| `core_enrol_get_enrolled_users` | Utilisateurs inscrits à un cours |
| `core_enrol_get_users_courses` | Cours auxquels un utilisateur est inscrit |
| `core_completion_get_activities_completion_status` | Progression des activités |
| `local_sam_get_cohort_enrolments` | **[Plugin requis]** Associations cohorte-cours |

### Fonctions quiz (3)

| Fonction | Description |
|----------|-------------|
| `mod_quiz_get_quizzes_by_courses` | Lister les quiz d'un ou plusieurs cours |
| `mod_quiz_get_user_attempts` | Tentatives d'un utilisateur sur un quiz |
| `mod_quiz_get_attempt_review` | Détail d'une tentative (questions, réponses) |

---

## Étape 6b : Installer le plugin local_sam (requis)

Le plugin `local_sam` permet à SAM de récupérer les associations cohorte-cours de manière fiable.

### Pourquoi ce plugin est nécessaire ?

L'API standard Moodle `core_enrol_get_course_enrolment_methods` a des limitations de visibilité et retourne souvent un tableau vide. Le plugin `local_sam` interroge directement la table `mdl_enrol` pour obtenir les associations réelles.

### Installation

1. **Téléchargez** le plugin depuis le dossier `plugins/local_sam` de Bubul
2. **Copiez** le dossier vers votre Moodle : `/path/to/moodle/local/sam`
3. **Visitez** Moodle en tant qu'admin → La notification d'installation apparaît
4. **Cliquez** sur **Mettre à jour la base de données**

### Structure du plugin

```
local/sam/
├── version.php                          # Version 1.0.0
├── db/services.php                      # Déclaration webservice
├── classes/external/get_cohort_enrolments.php
└── lang/en/local_sam.php
```

### Ajouter la fonction au service

1. Allez dans **Administration** → **Plugins** → **Services web** → **Services externes**
2. Cliquez sur **Fonctions** à côté de votre service SAM
3. Cliquez sur **Ajouter des fonctions**
4. Ajoutez : `local_sam_get_cohort_enrolments`

### Ce que retourne la fonction

```json
[
  {
    "id": 42,
    "courseid": 16,
    "course_shortname": "1_2025_7311",
    "course_fullname": "Formation complète",
    "cohortid": 8,
    "cohort_name": "Cohorte - 1",
    "cohort_idnumber": "",
    "status": 0,
    "name": "Synchronisation des cohortes"
  }
]
```

| Champ | Description |
|-------|-------------|
| `courseid` | ID Moodle du cours |
| `cohortid` | ID Moodle de la cohorte |
| `status` | 0 = active, 1 = désactivée |

### Vérification

```bash
curl -X GET "https://votre-moodle.com/webservice/rest/server.php?\
wstoken=VOTRE_TOKEN&\
wsfunction=local_sam_get_cohort_enrolments&\
courseid=0&\
moodlewsrestformat=json"
```

**Paramètre `courseid`** :
- `0` = toutes les associations
- `16` = associations pour le cours ID 16 uniquement

---

## Étape 7 : Autoriser l'utilisateur sur le service

1. Retournez à **Services externes**
2. Cliquez sur **Utilisateurs autorisés** à côté du service SAM
3. Ajoutez l'utilisateur `sam_service`

---

## Étape 8 : Générer le token API

1. Allez dans **Administration du site** → **Plugins** → **Services web** → **Gérer les jetons**
2. Cliquez sur **Créer un jeton**
3. Configurez :
   - **Utilisateur** : `sam_service`
   - **Service** : `SAM - Suivi des Apprenants Moodle`
   - **Restrictions IP** : (optionnel, pour plus de sécurité)
   - **Date d'expiration** : (optionnel)
4. Cliquez sur **Enregistrer**
5. **Copiez le token généré** (il ne sera plus visible après)

---

## Étape 9 : Configurer Bubul

1. Connectez-vous à **Bubul**
2. Allez dans **Paramètres** → **Entreprise** (ou demandez à un admin)
3. Dans la section **Configuration Moodle** :
   - **URL Moodle** : `https://votre-moodle.com`
   - **Token API** : collez le token généré à l'étape 8
4. Cliquez sur **Enregistrer**
5. Cliquez sur **Tester la connexion** pour vérifier

---

## Vérification

### Test depuis Bubul

1. Allez dans **SAM** → **Stagiaires**
2. Cliquez sur **Rafraîchir**
3. Les utilisateurs Moodle devraient apparaître

### Test en ligne de commande

```bash
# Tester la connexion
curl -X GET "https://votre-moodle.com/webservice/rest/server.php?wstoken=VOTRE_TOKEN&wsfunction=core_webservice_get_site_info&moodlewsrestformat=json"
```

**Réponse attendue :**

```json
{
  "sitename": "Votre LMS",
  "username": "sam_service",
  "userid": 123,
  ...
}
```

---

## Dépannage

### Erreur "Accès refusé"

- Vérifiez que l'utilisateur `sam_service` a le rôle `sam_api` au niveau **système**
- Vérifiez que l'utilisateur est autorisé sur le service externe

### Erreur "Fonction non autorisée"

- Vérifiez que toutes les fonctions sont bien ajoutées au service
- Certaines fonctions nécessitent des plugins additionnels

### Erreur "Token invalide"

- Le token a peut-être expiré
- Régénérez un nouveau token

### Les cohortes ne s'affichent pas

- Vérifiez que l'utilisateur a la capacité `moodle/cohort:view` au niveau système
- Les cohortes doivent être de type "Système" (pas au niveau cours)

### La progression ne s'affiche pas

- Le suivi de complétion doit être activé sur le cours
- Les activités doivent avoir le suivi de complétion configuré

---

## Sécurité

### Bonnes pratiques

1. **Restreignez les IP** : Limitez l'accès au token depuis l'IP de votre serveur Bubul
2. **Utilisateur dédié** : N'utilisez jamais un compte admin pour l'API
3. **Rotation des tokens** : Changez le token périodiquement
4. **Audit** : Surveillez les logs Moodle pour détecter les anomalies

### Logs Moodle

Les appels API sont enregistrés dans :
- **Administration du site** → **Rapports** → **Journaux**
- Filtrez par utilisateur `sam_service`

---

## Résumé des étapes

| # | Action | Emplacement |
|---|--------|-------------|
| 1 | Activer les Web Services | Fonctions avancées |
| 2 | Activer REST | Services web → Protocoles |
| 3 | Créer le rôle `sam_api` | Définir les rôles |
| 4 | Créer l'utilisateur `sam_service` | Ajouter un utilisateur |
| 5 | Attribuer le rôle système | Attribution des rôles |
| 6 | Créer le service externe | Services externes |
| 6b | **Installer le plugin `local_sam`** | `/moodle/local/sam` |
| 7 | Ajouter les **19 fonctions** | Fonctions du service |
| 8 | Autoriser l'utilisateur | Utilisateurs autorisés |
| 9 | Générer le token | Gérer les jetons |
| 10 | Configurer dans Bubul | Paramètres entreprise |

---

## Liste complète des fonctions (copier-coller)

### Fonctions Moodle standard (18)

```
core_webservice_get_site_info
core_user_get_users
core_user_create_users
core_user_update_users
core_cohort_get_cohorts
core_cohort_get_cohort_members
core_cohort_create_cohorts
core_cohort_update_cohorts
core_cohort_delete_cohorts
core_cohort_add_cohort_members
core_cohort_delete_cohort_members
core_course_get_courses
core_course_get_contents
core_enrol_get_enrolled_users
core_enrol_get_users_courses
core_completion_get_activities_completion_status
mod_quiz_get_quizzes_by_courses
mod_quiz_get_user_attempts
mod_quiz_get_attempt_review
```

### Fonction plugin local_sam (1) - **Requis**

```
local_sam_get_cohort_enrolments
```

> **Note :** Cette fonction nécessite l'installation du plugin `local_sam` (voir Étape 6b).

---

**Auteur :** Andrew MAHE
**Dernière mise à jour :** 2026-02-14