diff --git a/docs/access_concept.md b/docs/access_concept.md new file mode 100644 index 0000000..9bdff36 --- /dev/null +++ b/docs/access_concept.md @@ -0,0 +1,171 @@ +# Berechtigungskonzept + +## Gruppen / Rollen - Wie funktioniert das? + +In hitobito können komplexe hierarchische Organisationen abgebildet werden. Alles basiert darauf, dass wir verschiedene Gruppentypen zulassen, welche auch definieren welche Rollen zur Verfügung stehen. + +- Jede Organisation kann aus mehreren Ebenen bestehen, z. B. Dachverband, Kantonalverband (, optionale Zwischenstufen wie Regionen) und Ortsgruppen. +- Jede Ebene kann intern wieder ihre innere Struktur haben, es gibt einen Vorstand, Arbeitsgruppen, Mitgliederlisten, Kontaktlisten. +- Jede Person hat eine oder mehrere Rollen. Diese Rollen definieren, wen man sehen kann, und von vom man gesehen wird. + +Hier einige Beispiele, wie das aussehen kann. + +### Karin ist Geschäftsleiter direkt im Dachverband + +technisch: `layer_and_below_full` direkt in Dachverband, inkl. `contact_data` + +#### Karin sieht: + +```{image} images/TopLayerFullRestrained.png +``` + +Karin hat vollen Zugriff auf ihrer Ebene und auf alle darunter liegenden Ebenen. Dadurch kann sie alle Personen im Dachverband, in Regionen und auf oberster Ebene der Ortsgruppen sehen und ändern. +Nicht sichtbar und änderbar sind für sie alle Personen, die innerhalb einer Ortsgruppe, also in einer Untergruppe unter der Ortsgruppe, aufgehängt sind. +Da Karin's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +#### Karin sehen: + +Karin ist für alle anderen Personen mit Rechten innerhalb der Ebene des Dachverbands sichtbar. +Auf Grund der Kontaktrelevanz von Karin's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +#### Luca ist ein Mitglied in einem Gremium im Dachverband + +technisch: `group_read` in Gremium ohne `contact_data` + +#### Luca sieht: + +```{image} images/TopLayerSubgroup.png +``` + +Luca sieht alle Mitglieder und Leitung innerhalb des Gremiums. Sonst sieht er niemanden ausserhalb des Gremiums. + +#### Luca sehen: + +Luca ist für Personen mit vollen Rechten (`layer_full` oder `layer_and_below_full`) für die Dachverbandsebene sicht- und änderbar. Zusätzlich kann die Leitung innerhalb seines Gremiums seine Daten einsehen und ändern (`group_full`). Seine Kollegen mit gleicher Rolle im Gremium sehen seine Daten, können diese aber nicht ändern (`group_read`) + +### Maria hat eine Rolle in der Region + +technisch: `group_read` inkl. `contact_data` + +#### Maria sieht + +```{image} images/MidlayerGroup.png +``` + +Maria kann alle Mitglieder ihrer Gruppe sehen, also alle Mitarbeitenden auf Regionsebene. + +Da Maria's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +#### Maria sehen + +Maria ist für alle anderen Personen mit Rechten innerhalb der Ebene des Dachverbands sichtbar. +Auf Grund der Kontaktrelevanz von Maria's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +### Petra leitet ein Gremium in der Region + +technisch: `layer_read` inkl. `contact_data` + +#### Petra sieht: + +```{image} images/MidlayerFull.png +``` + +Petra sieht alle Personen in der Region inkl. Personen in allfälligen Untergruppen. Sie sieht jedoch keine Personen in Ortsgruppen, welche der Region angehängt sind. + +Da Petra's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +#### Petra sehen + +Petra ist für Personen auf kantonaler oder Dachverbandsebene sichtbar, welche eine Rolle mit Zugriff auf untergeordnete Ebenen besitzen (`layer_and_below`). Zudem sehen alle Personen in der Region, die Rechte innerhalb der Gruppe oder der Ebene besitzen, ihre Daten. + +Auf Grund der Kontaktrelevanz von Petra's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +### Anna leitet eine Ortsgruppe + +technisch: `layer_full` incl. `contact_data` + +#### Anna sieht + +```{image} images/LowLayerFull.png +``` + +Anna sieht alle Personen innerhalb der Ortsgruppe. + +Da Anna's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +#### Anna sehen + +Anna ist für Personen oberhalb der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen unterhalb ihrer Ebene zu sehen. +Zudem können ihre Kolleginnen und Kollegen innerhalb der Ortsgruppe ihre Daten sehen, falls sie das Recht für die Gruppe oder die Ebene besitzen. +Auf Grund der Kontaktrelevanz von Anna's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +### Franz leitet eine Einheit innerhalb einer Ortsgruppe + +technisch: `layer_read` (ohne `contact_data`) + +#### Franz sieht + +```{image} images/LowLayerFull.png +``` + +Franz sieht alle Personen innerhalb der Ortsgruppe, kann diese aber nicht ändern. + +#### Franz sehen + +Franz ist für Personen in der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen innerhalb der ganzen Ebene zu sehen. Personen oberhalb der Ortsgruppe können Franz nicht sehen. + +### Jonas ist Mitglied innerhalb einer Gruppe in der Ortsgruppe + +technisch: `none` + +#### Jonas sieht + +```{image} images/LowLayerNone.png +``` + +Jonas sieht keine weiteren Personen. + +#### Jonas sehen + +Jonas ist für Personen in der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen innerhalb der ganzen Ebene zu sehen. Personen oberhalb der Ortsgruppe können Jonas nicht sehen. + +## Kumulierung von Rollen innerhalb der Struktur + +Die Zugriffe durch mehrere Rollen kumulieren sich. So ist ein Mitglied einer Ortsgruppe, das gleichzeitig in der Region aktiv ist, trotzdem für die Regionsleitung sichtbar. + +## Daten in Anlässen (Lagern, Kursen) + +Teilnehmer in einem Anlass können die Teilnehmerliste einsehen und sehen dort ihre gegenseitigen Kontaktdaten. Die Daten sind nur im Kontext "Anlass" sichtbar, wenn über die Teilnehmerliste zur Person navigiert wird. +Im Kontext einer "Gruppe", wenn über die Gruppenhierarchie zur Person navigiert wird, gelten die Zugriffsrechte gemäss den strukturbasierten Rechten oben. + +## Spezialfall `Contact_Data` + +Ist die Rolle einer Person als kontaktrelevant markiert, so hat diese Person auf alle anderen Personen mit kontaktrelevanten Rollen Zugriff. Gleichzeitig ist sie auch für alle anderen Personen mit kontaktrelevanten Rollen sichtbar. +Dies umfasst Rollen, welche häufig im Austausch mit Personen aus anderen Ortsgruppen stehen. + +## Spezialfall `finance` + +Erlaubt auf der entsprechenden Ebene Rechnungen zu erstellen und einzusehen. + +## Spezialfall `impersonation` + +Darf andere Accounts temporär übernehmen, z. B. für Support Aufgaben oder für Tests. Dies ist eine sehr mächtige Funktion und sollte nur an klar definierte Rollen vergeben werden. + +## Security: Zugriffsanfragen und manuelle Freigabe + +Angenommen, Anna möchte unberechtigt Zugriff auf die persönlichen Daten von John bekommen. Dazu kann Anna John einfach in einer Gruppe, einem Anlass oder Abo hinzufügen, in der sie Zugriffsrechte hat. Dieses Datenschutz-Problem kann in hitobito mit den "manuellen Freigaben" verhindert werden. + +Beim Hinzufügen von John in Gruppen, Anlässen und Abos überprüft hitobito Johns Haupt-Rolle (die Rolle die mit einem Stern markiert ist). Falls John keine aktive Rolle mehr hat, überprüft hitobito stattdessen die letzte Rolle die noch aktiv war. +Es wird überprüft, ob in der Ebene dieser Rolle die manuellen Freigaben aktiviert sind. Beispiel: John hat seine Haupt-Rolle in der Arbeitsgruppe "Saturn" des Vereins "Sterngucker Luzern". Die manuellen Freigaben können bei der Ebene (Verein Sterngucker Luzern) auf dem Anfragen-Tab aktiviert werden. + +Sind manuelle Freigaben in der Ebene aktiviert, dann wird John nicht direkt in die neue fremde Gruppe, Anlass oder Abo hinzugefügt, sondern es wird eine Zugriffsanfrage ausgelöst. Anna sieht dann folgende Nachricht: + +```{image} images/pending_role_approval.png +``` + +Alle Personen die auf dem Anfragen-Tab ausgewählt sind, sowie John falls er einen Login hat, bekommen ein E-Mail welches darüber informiert dass Anna John an einem neuen Ort hinzufügen will. Von diesem E-Mail aus oder auf dem Anfragen-Tab der Gruppe kann die Zugriffsanfrage akzeptiert oder abgelehnt werden. + +```{image} images/approvals_tab.png +``` + +So bekommt Anna nie unberechtigten Zugriff auf die Personendaten von John. Das Ganze funktioniert aber nur, wenn die manuellen Freigaben auf der Ebene aktiviert sind. Es wird keine Zugriffsanfrage ausgelöst wenn Anna bereits vorher Zugriff auf John hat (z.B. wenn beide eine Rolle mit `contact_data` haben). diff --git a/docs/access_concept.rst b/docs/access_concept.rst new file mode 100644 index 0000000..8a3e239 --- /dev/null +++ b/docs/access_concept.rst @@ -0,0 +1,198 @@ +Berechtigungskonzept +======================= + + +Gruppen / Rollen - Wie funktioniert das? +------------------------------------------------- + +In hitobito können komplexe hierarchische Organisationen abgebildet werden. Alles basiert darauf, dass wir verschiedene Gruppentypen zulassen, welche auch definieren welche Rollen zur Verfügung stehen. + +- Jede Organisation kann aus mehreren Ebenen bestehen, z. B. Dachverband, Kantonalverband (, optionale Zwischenstufen wie Regionen) und Ortsgruppen. +- Jede Ebene kann intern wieder ihre innere Struktur haben, es gibt einen Vorstand, Arbeitsgruppen, Mitgliederlisten, Kontaktlisten. +- Jede Person hat eine oder mehrere Rollen. Diese Rollen definieren, wen man sehen kann, und von vom man gesehen wird. + +Hier einige Beispiele, wie das aussehen kann. + + +Karin ist Geschäftsleiter direkt im Dachverband +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``layer_and_below_full`` direkt in Dachverband, inkl. ``contact_data`` + + +Karin sieht: +^^^^^^^^^^^^^^^^^^ + +.. image:: images/TopLayerFullRestrained.png + +Karin hat vollen Zugriff auf ihrer Ebene und auf alle darunter liegenden Ebenen. Dadurch kann sie alle Personen im Dachverband, in Regionen und auf oberster Ebene der Ortsgruppen sehen und ändern. +Nicht sichtbar und änderbar sind für sie alle Personen, die innerhalb einer Ortsgruppe, also in einer Untergruppe unter der Ortsgruppe, aufgehängt sind. +Da Karin's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + + + +Karin sehen: +^^^^^^^^^^^^^^^^^^ + +Karin ist für alle anderen Personen mit Rechten innerhalb der Ebene des Dachverbands sichtbar. +Auf Grund der Kontaktrelevanz von Karin's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +Luca ist ein Mitglied in einem Gremium im Dachverband +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +technisch: ``group_read`` in Gremium ohne ``contact_data`` + +Luca sieht: +^^^^^^^^^^^^^^^^^ + +.. image:: images/TopLayerSubgroup.png + +Luca sieht alle Mitglieder und Leitung innerhalb des Gremiums. Sonst sieht er niemanden ausserhalb des Gremiums. + +Luca sehen: +^^^^^^^^^^^^^^^^ + +Luca ist für Personen mit vollen Rechten (``layer_full`` oder ``layer_and_below_full``) für die Dachverbandsebene sicht- und änderbar. Zusätzlich kann die Leitung innerhalb seines Gremiums seine Daten einsehen und ändern (``group_full``). Seine Kollegen mit gleicher Rolle im Gremium sehen seine Daten, können diese aber nicht ändern (``group_read``) + +Maria hat eine Rolle in der Region +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``group_read`` inkl. ``contact_data`` + +Maria sieht +^^^^^^^^^^^^^^^ + +.. image:: images/MidlayerGroup.png + +Maria kann alle Mitglieder ihrer Gruppe sehen, also alle Mitarbeitenden auf Regionsebene. + +Da Maria's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +Maria sehen +^^^^^^^^^^^^^^ + +Maria ist für alle anderen Personen mit Rechten innerhalb der Ebene des Dachverbands sichtbar. +Auf Grund der Kontaktrelevanz von Maria's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +Petra leitet ein Gremium in der Region +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``layer_read`` inkl. ``contact_data`` + +Petra sieht: +^^^^^^^^^^^^^^^^ + +.. image:: images/MidlayerFull.png + + +Petra sieht alle Personen in der Region inkl. Personen in allfälligen Untergruppen. Sie sieht jedoch keine Personen in Ortsgruppen, welche der Region angehängt sind. + +Da Petra's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +Petra sehen +^^^^^^^^^^^^^^^ + +Petra ist für Personen auf kantonaler oder Dachverbandsebene sichtbar, welche eine Rolle mit Zugriff auf untergeordnete Ebenen besitzen (``layer_and_below``). Zudem sehen alle Personen in der Region, die Rechte innerhalb der Gruppe oder der Ebene besitzen, ihre Daten. + +Auf Grund der Kontaktrelevanz von Petra's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +Anna leitet eine Ortsgruppe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``layer_full`` incl. ``contact_data`` + +Anna sieht +^^^^^^^^^^^^^^ + +.. image:: images/LowLayerFull.png + + +Anna sieht alle Personen innerhalb der Ortsgruppe. + +Da Anna's Rolle als kontaktrelevant geführt ist (sog. ContactData-Flag, siehe unten), kann sie alle anderen Personen mit Kontaktrelevanz sehen, unabhängig von deren Position innerhalb der Struktur. + +Anna sehen +^^^^^^^^^^^^^ + +Anna ist für Personen oberhalb der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen unterhalb ihrer Ebene zu sehen. +Zudem können ihre Kolleginnen und Kollegen innerhalb der Ortsgruppe ihre Daten sehen, falls sie das Recht für die Gruppe oder die Ebene besitzen. +Auf Grund der Kontaktrelevanz von Anna's Rolle ist sie ebenfalls für alle anderen kontaktrelevanten Rollen sichtbar. + +Franz leitet eine Einheit innerhalb einer Ortsgruppe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``layer_read`` (ohne ``contact_data``) + +Franz sieht +^^^^^^^^^^^^^^^^^^^^^ +.. image:: images/LowLayerFull.png + +Franz sieht alle Personen innerhalb der Ortsgruppe, kann diese aber nicht ändern. + +Franz sehen +^^^^^^^^^^^^^^^^^^^^ +Franz ist für Personen in der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen innerhalb der ganzen Ebene zu sehen. Personen oberhalb der Ortsgruppe können Franz nicht sehen. + + +Jonas ist Mitglied innerhalb einer Gruppe in der Ortsgruppe +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +technisch: ``none`` + +Jonas sieht +^^^^^^^^^^^^^^^^^^^^ + +.. image:: images/LowLayerNone.png + + +Jonas sieht keine weiteren Personen. + +Jonas sehen +^^^^^^^^^^^^^^^^^^^^ + +Jonas ist für Personen in der Ortsgruppe sichtbar, falls diese das Recht besitzen, Personen innerhalb der ganzen Ebene zu sehen. Personen oberhalb der Ortsgruppe können Jonas nicht sehen. + +Kumulierung von Rollen innerhalb der Struktur +------------------------------------------------- + +Die Zugriffe durch mehrere Rollen kumulieren sich. So ist ein Mitglied einer Ortsgruppe, das gleichzeitig in der Region aktiv ist, trotzdem für die Regionsleitung sichtbar. + +Daten in Anlässen (Lagern, Kursen) +------------------------------------------------- + +Teilnehmer in einem Anlass können die Teilnehmerliste einsehen und sehen dort ihre gegenseitigen Kontaktdaten. Die Daten sind nur im Kontext "Anlass" sichtbar, wenn über die Teilnehmerliste zur Person navigiert wird. +Im Kontext einer "Gruppe", wenn über die Gruppenhierarchie zur Person navigiert wird, gelten die Zugriffsrechte gemäss den strukturbasierten Rechten oben. + +Spezialfall ``Contact_Data`` +------------------------------------------------- + +Ist die Rolle einer Person als kontaktrelevant markiert, so hat diese Person auf alle anderen Personen mit kontaktrelevanten Rollen Zugriff. Gleichzeitig ist sie auch für alle anderen Personen mit kontaktrelevanten Rollen sichtbar. +Dies umfasst Rollen, welche häufig im Austausch mit Personen aus anderen Ortsgruppen stehen. + +Spezialfall ``finance`` +------------------------------------------------- + +Erlaubt auf der entsprechenden Ebene Rechnungen zu erstellen und einzusehen. + +Spezialfall ``impersonation`` +------------------------------------------------- + +Darf andere Accounts temporär übernehmen, z. B. für Support Aufgaben oder für Tests. Dies ist eine sehr mächtige Funktion und sollte nur an klar definierte Rollen vergeben werden. + +Security: Zugriffsanfragen und manuelle Freigabe +------------------------------------------------- + +Angenommen, Anna möchte unberechtigt Zugriff auf die persönlichen Daten von John bekommen. Dazu kann Anna John einfach in einer Gruppe, einem Anlass oder Abo hinzufügen, in der sie Zugriffsrechte hat. Dieses Datenschutz-Problem kann in hitobito mit den "manuellen Freigaben" verhindert werden. + +Beim Hinzufügen von John in Gruppen, Anlässen und Abos überprüft hitobito Johns Haupt-Rolle (die Rolle die mit einem Stern markiert ist). Falls John keine aktive Rolle mehr hat, überprüft hitobito stattdessen die letzte Rolle die noch aktiv war. +Es wird überprüft, ob in der Ebene dieser Rolle die manuellen Freigaben aktiviert sind. Beispiel: John hat seine Haupt-Rolle in der Arbeitsgruppe "Saturn" des Vereins "Sterngucker Luzern". Die manuellen Freigaben können bei der Ebene (Verein Sterngucker Luzern) auf dem Anfragen-Tab aktiviert werden. + +Sind manuelle Freigaben in der Ebene aktiviert, dann wird John nicht direkt in die neue fremde Gruppe, Anlass oder Abo hinzugefügt, sondern es wird eine Zugriffsanfrage ausgelöst. Anna sieht dann folgende Nachricht: + +.. image:: images/pending_role_approval.png + +Alle Personen die auf dem Anfragen-Tab ausgewählt sind, sowie John falls er einen Login hat, bekommen ein E-Mail welches darüber informiert dass Anna John an einem neuen Ort hinzufügen will. Von diesem E-Mail aus oder auf dem Anfragen-Tab der Gruppe kann die Zugriffsanfrage akzeptiert oder abgelehnt werden. + +.. image:: images/approvals_tab.png + +So bekommt Anna nie unberechtigten Zugriff auf die Personendaten von John. Das Ganze funktioniert aber nur, wenn die manuellen Freigaben auf der Ebene aktiviert sind. Es wird keine Zugriffsanfrage ausgelöst wenn Anna bereits vorher Zugriff auf John hat (z.B. wenn beide eine Rolle mit `contact_data` haben). diff --git a/docs/ebics.md b/docs/ebics.md new file mode 100644 index 0000000..f472b3a --- /dev/null +++ b/docs/ebics.md @@ -0,0 +1,64 @@ +# EBICS Schnittstelle + +## Allgemeines + +Hitobito lässt sich mit einem Bank- oder Postkonto verbinden. Dies bedeutet folgendes: + +Wird eine Zahlung über hitobito ausgelöst und vom Empfänger bezahlt, ist diese Information nicht mehr nur +im Bankkonto ersichtlich, sondern wird auch im hitobito ausgewiesen. Hitobito kann so die Buchhaltung +unterstützen, da damit die Zahlungseingänge zentral und personifiziert überwacht werden können. + +Als Schnittstelle verwendet hitobito die Technologie EBICS. EBICS ist eine standardisierte Schnittstelle zu +Finanzapplikationen und wird in der Schweiz von beinahe allen Banken angeboten (Ausnahmen sind +möglich, uns aber nicht bekannt). Mehr Informationen zu EBICS findet ihr auf den Webseiten der +verschiedenen Banken. + +Über die [EBICS Schnittstelle](https://www.six-group.com/de/products-services/banking-services/payment-standardization/standards/ebics.html) können camt054 Dateien regelmässig von einem Finanzinstitut bezogen werden. Mittels Referenznummer werden die Zahlungen einer Rechnung von der Ebene zugewiesen. Zahlungen die keiner Rechnung zugewiesen werden können, werden ignoriert + +In den Rechnungseinstellungen kann pro Ebene die EBICS Schnittstelle definiert werden. Zugangsdaten werden verschlüsselt in Hitobito abgelegt. + +## Wir richte ich die Schnittstelle ein? + +1. Über die eigene Bank/Post muss ein EBICS Vertrag angefordert werden. + : 1. Der Vertrag regelt, welche Konten mit hitobito verknüpft werden. Es können mehrere Konten gleichzeitig über EBICS mit hitobito verknüpft werden. + 2. Im Vertrag muss EBICS als Schnittstelle ausgewählt werden, falls Euch der Vertrag mehrere Optionen gibt. + 3. Im Vertrag muss eine Software angegeben werde, damit ist hitobito gemeint. Angegeben werden soll als Software «hitobito» und als Hersteller «Puzzle ITC» + 4. Die Buchungsart ist Sammelbuchung, die Periodizität ist Euch selbst überlassen. +2. Der Vertrag wird der Bank/Post zurückgeschickt. Von Seiten der Bank/Post wird nun ein Dokument mit der Vertrags-ID und der Kunden-ID für EBICS erstellt und Euch zur Verfügung gestellt. (Die genaue Bezeichnung kann variieren und auch als Teilnehmer-ID / Partner-ID o.Ä. bezeichnet sein.) +3. Mit diesem Dokument der Bank/Post könnt Ihr in hitobito unter den Rechnungseinstellungen->Zahlungsschnittstellen die Vertrags-ID und die Kunden-ID eingeben. Sobald dies gemacht ist, erscheint in Hitobito ein Button zur generierung des Initialisierungs-Dokuments (INI-Brief). +4. Dieses Dokument muss dem Bankinstitut unterschrieben zurückgeschickt werden, damit die Verbindung zwischen Konto und hitobito erstellt werden kann. +5. Die Bank informiert Euch, sobald die Schnittstelle eingerichtet und aktiv ist. +6. Ist dies der Fall, werden Zahlungen, die in hitobito ausgelöst wurden, auch in hitobito abgebucht. + +ACHTUNG: Für die Zuordnung einer Zahlung an eine Person ist die Referenznummer einziges relevantes +Merkmal. Macht Eure Mitglieder darauf Aufmerksam, dass Zahlungen nicht mit alten Referenznummern +gemacht werden sollen. Fehlerquellen sind hauptsächlich falsch eingegebene oder alte Referenznummern. +In solchen Fällen muss über die Bank die Nachforschung zur entsprechenden Zahlung gemacht werden. Weder Puzzle ITC noch Hitobito kann in solchen Fällen unterstützen. + +## Einrichten + +- Beim Einrichten der Schnittstelle wird ein HTML File generiert das ausgedruckt und per Post an die Bank gesendet wird. +- Anschliessend kann Teilnehmer-ID und Kunden-ID ausgefüllt werden +- Das Passwort wird verwendet um die Kommunikation zu verschlüsseln. Wenn dieses Passwort geändert wird, muss die ganze Einrichtung der Schnittstelle wiederholt werden. + +## Unterstützte Finanzinstitute + +Folgende Banken können via EBICS angebunden werden. + +- Postfinance +- Raiffeisen Schweiz + +Vorhanden, jedoch noch keine abschliessende Verifikation: + +- Credit Suisse +- UBS +- Luzerner Kantonalbank +- St.Galler Kantonalbank +- Thurgauer Kantonalbank +- Zürcher Kantonalbank +- BancaStato +- BEKB | BCBE +- Valiant +- Zuger Kantonalbank + +Gerne ergänzen wir diese Liste mit weiteren Banken. diff --git a/docs/ebics.rst b/docs/ebics.rst new file mode 100644 index 0000000..61e2462 --- /dev/null +++ b/docs/ebics.rst @@ -0,0 +1,71 @@ +EBICS Schnittstelle +=================== + +Allgemeines +----------- +Hitobito lässt sich mit einem Bank- oder Postkonto verbinden. Dies bedeutet folgendes: + +Wird eine Zahlung über hitobito ausgelöst und vom Empfänger bezahlt, ist diese Information nicht mehr nur +im Bankkonto ersichtlich, sondern wird auch im hitobito ausgewiesen. Hitobito kann so die Buchhaltung +unterstützen, da damit die Zahlungseingänge zentral und personifiziert überwacht werden können. + +Als Schnittstelle verwendet hitobito die Technologie EBICS. EBICS ist eine standardisierte Schnittstelle zu +Finanzapplikationen und wird in der Schweiz von beinahe allen Banken angeboten (Ausnahmen sind +möglich, uns aber nicht bekannt). Mehr Informationen zu EBICS findet ihr auf den Webseiten der +verschiedenen Banken. + + +Über die `EBICS Schnittstelle `_ können camt054 Dateien regelmässig von einem Finanzinstitut bezogen werden. Mittels Referenznummer werden die Zahlungen einer Rechnung von der Ebene zugewiesen. Zahlungen die keiner Rechnung zugewiesen werden können, werden ignoriert + +In den Rechnungseinstellungen kann pro Ebene die EBICS Schnittstelle definiert werden. Zugangsdaten werden verschlüsselt in Hitobito abgelegt. + +Wir richte ich die Schnittstelle ein? +------------------------------------- + +1) Über die eigene Bank/Post muss ein EBICS Vertrag angefordert werden. + a) Der Vertrag regelt, welche Konten mit hitobito verknüpft werden. Es können mehrere Konten gleichzeitig über EBICS mit hitobito verknüpft werden. + b) Im Vertrag muss EBICS als Schnittstelle ausgewählt werden, falls Euch der Vertrag mehrere Optionen gibt. + c) Im Vertrag muss eine Software angegeben werde, damit ist hitobito gemeint. Angegeben werden soll als Software «hitobito» und als Hersteller «Puzzle ITC» + d) Die Buchungsart ist Sammelbuchung, die Periodizität ist Euch selbst überlassen. +2) Der Vertrag wird der Bank/Post zurückgeschickt. Von Seiten der Bank/Post wird nun ein Dokument mit der Vertrags-ID und der Kunden-ID für EBICS erstellt und Euch zur Verfügung gestellt. (Die genaue Bezeichnung kann variieren und auch als Teilnehmer-ID / Partner-ID o.Ä. bezeichnet sein.) +3) Mit diesem Dokument der Bank/Post könnt Ihr in hitobito unter den Rechnungseinstellungen->Zahlungsschnittstellen die Vertrags-ID und die Kunden-ID eingeben. Sobald dies gemacht ist, erscheint in Hitobito ein Button zur generierung des Initialisierungs-Dokuments (INI-Brief). +4) Dieses Dokument muss dem Bankinstitut unterschrieben zurückgeschickt werden, damit die Verbindung zwischen Konto und hitobito erstellt werden kann. +5) Die Bank informiert Euch, sobald die Schnittstelle eingerichtet und aktiv ist. +6) Ist dies der Fall, werden Zahlungen, die in hitobito ausgelöst wurden, auch in hitobito abgebucht. + + +ACHTUNG: Für die Zuordnung einer Zahlung an eine Person ist die Referenznummer einziges relevantes +Merkmal. Macht Eure Mitglieder darauf Aufmerksam, dass Zahlungen nicht mit alten Referenznummern +gemacht werden sollen. Fehlerquellen sind hauptsächlich falsch eingegebene oder alte Referenznummern. +In solchen Fällen muss über die Bank die Nachforschung zur entsprechenden Zahlung gemacht werden. Weder Puzzle ITC noch Hitobito kann in solchen Fällen unterstützen. + + +Einrichten +---------- + +- Beim Einrichten der Schnittstelle wird ein HTML File generiert das ausgedruckt und per Post an die Bank gesendet wird. +- Anschliessend kann Teilnehmer-ID und Kunden-ID ausgefüllt werden +- Das Passwort wird verwendet um die Kommunikation zu verschlüsseln. Wenn dieses Passwort geändert wird, muss die ganze Einrichtung der Schnittstelle wiederholt werden. + +Unterstützte Finanzinstitute +---------------------------- + +Folgende Banken können via EBICS angebunden werden. + +- Postfinance +- Raiffeisen Schweiz + +Vorhanden, jedoch noch keine abschliessende Verifikation: + +- Credit Suisse +- UBS +- Luzerner Kantonalbank +- St.Galler Kantonalbank +- Thurgauer Kantonalbank +- Zürcher Kantonalbank +- BancaStato +- BEKB | BCBE +- Valiant +- Zuger Kantonalbank + +Gerne ergänzen wir diese Liste mit weiteren Banken. diff --git a/docs/events.md b/docs/events.md new file mode 100644 index 0000000..6793b6b --- /dev/null +++ b/docs/events.md @@ -0,0 +1,29 @@ +# Events + +In Hitobito können unterschiedliche Arten von Events geführt werden. Einfache Anlässe und Kurse. Für gewisse Instanzen wurden zusätzliche Eventsarten wie Lager, Ferienlager oder Musikfeste ergänzt. + +## Anlässe + +In der Organisation von Anlässen unterstützt Hitobito auf eine einfache Weise. Mitglieder können sich mit ihrem Benutzer direkt anmelden, ohne erneut ihre Angaben wie Adressen eingeben zu müssen. + +## Kurse + +Die Kurse bauen auf den Anlässen auf, sind durch zusätzliche Funktionen ergänzt. So können Anmeldebedingugen definiert werden und Teilnehmer können aufgrund ihrer angegebenen Priorität zugewiesen werden. + +## Einladungen + +Einladungen sind nützliche, wenn bestimmte Personen an einem Anlass oder Kurs teilnehmen sollten. +In diesem Fall können die Verantwortlichen diese Personen auf dem *Einladungen*-Tab hinzufügen. +Das *Einladungen*-Tab zeigt den Status aller eingeladenen Personen. + +```{image} images/invitation_list.png +``` + +Die eingeladenen Personen können sich dann auf der Anlass-Seite für den Anlass an- oder abmelden. + +```{image} images/invitation_reply.png +``` + +Die eingeladenen Personen erhalten kein automatische Benachrichtigung, +da die Betroffenen wohl in vielen Fällen (z.B. Sitzungen, Generalversammlung) +separat ausführlich informiert werden müssen. diff --git a/docs/events.rst b/docs/events.rst new file mode 100644 index 0000000..8da34df --- /dev/null +++ b/docs/events.rst @@ -0,0 +1,28 @@ +Events +======================== +In Hitobito können unterschiedliche Arten von Events geführt werden. Einfache Anlässe und Kurse. Für gewisse Instanzen wurden zusätzliche Eventsarten wie Lager, Ferienlager oder Musikfeste ergänzt. + +Anlässe +------- +In der Organisation von Anlässen unterstützt Hitobito auf eine einfache Weise. Mitglieder können sich mit ihrem Benutzer direkt anmelden, ohne erneut ihre Angaben wie Adressen eingeben zu müssen. + +Kurse +----- +Die Kurse bauen auf den Anlässen auf, sind durch zusätzliche Funktionen ergänzt. So können Anmeldebedingugen definiert werden und Teilnehmer können aufgrund ihrer angegebenen Priorität zugewiesen werden. + +Einladungen +----------- + +Einladungen sind nützliche, wenn bestimmte Personen an einem Anlass oder Kurs teilnehmen sollten. +In diesem Fall können die Verantwortlichen diese Personen auf dem *Einladungen*-Tab hinzufügen. +Das *Einladungen*-Tab zeigt den Status aller eingeladenen Personen. + +.. image:: images/invitation_list.png + +Die eingeladenen Personen können sich dann auf der Anlass-Seite für den Anlass an- oder abmelden. + +.. image:: images/invitation_reply.png + +Die eingeladenen Personen erhalten kein automatische Benachrichtigung, +da die Betroffenen wohl in vielen Fällen (z.B. Sitzungen, Generalversammlung) +separat ausführlich informiert werden müssen. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..f7cdbed --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,48 @@ +# Fragen und Antworten + +## Hitobito meldet, dass die IBAN Nummer ungültig ist + +Falls als Einzahlungschein QR Rechnungen ausgewählt sind, muss eine spezielle QR-IBAN () hinterlegt werden. Diese unterscheidet sich von der bestehenden IBAN Nummer. + +## Die Haupt-E-Mail kann nicht geändert werden + +Wenn ein Account beispielsweise bei einer Ortsgruppe und im Dachverband eine aktive Rolle hat, kann die **Haupt-E-Mail** nur von einer Person geändert werden, welche Schreibrechte in beiden Gruppen hat. Folgende Nachricht wird dann jeweils angezeigt: "Die Haupt-E-Mail Adresse einer Person mit mehreren Rollen kann nur von einem über alle diese Rollen übergeordneten Benutzer geändert werden" +Der Account selbst kann seine Haupt-E-Mail immer ändern. + +Ein Beispiel: Ich bin in der Ortsgruppe Wabern und habe eher wenig Rechte im System. Ich kann aber in meiner Gruppe einen Admin zu meiner Gruppe hinzufügen, der auf dem Dachverband sehr viele Rechte hat. Dadurch erhalte ich Schreibrechte auf dieser Person. Ich könnte die primäre Mailadresse auf eine mir zugängliche Adresse ändern, ein Passwortreset auf dem User machen und mich anschliessend als Dachverbands-Admin einloggen. Um das Ganze zu vertuschen, könnte ich danach die Mailadresse wieder zurückändern. Aus diesem Grund ist das Ändern der primären Mailadresse nur zugelassen wenn ich die Berechtigung über alle Gruppen des Admins habe. + +## Geänderte Haupt-E-Mail muss bestätigt werden + +Wird die Haupt-E-Mail einer Person mit Login geändert, so wird ein Mail mit Bestätigungslink an die **neue** E-Mail-Adresse gesendet. So wird sichergestellt, dass die neue Adresse funktioniert und die Person hinter der E-Mail-Adresse mit der Verwendung einverstanden ist. Die Haupt-E-Mail von Personen ohne aktiviertem Login lassen sich sofort ändern. + +Die Bestätigung ist wichtig, da Hitobito als OAuth Provider genutzt werden kann und viele OAuth Dienste die E-Mail zur Identifikation nutzen. Ohne Bestätigung würde folgendes Angriffsszenario funktionieren: + +1. Eine Person A loggt sich via hitobito bei einem Drittservice ein +2. Der Drittservice merkt sich A anhand der Haupt-E-Mailadresse +3. Eine Person X mit Schreibzugriff auf A bearbeitet A und löscht die Haupt-E-Mailadresse +4. Person X füllt bei sich selber die ehemalige Haupt-E-Mailadresse von Person A ein. *Dieser Schritt wird durch die aktuelle E-Mail-Verifikation verhindert.* +5. Person X verwendet beim Drittservice den "Login via hitobito" und kann nun den dortigen Account von Person A übernehmen. + +## Wie werden Personen-Duplikate erkannt? + +Wenn eine Person mehrfach erfasst wurde, dann kann man die Duplikate zusammenführen. Dazu gibt es auf dem "Personen"-Tab einer {doc}`Ebene` (z.B. Dachverband, Region, Ortsgruppe) einen Button "Duplikate". Der Button ist nur für Personen mit sehr hohen Berechtigungen (`layer_and_below_full` oder `admin`) sichtbar. + +Hitobito analysiert jede Nacht die Einträge in der Datenbank und ergänzt die Liste von Duplikaten. Zwei Personen zählen als Duplikate, wenn die Felder Vorname, Nachname, Firmenname, Postleitzahl und Geburtsdatum übereinstimmen (bei Postleitzahl und Geburtsdatum zählt es auch, wenn das Feld bei einer der Personen leer ist). Ein Beispiel: Anna Berger (PLZ 1000, Geburtsdatum 01.01.1970) wird als Duplikat von Anna Berger (ohne PLZ oder Geburtsdatum) erkannt. Anna (PLZ 1000, Geburtsdatum 01.01.1970) ohne Nachname ist hingegen kein Duplikat, der Nachname muss zwingend übereinstimmen oder bei beiden Personen leer sein. + +Dieselbe Duplikatserkennung wird auch schon direkt während dem Import einer CSV-Datei angewendet. Dort bekommt man gleich während dem Import noch die Möglichkeit, auszuwählen welche Zeilen eine bestehende Person aktualisieren sollen und welche Zeilen wirklich neue Personen sind. + +## Wann wird welche Referenznummer verwendet? + +Hitobito unterstützt sowohl die QR-Referenz wie die Creditor Reference (SCOR). Die QR-Referenz entspricht im Aufbau der ESR-Referenz (immer 26 numerische Zeichen gefolgt von einer Prüfziffer nach Modulo 10 rekursiv) und kann vom Rechnungssteller als strukturierte Referenz verwendet werden. +Creditor Reference ist gemäss ISO-11649-Standard implementiert. Die Prüfziffer der Creditor Reference muss mit Modulo 97-10 berechnet werden. Weitere Infos unter + + +Wenn keine QR-IBAN in Hitobito erfasst wurde, wird eine Creditor Reference (SCOR) bei der generierung von Rechnungen verwendet. + +## Über hitobito können verschiedene Mails verschickt werden. Welcher Absender wird da verwendet? + +Wenn du ein Mail an ein Abo schickst, wirst du beim Empfänger auch als Absender angezeigt. Der technische Absender ist aber eine bounced Mailadresse pro Abo mit der Kundendomaine verwendet. Vom System generierte Mails wie Rechnungen, Passwortresets haben einen pro Instanz definierten Absender. Die Mails werden über den hitobito eigenen Mailserver (mxout.appuio.puzzle.ch) verschickt. Mittels SPF Eintrag sorgen wir dafür, dass dieser Mailserver im Namen der Kundendomaine verschicken darf. + +## Was bedeutet Hitobito 人人 + +Hitobito kommt aus dem Japanischen und bedeutet Mensch. Durch die beiden 人人 ist die Mehrzahl gemeint: Menschen oder auch Gemeinschaft. Quelle: diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..f2f120a --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,59 @@ +Fragen und Antworten +==================== + +Hitobito meldet, dass die IBAN Nummer ungültig ist +-------------------------------------------------- + +Falls als Einzahlungschein QR Rechnungen ausgewählt sind, muss eine spezielle QR-IBAN (https://www.moneytoday.ch/lexikon/qr-iban/) hinterlegt werden. Diese unterscheidet sich von der bestehenden IBAN Nummer. + +Die Haupt-E-Mail kann nicht geändert werden +------------------------------------------- + +Wenn ein Account beispielsweise bei einer Ortsgruppe und im Dachverband eine aktive Rolle hat, kann die **Haupt-E-Mail** nur von einer Person geändert werden, welche Schreibrechte in beiden Gruppen hat. Folgende Nachricht wird dann jeweils angezeigt: "Die Haupt-E-Mail Adresse einer Person mit mehreren Rollen kann nur von einem über alle diese Rollen übergeordneten Benutzer geändert werden" +Der Account selbst kann seine Haupt-E-Mail immer ändern. + +Ein Beispiel: Ich bin in der Ortsgruppe Wabern und habe eher wenig Rechte im System. Ich kann aber in meiner Gruppe einen Admin zu meiner Gruppe hinzufügen, der auf dem Dachverband sehr viele Rechte hat. Dadurch erhalte ich Schreibrechte auf dieser Person. Ich könnte die primäre Mailadresse auf eine mir zugängliche Adresse ändern, ein Passwortreset auf dem User machen und mich anschliessend als Dachverbands-Admin einloggen. Um das Ganze zu vertuschen, könnte ich danach die Mailadresse wieder zurückändern. Aus diesem Grund ist das Ändern der primären Mailadresse nur zugelassen wenn ich die Berechtigung über alle Gruppen des Admins habe. + + +Geänderte Haupt-E-Mail muss bestätigt werden +-------------------------------------------- + +Wird die Haupt-E-Mail einer Person mit Login geändert, so wird ein Mail mit Bestätigungslink an die **neue** E-Mail-Adresse gesendet. So wird sichergestellt, dass die neue Adresse funktioniert und die Person hinter der E-Mail-Adresse mit der Verwendung einverstanden ist. Die Haupt-E-Mail von Personen ohne aktiviertem Login lassen sich sofort ändern. + +Die Bestätigung ist wichtig, da Hitobito als OAuth Provider genutzt werden kann und viele OAuth Dienste die E-Mail zur Identifikation nutzen. Ohne Bestätigung würde folgendes Angriffsszenario funktionieren: + +1. Eine Person A loggt sich via hitobito bei einem Drittservice ein +2. Der Drittservice merkt sich A anhand der Haupt-E-Mailadresse +3. Eine Person X mit Schreibzugriff auf A bearbeitet A und löscht die Haupt-E-Mailadresse +4. Person X füllt bei sich selber die ehemalige Haupt-E-Mailadresse von Person A ein. *Dieser Schritt wird durch die aktuelle E-Mail-Verifikation verhindert.* +5. Person X verwendet beim Drittservice den "Login via hitobito" und kann nun den dortigen Account von Person A übernehmen. + +Wie werden Personen-Duplikate erkannt? +-------------------------------------- + +Wenn eine Person mehrfach erfasst wurde, dann kann man die Duplikate zusammenführen. Dazu gibt es auf dem "Personen"-Tab einer :doc:`Ebene` (z.B. Dachverband, Region, Ortsgruppe) einen Button "Duplikate". Der Button ist nur für Personen mit sehr hohen Berechtigungen (``layer_and_below_full`` oder ``admin``) sichtbar. + +Hitobito analysiert jede Nacht die Einträge in der Datenbank und ergänzt die Liste von Duplikaten. Zwei Personen zählen als Duplikate, wenn die Felder Vorname, Nachname, Firmenname, Postleitzahl und Geburtsdatum übereinstimmen (bei Postleitzahl und Geburtsdatum zählt es auch, wenn das Feld bei einer der Personen leer ist). Ein Beispiel: Anna Berger (PLZ 1000, Geburtsdatum 01.01.1970) wird als Duplikat von Anna Berger (ohne PLZ oder Geburtsdatum) erkannt. Anna (PLZ 1000, Geburtsdatum 01.01.1970) ohne Nachname ist hingegen kein Duplikat, der Nachname muss zwingend übereinstimmen oder bei beiden Personen leer sein. + +Dieselbe Duplikatserkennung wird auch schon direkt während dem Import einer CSV-Datei angewendet. Dort bekommt man gleich während dem Import noch die Möglichkeit, auszuwählen welche Zeilen eine bestehende Person aktualisieren sollen und welche Zeilen wirklich neue Personen sind. + + +Wann wird welche Referenznummer verwendet? +------------------------------------------ + +Hitobito unterstützt sowohl die QR-Referenz wie die Creditor Reference (SCOR). Die QR-Referenz entspricht im Aufbau der ESR-Referenz (immer 26 numerische Zeichen gefolgt von einer Prüfziffer nach Modulo 10 rekursiv) und kann vom Rechnungssteller als strukturierte Referenz verwendet werden. +Creditor Reference ist gemäss ISO-11649-Standard implementiert. Die Prüfziffer der Creditor Reference muss mit Modulo 97-10 berechnet werden. Weitere Infos unter +https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-de.pdf + +Wenn keine QR-IBAN in Hitobito erfasst wurde, wird eine Creditor Reference (SCOR) bei der generierung von Rechnungen verwendet. + + +Über hitobito können verschiedene Mails verschickt werden. Welcher Absender wird da verwendet? +---------------------------------------------------------------------------------------------- + +Wenn du ein Mail an ein Abo schickst, wirst du beim Empfänger auch als Absender angezeigt. Der technische Absender ist aber eine bounced Mailadresse pro Abo mit der Kundendomaine verwendet. Vom System generierte Mails wie Rechnungen, Passwortresets haben einen pro Instanz definierten Absender. Die Mails werden über den hitobito eigenen Mailserver (mxout.appuio.puzzle.ch) verschickt. Mittels SPF Eintrag sorgen wir dafür, dass dieser Mailserver im Namen der Kundendomaine verschicken darf. + +Was bedeutet Hitobito 人人 +-------------------------- + +Hitobito kommt aus dem Japanischen und bedeutet Mensch. Durch die beiden 人人 ist die Mehrzahl gemeint: Menschen oder auch Gemeinschaft. Quelle: https://www.wordsense.eu/%E4%BA%BA%E4%BA%BA/ diff --git a/docs/images/AboAdd.png b/docs/images/AboAdd.png new file mode 100644 index 0000000..f6c98bf Binary files /dev/null and b/docs/images/AboAdd.png differ diff --git a/docs/images/AboTag.png b/docs/images/AboTag.png new file mode 100644 index 0000000..95eadc8 Binary files /dev/null and b/docs/images/AboTag.png differ diff --git a/docs/images/Base.png b/docs/images/Base.png new file mode 100644 index 0000000..eb8ed39 Binary files /dev/null and b/docs/images/Base.png differ diff --git a/docs/images/FilterLayer.png b/docs/images/FilterLayer.png new file mode 100644 index 0000000..e3ad84f Binary files /dev/null and b/docs/images/FilterLayer.png differ diff --git a/docs/images/FilterNew.png b/docs/images/FilterNew.png new file mode 100644 index 0000000..506f0ce Binary files /dev/null and b/docs/images/FilterNew.png differ diff --git a/docs/images/FilterRole.png b/docs/images/FilterRole.png new file mode 100644 index 0000000..ea6f288 Binary files /dev/null and b/docs/images/FilterRole.png differ diff --git a/docs/images/FilterSave.png b/docs/images/FilterSave.png new file mode 100644 index 0000000..404cf56 Binary files /dev/null and b/docs/images/FilterSave.png differ diff --git a/docs/images/GroupAdd.png b/docs/images/GroupAdd.png new file mode 100644 index 0000000..8d46077 Binary files /dev/null and b/docs/images/GroupAdd.png differ diff --git a/docs/images/GroupDescription.png b/docs/images/GroupDescription.png new file mode 100644 index 0000000..bc8669d Binary files /dev/null and b/docs/images/GroupDescription.png differ diff --git a/docs/images/LowLayerFull.png b/docs/images/LowLayerFull.png new file mode 100644 index 0000000..570f5d8 Binary files /dev/null and b/docs/images/LowLayerFull.png differ diff --git a/docs/images/LowLayerGroup.png b/docs/images/LowLayerGroup.png new file mode 100644 index 0000000..9c7c60b Binary files /dev/null and b/docs/images/LowLayerGroup.png differ diff --git a/docs/images/LowLayerNone.png b/docs/images/LowLayerNone.png new file mode 100644 index 0000000..053e45c Binary files /dev/null and b/docs/images/LowLayerNone.png differ diff --git a/docs/images/MidlayerFull.png b/docs/images/MidlayerFull.png new file mode 100644 index 0000000..3fe9f08 Binary files /dev/null and b/docs/images/MidlayerFull.png differ diff --git a/docs/images/MidlayerGroup.png b/docs/images/MidlayerGroup.png new file mode 100644 index 0000000..de3d209 Binary files /dev/null and b/docs/images/MidlayerGroup.png differ diff --git a/docs/images/Tags.png b/docs/images/Tags.png new file mode 100644 index 0000000..2afe14a Binary files /dev/null and b/docs/images/Tags.png differ diff --git a/docs/images/TopLayerFull.png b/docs/images/TopLayerFull.png new file mode 100644 index 0000000..be1c8de Binary files /dev/null and b/docs/images/TopLayerFull.png differ diff --git a/docs/images/TopLayerFullRestrained.png b/docs/images/TopLayerFullRestrained.png new file mode 100644 index 0000000..5966813 Binary files /dev/null and b/docs/images/TopLayerFullRestrained.png differ diff --git a/docs/images/TopLayerSubgroup.png b/docs/images/TopLayerSubgroup.png new file mode 100644 index 0000000..e00eb76 Binary files /dev/null and b/docs/images/TopLayerSubgroup.png differ diff --git a/docs/images/approvals_tab.png b/docs/images/approvals_tab.png new file mode 100644 index 0000000..e095cb0 Binary files /dev/null and b/docs/images/approvals_tab.png differ diff --git a/docs/images/invitation_list.png b/docs/images/invitation_list.png new file mode 100644 index 0000000..bebe693 Binary files /dev/null and b/docs/images/invitation_list.png differ diff --git a/docs/images/invitation_reply.png b/docs/images/invitation_reply.png new file mode 100644 index 0000000..c96eb9a Binary files /dev/null and b/docs/images/invitation_reply.png differ diff --git a/docs/images/pending_role_approval.png b/docs/images/pending_role_approval.png new file mode 100644 index 0000000..9eccbf1 Binary files /dev/null and b/docs/images/pending_role_approval.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f7b8f28 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,46 @@ +% hitobito documentation master file, created by +% sphinx-quickstart on Mon Aug 13 09:21:58 2018. +% You can adapt this file completely to your liking, but it should at least +% contain the root `toctree` directive. + +# Benutzeranleitung für Hitobito + +Hier findest du die generische Benutzerdokumentation für Hitobito. + +Du kannst selbst deinen Beitrag leisten und Ergänzungen vornehmen, in dem du auf Github: Korrekturen an den Anleitungsseiten vornimmst. Wenn dir das zu kompliziert ist, kannst du einfach auch Änderungen, Ergänzungen über dieses Formular: vorschlagen. + +```{toctree} +:caption: Anleitung +:maxdepth: 3 + +roles +people_filter +events +tags +mailing_lists +invoices +access_concept +``` + +```{toctree} +:caption: Anbindung +:maxdepth: 3 + +mailing_lists_mailchimp_export +ebics +two_factor_authentication +``` + +```{toctree} +:caption: FAQ +:maxdepth: 3 + +faq +``` + +% Indices and tables +% ================== +% +% * :ref:`genindex` +% * :ref:`modindex` +% * :ref:`search` diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5673ef2 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,49 @@ +.. hitobito documentation master file, created by + sphinx-quickstart on Mon Aug 13 09:21:58 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Benutzeranleitung für Hitobito +============================== + +Hier findest du die generische Benutzerdokumentation für Hitobito. + +Du kannst selbst deinen Beitrag leisten und Ergänzungen vornehmen, in dem du auf Github: https://github.com/hitobito/user_documentation Korrekturen an den Anleitungsseiten vornimmst. Wenn dir das zu kompliziert ist, kannst du einfach auch Änderungen, Ergänzungen über dieses Formular: https://github.com/hitobito/user_documentation/issues/new vorschlagen. + + + +.. toctree:: + :maxdepth: 3 + :caption: Anleitung + + roles + people_filter + events + tags + mailing_lists + invoices + access_concept + +.. toctree:: + :maxdepth: 3 + :caption: Anbindung + + mailing_lists_mailchimp_export + ebics + two_factor_authentication + +.. toctree:: + :maxdepth: 3 + :caption: FAQ + + faq + + + + +.. Indices and tables + ================== + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/docs/invoices.md b/docs/invoices.md new file mode 100644 index 0000000..baab00f --- /dev/null +++ b/docs/invoices.md @@ -0,0 +1,50 @@ +# Rechnungen + +:::{warning} +Rechnungen sind ein Feature welches pro Instanz aktiviert werden kann. +::: + +:::{note} +Ob du Rechnungen verwalten kannst hängt davon ab, ob dir eine entsprechende Rolle vergeben wurde. Welche Rolle das ist hängt von der jeweiligen Organisation ab. +::: + +In hitobito können Rechnungen erstellt und Debitoren verwaltet werden. + +## Rechnungen erstellen + +:::{note} +Rechnungen werden nicht auf der Ansicht Rechnungen erstellt, sondern ausgehend von Personenlisten oder auf der Ansicht einer bestimmten Person. +::: + +Rechnungen können aus folgenden Ansichten erstellt werden: + +- Personenlisten +- Teilnehmerlisten von einem Event, Lager oder Kurs +- Einzelperson +- im Abo an die jeweiligen Empfänger, dies erstellt eine Sammelrechnung + +## Rechnung + +Hier finden Sie die Übersicht über alle erstellten Rechnungen und hier können diese verschickt, bearbeitet, gelöscht oder gedruckt werden. Pro Rechnung ist der Status sichtbar. Zahlungen können manuell auf der jeweiligen Rechnung erfasst oder mittels camt.054 XML-Datei [^f2] eingelesen werden. + +Bei Bedarf können die Rechnungen auch als CSV exportiert und in eine Buchhaltungsapplikation eingelesen werden. + +An dieser Stelle können auch **externe** Rechnungen erstellt werden, d.h. Rechnungen, welche an externe Empfänger geschickt werden, welche nicht in hitobito erfasst sind. + +## Sammelrechnungen + +Werden Rechnungen aus dem Abo generiert, wird eine Sammelrechnung erstellt. Dies fasst die Rechnungen zu einem Eintrag zusammen. Dabei wird neben der Anzahl Rechnungen auch die offenen und bezahlten Beträge angezeigt. + +## Rechnungsartikel + +Häufig verwendete Rechnungspositionen (z.B. Mitgliederbeitrag, Jahresabo, etc.) können hier vordefiniert werden. Diese Artikel können beim Erstellen von Rechnungen ausgewählt und individuell angepasst werden. + +## Einstellungen + +In den Rechnungseinstellungen können allgemeine Angaben gemacht werden, wie die Absenderadresse, Absender-E-Mail, Tage bis Fälligkeit, MwSt.-Nummer etc. Hier können auch die Texte für die erste, zweite und dritte Mahnung definiert werden. + +Diese Einstellungen können pro Ebene individuell vorgenommen werden. + +Du kannst rote und orange Einzahlungsscheine für Post und Bank erstellen. Zusätzlich stehen noch QR Rechnungen zur Verfügung. Für QR Rechnungen muss eine spezielle QR-IBAN () hinterlegt werden. Diese unterscheidet sich von der bestehenden IBAN Nummer. + +[^f2]: Eine camt.054 XML-Datei ist die Sammelbuchungs-auflösung und Belastungs- und Gutschriftsanzeige. Diese enthält eine Reihe verschiedene Buchungspositionen welche automatisiert auf Basis der ESR-Nummer bestehenden Rechnungen zugeordnet werden. diff --git a/docs/invoices.rst b/docs/invoices.rst new file mode 100644 index 0000000..4438e0b --- /dev/null +++ b/docs/invoices.rst @@ -0,0 +1,56 @@ +Rechnungen +================ + +.. warning:: Rechnungen sind ein Feature welches pro Instanz aktiviert werden kann. + + +.. note:: Ob du Rechnungen verwalten kannst hängt davon ab, ob dir eine entsprechende Rolle vergeben wurde. Welche Rolle das ist hängt von der jeweiligen Organisation ab. + + +In hitobito können Rechnungen erstellt und Debitoren verwaltet werden. + + +Rechnungen erstellen +-------------------------- + +.. note:: Rechnungen werden nicht auf der Ansicht Rechnungen erstellt, sondern ausgehend von Personenlisten oder auf der Ansicht einer bestimmten Person. + +Rechnungen können aus folgenden Ansichten erstellt werden: + +- Personenlisten +- Teilnehmerlisten von einem Event, Lager oder Kurs +- Einzelperson +- im Abo an die jeweiligen Empfänger, dies erstellt eine Sammelrechnung + +Rechnung +--------------------------------------- +Hier finden Sie die Übersicht über alle erstellten Rechnungen und hier können diese verschickt, bearbeitet, gelöscht oder gedruckt werden. Pro Rechnung ist der Status sichtbar. Zahlungen können manuell auf der jeweiligen Rechnung erfasst oder mittels camt.054 XML-Datei [#f2]_ eingelesen werden. + +Bei Bedarf können die Rechnungen auch als CSV exportiert und in eine Buchhaltungsapplikation eingelesen werden. + +An dieser Stelle können auch **externe** Rechnungen erstellt werden, d.h. Rechnungen, welche an externe Empfänger geschickt werden, welche nicht in hitobito erfasst sind. + +Sammelrechnungen +-------------------------------------- + +Werden Rechnungen aus dem Abo generiert, wird eine Sammelrechnung erstellt. Dies fasst die Rechnungen zu einem Eintrag zusammen. Dabei wird neben der Anzahl Rechnungen auch die offenen und bezahlten Beträge angezeigt. + + +Rechnungsartikel +-------------------------------------- + +Häufig verwendete Rechnungspositionen (z.B. Mitgliederbeitrag, Jahresabo, etc.) können hier vordefiniert werden. Diese Artikel können beim Erstellen von Rechnungen ausgewählt und individuell angepasst werden. + +Einstellungen +--------------------------------------- + +In den Rechnungseinstellungen können allgemeine Angaben gemacht werden, wie die Absenderadresse, Absender-E-Mail, Tage bis Fälligkeit, MwSt.-Nummer etc. Hier können auch die Texte für die erste, zweite und dritte Mahnung definiert werden. + +Diese Einstellungen können pro Ebene individuell vorgenommen werden. + +Du kannst rote und orange Einzahlungsscheine für Post und Bank erstellen. Zusätzlich stehen noch QR Rechnungen zur Verfügung. Für QR Rechnungen muss eine spezielle QR-IBAN (https://www.moneytoday.ch/lexikon/qr-iban/) hinterlegt werden. Diese unterscheidet sich von der bestehenden IBAN Nummer. + + + + +.. [#f2] Eine camt.054 XML-Datei ist die Sammelbuchungs-auflösung und Belastungs- und Gutschriftsanzeige. Diese enthält eine Reihe verschiedene Buchungspositionen welche automatisiert auf Basis der ESR-Nummer bestehenden Rechnungen zugeordnet werden. diff --git a/docs/mailing_lists.md b/docs/mailing_lists.md new file mode 100644 index 0000000..45fd694 --- /dev/null +++ b/docs/mailing_lists.md @@ -0,0 +1,55 @@ +# Mailinglisten / Abos + +Mit Mailinglisten / Abos können die Empfänger von Zeitschriften / Abos verwaltet werden, man kann sie auch für die interne Kommunikation benutzen. + +Für Mailversände und das Verwalten von Abonnementen könnt ihr entsprechende Verteilerlisten erfassen. + +## Neues Abo erstellen + +Mit den nötigen Berechtigungen könnt ihr im Tab "Abos" ein neues Abo erstellen. +Minimal muss ein Name für das Abo vergeben werden. +Falls das Abo für Mailversände verwendet werden soll, muss zudem unter "Mailinglisten Adresse" +eine Adresse eingetragen werden. + +### Absender-Rechte + +Ohne weitere Konfiguration dürfen alle Personen, die das Abo bearbeiten können auch Mails an den Verteiler senden. +Kontrolliert wird dabei ob die im Absender eingetragene Mail-Adresse bei den berechtigten Kontakten als Haupt- oder weitere Mailadresse hinterlegt ist. + +Die Mailadressen der Gruppe, zu dem das Abo gehört, dürfen ebenfalls jederzeit Mails an den Verteiler senden. + +Zusätzliche Absender können mit folgenden Optionen berechtigt werden + +1. Das Feld "Zusätzliche Absender": Mails mit den aufgeführten Absender-Adressen dürfen auf die Liste schreiben. +2. "Abonnenten dürfen auf die Mailingliste schreiben": Die bei den Abonnenten erfassten Mail-Adressen dürfen auf die Liste schreiben. +3. "Beliebige Absender/-innen dürfen auf die Mailingliste schreiben": Alle, die die Abo-Adresse kennen, können Mails dorthin senden. + +## Empfänger zuweisen + +In einem zweiten Schritt gilt es noch, die Empfänger dieses Abos zu bestimmen. Hierfür orientieren wir uns primär an den Organisationsstrukturen und den definierten Rollen. + +### Gruppe/Rolle hinzufügen wählen + +```{image} images/AboAdd.png +``` + +### Nach Tags einschränken (optional) + +```{image} images/AboTag.png +``` + +## Mailversände + +Wenn ihr für das vorliegende Beispiel eine Einladung an alle Mitglieder der Region Bern versenden möchtet, könnt ihr diese an die gewählte E-Mail-Adresse senden. hitobito wird diese danach an die damit verknüpften Rollen, Anlässe etc. "weiterleiten". + +Im Abo kann definiert werden, wer auf das Abo schreiben dar. Nur Abonnenten auf der Mailingsliste, oder beliebige Absender\*innen. Im Feld "Zusätzlicher Absender" kann definiert werden, wenn von weiteren E-Mail Adressen auf den Mailverteiler geschrieben werden kann. +Ein Beispiel: +Abo ist ein Präsidiumsverteiler mit sämtlichen Personen mit der Rolle Präsident\*in. Da dürfen nur Personen welche im Abo sind drauf schreiben. Zusätzlich soll aber von auf dieses Abo geschrieben werden. In diesem Fall muss die Mailadresse in das Feld "Zusätzlicher Absender" eingetragen werden. Mittels Strichpunkt (;) können auch mehrere Adressen erfasst werden. + +## Etiketten drucken + +Falls ihr ein entsprechendes Etikettenformat definiert habt, könnt ihr diese im Abo unter "Export" auswählen, damit euch für physische Versände die Adressen der gewählten Mitglieder exportiert werden. + +## Mailinglisten nach Tags filtern + +Personen können beim hinzufügen via Rolle/Gruppe auch nach Tags gefiltert werden diff --git a/docs/mailing_lists.rst b/docs/mailing_lists.rst new file mode 100644 index 0000000..ed929bd --- /dev/null +++ b/docs/mailing_lists.rst @@ -0,0 +1,67 @@ +Mailinglisten / Abos +======================== + +Mit Mailinglisten / Abos können die Empfänger von Zeitschriften / Abos verwaltet werden, man kann sie auch für die interne Kommunikation benutzen. + + +Für Mailversände und das Verwalten von Abonnementen könnt ihr entsprechende Verteilerlisten erfassen. + + +Neues Abo erstellen +-------------------------- + +Mit den nötigen Berechtigungen könnt ihr im Tab "Abos" ein neues Abo erstellen. +Minimal muss ein Name für das Abo vergeben werden. +Falls das Abo für Mailversände verwendet werden soll, muss zudem unter "Mailinglisten Adresse" +eine Adresse eingetragen werden. + +Absender-Rechte +~~~~~~~~~~~~~~~ +Ohne weitere Konfiguration dürfen alle Personen, die das Abo bearbeiten können auch Mails an den Verteiler senden. +Kontrolliert wird dabei ob die im Absender eingetragene Mail-Adresse bei den berechtigten Kontakten als Haupt- oder weitere Mailadresse hinterlegt ist. + +Die Mailadressen der Gruppe, zu dem das Abo gehört, dürfen ebenfalls jederzeit Mails an den Verteiler senden. + +Zusätzliche Absender können mit folgenden Optionen berechtigt werden + +1. Das Feld "Zusätzliche Absender": Mails mit den aufgeführten Absender-Adressen dürfen auf die Liste schreiben. +2. "Abonnenten dürfen auf die Mailingliste schreiben": Die bei den Abonnenten erfassten Mail-Adressen dürfen auf die Liste schreiben. +3. "Beliebige Absender/-innen dürfen auf die Mailingliste schreiben": Alle, die die Abo-Adresse kennen, können Mails dorthin senden. + + +Empfänger zuweisen +------------------------- + +In einem zweiten Schritt gilt es noch, die Empfänger dieses Abos zu bestimmen. Hierfür orientieren wir uns primär an den Organisationsstrukturen und den definierten Rollen. + +Gruppe/Rolle hinzufügen wählen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/AboAdd.png + +Nach Tags einschränken (optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. image:: images/AboTag.png + + +Mailversände +--------------------- + +Wenn ihr für das vorliegende Beispiel eine Einladung an alle Mitglieder der Region Bern versenden möchtet, könnt ihr diese an die gewählte E-Mail-Adresse senden. hitobito wird diese danach an die damit verknüpften Rollen, Anlässe etc. "weiterleiten". + +Im Abo kann definiert werden, wer auf das Abo schreiben dar. Nur Abonnenten auf der Mailingsliste, oder beliebige Absender*innen. Im Feld "Zusätzlicher Absender" kann definiert werden, wenn von weiteren E-Mail Adressen auf den Mailverteiler geschrieben werden kann. +Ein Beispiel: +Abo ist ein Präsidiumsverteiler mit sämtlichen Personen mit der Rolle Präsident*in. Da dürfen nur Personen welche im Abo sind drauf schreiben. Zusätzlich soll aber von info@hitobitokunde.ch auf dieses Abo geschrieben werden. In diesem Fall muss die Mailadresse info@hitobitokunde.ch in das Feld "Zusätzlicher Absender" eingetragen werden. Mittels Strichpunkt (;) können auch mehrere Adressen erfasst werden. + + +Etiketten drucken +---------------------- + +Falls ihr ein entsprechendes Etikettenformat definiert habt, könnt ihr diese im Abo unter "Export" auswählen, damit euch für physische Versände die Adressen der gewählten Mitglieder exportiert werden. + + +Mailinglisten nach Tags filtern +------------------------------- +Personen können beim hinzufügen via Rolle/Gruppe auch nach Tags gefiltert werden diff --git a/docs/mailing_lists_mailchimp_export.md b/docs/mailing_lists_mailchimp_export.md new file mode 100644 index 0000000..1c09214 --- /dev/null +++ b/docs/mailing_lists_mailchimp_export.md @@ -0,0 +1,53 @@ +# MailChimp-Export von Mailinglisten / Abos + +Mit dem MailChimp-Export können die Abonnent\*innen von Mailinglisten exportiert werden in eine MailChimp-Liste. + +Bitte beachtet vor Benutzung dieses Features zwei Dinge: + +- Die MailChimp-Liste wird durch den Export **überschrieben** (siehe auch folgenden Abschnitt) +- Die MailChimp-Liste wird **regelmässig** (alle 24h) und bei Bedarf zusätzlich **auf Knopfdruck** exportiert + +## Grundsatz + +Das MailChimp-Feature ermöglicht es, die in Hitobito organisierten Daten zu brauchen, um mit MailChimp gestaltete Newsletter zu versenden. Es kann nicht gebraucht werden, um eine MailChimp-Liste mit einer Hitobito-Mailingliste zu synchronisieren, da es **keine Daten von MailChimp importiert** und **bestehende Daten von MailChimp bei jedem Export überschreibt**. + +## Verknüpfen einer Mailingliste mit MailChimp + +Mit jeder Mailingliste kann jeweils eine MailChimp-Liste verknüpft werden. Dies geschieht in den Einstellungen der Mailingliste durch die beiden Felder «MailChimp API-Schlüssel» und «MailChimp Listen-ID»: + +```{image} mailing_lists_mailchimp_export/mailing_list_settings.png +``` + +:::{hint} +Standardmässig werden nur die Haupt-E-Mailadressen der Abonnent\*innen synchronisiert. Sollen weitere E-Mailadressen, welche die Option "Versand" haben ebenfalls mit MailChimp synchronisiert werden, ist die Option "Alle Versandadressen synchronisieren" anzuwählen. +::: + +Die **«MailChimp Listen-ID»** kannst Du in den Einstellungen der gewünschten Liste in MailChimp holen (in gelb unten rechts): + +```{image} mailing_lists_mailchimp_export/mailchimp_list_id.png +``` + +Der **«MailChimp API-Schlüssel»** ermöglicht es einer fremden Applikation wie Hitobito, in deinem Namen Änderungen in MailChimp vorzunehmen. Du kannst einen neuen API-Schlüssel im Menu «Extras / API keys» in den Einstellungen deines Profils erstellen. Auf der entsprechenden Seite kannst Du «Create A Key» drücken (im Bild unten links) und den «API key» aus dem Textfeld (im Bild gelb hinterlegt) in das entsprechende Feld in Hitobito kopieren: + +```{image} mailing_lists_mailchimp_export/mailchimp_api_key.png +``` + +Gratuliere, nach dem Speichern dieser zwei Informationen ist nun deine Mailingliste mit der MailChimp-Liste verknüpft! + +## Exportieren nach MailChimp + +Um die Abonnent\*innen einer Mailingliste nach MailChimp zu exportieren, wähle die entsprechende Option im «Export»-Menu des «Abonnenten»-Tabs deiner Mailingliste in Hitobito aus. + +:::{danger} +Bitte beachte, dass der Export deine verknüpfte Liste in MailChimp überschreiben. Bestehende Kontakte werden in Mailchimp archiviert. +::: + +```{image} mailing_lists_mailchimp_export/mailing_list_export.png +``` + +Nach dem Auslösen des Exports wird die Liste im Hintergrund in die gewählte MailChimp-Liste exportiert und die Abonnent\*innen deiner Mailingliste sollten nach einiger Zeit dort erscheinen. +Sollten E-Mailadressen in Mailchimp den Status "cleaned" besitzen, wird in hitobito ein entsprechender Validation Tag gesetzt. (z.B. "Haupt-E-Mail ungültig") + +:::{note} +Abonnent\*innen Ihrer Mailingliste, welche sich in der Vergangenheit aktiv bei MailChimp von Ihrer Liste abgemeldet haben (über den Abmelden-Link in Ihrer E-Mail), behalten ihren «Unsubscribed»-Status und erhalten auch nach einem neuerlichen Export aus hitobito keine E-Mails mehr von Ihnen. +::: diff --git a/docs/mailing_lists_mailchimp_export.rst b/docs/mailing_lists_mailchimp_export.rst new file mode 100644 index 0000000..c78c088 --- /dev/null +++ b/docs/mailing_lists_mailchimp_export.rst @@ -0,0 +1,50 @@ +MailChimp-Export von Mailinglisten / Abos +========================================= + +Mit dem MailChimp-Export können die Abonnent*innen von Mailinglisten exportiert werden in eine MailChimp-Liste. + +Bitte beachtet vor Benutzung dieses Features zwei Dinge: + +* Die MailChimp-Liste wird durch den Export **überschrieben** (siehe auch folgenden Abschnitt) +* Die MailChimp-Liste wird **regelmässig** (alle 24h) und bei Bedarf zusätzlich **auf Knopfdruck** exportiert + + +Grundsatz +--------- + +Das MailChimp-Feature ermöglicht es, die in Hitobito organisierten Daten zu brauchen, um mit MailChimp gestaltete Newsletter zu versenden. Es kann nicht gebraucht werden, um eine MailChimp-Liste mit einer Hitobito-Mailingliste zu synchronisieren, da es **keine Daten von MailChimp importiert** und **bestehende Daten von MailChimp bei jedem Export überschreibt**. + + +Verknüpfen einer Mailingliste mit MailChimp +------------------------------------------- + +Mit jeder Mailingliste kann jeweils eine MailChimp-Liste verknüpft werden. Dies geschieht in den Einstellungen der Mailingliste durch die beiden Felder «MailChimp API-Schlüssel» und «MailChimp Listen-ID»: + +.. image:: mailing_lists_mailchimp_export/mailing_list_settings.png + +.. hint:: Standardmässig werden nur die Haupt-E-Mailadressen der Abonnent*innen synchronisiert. Sollen weitere E-Mailadressen, welche die Option "Versand" haben ebenfalls mit MailChimp synchronisiert werden, ist die Option "Alle Versandadressen synchronisieren" anzuwählen. + +Die **«MailChimp Listen-ID»** kannst Du in den Einstellungen der gewünschten Liste in MailChimp holen (in gelb unten rechts): + +.. image:: mailing_lists_mailchimp_export/mailchimp_list_id.png + +Der **«MailChimp API-Schlüssel»** ermöglicht es einer fremden Applikation wie Hitobito, in deinem Namen Änderungen in MailChimp vorzunehmen. Du kannst einen neuen API-Schlüssel im Menu «Extras / API keys» in den Einstellungen deines Profils erstellen. Auf der entsprechenden Seite kannst Du «Create A Key» drücken (im Bild unten links) und den «API key» aus dem Textfeld (im Bild gelb hinterlegt) in das entsprechende Feld in Hitobito kopieren: + +.. image:: mailing_lists_mailchimp_export/mailchimp_api_key.png + +Gratuliere, nach dem Speichern dieser zwei Informationen ist nun deine Mailingliste mit der MailChimp-Liste verknüpft! + + +Exportieren nach MailChimp +-------------------------- + +Um die Abonnent*innen einer Mailingliste nach MailChimp zu exportieren, wähle die entsprechende Option im «Export»-Menu des «Abonnenten»-Tabs deiner Mailingliste in Hitobito aus. + +.. danger:: Bitte beachte, dass der Export deine verknüpfte Liste in MailChimp überschreiben. Bestehende Kontakte werden in Mailchimp archiviert. + +.. image:: mailing_lists_mailchimp_export/mailing_list_export.png + +Nach dem Auslösen des Exports wird die Liste im Hintergrund in die gewählte MailChimp-Liste exportiert und die Abonnent*innen deiner Mailingliste sollten nach einiger Zeit dort erscheinen. +Sollten E-Mailadressen in Mailchimp den Status "cleaned" besitzen, wird in hitobito ein entsprechender Validation Tag gesetzt. (z.B. "Haupt-E-Mail ungültig") + +.. note:: Abonnent*innen Ihrer Mailingliste, welche sich in der Vergangenheit aktiv bei MailChimp von Ihrer Liste abgemeldet haben (über den Abmelden-Link in Ihrer E-Mail), behalten ihren «Unsubscribed»-Status und erhalten auch nach einem neuerlichen Export aus hitobito keine E-Mails mehr von Ihnen. diff --git a/docs/people_filter.md b/docs/people_filter.md new file mode 100644 index 0000000..442295c --- /dev/null +++ b/docs/people_filter.md @@ -0,0 +1,40 @@ +# Personenfilter + +Auf der Personenliste kann nach unterschiedlichen Kriterien gefilter werden: + +- Rollenfilter +- Qualifikationsfilter +- Felder +- Tags + +## Filtern von Personen + +### Neuen Filter Anlegen + +```{image} images/FilterNew.png +``` + +Unter `weitere Ansichten` `Neuer Filter` wählen. + +### Auswahl auf welcher Ebene / Gruppe gesucht werden soll. + +```{image} images/FilterLayer.png +``` + +### Auswahl an Personen mit gesuchten Rollen. + +```{image} images/FilterRole.png +``` + +26. 2. alle Leiter von Gremien/Projektgruppen + +:::{hint} +Tipp: Beim klicken auf die Gruppe, werden alle Rollen dieser Gruppe ausgewählt. +::: + +## Gefilterte Listen speichern + +```{image} images/FilterSave.png +``` + +Der definierte Filter kann gespeichert werden und, steht allen anderen Benutzern zur Verfügung. diff --git a/docs/people_filter.rst b/docs/people_filter.rst new file mode 100644 index 0000000..939878a --- /dev/null +++ b/docs/people_filter.rst @@ -0,0 +1,41 @@ +Personenfilter +============== + +Auf der Personenliste kann nach unterschiedlichen Kriterien gefilter werden: + +- Rollenfilter +- Qualifikationsfilter +- Felder +- Tags + +Filtern von Personen +------------------------- + +Neuen Filter Anlegen +~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/FilterNew.png + +Unter `weitere Ansichten` `Neuer Filter` wählen. + +Auswahl auf welcher Ebene / Gruppe gesucht werden soll. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/FilterLayer.png + +Auswahl an Personen mit gesuchten Rollen. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: images/FilterRole.png + +z. B. alle Leiter von Gremien/Projektgruppen + +.. hint:: Tipp: Beim klicken auf die Gruppe, werden alle Rollen dieser Gruppe ausgewählt. + +Gefilterte Listen speichern +--------------------------------- + + +.. image:: images/FilterSave.png + +Der definierte Filter kann gespeichert werden und, steht allen anderen Benutzern zur Verfügung. diff --git a/docs/roles.md b/docs/roles.md new file mode 100644 index 0000000..4a5f02d --- /dev/null +++ b/docs/roles.md @@ -0,0 +1,33 @@ +# Rollen + +Rollen sind ein zentrales Konzept in hitobito: + +- Jede Person kann beliebig viele Rollen in verschiedenen Kontexten + haben. Peter kann z. B. gleichzeitig Leiter eines Gremiums in einem + Kantonalverband sein, als auch Mitglied in einer Ortsgruppe. +- Welche Rollen zur Verfügung stehen, hängt davon ab, in welcher Gruppe + du die Person zuweist. Z. B. hat eine Gruppe vom Typ Vorstand Rollen + wie PräsidentIn und SekretärIn zur Verfügung. +- Die Rolle der Person bestimmt die [Zugriffsrechte] dieser Person. + +## Empfehlungen + +```{image} images/GroupAdd.png +``` + +Für jede Organisation stellen wir die passenden Rollen bereit. Versuch +also möglich die passende Art von Gruppentyp auszuwählen, damit du dort +der Person die richtige Rolle zuweisen kannst. + +## Eigene Bezeichnungen für Rollen + +```{image} images/GroupDescription.png +``` + +Du kannst neben der offiziellen Rollenbezeichnung noch deine eigene +ergänzen, indem du im Rollendialog das zusätzliche Feld ausfüllst. + +Nach diesen Bezeichnung kann allerdings aktuell noch nicht gefiltert +werden. + +[zugriffsrechte]: https://hitobito.readthedocs.io/de/latest/access_concept.html#berechtigunskonzept diff --git a/docs/roles.rst b/docs/roles.rst new file mode 100644 index 0000000..fc3d8de --- /dev/null +++ b/docs/roles.rst @@ -0,0 +1,35 @@ +Rollen +============================================== + +Rollen sind ein zentrales Konzept in hitobito: + +- Jede Person kann beliebig viele Rollen in verschiedenen Kontexten + haben. Peter kann z. B. gleichzeitig Leiter eines Gremiums in einem + Kantonalverband sein, als auch Mitglied in einer Ortsgruppe. +- Welche Rollen zur Verfügung stehen, hängt davon ab, in welcher Gruppe + du die Person zuweist. Z. B. hat eine Gruppe vom Typ Vorstand Rollen + wie PräsidentIn und SekretärIn zur Verfügung. +- Die Rolle der Person bestimmt die `Zugriffsrechte`_ dieser Person. + +Empfehlungen +------------ + +.. image:: images/GroupAdd.png + +Für jede Organisation stellen wir die passenden Rollen bereit. Versuch +also möglich die passende Art von Gruppentyp auszuwählen, damit du dort +der Person die richtige Rolle zuweisen kannst. + +Eigene Bezeichnungen für Rollen +------------------------------- + +.. image:: images/GroupDescription.png + + +Du kannst neben der offiziellen Rollenbezeichnung noch deine eigene +ergänzen, indem du im Rollendialog das zusätzliche Feld ausfüllst. + +Nach diesen Bezeichnung kann allerdings aktuell noch nicht gefiltert +werden. + +.. _Zugriffsrechte: https://hitobito.readthedocs.io/de/latest/access_concept.html#berechtigunskonzept diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 0000000..ea9bf68 --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,23 @@ +# Tags + +Mit Tags (engl. für Etikett, Schildchen) lassen sich in hitobito Kategorien oder Merkmale auf Personen abbilden. Tags sind nicht strukturierte Informationen und können frei definiert werden. Um Tags zu vergeben, sind schreibrechte auf der Person erforderlich. + +## Erfassen von Tags + +Beim Erfassen der Tags könnt ihr die Kategorie direkt eingeben oder auch Unterkategorien bilden. + +Bsp.: + +- Tag "Newsletter" vergeben, falls diese Person einen Newsletter erhalten soll. +- Tag "Mailings: News" oder "Mailings: Events" vergeben, wenn es Newsletter für verschiedene Fälle gibt. + +```{image} images/Tags.png +``` + +## Verwalten von Tags + +Als Administrator können die Tags unter Einstellungen für die ganze Instanz erstellt, bearbeitet, gelöscht und zusammengeführt werden. + +## Personen mit Tags auswählen + +Auf der Personenlisten können nach Tags gefilter werden. Weiter können bei Mailinglisten/Abo Personen aufgrund der gesetzten Tags ausgewählt werden. diff --git a/docs/tags.rst b/docs/tags.rst new file mode 100644 index 0000000..4ce1da5 --- /dev/null +++ b/docs/tags.rst @@ -0,0 +1,28 @@ +Tags +===== + +Mit Tags (engl. für Etikett, Schildchen) lassen sich in hitobito Kategorien oder Merkmale auf Personen abbilden. Tags sind nicht strukturierte Informationen und können frei definiert werden. Um Tags zu vergeben, sind schreibrechte auf der Person erforderlich. + +Erfassen von Tags +---------------------- + +Beim Erfassen der Tags könnt ihr die Kategorie direkt eingeben oder auch Unterkategorien bilden. + +Bsp.: + +- Tag "Newsletter" vergeben, falls diese Person einen Newsletter erhalten soll. +- Tag "Mailings: News" oder "Mailings: Events" vergeben, wenn es Newsletter für verschiedene Fälle gibt. + + +.. image:: images/Tags.png + +Verwalten von Tags +-------------------------------- + +Als Administrator können die Tags unter Einstellungen für die ganze Instanz erstellt, bearbeitet, gelöscht und zusammengeführt werden. + + +Personen mit Tags auswählen +-------------------------------- + +Auf der Personenlisten können nach Tags gefilter werden. Weiter können bei Mailinglisten/Abo Personen aufgrund der gesetzten Tags ausgewählt werden. diff --git a/docs/two_factor_authentication.md b/docs/two_factor_authentication.md new file mode 100644 index 0000000..a0426fb --- /dev/null +++ b/docs/two_factor_authentication.md @@ -0,0 +1,31 @@ +# Zwei-Faktor-Authentifizierung + +Hitobito unterstützt die Zwei-Faktor-Authentifizierung mit folgender Methode: + +- TOTP mittels Authenticator-App und sechsstelligem Code + +## Voraussetzungen + +Für die Zwei-Faktor-Authentifizierung wird ein Smartphone und eine Authenticator-App benötigt. Die Zwei-Faktor-Authentifizierung wurde mit der kostenfreien freeOTP App () entwickelt und getestet, sollte aber grundsätzlich auch mit anderen ähnlichen Apps wie andOTP () oder Google Authenticator funktionieren. + +## Einrichten + +Um die Zwei-Faktor-Authentifizierung einzurichten, muss man sich erst in Hitobito anmelden. Auf dem eigenen Profil kann man nun im Dropdown "Login" den Knopf "Zwei Faktor Authentifizierung einrichten" sehen. Durch Klicken auf diesen Knopf landet man auf einer Seite mit einem QR-Code. + +In der freeOTP App auf dem Smartphone klickt man nun auf den QR-Code-Knopf in der Kopfzeile. Dadurch öffnet sich die Kamera mit einem Quadrat in der Mitte. Der QR-Code in hitobito kann nun mit der Kamera gescannt werden. + +Sobald der Code gescannt wurde, schliesst sich die Kamera und ein neues Element in der Liste sollte auf der App ersichtlich sein. Dies erkennt man anhand der Bezeichnung ''hitobito'' und der E-Mail-Adresse. Durch einen Klick auf den Eintrag wird ein sechsstelliger Code wird angezeigt. + +Dieser Code ändert sich alle paar Sekunden. Nun tippt man den Code in hitobito ein und klickt auf "Absenden". Sollte der Code inkorrekt sein, wird eine enstprechende Nachricht angezeigt und mann muss es erneut versuchen. Sobald der Code korrekt und rechtzeitig eingegeben wurde, wird man auf das Profil zurückgeleitet, und die Zwei-Faktor-Authentifizierung ist eingerichtet. + +## Login mit Zwei-Faktor-Authentifizierung + +Sobald die Zwei-Faktor-Authentifizierung eingerichtet ist, muss der Code von der App bei jedem Login eingegeben werden. Nach der Eingabe von E-Mail und Passwort wird man auf eine Seite mit einer Eingabeaufforderung weitergeleitet. Hier tippt man nun wieder den Code aus der freeOTP App ab und klickt auf "Absenden". Sollte der Code nicht korrekt oder bereits abgelaufen sein, wird eine entsprechende Nachricht angezeigt. Ist der Code jedoch korrekt, wird man authentifiziert und in hitobito weitergeleitet. + +## Zurücksetzen und deaktivieren + +Administratoren können die Zwei-Faktor-Authentifizierung einer Person auf deren Profil zurücksetzen oder deaktivieren. Dort erscheinen unter dem Dropdown "Login" zwei Knöpfe "Zwei Faktor Authentifizierung zurücksetzen" und "Zwei Faktor Authentifizierung deaktivieren". + +Wird die Zwei-Faktor-Authentifizierung zurückgesetzt, wird der Nutzer beim nächsten Login einen neuen QR Code scannen müssen. + +Bei der Deaktivierung wird der Nutzer nicht mehr zur Zwei-Faktor-Authentifizierung aufgefordert. diff --git a/docs/two_factor_authentication.rst b/docs/two_factor_authentication.rst new file mode 100644 index 0000000..214802c --- /dev/null +++ b/docs/two_factor_authentication.rst @@ -0,0 +1,36 @@ +Zwei-Faktor-Authentifizierung +============================= + +Hitobito unterstützt die Zwei-Faktor-Authentifizierung mit folgender Methode: + +- TOTP mittels Authenticator-App und sechsstelligem Code + +Voraussetzungen +------------------------------- + +Für die Zwei-Faktor-Authentifizierung wird ein Smartphone und eine Authenticator-App benötigt. Die Zwei-Faktor-Authentifizierung wurde mit der kostenfreien freeOTP App (https://freeotp.github.io/) entwickelt und getestet, sollte aber grundsätzlich auch mit anderen ähnlichen Apps wie andOTP (https://github.com/andOTP/andOTP) oder Google Authenticator funktionieren. + +Einrichten +------------------------------ + +Um die Zwei-Faktor-Authentifizierung einzurichten, muss man sich erst in Hitobito anmelden. Auf dem eigenen Profil kann man nun im Dropdown "Login" den Knopf "Zwei Faktor Authentifizierung einrichten" sehen. Durch Klicken auf diesen Knopf landet man auf einer Seite mit einem QR-Code. + +In der freeOTP App auf dem Smartphone klickt man nun auf den QR-Code-Knopf in der Kopfzeile. Dadurch öffnet sich die Kamera mit einem Quadrat in der Mitte. Der QR-Code in hitobito kann nun mit der Kamera gescannt werden. + +Sobald der Code gescannt wurde, schliesst sich die Kamera und ein neues Element in der Liste sollte auf der App ersichtlich sein. Dies erkennt man anhand der Bezeichnung ''hitobito'' und der E-Mail-Adresse. Durch einen Klick auf den Eintrag wird ein sechsstelliger Code wird angezeigt. + +Dieser Code ändert sich alle paar Sekunden. Nun tippt man den Code in hitobito ein und klickt auf "Absenden". Sollte der Code inkorrekt sein, wird eine enstprechende Nachricht angezeigt und mann muss es erneut versuchen. Sobald der Code korrekt und rechtzeitig eingegeben wurde, wird man auf das Profil zurückgeleitet, und die Zwei-Faktor-Authentifizierung ist eingerichtet. + +Login mit Zwei-Faktor-Authentifizierung +----------------------------------------------- + +Sobald die Zwei-Faktor-Authentifizierung eingerichtet ist, muss der Code von der App bei jedem Login eingegeben werden. Nach der Eingabe von E-Mail und Passwort wird man auf eine Seite mit einer Eingabeaufforderung weitergeleitet. Hier tippt man nun wieder den Code aus der freeOTP App ab und klickt auf "Absenden". Sollte der Code nicht korrekt oder bereits abgelaufen sein, wird eine entsprechende Nachricht angezeigt. Ist der Code jedoch korrekt, wird man authentifiziert und in hitobito weitergeleitet. + +Zurücksetzen und deaktivieren +-------------------------------------- + +Administratoren können die Zwei-Faktor-Authentifizierung einer Person auf deren Profil zurücksetzen oder deaktivieren. Dort erscheinen unter dem Dropdown "Login" zwei Knöpfe "Zwei Faktor Authentifizierung zurücksetzen" und "Zwei Faktor Authentifizierung deaktivieren". + +Wird die Zwei-Faktor-Authentifizierung zurückgesetzt, wird der Nutzer beim nächsten Login einen neuen QR Code scannen müssen. + +Bei der Deaktivierung wird der Nutzer nicht mehr zur Zwei-Faktor-Authentifizierung aufgefordert.