====== efaCLI - Kommandoschnittstelle ======

efaCLI ist eine kommandozeilen-basierte Schnittstelle von efa, über die Kommandobasiert auf die Daten von efa zugegriffen werden kann. Außerdem lassen sich über diese Schnittstelle häufige Aufgaben automatisieren, wie z.B. das Erstellen von Backups oder Statistiken. Die von efaCLI unterstützten Kommandos können auch in der efa-Konfiguration zur Ausführung von [[config_cron|Automatischen Abläufen (Cron Jobs)]] verwendet werden.

===== Aufruf von efaCLI =====

Syntax: ''efaCLI [username[:password]@][host[:port]][/project] [-cmd command]''

efaCLI greift nicht selbst auf lokal gespeicherte Daten zu, sondern verbindet sich an efa-Bootshaus und bezieht seine Daten von dort. Damit efaCLI funktioniert, muß efa-Bootshaus zeitgleich auf demselben oder einem anderen Computer laufen.

Für den Zugriff auf efa-Bootshaus benötigt efaCLI den Benutzernamen und Paßwort eines Administrators, der die Berechtigung //Remote-Zugriff über efaRemote// hat. Wenn kein Administrator explizit angegeben wird, verwendet efaCLI den Admin //admin//. Wird kein Paßwort beim Aufruf angegeben, so erfolgt die Abfrage interaktiv. Zur besseren Sicherheit sollte anstelle der Angabe des Paßworts auf der Kommandozeile wie [[config_nopassword|hier]] beschrieben eine Datei ''.efacred'' im Heimatverzeichnis des Betriebssystem-Benutzers angelegt werden, welche Admin-Namen und Paßwort in einer Zeile enthält, z.B. ''admin geheim''.

Desweiteren benötigt efaCLI den Hostnamen (oder die IP-Adresse) und Port des Computers, auf dem efa-Bootshaus läuft. Fehlt diese Angabe, versucht efaCLI sich an den lokalen Computer an Port 3834 zu verbinden.

Die dritte erforderliche Angabe ist der Name des Projekts, auf welches efaCLI zugreifen soll. Dieses muß zum Zeitpunkt des Zugriffs über efaCLI in efa-Bootshaus geöffnet sein. Nach dem ersten erfolgreichen Aufruf von efaCLI merkt sich efaCLI das zuletzt geöffnete Projekt, und verwendet dieses beim nächsten Start erneut.

Ein beispielhafter Aufruf von efaCLI unter Windows könnte folgendermaßen aussehen:

''efaCLI.bat admin@localhost/meinprojekt''

Unter Linux hat der entsprechende Aufruf die Form:

''./efaCLI.sh admin@localhost/meinprojekt''

Ohne Angabe eines Kommandos startet efaCLI eine interaktive Shell, in der Kommandos eingegeben werden können. efaCLI hat mehrere Menüebenen, die durch den Eingabeprompt angezeigt werden. Das Kommando ''help'' zeigt eine Hilfe für das aktuelle Menü. Mit ''exit'' wird das Menü verlassen, und ''quit'' beendet efaCLI:

<code>./efaCLI.sh admin@localhost/meinprojekt
INPUT - CLI003 - efaCLI:main> help
INFO - CLI001 - Help for Menu: main
INFO - CLI001 - ==========================================================================
INFO - CLI001 - boats boat administration
INFO - CLI001 - persons person administration
INFO - CLI001 - destinations destination administration
...
INPUT - CLI003 - efaCLI:main> boats
INPUT - CLI003 - efaCLI:boats> help
INFO - CLI001 - Help for Menu: boats
INFO - CLI001 - ==========================================================================
INFO - CLI001 - list [all|invisible|deleted] list boats
INFO - CLI001 - show [name|index] show record
...
INPUT - CLI003 - efaCLI:boats> exit
INPUT - CLI003 - efaCLI:main> quit</code>

Zur Automatisierung von Aufgaben ist eine //interaktive// Benutzung von efaCLI nicht sinnvoll. Stattdessen sollte efaCLI direkt mit einem Kommando gestartet werden. Wenn das Paßwort wie beschrieben in einer Datei hinterlegt ist, führt efaCLI so beim Aufruf das Kommando aus und beendet sich anschließend wieder. Das auszuführende Kommando wird mittels ''-cmd command'' an efaCLI übergeben. //command// muß von der Shell als ein einzelner Parameter an efaCLI übergeben werden und daher im Falle von Leerzeichen durch Kochkomma eingeschlossen sein.

Um beispielsweise ein Backup aller Daten zu erstellen, kann efaCLI wie folgt aufgerufen werden:

''./efaCLI.sh admin@localhost/meinprojekt -cmd "backup create all"''

Eine Statistik zu einer abgespeicherten Statistikeinstellung //Kilometerliste (HTML)// kann folgendermaßen in efaCLI aufgerufen werden:

''./efaCLI.sh admin@localhost/meinprojekt -cmd "statistics create Kilometerliste (HTML)"''

===== Kommandoübersicht =====

==== Anzeigen und Bearbeiten von Daten ====

Folgende Kommandos erlauben Zugriff auf die jeweiligen Daten:

^ Kommando	     ^ Daten                   ^
| ''boats''	             | Boote                   |
| ''persons''	     | Personen                |
| ''destinations''	     | Ziele                   |
| ''damages''	     | Bootsschäden            |
| ''reservations''	     | Bootsreservierungen     |
| ''boatstatus''	     | Bootsstatus             |
| ''crews''	             | Mannschaften            |
| ''groups''	     | Gruppen                 |
| ''status''	     | Status                  |
| ''waters''	     | Gewässer                |
| ''fahrtenabzeichen''   | Fahrtenabzeichen        |
| ''messages''	     | Nachrichten             |
| ''statistics''	     | Statistikeinstellungen  |

Die oben genannten Kommandos unterstützen folgende Unterkommandos und Optionen:

^ Unterkommando ^ Optionen                    ^ Beschreibung ^
| ''list''	        | ''%%[all|invisible|deleted]%%''     | Datensätze auflisten (wahlweise alle Datensätze, unsichtbare, oder gelöschte) |
| ''show''          | ''%%[name|index]%%''                 | Einen bestimmten Datensatz anzeigen, identifiziert durch seinen Namen (wie von list ausgegeben, oder einen Index (nach vorherigem Aufruf von list) |
| ''export''        | ''%%[-format=xml|csv] <filename>%%'' | Alle Datensätze in eine Datei namens filename exportieren, wahlweise im XML- oder CSV-Format |
| ''import''        | ''%%[-encoding=ENCODING] [-csvsep=X] [-csvquote=X] [-impmode=add|update|addupdate] [-updversion=update|new] [-entryno=dupskip|dupadd|alwaysadd] <filename>%%'' | Datensätze aus einer Datei filename importieren. Die weiteren Optionen spezifizieren den Zeichensatz der zu importierenden Datei (encoding, entweder UTF-8 oder ISO-8859-1), den Feldtrenner (csvsep) und Texttrenner (csvquote) für CSV-Imports, den Import-Modus (impmode - hinzufügen und/oder aktualisieren), das Verhalten beim Update von bestehenden versionierten Datensätzen (updversion - neue Version erstellen oder vorhandene aktualisieren), sowie das Verhalten beim Import von Fahrtenbucheinträgen (entryno - doppelte Einträge nicht importieren, doppelte Einträge mit neuer LfdNr hinzufügen oder alle Einträge mit neuer LfdNr hinzufügen) |

Beispiele:

Um eine Personenliste im CSV-Format in die Datei ''/tmp/personen.csv'' zu exportieren:

''persons export -format=csv /tmp/personen.csv''

Um eine Bootsliste aus der Datei ''/tmp/boote.xml'' zu importieren und nur Einträge zu aktualisieren:

''boats import -impmode=update /tmp/boote.xml''

==== Statistiken erstellen ====

Statistiken werden über das Kommando ''statistics create'' erstellt:

^ Kommando   ^ Unterkommando  ^ Optionen   ^ Beschreibung ^
| ''statistics'' | ''create''         |	''%%[-all|-status=name|-name=name] [name|index]%%'' | Statistik mit Name //name// erstellen (Name wie vom ''list'' Kommando ausgegeben). Statt eines Namens kann auch der Index der Statistik, wie zuvor vom ''list'' Kommando ausgegeben, angegeben werden. Für Individuelle Statistiken kann zusätzlich spezifiziert werden, ob diese für alle Personen/Boote (''-all''), nur für Personen mit Status //name// (''-status=name''), oder nur für eine einzelne Person/ein einzelnes Boot mit Namen //name// (''-name=name'') erzeugt werden sollen. |

**Hinweis:** Die Kommandos erlauben nur das Erstellen von Statistiken, die in Dateien ausgegeben, per email versand oder per FTP hochgeladen werden. Interaktive Statistiken (zur graphischen Anzeige) lassen sich über diese Kommandos nicht erstellen.


Beispiele:
Um eine Kilometerliste zu erstellen, die unter dem Namen //Kilometerliste// als Statistikeinstellung abgespeichert wurde:

''statistics create Kilometerliste''

Um ein individuelles Fahrtenbuch für Manfred Mustermann zu erstellen, unter Verwendung der zuvor erzeugten Statistikeinstellung //Individuelles Fahrtenbuch//:

''statistics create -name=Mustermann,_Manfred Individuelles Fahrtenbuch'' (beachte den Unterstrich!)

Um ein individuelles Fahrtenbuch für alle Personen zu erstellen, unter Verwendung der zuvor erzeugten Statistikeinstellung //Individuelles Fahrtenbuch//:

''statistics create all Individuelles Fahrtenbuch'' (hierbei wird für jede Person eine separate Datei erstellt bzw. separate email verschickt)

==== Datensicherungen erstellen und wiederherstellen ====

Datensicherungen werden über das Kommando ''backup'' erstellt:

^ Kommando ^ Unterkommando ^ Optionen               ^ Beschreibung ^
| ''backup''   | ''create''        | ''%%[project|config|all] [directory/file]%%'' | Erstellt ein Backup des aktuell geöffneten Projekts (project), der Konfiguration ((config), oder von Projekt und Konfiguration (all). Ohne Angabe eines Dateinamens erstellt efa ein Backup im Backup-Verzeichnis. Werden Verzeichnis- und/oder Dateiname angegeben, so verwendet efa diese. Um das Backup als email zu verschicken, kann anstelle einer Datei eine email-Adresse in der Form mailto:name@domain.com angegeben werden. |
| ''backup''   | ''restore''       | ''%%<zipfile> [objects...]%%'' | Stellt aus einer Sicherungsdatei zipfile alle oder einzelne ausgewählte Objekte wieder her. |
| ''backup''   | ''show''          | ''%%<zipfile>%%''              | Zeigt den Inhalt der Sicherungsdatei zipfile an. |

Beispiele:

Um ein Backup des aktuellen Projekts und der Konfiguration zu erstellen:

''backup create all''

Um ein Backup des aktuellen Projekts an die email-Adresse //name@domain.com// zu verschicken:

''backup create project mailto:name@domain.com''

Um eine komplette Sicherung aus der Datei //efaBackup_20130513_223131.zip// wiederherzustellen:

''backup restore efaBackup_20130513_223131.zip''

Um nur das 2013er Fahrtenbuch (mit dem Namen //2013//) einer Sicherung aus der Datei //efaBackup_20130513_223131.zip// wiederherzustellen:

''backup restore efaBackup_20130513_223131.zip 2013.efa2logbook''

==== Synchronisation mit Kanu-eFB ====

Die Synchronisation mit dem Kanu-eFB des DKV kann über das Kommando ''syncefb'' gestartet werden:

^ Kommando ^ Unterkommando ^ Optionen               ^ Beschreibung ^
| ''syncefb''   | ''run''        | ''%%[logbook]%%'' \\ ''%%[-verbose]%%'' | Synchronisiert die Fahrten des aktuell geöffneten Fahrtenbuchs mit dem Kanu-eFB. Durch Angabe eines speziellen Fahrtenbuchs kann dieses anstelle des derzeit geöffneten Fahrtenbuchs synchronisiert werden. \\ \\ Der optionale Parameter ''%%-verbose%%'' ist ab Version 2.4 vorhanden und sorgt für eine detaillierte Protokollierung der //nicht// synchronisierten Fahrten in das efa.log. \\ \\ Damit ist es möglich, einzelne nicht synchronisierte Fahrten und die Ursachen dafür zu erkennen. |

Beispiele:

Um die Fahrten des aktuell geöffneten Fahrtenbuchs zu synchronisieren:

''syncefb run''

Um die Fahrten des Fahrtenbuchs //2013// zu synchronisieren:

''syncefb run 2013''

===== Return Codes =====

Nach der Ausführung von efaCLI gibt efaCLI die folgenden Return Codes zurück, wobei 0 eine erfolgreiche Ausführung anzeigt, und Werte ungleich null einen Fehler signalisieren:

^ Return Code                      ^ Wert ^
| RC_OK                            |    0 |
| RC_ERROR_LOGIN                   |    1 |
| RC_ERROR_OPEN_PROJECT            |    2 |
| RC_UNKNOWN_COMMAND               |    3 |
| RC_INVALID_COMMAND               |    4 |
| RC_NO_PERMISSION                 |    5 |
| RC_COMMAND_COMPLETED_WITH_ERRORS |   10 |
| RC_COMMAND_FAILED                |   11 |