08 ONYX Reporter interface

author	version	line-number	content
		1	{{layout-cell}}
		2	{{panel borderColor="#ddd" bgColor="#f0f0f0" borderStyle="solid" title="Content"}}
		3	{{toc start="2"/}}
		4
		5
		6	{{/panel}}
		7	{{/layout-cell}}
		8
		9
		10
		11	== General information ==
		12
		13	The API to the ONYX WebReporter enables the communication between the LMS and the Reporter. Therefore, a couple of commands will be executed:
		14
		15	\|(((
		16	armSite
		17	)))\|(((
		18	Registration of sequence requests at the ONYX Reporter
		19	)))
		20	\|(((
		21	initiateSite
		22	)))\|(((
		23	Initiates the Reporter session (transmission of the CP).
		24	)))
		25	\|(((
		26	disarmSite
		27	)))\|(((
		28	Release of all Reporter resources for this session.
		29	)))
		30	\|(((
		31	getResultValues
		32	)))\|(((
		33	Returns all (requested) results for the test. Condition: There is only one student in the list transmitted with initiateSite.
		34	)))
		35	\|(% colspan="1" %)(% colspan="1" %)
		36	(((
		37	getResultVariables
		38	)))\|(% colspan="1" %)(% colspan="1" %)
		39	(((
		40	Returns all (requested) outcome variables for the test. No armSite, initiateSite, or disarmSite is required.
		41	)))
		42
		43	== Login through the LMS ==
		44
		45	{{code language="xml" title="Login through the LMS"}}
		46	@WebMethod(operationName = „armSite")
		47	public String armSite(
		48	@WebParam(name = „version") final Integer version,
		49	@WebParam(name = „userId") final String userId,
		50	@WebParam(name = „optionalRole") final Integer role,
		51	@WebParam(name = „secretToShare") final String secretToShare,
		52	@WebParam(name = „optionalUserLastName") final String userLastName,
		53	@WebParam(name = „optionalUserFirstName") final String userFirstName,
		54	@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
		55	}
		56	{{/code}}
		57
		58	=== Parameter armSite ===
		59
		60	\|(((
		61	version
		62	)))\|(((
		63	Requested version: 1
		64	)))
		65	\|(((
		66	userId
		67	)))\|(((
		68	UserId of the requested Reporter user
		69	)))
		70	\|(((
		71	optionalRole
		72	)))\|(((
		73	Optional. User role. 0 = student, 1 = tutor
		74	)))
		75	\|(((
		76	secretToShare
		77	)))\|(((
		78	A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
		79	)))
		80	\|(((
		81	optionalUserLastName
		82	)))\|(((
		83	Optional. Last name of the user.
		84	)))
		85	\|(% colspan="1" %)(% colspan="1" %)
		86	(((
		87	optionalUserFirstName
		88	)))\|(% colspan="1" %)(% colspan="1" %)
		89	(((
		90	Optional. First name of the user.
		91	)))
		92	\|(% colspan="1" %)(% colspan="1" %)
		93	(((
		94	additionalParams
		95	)))\|(% colspan="1" %)(% colspan="1" %)
		96	(((
		97	Reserved for future use.
		98	)))
		99
		100	=== ReturnValue armSite ===
		101
		102	\|(((
		103	String
		104	)))\|(((
		105	Session ID which has to be used to mark any other Reporter call.
		106	)))
		107
		108	== Initialisation through LMS ==
		109
		110	{{code language="xml" title="Initialisation through LMS"}}
		111	@WebMethod(operationName = „initiateSite")
		112	public String initiateSite(
		113	@WebParam(name = „version") final Integer version,
		114	@WebParam(name = „sessionId") final String sessionId,
		115	@WebParam(name = „secretToShare") final String secretToShare,
		116	@WebParam(name = „students") final ArrayList<ResultsForStudent> students,
		117	@WebParam(name = „optionalContentPackage") final byte[] contentPackage,
		118	@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
		119	}
		120	{{/code}}
		121
		122	=== Parameter initiateSite ===
		123
		124	\|(((
		125	version
		126	)))\|(((
		127	Requested version: 1
		128	)))
		129	\|(% colspan="1" %)(% colspan="1" %)
		130	(((
		131	sessionId
		132	)))\|(% colspan="1" %)(% colspan="1" %)
		133	(((
		134	SessionId, as returned by armSite.
		135	)))
		136	\|(((
		137	secretToShare
		138	)))\|(((
		139	A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
		140	)))
		141	\|(((
		142	students
		143	)))\|(((
		144	List of students and their results. See below.
		145	)))
		146	\|(((
		147	optionalContentPackage
		148	)))\|(((
		149	Optional. Content package (zipped) as byte array.
		150	)))
		151	\|(((
		152	additionalParams
		153	)))\|(((
		154	Reserved for future use.
		155	)))
		156
		157	=== ReturnValue initiateSite ===
		158
		159	\|(((
		160	String
		161	)))\|(((
		162	Absolute URL of the Reporter site for the IFrame. The URL has to be amended by the LMS with the following URL parameters:
		163
		164	* sid: Session ID, as returned by armSite
		165	* (((
		166	uid: Student ID, as registrated in the initiateSite at the ONYX Reporter
		167	)))
		168	)))
		169
		170	{{code language="xml"}}
		171	public class ResultsForStudent {
		172	private String studentId = „";
		173	private String firstname = „";
		174	private String lastname = „";
		175	private String groupname = „";
		176	private String tutorname = „";
		177	private File contentFile = null;
		178	private byte[] resultsFile = null;
		179	}
		180	{{/code}}
		181
		182	== Logout through the LMS ==
		183
		184
		185	{{code}}
		186	@WebMethod(operationName = „disarmSite")
		187	public Boolean disarmSite(
		188	@WebParam(name = „version") final Integer version,
		189	@WebParam(name = „sessionId") final String sessionId,
		190	@WebParam(name = „secretToShare") final String secretToShare,
		191	@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
		192	}
		193	{{/code}}
		194
		195
		196	=== Parameter disarmSite ===
		197
		198	\|(((
		199	version
		200	)))\|(((
		201	Requested version: 1
		202	)))
		203	\|(% colspan="1" %)(% colspan="1" %)
		204	(((
		205	sessionId
		206	)))\|(% colspan="1" %)(% colspan="1" %)
		207	(((
		208	SessionId, as returned by armSite.
		209	)))
		210	\|(((
		211	secretToShare
		212	)))\|(((
		213	A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
		214	)))
		215	\|(((
		216	additionalParams
		217	)))\|(((
		218	Reserved for future use.
		219	)))
		220
		221	=== ReturnValue disarmSite ===
		222
		223	\|(((
		224	Boolean
		225	)))\|(((
		226	True in the case of success, otherwise false.
		227	)))
		228
		229	== Request of learner results through the LMS ==
		230
		231	{{code language="xml" title="Request of learner results through the LMS"}}
		232	@WebMethod(operationName = „getResultValues")
		233	public HashMapWrapper getResultValues(
		234	@WebParam(name = „version") final Integer version,
		235	@WebParam(name = „sessionId") final String sessionId,
		236	@WebParam(name = „secretToShare") final String secretToShare,
		237	@WebParam(name = „requestedValues") final HashMap<String, String>
		238	requestedValues,
		239	@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
		240	}
		241	{{/code}}
		242
		243	=== Parameter getResultValues ===
		244
		245	\|(((
		246	version
		247	)))\|(((
		248	Requested version: 1
		249	)))
		250	\|(% colspan="1" %)(% colspan="1" %)
		251	(((
		252	sessionId
		253	)))\|(% colspan="1" %)(% colspan="1" %)
		254	(((
		255	SessionId, as returned by armSite.
		256	)))
		257	\|(((
		258	secretToShare
		259	)))\|(((
		260	A secret string that allows the server and client to encrypt their communication. Must remain the same for any further communication.
		261	)))
		262	\|(((
		263	requestedValues
		264	)))\|(((
		265	Can be empty, in which case all result variables are returned. If keys are included, only the keys will be returned.
		266	)))
		267	\|(((
		268	additionalParams
		269	)))\|(((
		270	Reserved for future use.
		271	)))
		272
		273	=== ReturnValue getResultValues ===
		274
		275	\|(((
		276	HashMap<String, String>
		277	)))\|(((
		278	Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)
		279	)))
		280
		281	== Request of result variables through the LMS ==
		282
		283	{{code language="xml" title="Request of result variables through the LMS"}}
		284	@WebMethod(operationName = „getResultVariables")
		285	public HashMapWrapper getResultVariables(
		286	@WebParam(name = „version") final Integer version,
		287	@WebParam(name = „contentPackage") final byte[] contentPackage,
		288	@WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
		289	}
		290	{{/code}}
		291
		292	=== Parameter getResultVariables ===
		293
		294	\|(((
		295	version
		296	)))\|(((
		297	Requested version: 1
		298	)))
		299	\|(((
		300	contentPackage
		301	)))\|(((
		302	Content package (zipped) as byte array.
		303	)))
		304	\|(((
		305	additionalParams
		306	)))\|(((
		307	Reserved for future use.
		308	)))
		309
		310	=== ReturnValue getResultVariables ===
		311
		312	\|(((
		313	HashMap<String, String>
		314	)))\|(((
		315	Map of result variables, key is the variable name, value is the respective variable's value (HashMap is wrapped)
		316	)))
		317
		318	== Wrapper ==
		319
		320	Since the transmission of maps and lists via JAX-WS can cause problems, they have to be wrapped.
		321
		322	=== Wrapper for HashMap<String, String> ===
		323
		324	HashMapWrapper.java:
		325
		326	[[image:attach:HashMapWrapperjava.png\|\|data-xwiki-image-style="img-screen" data-xwiki-image-style-border="true" width="500"]]
		327
		328	[[image:attach:HashMapWrapperjava2.png\|\|data-xwiki-image-style="img-screen" data-xwiki-image-style-border="true" width="500"]]
		329
		330	=== Wrapper for the ArrayList<ResultsForStudent> ===
		331
		332	ResultsForStudentsWrapper.java:
		333
		334	[[image:attach:ResultsForStudentsWrapperjava.png\|\|data-xwiki-image-style="img-screen" data-xwiki-image-style-border="true" width="500"]]