Univention Bugzilla – Bug 41739
ucsschool-import: write manual
Last modified: 2017-10-20 10:47:56 CEST
Create a manual that explains usage of the import tool and how to extend it. Include information about - school change - yearly class changes - ou-spanning user accounts
The documenation is ready for review in the OX Drive: Öff.Dateien → Fokus Schulträger → Technik → import-doku.odt Please review it before I convert it to the docbook format.
Added new document in 70985, 70990, 70993.
The document was published to http://docs.software-univention.de/en/ucsschool41R2.html . A warning was added to the text, that it is a pre-release, as it has not been QAed.
Wrong method names were fixed in r71260. Published with r71261.
For QA: it should be mentioned what defaults for ucsschoolRecordUID and ucsschoolSourceUID are used by a) the legacy import b) the UMC wizards
We got Feedback on Ticket#2016082421000167 related to the Import-Interface which I will highlight here: 1. The documentation should make more clearly that the counters [ALWAYSCOUNTER] and [COUNTER2] can be only used for username generation. 2. The behaviour of the sourceUID and recordUID and the importance for the whole import process must be more clearly as well. I know the term "more clearly" isn't a straight forward solution for both items. At least for the sourceUID I guess it is important to make explicit one main use case for customers. They often have few CSV-Files. Normally per school, sometimes even splitted into students and teachers and they try to import them. So, they have to set one specific sourceUID per file. That must be somehow more explicitly described (e.g. as example).
A description of the "Array"-Syntax -> [0] would be necessary in the chapter: http://docs.software-univention.de/ucsschool-import-handbuch-4.1R2.html#configuration:default_key At least that it is a python array syntax and it is possible to generate usernames with something like: [1] = second character [2:4] = Range (third & fourth character) [:3] = Range (first three characters)
(In reply to Michel Smidt from comment #7) > A description of the "Array"-Syntax -> [0] would be necessary in the chapter: > http://docs.software-univention.de/ucsschool-import-handbuch-4.1R2. > html#configuration:default_key > > At least that it is a python array syntax and it is possible to generate > usernames with something like: > [1] = second character > [2:4] = Range (third & fourth character) > [:3] = Range (first three characters) Already mentioned in the UCS@school manual: """Aus diesem Grund unterstützt die Importsoftware die Erzeugung von Attributen mit Hilfe von konfigurierbaren Schemata. Das Format ist das gleiche wie das bei den Benutzervorlagen eingesetzte (siehe [ucs-handbuch]).""" We should add a direct link to UCS manual section "Benutzervorlagen".
Created attachment 8831 [details] patch I attached a patch with various corrections of typos and comments. The image http://docs.software-univention.de/illustrations41/import_ablauf.png contains a typo "Neuen Password". Vielleicht wäre es sinnvoll zu schreiben, an wen sich dieses Dokument richtet. Programmierer? Ich würde die Kapitel, die Programmcode enthalten und da tief einsteigen ganz ans Ende stellen, damit man vorher noch z.B. die Schulwechsel-Kapitel (5,6,7) liest (was man nicht tun würde wenn man abbricht, falls man die Doku zu kompliziert findet). Überall ist die Rede von UDM-"Attribut". Wir haben aber UDM-"Properties"/"Eigenschaften" und LDAP-Attribute. Es gibt einen Fall wo UDM-Eigenschaft benutzt wird ("Univention Directory Manager-Eigenschaft sambahome").
The very first sentence is "Wie bereits im UCS@school-Handbuch für Administratoren beschrieben wurde, …". This seems a unfriendly introduction as it could lead to the impression that the appeal behind it is to read that manual first.
*** Bug 45506 has been marked as a duplicate of this bug. ***
(In reply to Sönke Schwardt-Krummrich from comment #5) > For QA: > it should be mentioned what defaults for ucsschoolRecordUID and > ucsschoolSourceUID are used by a) the legacy import b) the UMC wizards a) -> added a "caution" note in section 2.2 b) is not the case (In reply to Michel Smidt from comment #6) > We got Feedback on Ticket#2016082421000167 related to the Import-Interface > which I will highlight here: > 1. The documentation should make more clearly that the counters > [ALWAYSCOUNTER] and [COUNTER2] can be only used for username generation. I made this more clear in the options reference. Since 4.2 v4 the counter variables can also be used for email addresses. > 2. The behaviour of the sourceUID and recordUID and the importance for the > whole import process must be more clearly as well. > > I know the term "more clearly" isn't a straight forward solution for both > items. > At least for the sourceUID I guess it is important to make explicit one main > use case for customers. They often have few CSV-Files. Normally per school, > sometimes even splitted into students and teachers and they try to import > them. > So, they have to set one specific sourceUID per file. That must be somehow > more explicitly described (e.g. as example). Three examples for sourceUID usage were added to the chapter "2.2. Zuordnung von Benutzern des Quellverzeichnisses zu UCS@school-Benutzern". (In reply to Sönke Schwardt-Krummrich from comment #8) > (In reply to Michel Smidt from comment #7) > > A description of the "Array"-Syntax -> [0] would be necessary in the chapter: > > http://docs.software-univention.de/ucsschool-import-handbuch-4.1R2. > > html#configuration:default_key > > > > At least that it is a python array syntax and it is possible to generate > > usernames with something like: > > [1] = second character > > [2:4] = Range (third & fourth character) > > [:3] = Range (first three characters) > > Already mentioned in the UCS@school manual: > """Aus diesem Grund unterstützt die Importsoftware die Erzeugung von > Attributen mit Hilfe von konfigurierbaren Schemata. Das Format ist das > gleiche wie das bei den Benutzervorlagen eingesetzte (siehe > [ucs-handbuch]).""" > > We should add a direct link to UCS manual section "Benutzervorlagen". I added both a hint about the brackets as well as a hyperlink to the ucs manual. (In reply to Florian Best from comment #9) > Created attachment 8831 [details] > patch > > I attached a patch with various corrections of typos and comments. Thanks a lot. > The image > http://docs.software-univention.de/illustrations41/import_ablauf.png > contains a typo "Neuen Password". Fixed > Vielleicht wäre es sinnvoll zu schreiben, an wen sich dieses Dokument > richtet. Programmierer? Administrators and programmers. I added a section "Zielgruppe". > Ich würde die Kapitel, die Programmcode enthalten und da tief einsteigen > ganz ans Ende stellen, damit man vorher noch z.B. die Schulwechsel-Kapitel > (5,6,7) liest (was man nicht tun würde wenn man abbricht, falls man die Doku > zu kompliziert findet). I move the chapter about extending the code to the end of the document. > Überall ist die Rede von UDM-"Attribut". Wir haben aber > UDM-"Properties"/"Eigenschaften" und LDAP-Attribute. Im UCS Handbuch wird im Zusammenhang mit UDM auch von "Attributen" gesprochen. Es ist das passende deutsche Wort. "Eigenschaften" hilft dem Verständnis nicht. > Es gibt einen Fall wo UDM-Eigenschaft benutzt wird ("Univention Directory > Manager-Eigenschaft sambahome"). Habe UDM-Eigenschaft mit UDM-Attribut ersetzt. Dann ist es in dem Dokument konsistent. ucsschool/4.2 3583e0df : update import manual ucsschool/4.2 1d1c184e : programlisting not allowed as child of simpara ucsschool/4.2 da94972f : syntax fixes ucsschool/4.2 868ee0bf : add space in word, allowing line break to prevent table cell overflow docbook/master 96495733 : dictionary updates HTML: http://jenkins.knut.univention.de:8080/job/UCSschool%204.2/job/Manual/11/artifact/webroot/ucsschool-import-handbuch-4.2.html#extending PDF: http://jenkins.knut.univention.de:8080/job/UCSschool%204.2/job/Manual/11/artifact/webroot/ucsschool-import-handbuch-4.2.pdf
Can you please make the examples in 3.2 more distinguishable? I cannot really visibly see where the second example starts. Maybe "unangetastet" → "unverändert"/"erhalten" ? Can you set the document <title>? typo: "ohne dass Änderungen am UCS@school-Benutzern" s/am/an/ "Geschachtelte Konfigurationsvariablen" → Verschachtelte? I think the chapter "4.7. Benutzer löschen" is wrong with out latest changes? Better use "service" instead of "invoke-rc.d".
(In reply to Florian Best from comment #13) > Can you please make the examples in 3.2 more distinguishable? I cannot > really visibly see where the second example starts. That's a bug in the HTML generation code. Please see the PDF. > Maybe "unangetastet" → "unverändert"/"erhalten" ? fixed: 23c001fe > Can you set the document <title>? It is set. That's another bug in the HTML generation code. Please see the PDF. > typo: "ohne dass Änderungen am UCS@school-Benutzern" > s/am/an/ fixed: 23c001fe > "Geschachtelte Konfigurationsvariablen" → Verschachtelte? fixed: 23c001fe > I think the chapter "4.7. Benutzer löschen" is wrong with out latest changes? The correct text was in ad1c9a3c. It didn't end up in build #11, but in a later build (which was released to docs.univention.de). The OP of Bug #45467 explicitly didn't want me to merge it to 4.2, and did it later himself, when releasing. > Better use "service" instead of "invoke-rc.d". fixed: 23c001fe [4.2 23c001fe] Bug #41739: fix typos/wording → http://jenkins.knut.univention.de:8080/job/UCSschool%204.2/job/Manual/16/artifact/webroot/ucsschool-import-handbuch-4.2.pdf
OK