08 ONYX Reporter interface

Last modified by Carina Enke on 13.02.2024

General information

The API to the ONYX WebReporter enables the communication between the LMS and the Reporter. Therefore, a couple of commands will be executed:

armSite

Registration of sequence requests at the ONYX Reporter

initiateSite

Initiates the Reporter session (transmission of the CP).

disarmSite

Release of all Reporter resources for this session.

getResultValues

Returns all (requested) results for the test. Condition: There is only one student in the list transmitted with initiateSite.

getResultVariables

Returns all (requested) outcome variables for the test. No armSite, initiateSite, or disarmSite is required.

Login through the LMS

Login through the LMS
@WebMethod(operationName = „armSite")
public String armSite(
@WebParam(name = „version") final Integer version,
@WebParam(name = „userId") final String userId,
@WebParam(name = „optionalRole") final Integer role,
@WebParam(name = „secretToShare") final String secretToShare,
@WebParam(name = „optionalUserLastName") final String userLastName,
@WebParam(name = „optionalUserFirstName") final String userFirstName,
@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
}

Parameter armSite

version

Requested version: 1

userId

UserId of the requested Reporter user

optionalRole

Optional. User role. 0 = student, 1 = tutor

secretToShare

A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.

optionalUserLastName

Optional. Last name of the user.

optionalUserFirstName

Optional. First name of the user.

additionalParams

Reserved for future use.

ReturnValue armSite

String

Session ID which has to be used to mark any other Reporter call.

Initialisation through LMS

Initialisation through LMS
@WebMethod(operationName = „initiateSite")
public String initiateSite(
@WebParam(name = „version") final Integer version,
@WebParam(name = „sessionId") final String sessionId,
@WebParam(name = „secretToShare") final String secretToShare,
@WebParam(name = „students") final ArrayList<ResultsForStudent> students,
@WebParam(name = „optionalContentPackage") final byte[] contentPackage,
@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
}

Parameter initiateSite

version

Requested version: 1

sessionId

SessionId, as returned by armSite.

secretToShare

A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.

students

List of students and their results. See below.

optionalContentPackage

Optional. Content package (zipped) as byte array.

additionalParams

Reserved for future use.

ReturnValue initiateSite

String

Absolute URL of the Reporter site for the IFrame. The URL has to be amended by the LMS with the following URL parameters:

  • sid: Session ID, as returned by armSite
  • uid: Student ID, as registrated in the initiateSite at the ONYX Reporter

public class ResultsForStudent {
   private String studentId = „";
   private String firstname = „";
   private String lastname = „";
   private String groupname = „";
   private String tutorname = „";
   private File contentFile = null;
   private byte[] resultsFile = null;
}

Logout through the LMS

@WebMethod(operationName = disarmSite")
public Boolean disarmSite(
@WebParam(name = „version"
) final Integer version,
@WebParam(name = sessionId") final String sessionId,
@WebParam(name = „secretToShare"
) final String secretToShare,
@WebParam(name = additionalParams") final HashMapWrapper additionalParams) {
}

Parameter disarmSite

version

Requested version: 1

sessionId

SessionId, as returned by armSite.

secretToShare

A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.

additionalParams

Reserved for future use.

ReturnValue disarmSite

Boolean

True in the case of success, otherwise false.

Request of learner results through the LMS

Request of learner results through the LMS
 @WebMethod(operationName = „getResultValues")
public HashMapWrapper getResultValues(
   @WebParam(name = „version") final Integer version,
   @WebParam(name = „sessionId") final String sessionId,
   @WebParam(name = „secretToShare") final String secretToShare,
   @WebParam(name = „requestedValues") final HashMap<String, String>
        requestedValues,
   @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
}

Parameter getResultValues

version

Requested version: 1

sessionId

SessionId, as returned by armSite.

secretToShare

A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.

requestedValues

Can be empty, in which case all result variables are returned. If keys are included, only the keys will be returned.

additionalParams

Reserved for future use.

ReturnValue getResultValues

HashMap<String, String>

Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)

Request of result variables through the LMS

Request of result variables through the LMS
 @WebMethod(operationName = „getResultVariables")
public HashMapWrapper getResultVariables(
@WebParam(name = „version") final Integer version,
@WebParam(name = „contentPackage") final byte[] contentPackage,
@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
}

Parameter getResultVariables

version

Requested version: 1

contentPackage

Content package (zipped) as byte array.

additionalParams

Reserved for future use.

ReturnValue getResultVariables

HashMap<String, String>

Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)

Wrapper

Since the transmission of maps and lists via JAX-WS can cause problems, they have to be wrapped.

Wrapper for HashMap<String, String>

HashMapWrapper.java:

HashMapWrapperjava.png

HashMapWrapperjava2.png

Wrapper for the ArrayList<ResultsForStudent>

ResultsForStudentsWrapper.java:

ResultsForStudentsWrapperjava.png