08 ONYX Reporter interface

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

Wiki source code of 08 Schnittstelle ONYX Reporter