07 Schnittstelle ONYX Player

Zuletzt geändert von Carina Enke am 13.02.2024

The API between the ONYX Player and the LMS consists of the following components:

  • Registration of a test with the ONYX Player through the LMS
  • Registration of a participant with the ONYX Player through the LMS
  • Test control
  • Return of test results to the LMS through the ONYX Player
  • Deregistration of the test

Content

General information

The ONYX Player defines a web service, which is accessible via the URL <ONYXPlayer-URL>/onyx/onyxexamservices.

Link to the WSDL of the public demo runtime: http://demo.bps-system.de/onyx/onyxexamservices?wsdl

Registration of a test

Before participants can take tests, the tests need to be registered with ONYX.

Registration
@WebMethod(operationName = „registerTest")
public Long registerTest(
@WebParam(name = „testSessionId") final Long testSessionId,
@WebParam(name = „providerId") final String providerId,
@WebParam(name = „contentPackage") final byte[] contentPackage,
@WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
}

Parameters registerTest

testSessionId

Unique ID assigned by the LMS, which serves as an identifier for this test.

providerId

Identification under which the requesting LMS is registrated with ONYX.

contentPackage

The IMS QTI v2.1 CP (zip file as byte array).

parameters

List of parameters to control the test. It is also possible to set additional parameters for the individual participant (registerStudent).  

All parameters are optional. The default setting is shown in bold.  

Paramter

Description

showSolution [true|false]

Should the correct answer be displayed to the user?

isSynchronized [true|false]

Is the test for which the test start is synchronised across all users in the exam mode?

continuationAllowed [true|false]

Is it allowed to continue the test session at any time? If not, each test start must be performed via the LMS.

suspendAllowed [true|false]

Is it is allowed to interrupt the test? If this is the case, the button "Suspend" will additionally be displayed.

Templateid:

Currently only supported: onyxwithoutnav - hides the navigation tree.

dontShowItemTitles [true|false]

Should the titles of the questions not be displayed?

Since ONYX version 5.15, the following parameters can be used to control the feedback and evaluation display for the participant while taking the test. A detailed description of the functionality from the user's perspective is provided in the section "Test procedure configuration".

Questions evaluation:

Parameter

Description

itemShowFeedback [true|false]

The question feedback defined by the author is displayed to the participant after submitting an answer to the question.

itemShowMaxScore [true|false]

The participant is shown the maximum possible score for each question.

itemShowScore [true|false]

The participant is shown the number of points achieved for the question after submitting their answer.

itemShowCorrect [true|false]

The participant is shown whether their answer was correct or incorrect after submitting their answer. Implies itemShowScore=true.

itemShowSolution [true|false]

The participant is shown the correct solution after submitting their answer. Implies itemShowCorrect=true and itemShowScore=true.

Test evaluation:

Parameter

Description

testShowFeedback [true|false]

After submitting the test, the participant is shown a test completion page, which does (not) contain the test feedback defined by the author.

testShowScore [true|false]

After submitting the test, the participant is shown a test completion page, which does (not) contain all determined point values, such as the total test score and the points per test section, if applicable.

testShowPassed [true|false]

After submitting the test, the participant is shown a test completion page, which does (not) contain information about whether or not the test was passed. The default is the value given in testShowScore or its default.

Note

If no evaluation information is displayed on question level (itemShowFeedback = false, itemShowScore = false, itemShowCorrect = false, itemShowSolution = false), then the participant will not be shown the button to submit questions while taking the test. Instead, the answers are saved at any time and assessed after test submission.

The following parameters are no longer available since ONYX version 5.15:

  • showSolution [true |false] - Replaced by testShowScore, testShowPassed, itemShowSolution (including implications)
  • showFeedback [true |false] - Replaced by testShowFeedback and itemShowFeedback

ReturnValue registerTest

Long

One of the following values:

  • WAITING(0) – waiting for test start
  • WORKING(1) – is processing the test
  • FINISHED(2) – submitted the test
  • RESUME_ALLOWED(3) – resuming allowed
  • NOT_ENTERED(4) – has not yet entered the test
  • CANCELED(5) – has cancelled the testing process
  • RESUME_REQUESTED(6) – wishes to continue
  • RESUMED(7) – has continued
  • DISCONNECTED(8) – client is not / no longer reachable
  • SUSPENDED(9) – testing process has been interrupted
  • RESUME_SUSPENDED(10) – interrupted testing process is continued
  • OK(42) – OK

 

Error codes:

  • ERROR_RETURN_RESULTS(0xFF01)
  • ERROR_MULTIPLE_REGISTER_STUDENT_WITH_SAME_ID_CALLS(0xFF02)
  • ERROR_REGISTER_STUDENT_WITH_UNKNOWN_TEST_ID(0xFF03)
  • ERROR_REGISTER_STUDENT_WITH_EMPTY_TEST_ID(0xFF04)
  • ERROR_REGISTER_STUDENT_WITH_EMPTY_STUDENT_ID(0xFF05)
  • ERROR_REGISTER_STUDENT_TO_RESUME_WITHOUT_PAYLOAD(0xFF06)
  • ERROR_REGISTER_STUDENT_FOR_UNKNOWN_PROVIDER(0xFF07)
  • UNKNOWN(-1)

Registration of a student

Students can use a test after it has been registered, provided that they have been registered as well.

Registration
@WebMethod(operationName = „registerStudent")
public Long registerStudent(
@WebParam(name = „testSessionId", partName = „testSessionId") final Long test
SessionId,
@WebParam(name = „studentId", partName = „studentId") final Long studentId,
@WebParam(name = „payload", partName = „payload") final byte[] payload,
@WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
}

Parameters registerStudent

testSessionId

Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).

studentId

Unique identification for test participants. ID will be returned by ONYX when status changes or results are transmitted.

payload

Optional. Results for the participant (e. g. if interrupted tests are continued).

parameters

List of test control parameters (all optional, bold = default):

  • Language [de|en|fr|es]: Language of the ONYX user interface.
  • Status: Initial status of the participant (currently only RESUME_SUSPENDED(10) is supported).

ReturnValue registerStudent

Long

One of the values as described under "Registration of a test".

Test control

The status of registered test participants can be controlled by the LMS, e. g. to start, finish, or continue the test for everyone after the tutor has approved of it.

Test control
@WebMethod(operationName = „testControl")
public Long testControl(
@WebParam(name = „testSessionId") final Long testSessionId,
@WebParam(name = „studentIds") final StudentIdsWrapper students,
@WebParam(name = „status") final Integer status,
@WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
}

Parameters testControl

testSessionId

Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).

studentIds

List of unique IDs for test participants.

status

New status to be set for the given test participants.

parameters

List of test control parameters (all optional):

  • addTime: Time in minutes to add to the test session.

ReturnValue testControl

Long

One of the values as described under "Registration of a test".

Clear storage

When all participants have finished the test, the LMS can inform ONYX to deregister the test and to clear the storage.

Test control
@WebMethod(operationName = „deregisterTest")
public Long deregisterTest(
@WebParam(name = „testSessionId") final Long testSessionId,
@WebParam(name = „providerId") final String providerId,
@WebParam(name = „parameters") final MapWrapper parameters) throws Exception {
}

Parameters deregisterTest

testSessionId

Unique ID assigned by the LMS, which serves as an identifier for the test (cf. registerTest).

providerId

Identification under which the requesting LMS is registered with ONYX.

parameters

Currently not used.

ReturnValue deregisterTest

Long

One of the values as described under "Registration of a test".

Test display

After a test has been registered with the Player, the user can display it exactly once. For this reason, the LMS will show an IFrame with the target URL <ONYXWebPlayer-URL>/onyx/onyxrun?id=<UID> in the browser window. The <UID> must be the unique studentId used in the test registration. The test will then be started. If the user finishes the test, the results will be returned to the LMS. The LMS then needs to define a web service API that exactly matches the WSDL available under the following URL:

URL

http://demo.bps-system.de/olatce/services/ReturnWSService?wsdl
Only the URL in the lower part of the WSDL has to be adapted to the LMS.

Configuration of the ONYX Player

The ONYX Player uses a configuration file named onyxplugin.config.xml, which must be stored in the Java Classpath.

Security

Both the WSDL of the ONYX Player and the LMS should not be accessible/visible "from the outside". This also applies to the respective web services. The web GUI of the LMS and the ONYX Player, in contrast, must be visible to and accessible by all users. If HTTPS is used during the test process (which is strongly recommended), then the appropriate certificate must be known to the corresponding JVM of the LMS and the ONYX Player. Otherwise web service communication will not be possible.

If you have any questions about the configuration or the use of the ONYX Testsuite in other platforms, we will be happy to help you.

BPS Bildungsportal Sachsen GmbH

BPS-Logo-web.png

Phone: +49 (0) 371 666 2739 0
Email: support@bps-system.de

You are also welcome to use our Contact form.