Viele Frameworks und Tools nutzen CLIs als kleinen Helfer. Laravel benutzt Artisan (zu deutsch Handwerker), Spring Boot hat eine CLI genauso wie VueJS. Über die Kommandozeile (CMD bei Windows, Terminal bei Mac) startet man ein kleines Programm und kann mittels einfacher Befehlen Konfigurationen vornehmen, Code generieren und Daten bereinigen.

CLI-Tools haben dabei wichtige Vorteile:

• Leichtgewichtig: Die Ausführung benötigt keine große Umgebung oder ein aufwendiges User-Interface. Die Interaktion über die Kommandozeile reduziert die Interaktion auf das nötigste.
• Lokal ausführbar: Im Gegensatz zu großen Internet-Services kann ich ein CLI-Tool lokal auf meinem Rechner ausführen und behalte die Hoheit über alle Daten.
• Macht der Sprache: Durch die textuelle Schnittstelle, lassen sich ähnlich wie bei einer Sprache verschiedene Blöcke miteinander kombinieren. Diese Vielzahl an Kombinationen ist in einem User-Interface nur unter hohem Aufwand darstellbar.

Mit der ChurchTools CLI wollen wir diese Vorteile nutzen.

Installation und Konfiguration

1. PHP Interpeter installieren

Die CLI ist in der Programmiersprache PHP entwickelt. Für die Ausführung benötigst du deshalb auf deinem Computer einen PHP Interpreter (min. Version PHP 8.0). Es gibt verschiedene Wege PHP auf einem Client zu installieren. An dieser Stelle lege ich dir folgende Möglichkeiten ans Herz:

Du kannst überprüfen, ob die Installation von PHP erfolgreich war, indem du eine Kommandozeile öffnest (Windows: CMD / Mac: Terminal) und folgenden Befehl eingibst:

php -v

Wenn alles richtig installiert ist, zeigt dir die Kommandozeile die installierte PHP Version an.

Damit das CLI-Tool HTTP-Anfragen an deine ChurchTools Instanz schicken kann, ist es notwendig das du „curl“ in deiner php.ini Konfigurationsdatei aktiviert. Dafür entfernst du in der php.ini Datei einfach das Semikolon vor dem Eintrag:

;extension=curl
extension=curl

2. Download und Konfiguration ChurchTools CLI

Jetzt kannst du die ChurchTools CLI herunterladen:

In folgendem Video siehst du alle Schritte, die für die Installation und Konfiguration notwendig sind:

Wenn dir eine textuelle Beschreibung lieber ist, beschreibe ich dir hier die einzelnen Schritte kurz:

1. Verschiebe die ct.phar Datei am besten in einen separaten Ordner und öffne eine Kommandozeile in diesem Ordner.
2. Mit dem Befehl „php ct.phar list“ kannst du dir alle verfügbaren Befehle anzeigen lassen. Das dürfte sehr hilfreich sein, um einen geeigneten Befehl zu finden. Für die Konfiguration benötigen wir den Befehl „settings:setup“.
3. Führe den Befehl „php ct.phar settings:setup“ in der Kommandozeile aus. Das Tool fragt dich nach verschiedenen Konfigurationwerten, wie ChurchTools-Url, Benutzername, Passwort, …
4. Damit ist die ChurchTools-CLI einsatzbereit!
5. Als Beispiel kannst du jetzt den Song-Pool aus ChurchTools anzeigen und exportieren. Dafür nutzt du den Befehl: „php ct.phar show:songs --export„

Alle Befehle haben den selben Aufbau, der am Song-Pool Export Beispiel gezeigt werden soll:

• PHP Interpreter Aufruf: Der Ausdruck „php“ gibt an, dass die Kommandozeile ein PHP-Anwendung starten soll.
• ChurchTools-CLI Archiv: Die Datei ct.phar ist die ChurchTools-CLI Anwendung, die gestartet werden soll. Dieser Teil bleibt immer gleich.
• Command: Der Befehl für das auslesen und anzeigen des Songpools lautet show:songs. Alle verfügbaren Befehle können mit php ct.phar list angezeigt werden.
• Arguments: Dieser Befehl besitzt keine Argumente. Anders sieht es z.B. bei dem Befehl php ct.phar show:group-members 242 aus, der die Mitglieder einer Gruppe ausliest. Hier muss als Argument die Gruppen-ID (in diesem Fall 242) übergeben werden.
• Options: Diese sind immer Optional und werden mit einem doppelten Spiegelstrich eingeführt. In obigem Beispiel hat die Option --export die Funktion, den Song-Pool auch in einer Excel-Datei zu speichern. Es können auch mehrere Options eingesetzt werden. Hier ein Beispiel:
  php ct.phar show:songs --name=komm --export
  Die Option „name“ ermöglicht das Suchen nach Begriffen, die Option Export exportiert die Tabelle in eine Excel-Datei.

Damit du dir nicht alle Befehle, Argumente und Options aus der Dokumentation merken musst, kannst du mit der Option --help auch immer Informationen zu den einzelnen Befehlen anzeigen lassen.

Was die ChurchTools CLI kann…

Es macht keinen Sinn alle Befehle im Detail zu besprechen, deshalb gebe ich dir einen Überblick über die 5 wichtigsten Aufgaben die du mit der ChurchToosl CLI erledigen kannst. Dazu will ich dir jeweils ein Beispiel geben.

…Daten anzeigen

Natürlich kannst du Daten von ChurchTools abrufen. Wie in diesem Beispiel eine Liste aller verfügbaren Kalender:

Diese Befehle haben jeweils den Präfix „show:„. Du kannst außerdem Abwesenheiten, Gruppen, Gruppen-Teilnehmer, Resourcen, Buchungen, Veranstaltungen, Dienste, Songs und Songkategorien abrufen. (siehe Docs)

Für alle „show“-Befehle stehen dir folgende Options zur Verfügung:

• --export: Exportiert die angezeigten Daten in eine Excel-Datei
• --export-json: Exportiert die angezeigten Daten in eine JSON-Datei
• --export-json-object: Exportiert die JSON-Objekte der angezeigten Datensätze in eine JSON-Datei

Zusätzliche Options der einzelnen Befehle musst du dir über die --help Option anzeigen lassen.

…Daten exportieren

In einigen Fällen reicht die Export Option der show-Befehle nicht aus, weil ein Export eine aufwendigere Berechnung benötigt. Dafür gibt es die Export-Befehle. Hier ein Beispiel für den Export der „Song Nutzungshäufigkeit“. Hier wird für jeden Song bestimmt wie häufig er in einem bestimmten Zeitraum gespielt wurde:

Die Export-Befehle besitzen den Präfix „export:„. Exportieren kannst du unter anderem:

• Eine Liste mit CheckIn-Daten für bestimmte Gruppen (export:check-in)
• Die ChordSheets aller Songs eines bestimmten Gottesdienstes (export:event-setlist)
• Die Gruppenbilder für eine Liste an Gruppen (export:group-images)
• Die Avatare der Gruppenteilnehmer einer bestimmten Gruppe (export:group-member-avatars)
• Eine Tabelle mit allen Berechtigungskonfigurationen (export:permissions)
• Eine Liste mit „runden“ Geburtstage im kommenden Jahr (export:round-birthdays)
• Eine Übersicht wie häufig Mitarbeiter im Dienst der letzten Gottesdienste eingeteilt waren (export:service-person)

Für jeden Export gibt es unterschiedliche Konfigurationen über die Arguments und Options. Diese kannst du in den Docs oder der „help“-Option anschauen.

…Templates anlegen

Befehle können zum Teil sehr lang werden und gerade, wenn man die verschiedenen IDs nicht im Kopf hat ist es praktisch Befehle als Templates zu speichern. Hierzu ein Beispiel:

Um ein Template anzulegen fügst du an das Ende des Befehlt einfach die Option:
--add-template=ExampleTemplateName

Danach steht dir das Template zu Verfügung und du kannst es mit folgendem Befehl ausführen:

php ct.phar template:run ExampleTemplateName

Die Templates werden in dem Ordner config abgelegt und können auch zwischen Geräten ausgetauscht werden. Das ist besonders für die Ausführung auf einem Webspace interessant. Mehr zu Templates findest du in den Docs.

…Datenmigration

Während alle bisher vorgestellten Befehle nur Daten aus ChurchTools ausgelesen haben, sind die „migrate“-Befehle für die Anpassung von Daten in ChurchTools zuständig. Es gibt folgende Befehle:

• Vererbung von Gruppenmitgliedern (migrate:group-member-hierarchy)
• Automatisches ausfüllen der BPM in Song-Arrangements (migrate:song-arrangement-bpm)
• Automatische Benennung der Song-Arrangements nach Tonart (migrate:song-arrangement-names)
• Entfernen des „Song zum Lernen markieren“-Flag an allen Songs (migrate:song-should-practice-clear)

WICHTIG: Im Standard-Fall werden alle migrate-Befehle in einem „Test-Modus“ ausgeführt. Das bedeuetet, die Daten in ChurchTools werden nicht wirklich geändert, sondern die Änderung nur simuliert. Dadurch kann man die Konfiguration einer Migration ausprobieren ohne direkt Änderungen vorzunehmen. Um den Test-Modus zu deaktivieren muss die Option --no-testmode verwendet werden.

Weitere Informationen dazu in den Docs.

…Reports erstellen

Reports generieren textuellen Output in Form einer Markdown Datei. In folgendem Beispiel wird ein Report erstellt über die Schnittmenge der in zwei Gruppen befindenden Mitglieder:

Das Ergebnis dieses Reports sieht wie folgt aus:

Mehr zu Reports in den Docs.

Beispiele aus der Praxis

An dieser Stelle will ich dich auch auf unsere Case Studies aufmerksam machen, die dir Beispiele aus unserer Gemeinde zeigen wie du die ChurchTools CLI einsetzen kannst:

Die Möglichkeiten die ChurchTools CLI einzusetzen ist mit sicherheit noch nicht erschöpft. Wenn du Ideen für weitere Befehle und Anwendungsfälle hast, lass es uns gern wissen. Du bist auch herzlich eingeladen, das Projekt durch einen PR voranzubringen. Für Bugs darfst du gern einen Issue bei GitHub einstellen.

Wir freuen uns von dir zu hören!