Tool Sync : API de Web Services

Service de pilotage à distance du composant

Les Web services permettent une interaction de briques logicielles externes avec le composant.

tool_sync_set_config( service, confkey, confvalue )

Synopsys : Cette fonction permet de modifier à distance n'importe quel paramètre de configuration de l'outil de synchronisation.

service : Identifiant du service de synchronisation (courses, users, enrols, cohorts)

confkey : Clef de configuration

confvalue : Valeur de configuration

Tables de configuration de service

Service : courses

Clef	Valeurs
fileuploadlocation	nom de fichier
filedeletelocation	nom de fichier
filedeleteidentifier	id, shortname, idnumber
fileexistlocation	nom de fichier
existfileidentifier	id, shortname, idnumber
fileresetlocation	nom de fichier
fileresetidentifier	id, shortname, idnumber
forceupdate	0 ou 1

Service : users

Clef	Valeurs
filelocation	nom de fichier
primaryidentity	id, idnumber, username, email

Service : enrols

Clef	Valeurs
filelocation	nom de fichier
courseidentifier	id, idnumber, shortname
useridentifier	id, idnumber, username, email

Service : cohorts

Clef	Valeurs
filelocation	nom de fichier
useridentifier	id, idnumber, username, email
cohortidentifier	id, idnumber
autocreate	0 ou 1
syncdelete	0 ou 1

tool_sync_commit_file( draftitemid )

Synopsis : Cette fonction permet de déplacer un fichier préalablement téléchargé en zone draft vers son emplacement final dans le système de fichiers de l'outil de synchronisation.

draftitemid : L'identifiant de zone draft récupéré lors du dernier appel au service web de téléchargement.

Exemple de mise en oeuvre en PHP :

$path = '<location_of_the_file>';
$params = array('token' => '<valid_token>',
'itemid' => 0,
'filearea' => 'draft');
$uploadurl = '<moodle_url>/webservice/upload.php';
$ch = curl_init($uploadurl);
$curlfile = new CURLFile($path, 'x-application/zip', basename($path));
$params['resourcefile'] = $curlfile;
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
echo "Firing CUrl $uploadurl ... \n";
if (!$result = curl_exec($ch)) {
echo "CURL Error : ".curl_error($ch)."\n";
return;
}
$result = json_decode($result);
$filerec = array_pop($result);
// Now commit the file.
$params = array('wstoken' => '<valid_token>',
'wsfunction' => 'tool_sync_commit_file',
'moodlewsrestformat' => 'json',
'draftitemid' => $filerec->itemid);
$commiturl = '<moodle_url>/webservice/rest/server.php';
$this->send($commiturl, $params);

tool_synch_process( service, action )

Synopsis : Déclenche le traitement de synchronisation approprié sur la base de la configuration actuelle de l'outil.

service : Indicatif du service de synchronisation ( 'courses', 'enrols', 'users' ou 'cohorts')

action : Indicatif de l'opération (valable pour les cours : 'create', 'delete', 'reset', sinon 'sync' pour tous les autres services).

tool_sync_deploy_course( categorysourceid, categoryid, templatesourceid, templateid, shortname, fullname, idnumber, replacements)

Synopsis : Permet de déployer un cours sur la base d'une archive de cours existante ou d'une sauvegarde disponible dans le système de fichiers.

categorysourceid : Source de l'odentifiant de catégorie (peut être 'id' ou 'idnumber')

categoryid : Identifiant de catégorie destinataire

templateidsource : Source de l'identifiant de cours modèle (peut être 'id', 'shortname', 'idnumber')

templateid : Identifiant du cours modèle. Si cet identifiant n'est pas assimilable à un identifiant, mais plutot à un chemin dans le système de fichiers, alors l'archive correspondant à ce chemin sera considérée comme source des données du cours.

shortname : Nom court du cours à créer

fullname : Nom long du cours à créer

idnumber : Identifiant externe du cours à créer

replacements : Une structure sérialisée en JSON comprenant des indicateurs de remplacement à effectuer dans différents champs et objets du cours. (*)

(*) Syntaxe en cours d'expérimentation / documentation à développer

Exemple de séquence de déclenchement externe

Pour une opération pilotée de l'extérieur, voici la séquence complète d'opérations à effectuer :

Téléchargement du fichier par l'upload “standard” de moodle

Commit du draftitemid récupéré (tool_sync_commit) pour le déplacer du draft vers le container de fichiers du tool sync

Modification de la configuration (si le nom du fichier a changé. sinon la config est déjà prete pour tourner) (tool_sync_set_config,pour le service désiré) cela recalera le nom de fichier d'une des “location” pour le bon service et la bonne action. Les WS peuvent modifier touts les clefs de configuration du tool_sync

Lancement du tool_sync_process correspondant au service désiré, avec la configuration enregistrée.

Service d'unification des manoeuvres des objets métiers primaires

Ce service est destiné à compléter ou prendre la main sur les Web Services standards de Moodle, lorsque ces derniers sont en carence d'unification d'API en particulier en ce qui concerne les identifiants primaires des objets métiers principaux de Moodle.

Ce plan de service ajoutera des fonctions manquates à l'API standard, ou proposera une signature alternative pour les fonctions qui ne présentent pas de possibilité d'utiliser les identifiants externes ou alternatifs sur les objets métiers à manoeuvrer.

En général, on s'accorde de pouvoir fournir toutes les entrées possibles d'identification sur les bases suivantes :

Entité	Identifiants possibles
Cours	id, shortname, idnumber
Utilisateur	id, username(@mnethostid), idnumber, email
Cohorte	id, idnumber
Groupe de cours	id, IDCours@name
Role	id, shortname

Actuellement implémenté

tool_sync_enrol_user_enrol()

tool_sync_enrol_user_unenrol()

Retour au guide technique - Retour à l'index du composant - Retour au catalogue