Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

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