Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

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