.. _t2core_t2ldap_importer_vcf:

Importer VCF
============

Der VCF Importer kann Kontakt Daten aus VCard Dateien oder via CardDAV / CVF via HTTP lesen und in einer :ref:`t2core_t2ldap_importer_http_interface` bereit stellen.


Konfiguration mit t2core
------------------------

Die Konfiguration erfolgt über Environment Variablen im Container. Diese werden über t2core entsprechend gesetzt beim Starten der Container.



VCF aus Datei lesen
'''''''''''''''''''

Liest Kontakte aus einer lokalen Datei ``/trizwo-vcf-exporter/examples/support.vcf``.
Diese wird mit dem Importer Container ausgeliefert als Beispiel und ist daher bereits vorhanden.
Externe Dateien müssen dem Importer Container in das Dateisystem gemountet werden.
Die Konfiguration beschränkt sich auf die Angabe der VCF Datei::

   # File to read from. In this case a example file shiped inside to t2core Container.
   file: /trizwo-vcf-exporter/examples/support.vcf


VCF via HTTP lesen
''''''''''''''''''

Liest Kontakte von einem VCard/CardDAV Server via HTTP.
Die Konfiguration beschränkt sich auf die Angabe der VCF Datei::

   # url to read from.
   url: https://intranet.trizwo.de/remote.php/dav/addressbooks/users/rico/rico/?export

   # Login on Request to CardDAV Server. Used, if username is set and not empty
   username: user1

   # Login Password
   password: passowrd_user1

   # Login method used. Options are digest or basic, default is basic
   auth: basic

   # Check TLS Certificate on Requests to CardDAV Server. Options are true/false, default is set to true
   verify: true

   # HTTP Request Method. Only GET supported. default is GET ^^
   method: "GET"

.. note:: Wenn der CardDAV Server eine Nextcloud Installation ist, dann wird die URL zum Laden der Kontakte aus der Contacts Apps vermutlich dem Schema ``https://< hostname >/remote.php/dav/addressbooks/users/< username> >/< addressbookname >/?export`` folgen.

Konfiguration als externer Importer
-----------------------------------

Greifen mehrere t2core Instanzen auf einen Importer zu, kann dieser als sog. 'externer Importer' laufen.
Dabei werden die Importer über docker-compose konfiguriert und gestartet.
Die diese Importer nutzenden t2core Instanzen verbinden sich dann über HTTP, statt die Importer lokal zu starten.
In einer entsprechenden docker-compose Datei werden die zum Betrieb nötigen Parameter wie ``file`` oder ``url`` oder ``username`` und ``password`` werden als Environment Variablen gesetzt.

.. literalinclude:: docker-compose-vcf.yml
   :language: yaml
   :linenos:

In diesem Beispiel werden die Kontakte von zwei Usern abgeholt und auf den jeweiligen Importern als JSON/YAML auf HTTP Ports erreichbar gemacht.
Im t2core können dann ``externe Importer`` angelegt werden, die die Daten von ``http://<host>:7777/json`` bzw. ``http://<host>:7776/json`` abrufen.

Konfiguration Import von Dateien
--------------------------------

In Abwandlung des vorstehenden Beispiel ẁerden hier zwei Importer konfiguriert, die Dateien zum Importieren gemountet bekommen und anschließend via Port 7777 und 7776 angerufen werden können.

.. literalinclude:: docker-compose-vcf-file.yml
   :language: yaml
   :linenos:

In diesem Beispiel werden die Dateien ``/path/on/the/host/file_internal.vcf`` und ``/path/on/the/host/file_support.vcf`` auf den jeweiligen Importern als JSON/YAML auf HTTP Ports erreichbar gemacht.
Im t2core können dann ``externe Importer`` angelegt werden, die die Daten von ``http://<host>:7777/json`` bzw. ``http://<host>:7776/json`` abrufen.

CLI Tool
''''''''

Im Container ist ein Tool installiert, mit dem das Abholen und das Umwandeln zu JSON getestet werden kann::

    root@a5a5adf29a6e:/trizwo-vcf-importer# ./reader.py  --help
    usage: reader.py [-h] [--file FILE] [--url URL] [--username USERNAME]
                     [--password PASSWORD] [--output OUTPUT] [--verify VERIFY]
                     [--auth AUTH]

    convert VCF to JSON

    optional arguments:
      -h, --help           show this help message and exit
      --file FILE          read VCF Data from file
      --url URL            read VCF Data from HTTP. maybe requires setting
                           connection Parameters like User/Pass.
      --username USERNAME  HTTP Username
      --password PASSWORD  HTTP Password
      --output OUTPUT      Outfile to write JSON Data
      --verify VERIFY      check TLS Certificate at HTTP Request
      --auth AUTH          used HTTP Auth Method. digest/basic (default)

Beispiel Abruf via Url mit Login per Digest Auth und Ausgabe per ``contacts.json``::

    ./reader.py  --output contacts.json --auth digest --username user1 --password password2 --url "http://192.168.178.24:7778/remote.php/dav/addressbooks/users/user1/contacts?export"