Zum Inhalt springen

Wiki-Quellcode von Schnittstelle ONYX Reporter

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