Découvrir l'API, sa structure et l'utilisation du SSO (Lära et Via HTML)

Table des matières

Table des matières
Introduction
Notes
Activation de l’API
Définition des balises API dans les champs personnalisés
    Structure des appels API
    Gestion des erreurs
Utilisation du SSO
De votre application vers VIA : user/getsso

Introduction

Lära LMS possède une API qui vous permet d’appeler ses fonctions par n’importe quel système pour créer des branches, des fournisseurs de services, des formations et événements, des utilisateurs, etc. Il est simple, rapide et sécuritaire de l’utiliser.

Les sections qui suivent donnent aux développeurs toute l’information pertinente au développement d’un pont entre leur système et Lära LMS en utilisant l’API. 

Notes

Activation de l’API

Voici les étapes à suivre pour activer l'API sur le système Lära LMS. Vous pouvez demande l'aide de votre conseiller en implantation pour procéder à ces manoeuvre.

1. Vous devez tout d’abord activer l’API avant de pouvoir adresser des requêtes au système. Rendez-vous dans les « Réglages avancés » du menu administration, puis sous l'onglet « API ». ATTENTION : vous devez disposer de droits administratifs élevés pour accéder à ces informations.
    
2. Une fois dans la fenêtre « API », la liste des accès API créés sera présentée.
   
3.  Cliquez sur « Ajouter une API » pour créer votre nouvel accès API
   
4. Entrer un Nom (administratif) et ajouter vos adresses IP à l’aide du bouton « AJOUTER UNE ADRESSE IP ».

ATTENTION : Pour ajouter une plage d'adresse, veuillez utiliser la syntaxe suivante: 127.0.0.1-127.0.0.100 

Définition des balises API dans les champs personnalisés

Le portail permet la création de champs personnalisés (customs fields) sur plusieurs de ses entités (utilisateurs, formation et événements, etc.). Il vous est possible d’obtenir les informations sur ces champs par la page « Champs personnalisés » qui se trouve sous « Administration ».

Par exemple, si vous choisissiez comme élément concerné « formation et événements » la propriété correspondant à votre champ personnalisé sera prise en charge dans les appels de l’API.

Structure des appels API

La structure des appels API est simple : 

• Les appels sont en HTTP à l’URL fourni dans votre portail dans la section API. 
• La méthode d’appel doit être en POST 
• Le format de données est en JSON  

Lors de l’appel des fonctions, une entête HTTP doit être ajoutée pour contenir la clé « ApiID » et sa valeur. Cette dernière vous a été attribuée sur le portail (dans votre fournisseur de service). 

Exemple de clé ApiID  :  20a3581253484dcfa055904e33b3d655

Gestion des erreurs

Lorsque des erreurs surviennent sur les appels d’API, ce dernier retourne la structure générique suivante :

{
  "errors": {
    "message": "Invalid userId",
    "code": 39
  }
}

Description des codes d’erreurs génériques

Utilisation du SSO

De votre application vers VIA : user/getsso

https://www.domaine.com/lmsapi/user/getsso

Exemple d’appel :

{
  "id": "MS6Hj2EsyN8wvPrcAWAZMA%3d%3d",
  "portalId": "Ej1w%2flaWRrB8V5JBIxl7Cg%3d%3d",
  "refId": "WSmUkyUmFT%2bEGm2dllhihg%3d%3d",
  "subRefId": "WSmUkyUmFT%2bEGm2dllhihg%3d%3d",
  "redirectType": 4,
  "urlRedirect": null,
  "forceAccess": 1
}

Réponse de l’appel (par l’API)
https://www.domaine.com/lmsapi/user/getsso

{
  "urlSSO": “https://portailpreprod.sviesolutions.com/Web/SignInSSO?token=8c629721c8dc40c399fa454a289cc883"
}

Description des champs

Nom	Obligatoire	Commentaires/description
id		Il s’agit de l’identifiant de l’utilisateur pour lequel on désire produire un lien de transfert vers Via. (Type String)
portalId		Portail par défaut pour la personnalisation et le sign out. Si la valeur est vide, le portail par défaut est utilisé.  (Type String)
refId		ID de référence en fonction du redirectType, nécessaire pour les modes 3, 4 et 8. (Type String) Il est important de récupérer le returnURL placé sur l’url du bouton qui envoie l’utilisateur vers le SSO afin que vous puissiez le retourner connecté dans le bon contexte. Vous devez réencoder en format URL ce paramètre afin qu’il puisse être valide.
subRefId		ID de référence en fonction du redirectType, nécessaire pour le mode 8(ID d’enregistrement). (Type String)  Il est important de récupérer le returnURL placé sur l’url du bouton qui envoie l’utilisateur vers le SSO afin que vous puissiez le retourner connecté dans le bon contexte. Vous devez réencoder en format URL ce paramètre afin qu’il puisse être valide.
redirectType		RedirectTypes : MyDashboard = 1 MyWorkspaces = 2 WorkspaceInstance = 3 Workspace = 4 MyFolder = 5 Application Via HTML5 = 8 Noter que la valeur urlRedirect n’est pas obligatoire si la valeur redirectType est fournie.
urlRedirect		Il s’agit de l’url de redirection une fois l’utilisateur authentifié. Noter que la valeur redirectType n’est pas obligatoire si la valeur urlRedirect est fournie.
forceAccess		Paramètre optionnel qui est prit en compte uniquement pour le redirectType 8 (Application Via HTML5).  La valeur True (1) permettra à l’utilisateur d’accéder à l’activité comme animateur sans avoir besoin d’être associé à l’activité (Type Boolean)

Retour d'appel : 

{
  "urlSSO": url de redirection pour le sso. (Type String)
}