Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

Version 380.1 von sandra_riediger am 17.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 style="square" maxLevel="5" 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
396 {{/layout-cell}}
397 {{/layout-section}}
398
399 {{layout-section ac:type="single"}}
400 {{layout-cell}}
401
402
403 == General ==
404
405 The API to the ONYX WebReporter enables the communication between the LMS and the reporter. Therefore, a couple of commands will be executed:
406
407 |(((
408 armSite
409 )))|(((
410 Registration of sequence requests at the ONYX reporter
411 )))
412 |(((
413 initiateSite
414 )))|(((
415 Initiates the reporter session (transmission of the CP).
416 )))
417 |(((
418 disarmSite
419 )))|(((
420 Release of all reporter resources for this session.
421 )))
422 |(((
423 getResultValues
424 )))|(((
425 Returns all or all requested results for the test. Condition: there is exactly one student in list transmitted in the initiateSite.
426 )))
427 |(% colspan="1" %)(% colspan="1" %)
428 (((
429 getResultVariables
430 )))|(% colspan="1" %)(% colspan="1" %)
431 (((
432 Returns all or all requested outcome variables for the test. No armSite, initiateSite or disarmSite is necessary.
433 )))
434
435 == Connection to the LMS ==
436
437 {{code title="Anmeldung des LMS" language="xml"}}
438 @WebMethod(operationName = „armSite")
439 public String armSite(
440 @WebParam(name = „version") final Integer version,
441 @WebParam(name = „userId") final String userId,
442 @WebParam(name = „optionalRole") final Integer role,
443 @WebParam(name = „secretToShare") final String secretToShare,
444 @WebParam(name = „optionalUserLastName") final String userLastName,
445 @WebParam(name = „optionalUserFirstName") final String userFirstName,
446 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
447 }
448 {{/code}}
449
450 === Parameter armSite ===
451
452 |(((
453 version
454 )))|(((
455 Requested version: 1
456 )))
457 |(((
458 userId
459 )))|(((
460 UserId of the requested reporter user
461 )))
462 |(((
463 optionalRole
464 )))|(((
465 Optional. User role. 0=student, 1=tutor
466 )))
467 |(((
468 secretToShare
469 )))|(((
470 Shared secret. Has to remain identical for every communication.
471 )))
472 |(((
473 optionalUserLastName
474 )))|(((
475 Optional. User lastname.
476 )))
477 |(% colspan="1" %)(% colspan="1" %)
478 (((
479 optionalUserFirstName
480 )))|(% colspan="1" %)(% colspan="1" %)
481 (((
482 Optional. User firstname.
483 )))
484 |(% colspan="1" %)(% colspan="1" %)
485 (((
486 additionalParams
487 )))|(% colspan="1" %)(% colspan="1" %)
488 (((
489 Reserved for future use.
490 )))
491
492 === ReturnValue armSite ===
493
494 |(((
495 String
496 )))|(((
497 Session ID that has to be used to mark any further reporter call.
498 )))
499
500 == Initialisation through LMS ==
501
502 {{code title="Initialisierung durch LMS" language="xml"}}
503 @WebMethod(operationName = „initiateSite")
504 public String initiateSite(
505 @WebParam(name = „version") final Integer version,
506 @WebParam(name = „sessionId") final String sessionId,
507 @WebParam(name = „secretToShare") final String secretToShare,
508 @WebParam(name = „students") final ArrayList<ResultsForStudent> students,
509 @WebParam(name = „optionalContentPackage") final byte[] contentPackage,
510 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
511 }
512 {{/code}}
513
514 === Parameter initiateSite ===
515
516 |(((
517 version
518 )))|(((
519 Requested version: 1
520 )))
521 |(% colspan="1" %)(% colspan="1" %)
522 (((
523 sessionId
524 )))|(% colspan="1" %)(% colspan="1" %)
525 (((
526 SessionId, as returned by armSite.
527 )))
528 |(((
529 secretToShare
530 )))|(((
531 Shared secret. Has to remain identical at every communication.
532 )))
533 |(((
534 students
535 )))|(((
536 List of students with their results. See below.
537 )))
538 |(((
539 optionalContentPackage
540 )))|(((
541 Optional. Content Package (zipped) as byte array.
542 )))
543 |(((
544 additionalParams
545 )))|(((
546 Reserved for future use.
547 )))
548
549 === ReturnValue initiateSite ===
550
551 |(((
552 String
553 )))|(((
554 Absolute URL of the reporter site for the frame. It has to be enriched by the LMS with the following URLparameters:
555
556 * sid: Session ID as returned by armSite
557 * (((
558 uid: Student ID as registrated in the initiateSite at the ONYX Reporter.
559 )))
560 )))
561
562 {{code language="xml"}}
563 public class ResultsForStudent {
564    private String studentId = „";
565    private String firstname = „";
566    private String lastname = „";
567    private String groupname = „";
568    private String tutorname = „";
569    private File contentFile = null;
570    private byte[] resultsFile = null;
571 }
572 {{/code}}
573
574 == Deconnection through the LMS ==
575
576
577
578 {{code}}
579 @WebMethod(operationName = „disarmSite")
580 public Boolean disarmSite(
581 @WebParam(name = „version") final Integer version,
582 @WebParam(name = „sessionId") final String sessionId,
583 @WebParam(name = „secretToShare") final String secretToShare,
584 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
585 }
586 {{/code}}
587
588
589
590 === Parameter disarmSite ===
591
592 |(((
593 version
594 )))|(((
595 Requested version: 1
596 )))
597 |(% colspan="1" %)(% colspan="1" %)
598 (((
599 sessionId
600 )))|(% colspan="1" %)(% colspan="1" %)
601 (((
602 SessionId, as returned by armSite.
603 )))
604 |(((
605 secretToShare
606 )))|(((
607 Shared secret. Has to remain identical at every communication.
608 )))
609 |(((
610 additionalParams
611 )))|(((
612 Reserved for future use.
613 )))
614
615 === ReturnValue disarmSite ===
616
617 |(((
618 Boolean
619 )))|(((
620 True if successful, otherwise false.
621 )))
622
623 == Request of learning results through the LMS ==
624
625 {{code title="Abfrage von Lernerresultaten durch LMS" language="xml"}}
626  @WebMethod(operationName = „getResultValues")
627 public HashMapWrapper getResultValues(
628 @WebParam(name = „version") final Integer version,
629 @WebParam(name = „sessionId") final String sessionId,
630 @WebParam(name = „secretToShare") final String secretToShare,
631 @WebParam(name = „requestedValues") final HashMap<String, String>
632 requestedValues,
633 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
634 }
635 {{/code}}
636
637 === Parameter getResultValues ===
638
639 |(((
640 version
641 )))|(((
642 Requested version: 1
643 )))
644 |(% colspan="1" %)(% colspan="1" %)
645 (((
646 sessionId
647 )))|(% colspan="1" %)(% colspan="1" %)
648 (((
649 SessionId, as returned by armSite.
650 )))
651 |(((
652 secretToShare
653 )))|(((
654 Shared secret. Has to remain identical at every communication.
655 )))
656 |(((
657 requestedValues
658 )))|(((
659 Can be empty, thus all result variables will be returned. If it contains keys, only those will be returned.
660 )))
661 |(((
662 additionalParams
663 )))|(((
664 Reserved for future use.
665 )))
666
667 === ReturnValue getResultValues ===
668
669 |(((
670 HashMap<String, String>
671 )))|(((
672 Map of result variables, key is the variable name, value the corresponding value (HashMap is wrapped)
673 )))
674
675 == Request of result variables through the LMS ==
676
677 {{code title="Abfrage von Ergebnisvariablen durch LMS" language="xml"}}
678  @WebMethod(operationName = „getResultVariables")
679 public HashMapWrapper getResultVariables(
680 @WebParam(name = „version") final Integer version,
681 @WebParam(name = „contentPackage") final byte[] contentPackage,
682 @WebParam(name = „additionalParams") final HashMapWrapper additionalParams) {
683 }
684 {{/code}}
685
686 === Parameter getResultVariables ===
687
688 |(((
689 version
690 )))|(((
691 Requested version: 1
692 )))
693 |(((
694 contentPackage
695 )))|(((
696 Content package (zipped) as byte array.
697 )))
698 |(((
699 additionalParams
700 )))|(((
701 Reserved for future use.
702 )))
703
704 === ReturnValue getResultVariables ===
705
706 |(((
707 HashMap<String, String>
708 )))|(((
709 Map of result variables, key is the variable name, value the corresponding
710 value (HashMap is wrapped).
711 )))
712
713 == Wrapper ==
714
715 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.
716
717 === Wrapper for HashMap<String, String> ===
718
719 HashMapWrapper.java:
720
721 [[image:attach:HashMapWrapperjava.png]]
722
723 [[image:attach:HashMapWrapperjava2.png]]
724
725 === Wrapper for the ArrayList<ResultsForStudent> ===
726
727 ResultsForStudentsWrapper.java:
728
729 [[image:attach:ResultsForStudentsWrapperjava.png]]
730 {{/layout-cell}}
731 {{/layout-section}}
732 {{/layout}}
733 {{/sv-translation}}