Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

Version 318.1 von Carina Enke am 30.05.2018
Zeige letzte Bearbeiter
1 {{sv-translation language="de"}}
2 {{layout}}
3 {{layout-section ac:type="single"}}
4 {{layout-cell}}{{/layout-cell}}
5 {{/layout-section}}
6
7 {{layout-section ac:type="two_right_sidebar"}}
8 {{layout-cell}}
9 ====== Inhalt: ======
10
11
12
13 {{toc maxLevel="5" outline="true" absoluteUrl="true" style="square"/}}
14 {{/layout-cell}}
15
16 {{layout-cell}}
17
18 {{/layout-cell}}
19 {{/layout-section}}
20
21 {{layout-section ac:type="single"}}
22 {{layout-cell}}
23 == Allgemeines ==
24
25 Über die Schnittstelle zum ONYX WebReporter erfolgt jede Kommunikation zwischen dem LMS und dem Reporter. Dazu erfolgt eine Reihe von Aufrufen:
26
27 |(((
28 armSite
29 )))|(((
30 Anmeldung von Folgerequests beim ONYX Reporter.
31 )))
32 |(((
33 initiateSite
34 )))|(((
35 Initiiert die Reporter-Session (Übertragung des CPs).
36 )))
37 |(((
38 disarmSite
39 )))|(((
40 Freigabe von allen Reporter-Ressourcen für diese Session.
41 )))
42 |(((
43 getResultValues
44 )))|(((
45 Gibt alle bzw. die angeforderten Resultate für den Test zurück. Voraussetzung: Es ist nur exakt ein Student in der bei initiateSite übertragenen Liste.
46 )))
47 |(% colspan="1" %)(% colspan="1" %)
48 (((
49 getResultVariables
50 )))|(% colspan="1" %)(% colspan="1" %)
51 (((
52 Gibt alle bzw. die angeforderten Outcome-Variablen für den Test zurück. Hierfür sind kein armSite, initiateSite oder disarmSite erforderlich.
53 )))
54
55 == Anmeldung des LMS ==
56
57 {{code language="xml" title="Anmeldung des LMS"}}
58 @WebMethod(operationName = „armSite")
59 public String armSite(
60 @WebParam(name = „version") final Integer version,
61 @WebParam(name = „userId") final String userId,
62 @WebParam(name = „optionalRole") final Integer role,
63 @WebParam(name = „secretToShare") final String secretToShare,
64 @WebParam(name = „optionalUserLastName") final String userLastName,
65 @WebParam(name = „optionalUserFirstName") final String userFirstName,
66 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
67 }
68 {{/code}}
69
70 === Parameter armSite ===
71
72 |(((
73 version
74 )))|(((
75 Angefragte Version: 1
76 )))
77 |(((
78 userId
79 )))|(((
80 UserId des anfragenden Reporter-Benutzers
81 )))
82 |(((
83 optionalRole
84 )))|(((
85 Optional. Rolle des Benutzers. 0 = Student, 1= Tutor
86 )))
87 |(((
88 secretToShare
89 )))|(((
90 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
91 )))
92 |(((
93 optionalUserLastName
94 )))|(((
95 Optional. Nachname des Benutzers.
96 )))
97 |(% colspan="1" %)(% colspan="1" %)
98 (((
99 optionalUserFirstName
100 )))|(% colspan="1" %)(% colspan="1" %)
101 (((
102 Optional. Vorname des Benutzers.
103 )))
104 |(% colspan="1" %)(% colspan="1" %)
105 (((
106 additionalParams
107 )))|(% colspan="1" %)(% colspan="1" %)
108 (((
109 Reserved for future use.
110 )))
111
112 === ReturnValue armSite ===
113
114 |(((
115 String
116 )))|(((
117 Session ID, mit der alle weiteren Reporter-Aufrufe gekennzeichnet werden müssen.
118 )))
119
120 == Initialisierung durch LMS ==
121
122 {{code language="xml" title="Initialisierung durch LMS"}}
123 @WebMethod(operationName = „initiateSite")
124 public String initiateSite(
125 @WebParam(name = „version") final Integer version,
126 @WebParam(name = „sessionId") final String sessionId,
127 @WebParam(name = „secretToShare") final String secretToShare,
128 @WebParam(name = „students") final ArrayList<ResultsForStudent> students,
129 @WebParam(name = „optionalContentPackage") final byte[] contentPackage,
130 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
131 }
132 {{/code}}
133
134 === Parameter initiateSite ===
135
136 |(((
137 version
138 )))|(((
139 Angefragte Version: 1
140 )))
141 |(% colspan="1" %)(% colspan="1" %)
142 (((
143 sessionId
144 )))|(% colspan="1" %)(% colspan="1" %)
145 (((
146 SessionId, wie von armSite zurück geliefert.
147 )))
148 |(((
149 secretToShare
150 )))|(((
151 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
152 )))
153 |(((
154 students
155 )))|(((
156 Liste der Studenten mit ihren Resultaten. Siehe unten.
157 )))
158 |(((
159 optionalContentPackage
160 )))|(((
161 Optional. Content Package (gezippt) als Byte-Array.
162 )))
163 |(((
164 additionalParams
165 )))|(((
166 Reserved for future use.
167 )))
168
169 === ReturnValue initiateSite ===
170
171 |(((
172 String
173 )))|(((
174 Absolute URL der Reporter-Seite für den IFrame. Dieser ist vom LMS durch die folgenden URL-Parameter anzureichern:
175
176 * sid: Session ID, wie von armSite zurück gegeben
177 * uid: Student ID, wie in initiateSite beim Reporter angemeldet
178 )))
179
180 {{code language="xml"}}
181 public class ResultsForStudent {
182    private String studentId = „";
183    private String firstname = „";
184    private String lastname = „";
185    private String groupname = „";
186    private String tutorname = „";
187    private File contentFile = null;
188    private byte[] resultsFile = null;
189 }
190 {{/code}}
191
192 == Abmeldung durch LMS ==
193
194
195
196 {{code}}
197 @WebMethod(operationName = „disarmSite")
198 public Boolean disarmSite(
199 @WebParam(name = „version") final Integer version,
200 @WebParam(name = „sessionId") final String sessionId,
201 @WebParam(name = „secretToShare") final String secretToShare,
202 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
203 }
204 {{/code}}
205
206
207
208 === Parameter disarmSite ===
209
210 |(((
211 version
212 )))|(((
213 Angefragte Version: 1
214 )))
215 |(% colspan="1" %)(% colspan="1" %)
216 (((
217 sessionId
218 )))|(% colspan="1" %)(% colspan="1" %)
219 (((
220 SessionId, wie von armSite zurück geliefert.
221 )))
222 |(((
223 secretToShare
224 )))|(((
225 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
226 )))
227 |(((
228 additionalParams
229 )))|(((
230 Reserved for future use.
231 )))
232
233 === ReturnValue disarmSite ===
234
235 |(((
236 Boolean
237 )))|(((
238 True bei Erfolg, sonst false.
239 )))
240
241 == Abfrage von Lernerresultaten durch LMS ==
242
243 {{code language="xml" title="Abfrage von Lernerresultaten durch LMS"}}
244  @WebMethod(operationName = „getResultValues")
245 public HashMapWrapper getResultValues(
246 @WebParam(name = „version") final Integer version,
247 @WebParam(name = „sessionId") final String sessionId,
248 @WebParam(name = „secretToShare") final String secretToShare,
249 @WebParam(name = „requestedValues") final HashMap<String, String>
250 requestedValues,
251 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
252 }
253 {{/code}}
254
255 === Parameter getResultValues ===
256
257 |(((
258 version
259 )))|(((
260 Angefragte Version: 1
261 )))
262 |(% colspan="1" %)(% colspan="1" %)
263 (((
264 sessionId
265 )))|(% colspan="1" %)(% colspan="1" %)
266 (((
267 SessionId, wie von armSite zurück geliefert.
268 )))
269 |(((
270 secretToShare
271 )))|(((
272 Ein geheimer String, mit dessen Hilfe Server und Client ihre Kommunikation verschlüsseln. Muss bei jeder weiteren Kommunikation gleich bleiben.
273 )))
274 |(((
275 requestedValues
276 )))|(((
277 Kann leer sein, dann werden alle Result-Variables zurück geliefert. Sind Keys enthalten, so kommen nur diese zurück.
278 )))
279 |(((
280 additionalParams
281 )))|(((
282 Reserved for future use.
283 )))
284
285 === ReturnValue getResultValues ===
286
287 |(((
288 HashMap<String, String>
289 )))|(((
290 Map der Result-Variables, Key ist der Variablenname, Value der jeweilige Wert (HashMap ist gewrappt)
291 )))
292
293 == Abfrage von Ergebnisvariablen durch LMS ==
294
295 {{code language="xml" title="Abfrage von Ergebnisvariablen durch LMS"}}
296  @WebMethod(operationName = „getResultVariables")
297 public HashMapWrapper getResultVariables(
298 @WebParam(name = „version") final Integer version,
299 @WebParam(name = „contentPackage") final byte[] contentPackage,
300 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
301 }
302 {{/code}}
303
304 === Parameter getResultVariables ===
305
306 |(((
307 version
308 )))|(((
309 Angefragte Version: 1
310 )))
311 |(((
312 contentPackage
313 )))|(((
314 Content Package (gezippt) als Byte-Array.
315 )))
316 |(((
317 additionalParams
318 )))|(((
319 Reserved for future use.
320 )))
321
322 === ReturnValue getResultVariables ===
323
324 |(((
325 HashMap<String, String>
326 )))|(((
327 Map der Result-Variables, Key ist der Variablenname, Value der jeweilige Wert (HashMap ist gewrappt)
328 )))
329
330 == Wrapper ==
331
332 Da die Übertragung von Maps und Listen über JAX-WS Probleme machen kann, müssen diese gewrappt werden.
333
334 === Wrapper für die HashMap<String, String> ===
335
336 HashMapWrapper.java:
337
338 [[image:attach:HashMapWrapperjava.png]]
339
340 [[image:attach:HashMapWrapperjava2.png]]
341
342 === Wrapper für die ArrayList<ResultsForStudent> ===
343
344 ResultsForStudentsWrapper.java:
345
346 [[image:attach:ResultsForStudentsWrapperjava.png]]
347 {{/layout-cell}}
348 {{/layout-section}}
349
350 {{layout-section ac:type="two_right_sidebar"}}
351 {{layout-cell}}
352
353 {{/layout-cell}}
354
355 {{layout-cell}}
356 ====== relevante Links: ======
357
358 * [[doc:ONYX Player Interface]]
359 {{/layout-cell}}
360 {{/layout-section}}
361 {{/layout}}
362 {{/sv-translation}}
363
364 {{sv-translation language="en"}}
365 {{layout}}
366 {{layout-section ac:type="two_equal"}}
367 {{layout-cell}}
368 ====== Content: ======
369
370
371
372 {{toc maxLevel="5" outline="true" absoluteUrl="true" style="square"/}}
373 {{/layout-cell}}
374
375 {{layout-cell}}
376
377 {{/layout-cell}}
378 {{/layout-section}}
379
380 {{layout-section ac:type="single"}}
381 {{layout-cell}}
382 == General ==
383
384 The API to the ONYX WebReporter enables the communication between the LMS and the reporter. Therefore, a couple of commands will be executed:
385
386 |(((
387 armSite
388 )))|(((
389 Registration of sequence requests at the ONYX reporter
390 )))
391 |(((
392 initiateSite
393 )))|(((
394 Initiates the reporter session (transmission of the CP).
395 )))
396 |(((
397 disarmSite
398 )))|(((
399 Release of all reporter resources for this session.
400 )))
401 |(((
402 getResultValues
403 )))|(((
404 Returns all or all requested results for the test. Condition: there is exactly one student in list transmitted in the initiateSite.
405 )))
406 |(% colspan="1" %)(% colspan="1" %)
407 (((
408 getResultVariables
409 )))|(% colspan="1" %)(% colspan="1" %)
410 (((
411 Returns all or all requested outcome variables for the test. No armSite, initiateSite or disarmSite is necessary.
412 )))
413
414 == Connection to the LMS ==
415
416 {{code language="xml" title="Anmeldung des LMS"}}
417 @WebMethod(operationName = „armSite")
418 public String armSite(
419 @WebParam(name = „version") final Integer version,
420 @WebParam(name = „userId") final String userId,
421 @WebParam(name = „optionalRole") final Integer role,
422 @WebParam(name = „secretToShare") final String secretToShare,
423 @WebParam(name = „optionalUserLastName") final String userLastName,
424 @WebParam(name = „optionalUserFirstName") final String userFirstName,
425 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
426 }
427 {{/code}}
428
429 === Parameter armSite ===
430
431 |(((
432 version
433 )))|(((
434 Requested version: 1
435 )))
436 |(((
437 userId
438 )))|(((
439 UserId of the requested reporter user
440 )))
441 |(((
442 optionalRole
443 )))|(((
444 Optional. User role. 0=student, 1=tutor
445 )))
446 |(((
447 secretToShare
448 )))|(((
449 Shared secret. Has to remain identical for every communication.
450 )))
451 |(((
452 optionalUserLastName
453 )))|(((
454 Optional. User lastname.
455 )))
456 |(% colspan="1" %)(% colspan="1" %)
457 (((
458 optionalUserFirstName
459 )))|(% colspan="1" %)(% colspan="1" %)
460 (((
461 Optional. User firstname.
462 )))
463 |(% colspan="1" %)(% colspan="1" %)
464 (((
465 additionalParams
466 )))|(% colspan="1" %)(% colspan="1" %)
467 (((
468 Reserved for future use.
469 )))
470
471 === ReturnValue armSite ===
472
473 |(((
474 String
475 )))|(((
476 Session ID that has to be used to mark any further reporter call.
477 )))
478
479 == Initialisation through LMS ==
480
481 {{code language="xml" title="Initialisierung durch LMS"}}
482 @WebMethod(operationName = „initiateSite")
483 public String initiateSite(
484 @WebParam(name = „version") final Integer version,
485 @WebParam(name = „sessionId") final String sessionId,
486 @WebParam(name = „secretToShare") final String secretToShare,
487 @WebParam(name = „students") final ArrayList<ResultsForStudent> students,
488 @WebParam(name = „optionalContentPackage") final byte[] contentPackage,
489 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
490 }
491 {{/code}}
492
493 === Parameter initiateSite ===
494
495 |(((
496 version
497 )))|(((
498 Requested version: 1
499 )))
500 |(% colspan="1" %)(% colspan="1" %)
501 (((
502 sessionId
503 )))|(% colspan="1" %)(% colspan="1" %)
504 (((
505 SessionId, as returned by armSite.
506 )))
507 |(((
508 secretToShare
509 )))|(((
510 Shared secret. Has to remain identical at every communication.
511 )))
512 |(((
513 students
514 )))|(((
515 List of students with their results. See below.
516 )))
517 |(((
518 optionalContentPackage
519 )))|(((
520 Optional. Content Package (zipped) as byte array.
521 )))
522 |(((
523 additionalParams
524 )))|(((
525 Reserved for future use.
526 )))
527
528 === ReturnValue initiateSite ===
529
530 |(((
531 String
532 )))|(((
533 Absolute URL of the reporter site for the frame. It has to be enriched by the LMS with the following URLparameters:
534
535 * sid: Session ID as returned by armSite
536 * (((
537 uid: Student ID as registrated in the initiateSite at the ONYX Reporter.
538 )))
539 )))
540
541 {{code language="xml"}}
542 public class ResultsForStudent {
543    private String studentId = „";
544    private String firstname = „";
545    private String lastname = „";
546    private String groupname = „";
547    private String tutorname = „";
548    private File contentFile = null;
549    private byte[] resultsFile = null;
550 }
551 {{/code}}
552
553 == Deconnection through the LMS ==
554
555
556
557 {{code}}
558 @WebMethod(operationName = „disarmSite")
559 public Boolean disarmSite(
560 @WebParam(name = „version") final Integer version,
561 @WebParam(name = „sessionId") final String sessionId,
562 @WebParam(name = „secretToShare") final String secretToShare,
563 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
564 }
565 {{/code}}
566
567
568
569 === Parameter disarmSite ===
570
571 |(((
572 version
573 )))|(((
574 Requested version: 1
575 )))
576 |(% colspan="1" %)(% colspan="1" %)
577 (((
578 sessionId
579 )))|(% colspan="1" %)(% colspan="1" %)
580 (((
581 SessionId, as returned by armSite.
582 )))
583 |(((
584 secretToShare
585 )))|(((
586 Shared secret. Has to remain identical at every communication.
587 )))
588 |(((
589 additionalParams
590 )))|(((
591 Reserved for future use.
592 )))
593
594 === ReturnValue disarmSite ===
595
596 |(((
597 Boolean
598 )))|(((
599 True if successful, otherwise false.
600 )))
601
602 == Request of learning results through the LMS ==
603
604 {{code language="xml" title="Abfrage von Lernerresultaten durch LMS"}}
605  @WebMethod(operationName = „getResultValues")
606 public HashMapWrapper getResultValues(
607 @WebParam(name = „version") final Integer version,
608 @WebParam(name = „sessionId") final String sessionId,
609 @WebParam(name = „secretToShare") final String secretToShare,
610 @WebParam(name = „requestedValues") final HashMap<String, String>
611 requestedValues,
612 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
613 }
614 {{/code}}
615
616 === Parameter getResultValues ===
617
618 |(((
619 version
620 )))|(((
621 Requested version: 1
622 )))
623 |(% colspan="1" %)(% colspan="1" %)
624 (((
625 sessionId
626 )))|(% colspan="1" %)(% colspan="1" %)
627 (((
628 SessionId, as returned by armSite.
629 )))
630 |(((
631 secretToShare
632 )))|(((
633 Shared secret. Has to remain identical at every communication.
634 )))
635 |(((
636 requestedValues
637 )))|(((
638 Can be empty, thus all result variables will be returned. If it contains keys, only those will be returned.
639 )))
640 |(((
641 additionalParams
642 )))|(((
643 Reserved for future use.
644 )))
645
646 === ReturnValue getResultValues ===
647
648 |(((
649 HashMap<String, String>
650 )))|(((
651 Map of result variables, key is the variable name, value the corresponding value (HashMap is wrapped)
652 )))
653
654 == Request of result variables through the LMS ==
655
656 {{code language="xml" title="Abfrage von Ergebnisvariablen durch LMS"}}
657  @WebMethod(operationName = „getResultVariables")
658 public HashMapWrapper getResultVariables(
659 @WebParam(name = „version") final Integer version,
660 @WebParam(name = „contentPackage") final byte[] contentPackage,
661 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
662 }
663 {{/code}}
664
665 === Parameter getResultVariables ===
666
667 |(((
668 version
669 )))|(((
670 Requested version: 1
671 )))
672 |(((
673 contentPackage
674 )))|(((
675 Content package (zipped) as byte array.
676 )))
677 |(((
678 additionalParams
679 )))|(((
680 Reserved for future use.
681 )))
682
683 === ReturnValue getResultVariables ===
684
685 |(((
686 HashMap<String, String>
687 )))|(((
688 Map of result variables, key is the variable name, value the corresponding
689 value (HashMap is wrapped).
690 )))
691
692 == Wrapper ==
693
694 As the transmission of maps and lists generate problems via JAX-WS (lists filled by the customer are sent without any data and thus reach the server without data) they have to be wrapped.
695
696 === Wrapper for HashMap<String, String> ===
697
698 HashMapWrapper.java:
699
700 [[image:attach:HashMapWrapperjava.png]]
701
702 [[image:attach:HashMapWrapperjava2.png]]
703
704 === Wrapper for the ArrayList<ResultsForStudent> ===
705
706 ResultsForStudentsWrapper.java:
707
708 [[image:attach:ResultsForStudentsWrapperjava.png]]
709 {{/layout-cell}}
710 {{/layout-section}}
711 {{/layout}}
712 {{/sv-translation}}