Epistema LMS Web Services
Un article de EpistemaWiki.
Epistema LMS and Epistema Assessment Server both implement a number of web services that can be used to interface your application with third-parties.
This documentation is subject to changes, and you should always refer directly to the web services self description feature of the web services server.
Sommaire |
Servers URL
Two servers are available for querying Epistema LMS:
- http:/.... your application url .../xmlrpc/server.php -> this implements a xmlrpc server
- http:/.... your application url .../xmlrpc/server_json.php -> this implements a jsonrpc server
You can use one or the other depending on the 3rd party environnement: XML is commonly used in many languages, but JSON can be usefull is Javascript based applications (Ajax).
You can find here a description of both formats: http://en.wikipedia.org/wiki/XML-RPC and http://en.wikipedia.org/wiki/JSON-RPC
Both implement exactly the same set of services, so you should base your choice on convenience only.
Some might wonder why XMLRPC and not SOAP ? Here is why.
Authentification
Most web services will require authentification. This is done based on HTTP authentification. The login and password should be those of a back-office user. The rights of the back-office user can change the way he has access to the web service. For exemple, a fully authentified user will not be able to use the trainee creation service if he is not allowed to create trainees.
When the web service is related to a trainee, the trainee must be in the group of the authenticated back-office user, otherwise the web service will fail.
Test interface
Epistema LMS embeds a fully functionnal test interface for its own web services. You can reach it by browsing to : http://.... your application url .../tests/xmlrpc_test/
Using this interface, you will be able to discover the list of implemented web services on your platform (including those developped specifically), and, for each service, get the description, synopsis, and sample code for use in PHP (similar code is easy to write in any other languages).
Default services
Here's a list of a few of the web services that are available. Again, you should prefer looking directly at the list as it appears in the test interface, using the auto-discovery feature.
- EpistemaLMS.CheckUserName
- Checks that a trainee exists by that name in the system. The parameters are: login, name, firstname, email. You can leave any of these parameters empty to check the existence on the remaining ones.
- EpistemaLMS.CreateUser
- Adds a trainee into the system. Parameters are : name, firstname, email, login, password, reference number, activation, deduplication. In the activation parameter, D means disabled, a date means that the account will be active up until the date (inclusive), and nothing or anything else means the account is active. In the deduplication parameter (boolean), true means that if a duplicate is found it will be merged, false means a new account will be created. Deduplication works by checking the email or the login if they are specified, and the name and firstname if both the login and the email were left blank. All parameters but the first one are optional (they can be left empty). The method returns the login of the newly created account This method requires authentification using a valid user/password in the system (allowed to create trainees). The trainees are created in the group of the user.
- EpistemaLMS.UserLogon
- Logs a user in the system. The parameter is the login of the trainee. This method requires authentification using a valid user/password in the system (the trainee should be in the group of the user). The method returns a URL that can be used to connect the person automatically.
- EpistemaLMS.GetUserInformation
- Return an information set of a trainee. The parameters is the login of the trainee. This method requires authentification using a valid user/password in the system. The method returns an error if the trainee is not found. In other case, information will be an array containing : "succes", the login, the password, the name, the firstname, the creation date, the email, the reference number, the group name, the last connection date, and the status of the account (enabled or disabled).
- This web service has been added on 1rst of dec 2008, in v.2008.3.1
- EpistemaLMS.CheckloginAndPassword
- Return a simple "succes" if a trainee with a login and password exist. The parameters are the login and password of the trainee. This method requires authentification using a valid user/password in the system. The method returns an error message if the trainee is not found and a succes message if found.
- This web service has been added on 1rst of dec 2008, in v.2008.3.1
- EpistemaLMS.UserLogonFirstQuestionContent
- Logs a user in the system. The parameter is the login of the trainee and the id of the content. This method requires authentification using a valid user/password in the system. The method returns a URL that can be used to connect the person automatically to the first question of a quizz (used only for quizz).
- This web service has been added on 1rst of dec 2008, in v.2008.3.1
Common error messages
| Error code | Message |
|---|---|
| 801 | This service requires HTTP authentification. The user must be a valid backoffice user. |
| 802 | The HTTP authentification provided is not valid. The user must be a valid backoffice user. |
| 803 | The HTTP authentification provided is not valid. The user must have the right to create a frontoffice user. |
| 804 | No trainee was found with this login, in the group of the authenticated user. |
| 805 | No content was found with this id. |
| 806 | The trainee is not registered to the training. |
