Vai al contenuto principale

Integrazione con LMS - Automazione tramite API

  • Aggiornato

Questo articolo spiega come automatizzare tramite API le due operazioni richieste dall'Integrazione con LMS: collegare gli utenti di SMARTFENSE al loro utente nell'LMS e ottenere il pacchetto SCORM di una campagna.

Cosa si può automatizzare

L'attivazione dell'integrazione prevede due operazioni, e ciascuna può essere eseguita dalla piattaforma o tramite API. I due percorsi convivono: l'API è un canale aggiuntivo, non una sostituzione.

  • Collegamento degli utenti: dalla piattaforma si carica un file CSV; tramite API si inviano gli utenti con il loro ID dell'LMS.
  • Pacchetto SCORM: dalla piattaforma si scarica con il pulsante del Calendario; tramite API si richiede e la piattaforma restituisce un link di download.

Automatizzare queste operazioni è utile quando l'organizzazione registra utenti con frequenza, oppure gestisce diversi contenuti e non vuole scaricare e caricare manualmente ogni pacchetto.

Se cerca i passaggi manuali, consulti Integrazione con LMS - Collegamento degli utenti e Integrazione con LMS - Configurazione delle campagne.

Prima di iniziare

Entrambe le operazioni richiedono che la Sua organizzazione abbia sottoscritto il componente Integrazione con LMS e che l'istanza sia attiva e in regola.

Inoltre, è necessaria un'applicazione registrata in Configuración > Integraciones > API. La procedura completa di registrazione è disponibile in Integrazione delle API in SMARTFENSE.

Al momento di registrare l'applicazione, selezioni solo gli ambiti che utilizzerà:

  • Link users with an external LMS, per il collegamento.
  • Download LMS integration SCORM package, per il pacchetto.

Questi ambiti sono separati di proposito: un'integrazione che carica solo utenti non deve poter scaricare contenuti, e una che scarica solo pacchetti non deve poter modificare l'anagrafica.

Collegare gli utenti con l'LMS

Imposta o aggiorna l'ID che ogni utente ha nell'LMS esterno, identificandolo tramite il suo indirizzo email in SMARTFENSE.

 
POST /api/v1/users/lms-id

Il corpo della richiesta contiene l'elenco degli utenti da collegare:

 
json
{
  "users": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" },
    { "email": "juan.gomez@ejemplo.com", "lms_id": "jgomez" }
  ]
}

Regole della richiesta

  • Sono ammessi fino a 200 utenti per richiesta.
  • L'ID dell'LMS ammette fino a 250 caratteri. Inviarlo vuoto scollega l'utente.
  • L'ID dell'LMS non può iniziare con i caratteri =, +, @, virgola, punto e virgola o trattino, né contenere < o >. La piattaforma rifiuta questi valori invece di modificarli, perché alterarli comprometterebbe la corrispondenza con l'LMS.
  • Se una stessa richiesta ripete un'email o un ID dell'LMS, vengono rifiutate tutte le occorrenze ripetute, non solo la seconda.

Risposta

Gli utenti vengono elaborati in modo indipendente: se uno fallisce, non vengono annullati quelli già applicati, come avviene nell'importazione tramite CSV. La risposta separa i due gruppi:

 
json
{
  "processed": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" }
  ],
  "errors": [
    { "email": "no.existe@ejemplo.com", "error_code": "...", "error": "..." }
  ],
  "details": { "total_processed": 1, "total_errors": 1 }
}

Ogni elemento di errors indica il motivo: l'email non corrisponde a nessun utente dell'organizzazione, oppure l'email o l'ID erano ripetuti nella richiesta.

L'operazione viene registrata nell'audit di amministrazione, con il totale degli utenti aggiornati e il dettaglio per utente.

Ottenere il pacchetto SCORM di una campagna

Restituisce lo stesso pacchetto prodotto dal pulsante di download del Calendario, per caricarlo nell'LMS senza passaggi manuali.

 
GET /api/v1/campaigns/{tipo_de_campaña}/{id_de_campaña}/scorm-package

I tipi di campagna validi sono training (Moduli Interattivi), video, videogame ed exam.

La campagna deve essere configurata con l'opzione Integrar esta campaña con un LMS. Se non lo è, la risposta è la stessa che si otterrebbe se la campagna non esistesse.

Risposta

 
json
{
  "file_url": "https://...",
  "file_name": "lms-integration-....zip",
  "expires_in": 14400
}

Il link di download è temporaneo: expires_in indica, in secondi, per quanto tempo rimane valido. Scarichi il file entro quella finestra; una volta scaduto, sarà necessario richiedere nuovamente il pacchetto.

💡 Buone pratiche

  • Verificare che gli utenti esistano su entrambe le piattaforme prima di collegarli: l'API risolve l'utente tramite la sua email e restituisce un errore se non lo trova.
  • Inviare gli utenti in lotti di massimo 200 e controllare il blocco errors di ogni risposta prima di considerare completato il caricamento.
  • Utilizzare l'identificativo richiesto dal Suo LMS. In Moodle, ad esempio, corrisponde al campo username dell'utente.
  • Richiedere il pacchetto SCORM nel momento in cui verrà caricato nell'LMS, e non in anticipo, poiché il link scade.
  • Registrare un'applicazione per ogni integrazione, con gli ambiti minimi necessari a quella integrazione.

Articoli correlati