Benutzer-Werkzeuge

Webseiten-Werkzeuge


 [[entwicklung:techsheets:sophomorix4_json]] 

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen Revision Vorhergehende Überarbeitung
entwicklung:techsheets:sophomorix4_json [2017/11/30 20:03]
jeffbeck [Table]
entwicklung:techsheets:sophomorix4_json [2017/12/23 15:13] (aktuell)
jeffbeck [Table]
Zeile 1: Zeile 1:
 +{{tag> }}
 +
 +====== Returned data of sophomorix scripts ======
 +
 +===== JSON Objects =====
 +
 +
 +===== Why JSON? =====
 +
 +  * complex data can be returned
 +  * similar to perl/python data structures ​
 +  * less overhead than XML
 +
 +===== Interface =====
 +
 +  * JSON-Objects are printed to STDOUT
 +  * each script can return multiple JSON-Objects (CONFIG, RESULT, ....), see JSONINFO in the JSON-Object
 +  * between JSON-Objects there can be other printout
 +  * each JSON Object has a comment JSONCOMMENT
 +  * multivalues are JSON lists
 +    ​
 +
 +
 +===== Do return the JSON =====
 +
 +
 +To see the RETURN-JSON-Object on STDOUT the scripts must be called with one of the following options: ​
 +  * ''​--json''​ bzw. ''​-j'':​ human readable JSON-Object (pretty print)
 +  * ''​--json --json''​ bzw. ''​-jj'':​ compact JSON-Object (All in one line). 70% of the data size compared to ''​-j''​.
 +  * ''​--json --json --json''​ bzw. ''​-jjj'':​ returns perl hash with ''​Dumper''​ (Only for debugging!!)
 +
 +To additionally see the INFO-Object on STDOUT the scripts must be additionally be called with Option ''​-i''/''​--info''​
 +
 +If you give option ''​-i''/''​--info''​ without the JSON options (''​-j''/​...),​ you will see part or all data of the json-Object as console-formatted data, but NOT the JSON Object.
 +
 +The amount of console-formatted data depends on the verbosity level:
 +
 +  * without ''​-v'':​ basic output
 +  * ''​-v'':​ verbose output
 +  * ''​-vv'':​ very verbose output
 +  * To see really all data use option ''​-j''​ so see the INFO-JSON-Object
 +
 +The INFO-JSON-Object and the RETURN-JSON-Object are NOT affected by the verbosity level. They contain ALL data.
 + 
 +
 +==== 1) RETURN-JSON-Object ====
 +
 +
 +Every sophomorix-command can (see options) return a ''​RESULT''​-Object that contains:
 +
 +  * JSONINFO ​  -> RESULT
 +  * JSONCOMMENT -> created by script, ....
 +  * OUTPUT ​    -> List of Errors, Warnings, logging
 +    * type->​ERROR ​  -> Script ist stopped before doing anything
 +    * type->​WARNING
 +    * type->​LOGGING -> info
 +  * SUMMARY ​ -> What has been done
 +
 +For a list of what is omplemented see the table below  (column: RETURN-JSON)
 +=== Example ===
 +
 +In the package ''​sophomorix-developer''​ there is an example script:
 +
 +Here ist the JSON result object for schukonsole created by 
 +
 +  # sophomorix-JSON-example --json
 +
 +<​code>​
 +{
 +   "​JSONINFO"​ : "​RESULT",​
 +   "​OUTPUT"​ : [
 +      {
 +         "​MESSAGE_DE"​ : "​Fehlermeldung 1",
 +         "​NUMBER"​ : "​1",​
 +         "​MESSAGE_EN"​ : "ERROR 1",
 +         "​TYPE"​ : "​ERROR"​
 +      },
 +      {
 +         "​TYPE"​ : "​WARNING",​
 +         "​NUMBER"​ : "​1",​
 +         "​MESSAGE_DE"​ : "​Warnung 1",
 +         "​MESSAGE_EN"​ : "​Warning 1"
 +      },
 +      {
 +         "​TYPE"​ : "​LOG",​
 +         "​LOG"​ : "​Configuration file read!"
 +      },
 +      {
 +         "​MESSAGE_DE"​ : "​Fehlermeldung 2",
 +         "​NUMBER"​ : "​2",​
 +         "​MESSAGE_EN"​ : "ERROR 2",
 +         "​TYPE"​ : "​ERROR"​
 +      },
 +      {
 +         "​TYPE"​ : "​WARNING",​
 +         "​NUMBER"​ : "​2",​
 +         "​MESSAGE_DE"​ : "​Warnung 2",
 +         "​MESSAGE_EN"​ : "​Warning 2"
 +      }
 +   ],
 +   "​SUMMARY"​ : [
 +      {
 +         "​ERROR_COUNT"​ : {
 +            "​DESCRIPTION_PRE"​ : "Total number of Errors:",​
 +            "​FORMAT_TYPE"​ : 2,
 +            "​RESULT"​ : 0,
 +            "​RESULT_TYPE"​ : "​integer"​
 +         }
 +      },
 +      {
 +         "​ADD"​ : {
 +            "​FORMAT_TYPE"​ : 1,
 +            "​RESULT"​ : 123,
 +            "​DESCRIPTION_POST"​ : "users can be added in sophomorix.add",​
 +            "​RESULT_TYPE"​ : "​integer"​
 +         }
 +      },
 +      {
 +         "​UPDATE"​ : {
 +            "​RESULT"​ : 6,
 +            "​FORMAT_TYPE"​ : 1,
 +            "​DESCRIPTION_POST"​ : "users can be updated in sophomorix.update",​
 +            "​RESULT_TYPE"​ : "​integer"​
 +         }
 +      },
 +      {
 +         "​KILL"​ : {
 +            "​RESULT_TYPE"​ : "​integer",​
 +            "​RESULT"​ : 98,
 +            "​FORMAT_TYPE"​ : 1,
 +            "​DESCRIPTION_POST"​ : "users can be killed in sophomorix.kill"​
 +         }
 +      }
 +   ],
 +   "​JSONCOMMENT"​ : "The result hash of a script"​
 +}
 +</​code>​
 +
 +
 +==== 2) INFO-JSON-Object ====
 +
 +Farben:
 +
 +  * Blau: Schulkonsole-Anforderung (Schuko-Entwickler sagen was gebraucht wird)
 +  * Rot: Sophomorix-Anforderung (Sophomorix-Entwickler sagen was geliefert wird)
 +  * Orange: nicht so wichtig, later
 +  * Grün: Erledigt
 +
 +The following commands from package ''​sophomorix-samba''​ output INFO:
 +
 +=== Workflow commands (package ''​sophomorix-samba''​):​ ===
 +
 +^ command ​            ^ -i/​-ij ​                                                          ^ -iv/​-ivj ​ ^ -ivv/​-ivvj ​ ^ Processing ​                       ^ RETURN-JSON:​ -j  ^
 +| sophomorix-newfile ​ | @green:​--- ​                                                      | -         | -           | --                                | @orange:​todo ​    |
 +| sophomorix-check ​   | @green:​---/​config ​                                               | -         | -           | ---                               | @green:​done ​     |
 +| sophomorix-add ​     | @blue:users to add (oneliner)/​Todo:​ read sophomorix.add ​         | -         | -           | @green:​done ​                      | @green:​done ​     |
 +| sophomorix-update ​  | @blue: users to update (mutiliner)/​Todo:​ read sophomorix.update ​ | -         | -           | @green:​done ​                      | @green:​done ​     |
 +| sophomorix-kill ​    | @blue: users to kill (oneliner)/​Todo:​ read sophomorix.kill ​      | -         | -           | @green:​done ​                      | @green:​done ​     |
 +| sophomorix-device ​  | @green: overview of devices in AD                                |           ​| ​            | @green:done -> computer add/​kill ​ | @red:​todo ​       |
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +=== Object modifier scripts (package ''​sophomorix-samba''​):​ ===
 +
 +^ command ​                    ^ -i/​-ij ​                                   ^ -iv/​-ivj ​ ^ -ivv/​-ivvj ​ ^ Processing ​               ^ RETURN-JSON:​ -j  ^
 +| sophomorix-school ​          | @green: list of schools ​                  | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-admin ​           | @green: list of admins/​binduser ​          | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-class ​           | @green:list of classes ​                   | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-group ​           | @green:list of sophogroups ​               | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-managementgroup ​ | @green: list of mang.groups ​              | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-project ​         | @green:list of projects ​                  | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-session ​         | @green: list of sessions (-s: and users) ​ | -         | -           | @orange:​--- ​              | @red:​todo ​       |
 +| sophomorix-transfer ​        | ---                                       | ---       | ---         | @green: copying data      | @red:​todo ​       |
 +| sophomorix-exam-mode ​       | @orange: users in exammode ​               | -         | -           | @green: user adding done  | @red:​todo ​       |
 +| sophomorix-user ​            | @green: overview of users/-u ONE user     | -         | -           | ---                       | @orange:​todo ​    |
 +| sophomorix-room ​            | @orange: list of rooms                    | -         | -           | ---                       | @orange:​todo ​    |
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +=== Helper scripts (package ''​sophomorix-samba''​):​ ===
 +
 +^ command ​                 ^ -i/​-ij ​                  ^ -iv/​-ivj ​              ^ -ivv/​-ivvj ​ ^ Processing ​              ^ RETURN-JSON:​ -j  ^
 +| sophomorix-samba ​        | ???                      | -                      | -           | todo                     | NOT PLANNED ​     |
 +| sophomorix-cacls ​        | ???                      | -                      | -           | todo                     | NOT PLANNED ​     |
 +| sophomorix-objectsearch ​ | ???                      |                        |             ​| ​                         | NOT PLANNED ​     |
 +| sophomorix-passwd ​       | ???                      |                        |             ​| ​                         | todo             |
 +| sophomorix-repair ​       | ???                      |                        |             ​| ​                         | todo             |
 +| sophomorix-print ​        | nonexisting ​             |                        |             ​| ​                         | todo             |
 +| sophomorix-quota ​        | @green:calc list         ​| ​ @green:​detailed calc  |             | @green: via user update ​ | todo             |
 +| sophomorix-mail ​         | @green:​maillist/​account ​ |                        |             ​| ​                         | todo             |
 +| sophomorix-janitor ​      | nonexisting ​             |                        |             ​| ​                         | todo             |
 +| sophomorix-support ​      | nonexisting ​             |                        |             ​| ​                         | todo             |
 +| sophomorix-virusscan ​    | nonexisting ​             |                        |             ​| ​                         | todo             |
 +
 +
 +
 +
 +
 +
 +=== Package sophomorix-belwue-mail:​ ===
 +
 +^ command ​           ^ -i/​-ij ​ ^ -iv/​-ivj ​ ^ -ivv/​-ivvj ​ ^ Processing ​ ^ RETURN-JSON:​ -j  ^
 +| sophomorix-belwue ​ | ???     | -         | -           | todo        | todo             |
 +
 +
 +
 +
 +=== Package sophomorix-vampire:​ ===
 +
 +^ command ​               ^ -i/​-ij ​ ^ -iv/​-ivj ​ ^ -ivv/​-ivvj ​ ^ Processing ​ ^ RETURN-JSON:​ -j  ^
 +| sophomorix-vampire -i  | ???     | -         | -           | todo        | NOT PLANNED ​     |
 +
 +
 +
 +Todo:
 +
 +  * OK:Add every command here
 +  * plan what is to be outputted and in what level
 +  * implementing
 +    * all organisational Keys are WRITTEN in CAPITALLETTERS
 +    * how to do it:
 +      * create a perl hash
 +      * dump it with &​json_dump (as JSON to STDERR, see sophomorix.ini)->​ thats is for the schulkonsole ​
 +      * add a function to &​json_dump,​ $json=0, depending on JSONINFO
 +      * define this finction roughly, later perfectly
 +    *  show status of what is done and works and what not (red/green table background)
 +
 +
 +Where we have the following OBJECT-TYPE:​
 +  * USER
 +  * GROUP
 +  * SESSION
 +  * ONESESSION
 +  * DEVICE
 +  * ROOM
 +  * SCHOOL
 +  * ... possibly more
 +
 +The Object-List can contain none, one or more Objects
 +
 +The Object Type allows, that in ONE JSON-Object van be returned more object types, i.E. SESSIONS and USERS in that session
 +
 +Examples:
 +
 +  * USER_search_JSON()
 +    * Parameter: sophomorixRole (mehrere, die Filter zusammengebaut werden)
 +    * schoolname (selektiert user aus einer Schule, ist ein Zusatzfilter)
 +    * ? searchstring (sucht in allen irgendwie relevanten Feldern: vor/​nachname(UTF und ASCII), name description,​ ....)
 +    * ? Filteraddendum: ​ (sophomorixAdminClass=*7*) das durchgereicht wird
 +
 +For the console-output there are the following perl funcions:
 +
 +  * print_USER_from_JSON
 +    * Parameter:
 +      * verbosity_level
 +       * ohne: Einzeilig
 +         * Header schreiben
 +         * userliste abarbeiten: 1 Zeile je user
 +         * Footer schreiben
 +         * Erklärungen
 +       * -v/-vv
 +         * userliste abarbeiten: 1 mehrzeiliger Block je user, 
 +           * alle Infos -vv
 +           * viele infos -v
 +  * print_GROUP_from_JSON
 +  * ...
 +
 +Depending on the verbosity Level
 +  * print object in one line (if possible)
 +  * ''​-v''​ : print necessary Data in multiline
 +  * ''​-vv'':​ print more data
 +  * ''​-j''​ -> print the json Object
 +
 +
 +==== 3) More JSON-Objects ====
 +
 +=== sophomorix-check ===
 +
 +
 +sophomorix check can dump additionally the following data a JSON Objects
 +
 +  sophomorix-check -jj --dump-file ​             (User from the parsed files)
 +  sophomorix-check -jj --dump-AD ​               (User from AD)
 +  sophomorix-check -jj --dump-AD --dump-file ​   (Both User from the parsed files and User from AD)
 +
 +=== sophomorix-user ===
 +
 +  * Option ''​--list-teachers-by-year''​
 +
 +=== sophomorix-... ===
 +
 +====== sophomorix interna about logging an returning JSON Objects ======
 +
 +How return and logging ist handled in sophomorix-scripts
 +
 +
 +<​code>​
 +# create the return hash, add some basic information
 +my %sophomorix_result=&​result_sophomorix_init("​sophomorix-check"​);​
 +
 +    # Add warnings or errors to return->​OUTPUT
 +    &​result_sophomorix_add(\%sophomorix_result,"​WARNING|ERROR",​EXIT|NOEXIT ...);
 +   
 +        # if option -h/--help is given end exit
 +        ​
 +        ... more ways to exit: lock found, ...
 +    ​
 +        ######################################################################​
 +        # show info
 +        ######################################################################​
 +        ...
 +        # if option -i/--info ist given
 +        # create the info hash
 +        my %sophomorix_info=&​info_sophomorix_init();​
 +    ​
 +        ... fill the info hash
 +         
 +        # print info hash and result hash (console or JSON)
 +        &​info_sophomorix_print(\%sophomorix_info,​$json);​
 +        &​result_sophomorix_print(\%sophomorix_result,​$json);​
 +        # exit without logging
 +        exit;
 +
 +# Before changing anything, check if errors were so severe that we must exit
 +&​result_sophomorix_check_exit(\%sophomorix_result);​
 +
 +#################################################################################​
 +# change the system
 +#################################################################################​
 +# start logging to command.log
 +&​log_script_start(\@arguments,​\%sophomorix_result);​
 +
 +    ... do something
 +    # Add warnings or errors to return->​OUTPUT
 +    &​result_sophomorix_add(\%sophomorix_result,"​WARNING|ERROR",​EXIT|NOEXIT ...);
 +    ...
 +    # Add log lines to return->​OUTPUT
 +    &​result_sophomorix_add_log($ref_result,"​$0 terminated regularly"​);​
 +    ...
 +    # Add summary Header/​Result to return->​SUMMARY
 +    &​result_sophomorix_add_summary({...});​
 +
 +        # if something goes wrong exit with error
 +        # - log the exit to command.log
 +        # - print the JSON RESULT Object OR display result as console output
 +        # &​log_script_exit("",​1,​1,​0,​\@arguments,​\%sophomorix_result,​$json);​
 +
 +    ... continue doing something
 +    # Add warnings and errors to the return hash ()
 +    &​result_sophomorix_add(\%sophomorix_result,"​WARNING|ERROR",​EXIT|NOEXIT ...);
 +
 +
 +# end of script
 +# - log the exit to command.log
 +# - print the JSON RESULT Object OR display result as console output
 +&​log_script_end(\@arguments,​\%sophomorix_result,​$json);​
 +
 +</​code>​
 +
 +
 +
  
 [[entwicklung:techsheets:sophomorix4_json]] entwicklung/techsheets/sophomorix4_json.txt · Zuletzt geändert: 2017/12/23 15:13 von jeffbeck