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

I. Pour des raisons de sécurité, il n’est pas possible de procéder librement à des requêtes API. Pour ce faire, plusieurs informations chiffrées doivent vous être transmises afin de vous permettre d’appeler correctement et vous identifier auprès du service WEB de l’API et les adresses IP de vos serveurs appelants doivent figurer dans les adresses permises de votre environnement Lära. Veuillez demander l'aide de votre conseiller en implantation à cet effet;
II. Les termes techniques utilisés dans le présent guide sont définis dans l'article Consulter le lexique SVI du site Mon Assistance, qui, par ailleurs, contient beaucoup d'information sur votre nouveau système de gestion des apprentissages;
III. Les appels présents dans le présent article sont vivants et des modifications seront périodiquement apportées aux fonctions API;
IV. Veuillez noter que le genre masculin est utilisé de façon générique dans les articles d'assistance pour en alléger le contenu.

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

Numéro

Message

Commentaires/description

1

Required id

Vous devez fournir un identifiant.

2

Invalid id

L’identifiant fourni est invalide.

3

Invalid country

Le pays fourni est invalide.

4

Invalid state

La province ou l’état fourni est invalide.

5

Required state

La province ou l’état est requis.

6

Custom field required

Le champ personnalisé se trouvant dans le message d’erreur est requis.

7

Custom field does not exists

Le champ personnalisé se trouvant dans le message d’erreur n’existe pas.

8

Custom field cannot receive null

Le champ personnalisé se trouvant dans le message d’erreur ne peut pas recevoir la valeur null.

9

Custom field value is not “Type”

La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas du même type que le champ.

10

Custom field is not a valid value of this list value

La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas comprise dans la liste des valeurs.

11

Custom field value is not a valid country

La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas un pays valide.

12

Action empty

Vous devez fournir une action à votre requête.

13

Json data invalid : message

Le Json est invalide. Voir le message d’erreur pour obtenir plus de précision.

14

Action processor not found

Le processeur en lien avec votre action n’a pas été trouvé.

15

Api processor not found

Le processeur fourni n’a pas été trouvé.

16

ApiID is empty

Vous devez fournir un identifiant pour l’Api.

17

Invalid ApiID

L’identifiant fourni pour l’Api est invalide

18

Invalid Url

L’url fourni est invalide.

19

Invalid IP

L’adresse IP fourni est invalide.

20

message

Le message vous indiquera quel est l’erreur.

21

Custom field value is not a valid Location

La valeur fournie pour le champ personnalisé se trouvant dans le message d’erreur n’est pas un emplacement valide.

22

Missing search value

Aucune valeur de champ de recherche n’est spécifiée.

23

Unexpected Failure

Une erreur imprévue est survenue pendant l’opération d’une requête.

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)
}


Cette réponse a-t-elle été utile ? Oui Non

Envoyer vos commentaires
Nous sommes désolés de ne pas avoir pu répondre à votre question. Aidez-nous à améliorer cet article grâce à vos commentaires.