• Recent
    • Tags
    • Popular
    • Users
    • Groups
    • Search
    • Register
    • Login

    ChurchTools API Client (PHP)

    ChurchTools Schnittstellen
    5
    29
    1.5k
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • DumbergerLD
      DumbergerL
      last edited by

      Hallo zusammen,

      um in unseren PHP-Anwendungen eine direkte Integration mit ChurchTools zu ermöglichen haben wir in unserer Gemeinde einen ChurchTools-API Client entwickelt.

      Mit sehr geringem Konfigurationsaufwand kann man mittels Request Facade Daten aus ChurchTools abrufen, die in Objekten gekapselt werden. Damit spart man sich den Aufwand die rohen HTTP-Request zu parsen:

      Hier ein Beispiel um Personen abzurufen:

      $teenager = PersonRequest::where('birthday_before', '2007-01-01')
                          ->where('birthday_after', '2003-01-01')
                          ->orderBy('birthday')
                          ->get();
                           
      foreach($teenager as $teenPerson){
          echo "Hello Teenager with E-Mail: ".$teenPerson->getEmail();
      }
      

      Wir haben mittlerweile fast alle Endpunkte abgedeckt und auch Funktionalität aus der ajax-API integriert (z.B. Integration von CCLI). Dazu zählen...

      • … Personen und Gruppen
      • … Gruppen-Homepages
      • … Kalender
      • … Resourcen und Buchungen
      • … Events und Dienste
      • … Abwesenheiten
      • … Song-Bibliothek (CCLI-Integration, Songs / Arrangements editieren)
      • … Wiki
      • … Dateien (Anhänge, Avatar, Bilder, hochladen und herunterladen)
      • … Globale Suche

      Eine ausführlichere Einführung findest du unter: https://tech.5pm.zone/2022/03/19/churchtools-api/

      Oder im GitHub Repo: https://github.com/5pm-HDH/churchtools-api

      Feedback ist herzlich willkommen!

      B sctechS 2 Replies Last reply Reply Quote 5
      • B
        BiKi @DumbergerL
        last edited by BiKi

        @dumbergerl Vielen Dank, sieht super aus.

        Bisher haben wir die API Schnittstellen mit Jane immer generiert, das geht auch recht einfach. „Problem“ ist dabei, dass die openApi.json nicht immer ganz korrekt ist…

        Evtl stellen wir unsere Projekte auf dein Framework um. Was für eins unserer Projekte noch fehlt (Songstatistik) ist die Möglichkeit, die Songstatistik auszulesen, das geht (bisher) auch nur über die Ajax API - wenn ich dazu komme, ergänze ich das noch und stelle es bei Github ein.

        DumbergerLD 1 Reply Last reply Reply Quote 1
        • DumbergerLD
          DumbergerL @BiKi
          last edited by

          Hi @biki,

          ich hab den Client um die Songstatistik erweitert: https://github.com/5pm-HDH/churchtools-api/blob/master/docs/out/SongAPI.md#retrieve-song-statistics
          Passt das soweit auf deine Anforderung?

          B 1 Reply Last reply Reply Quote 1
          • B
            BiKi @DumbergerL
            last edited by

            @dumbergerl Sieht auf den ersten Blick super aus, werde es heute Abend mal in unserem Project testen... Danke dir für die Arbeit!

            1 Reply Last reply Reply Quote 0
            • sctechS
              sctech @DumbergerL
              last edited by

              @dumbergerl Wow, das sieht super aus - vielen Dank für eure Arbeit! Ich kann mir gut vorstellen (und sehe viel Potenzial darin), in unseren Projekten die bisherigen Methoden durch diesen API Client abzulösen.

              Nach ersten Tests stellen sich mir folgende zwei Fragen:

              Authentifizierung mit TOTP
              In einigen Applikationen bieten wir ein Benutzerlogin an, wobei die Authentifizierung über die ChurchTools API läuft. Dabei wird E-Mail, Passwort und der TOTP Code abgefragt. Wäre es möglich, den Client zu erweitern, sodass der TOTP Code ebenfalls angegeben und geprüft werden kann?

              z.B. als dritter Parameter :

              CTConfig::authWithCredentials("mail@example.com", "abcdef", "123456")
              

              Wenn beim Login für einen Benutzer die 2FA aktiviert ist, kommt von der API folgende Antwort:

              {
                  "data": {
                      "status": "totp",
                      "message": "2-Factor Authentication activated. TOTP needed.",
                      "personId": 1
                  }
              }
              

              Anschliessend muss der TOTP über den Endpunkt /api/login/totp verifiziert werden (Parameter: code, personId). Daraufhin ist der Benutzer korrekt eingeloggt:

              {
                  "data": {
                      "status": "success",
                      "redirectTo": ""
                  }
              }
              

              Benutzerdefinierte Felder
              Werden eigene Felder, welche in ChurchTools für Personen, Gruppen oder Gruppenteilnehmer angelegt wurden auch unterstützt? Wenn ja, wie können sie abgefragt werden? Wenn nein, ist diesbezüglich etwas in Planung?

              Danke fürs Feedback! 🙂

              DumbergerLD 1 Reply Last reply Reply Quote 1
              • DumbergerLD
                DumbergerL @sctech
                last edited by

                @sctech Vielen Dank für deine Vorschläge. Ich bin total dankbar für solche Hinweise!

                Ich habe das Feature Multi-faktor Authentifizierung eben umgesetzt (https://github.com/5pm-HDH/churchtools-api/pull/146) und hab es auf unserer ChurchTools Instanz getestet.

                Bezüglich der Benutzerdefinierten Felder habe ich mal einen Issue (https://github.com/5pm-HDH/churchtools-api/issues/147) angelegt, da dokumentiere ich den aktuellen Stand. Das setze ich auf jeden Fall als nächstes um, ich muss nur schauen wann ich dazukomme 😉

                VG Lukas

                sctechS 1 Reply Last reply Reply Quote 1
                • sctechS
                  sctech @DumbergerL
                  last edited by

                  @dumbergerl Sehr cool! Vielen Dank für die ultraschnelle Implementierung der 2FA! 🙂 👍

                  Ich werde den Client nun schrittweise in unsere Applikationen einbinden und alte Methoden ablösen. An einigen Stellen verwenden wir, wie erwähnt, benutzerdefinierte Felder. Ich freue mich, wenn dazu noch etwas kommen wird! 😉

                  Tausend Dank für dein Investment!

                  B 1 Reply Last reply Reply Quote 0
                  • B
                    BiKi @sctech
                    last edited by

                    @DumbergerL
                    Ich würde mich noch über einen Login mit Userid und Logintoken (statt Email und Passwort) freuen…
                    Ich habe das bei mir mal implementiert:

                    $response = $client->post('index.php?q=login/ajax',[
                    'json' => [
                    'func' => 'loginWithToken',
                    'id' => $id,
                    'token' => $token
                    ],
                    'headers' => [
                    'Cache-Control' => 'no-cache'
                    ]
                    ]);

                    Würde mich freuen, wenn du das übernehmen könntest.

                    Vielen Dank,
                    Birgit

                    DumbergerLD 1 Reply Last reply Reply Quote 0
                    • DumbergerLD
                      DumbergerL @BiKi
                      last edited by

                      @biki

                      Danke für den Vorschlag! Ich hab es mit eingefügt in PR155. Nun kann man auch mit User-ID und Logintoken den Client authentifizieren (siehe Docs):

                      use CTApi\CTConfig;
                      
                      $success = CTConfig::authWithLoginToken("29", "<login-token>");
                      
                      B sctechS 2 Replies Last reply Reply Quote 0
                      • B
                        BiKi @DumbergerL
                        last edited by

                        @dumbergerl Super, vielen Dank, und sooo schnell umgesetzt…. Freut mich sehr….

                        1 Reply Last reply Reply Quote 0
                        • sctechS
                          sctech @DumbergerL
                          last edited by

                          @dumbergerl Sehr gute Ergänzung, danke!

                          Es gibt wohl noch keine dokumentierte Methode, dies über die REST API (anstelle der alten AJAX API) zu tun? Weiss da jemand mehr?

                          Ich hatte bisher auch immer nur eine Krücke angewendet:

                          GET Request: /api/whoami
                          URL-Parameter: user_id, login_token
                          ... danach das Session Cookie für weitere Anfragen übernehmen

                          Aber eben - eigentlich müsste es doch hierfür einen offiziellen Endpoint geben?

                          narnitzN Ralf BürzeleR 2 Replies Last reply Reply Quote 0
                          • B
                            BiKi
                            last edited by

                            @sctech nein, soweit ich weiß, gibt es dafür (noch) keine Rest-API… mache das auch über die Ajax-API…

                            1 Reply Last reply Reply Quote 0
                            • narnitzN
                              narnitz ChurchToolsMitarbeiter @sctech
                              last edited by narnitz

                              @sctech sagte in ChurchTools API Client (PHP):

                              @dumbergerl Sehr gute Ergänzung, danke!

                              Es gibt wohl noch keine dokumentierte Methode, dies über die REST API (anstelle der alten AJAX API) zu tun? Weiss da jemand mehr?

                              Ich hatte bisher auch immer nur eine Krücke angewendet:

                              GET Request: /api/whoami
                              URL-Parameter: user_id, login_token
                              ... danach das Session Cookie für weitere Anfragen übernehmen

                              Aber eben - eigentlich müsste es doch hierfür einen offiziellen Endpoint geben?

                              Bei /api/login bekommst du entweder status=sucess zurück oder status=totp
                              Hier bekommst du auch die personId

                              Falls zweiteres ist folgendes der flow für den neuen API (hier beispielsweise mit dem churchtoolsClient):

                              churchtoolsClient.post('/login/totp', {
                              	code,
                              	personId
                              });
                              

                              Da solltest du dann den Token bekommen.

                              App-Entwickler bei ChurchTools

                              sctechS 1 Reply Last reply Reply Quote 0
                              • sctechS
                                sctech @narnitz
                                last edited by

                                @narnitz Danke - dieser Fall ist klar und auch bereits so implementiert. Die Frage war, ob es keinen Endpoint gibt, welcher den Login mit UserID und Token erlaubt. Der Endpoint /login funktioniert ja „nur“ mit Benutzername und Passwort.

                                Ralf BürzeleR 1 Reply Last reply Reply Quote 0
                                • Ralf BürzeleR
                                  Ralf Bürzele @sctech
                                  last edited by

                                  @sctech Wenn Du den Logintoken hast, brauchst Du Dich nicht einloggen, Du hängst den Token nur an jeden Request an.

                                  Pfarrer und CT-Admin der Evang. Kirchengemeinde Althütte

                                  narnitzN 1 Reply Last reply Reply Quote 0
                                  • narnitzN
                                    narnitz ChurchToolsMitarbeiter @Ralf Bürzele
                                    last edited by

                                    @ralf-bürzele Genau.

                                    App-Entwickler bei ChurchTools

                                    1 Reply Last reply Reply Quote 0
                                    • DumbergerLD
                                      DumbergerL
                                      last edited by

                                      @ralf-bürzele Stimmt es wäre ein Möglichkeit den Login-Token einfach jedes Mal an den Request zu hängen (im Header oder Query). Das hatte ich in der initialen Version auch so implementiert. Allerdings habe ich von ChurchTools die Rückmeldung, dass dann bei jedem Aufruf die Berechtigungen neu errechnet werden müssen. Performanter ist es, den Session-Cookie für die Authentifizierung von mehreren Requests zu verweden. Deshalb nutze ich den Login-Token jetzt nur für einen ersten Request um den Session-Cookie zu erstellen, der dann für alle weiteren Requests verwendet wird.

                                      Im API Client stehen jetzt folgende Authentifizierungmethoden (siehe Docs) zur Verfügung:

                                      1. ...E-Mail und Passwort:
                                      $auth = CTConfig::authWithCredentials($email, $password);
                                      
                                      1. ...E-Mail und Passwort mit Multi-Factor Authentication:
                                      $auth = CTConfig::authWithCredentials($email, $password, $totp);
                                      
                                      1. ...mit User-ID und Login-Token (alte Ajax-API)

                                      Wie @BiKi sich gewünscht hat (wobei für dich vermutlich auch Punkt 4 funktionieren würde?)

                                      $success = CTConfig::authWithUserIdAndLoginToken("29", "<login-token>");
                                      
                                      1. ...mit Login-Token (via REST-API):

                                      Wie @Ralf-Bürzele richtig vorschlägt:

                                      $auth = CTConfig::authWithLoginToken("<login-token>");
                                      

                                      Hinweis: Die Methoden getApiKey() und setApiKey() wurden als deprecated markiert und werden im nächsten Major-Release entfernt. Der Getter lässt sich durch AuthRequest::retrieveApiToken() ersetzen und der Setter durch CTConfig::authWithLoginToken().

                                      B Ralf BürzeleR 2 Replies Last reply Reply Quote 1
                                      • B
                                        BiKi @DumbergerL
                                        last edited by

                                        @dumbergerl vielen Dank!

                                        Ja für mich würde auch der Login mit Logintoken (ohne LoginId) reichen, das hatte ich so nicht auf dem Schirm, dass das auch so möglich ist…

                                        1 Reply Last reply Reply Quote 0
                                        • Ralf BürzeleR
                                          Ralf Bürzele @DumbergerL
                                          last edited by

                                          @dumbergerl ah, gut zu wissen. Dann werde ich bei meiner Implementation auch nach der ersten Verwendung des logintokens dann mit den cookies weiterarbeiten.

                                          Pfarrer und CT-Admin der Evang. Kirchengemeinde Althütte

                                          1 Reply Last reply Reply Quote 1
                                          • Ralf BürzeleR
                                            Ralf Bürzele @sctech
                                            last edited by

                                            @sctech Doch, gibt es. Man kann (vermutlich) jede REST-API-Funktion nehmen, den LoginToken anhängen und zurück kommt ein Session-Cookie, das man weiter verwursten kann. Eben mit /whoami getestet.

                                            Pfarrer und CT-Admin der Evang. Kirchengemeinde Althütte

                                            sctechS 1 Reply Last reply Reply Quote 0
                                            • First post
                                              Last post