doc/dokumentation.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <book id="kivitendo-documentation" lang="de">
   5   <title>kivitendo 3.5.6: Installation, Konfiguration,
   6   Entwicklung</title>
   7
   8   <chapter id="Aktuelle-Hinweise">
   9     <title>Aktuelle Hinweise</title>
  10
  11     <para>Aktuelle Installations- und Konfigurationshinweise gibt es:</para>
  12
  13     <itemizedlist>
  14       <listitem>
  15         <para>im Community-Forum: <ulink
  16         url="https://forum.kivitendo.de">https://forum.kivitendo.de</ulink></para>
  17       </listitem>
  18
  19       <listitem>
  20         <para>im Kunden-Forum: <ulink
  21         url="http://redmine.kivitendo-premium.de/projects/forum/boards/">http://redmine.kivitendo-premium.de/projects/forum/boards/</ulink></para>
  22       </listitem>
  23
  24       <listitem>
  25         <para>in der doc/UPGRADE Datei im doc-Verzeichnis der
  26         Installation</para>
  27       </listitem>
  28
  29       <listitem>
  30         <para>Im Schulungs- und Dienstleistungsangebot der entsprechenden
  31         kivitendo-Partner: <ulink
  32         url="http://www.kivitendo.de/partner.html">http://www.kivitendo.de/partner.html</ulink></para>
  33       </listitem>
  34     </itemizedlist>
  35   </chapter>
  36
  37   <chapter id="config">
  38     <title>Installation und Grundkonfiguration</title>
  39
  40     <sect1 id="Installation-Übersicht">
  41       <title>Übersicht</title>
  42
  43       <para>Die Installation von kivitendo umfasst mehrere Schritte. Die
  44       folgende Liste kann sowohl für Neulinge als auch für alte Hasen als
  45       Übersicht und Stichpunktliste zum Abhaken dienen, um eine Version mit
  46       minimalen Features möglichst schnell zum Laufen zu kriegen.</para>
  47
  48       <orderedlist>
  49         <listitem>
  50           <para><emphasis>Voraussetzungen überprüfen</emphasis>: kivitendo
  51           benötigt gewisse Ressourcen und benutzt weitere Programme. Das
  52           Kapitel "<xref linkend="Benötigte-Software-und-Pakete"/>" erläutert
  53           diese. Auch die Liste der benötigten Perl-Module befindet sich
  54           hier.</para>
  55         </listitem>
  56
  57         <listitem>
  58           <para><emphasis>Installation von kivitendo</emphasis>: Diese umfasst
  59           die "<xref linkend="Manuelle-Installation-des-Programmpaketes"/>"
  60           sowie grundlegende Einstellungen, die der "<xref
  61           linkend="config.config-file"/>" erläutert.</para>
  62         </listitem>
  63
  64         <listitem>
  65           <para><emphasis>Konfiguration externer Programme</emphasis>: hierzu
  66           gehören die Datenbank ("<xref
  67           linkend="Anpassung-der-PostgreSQL-Konfiguration"/>") und der
  68           Webserver ("<xref linkend="Apache-Konfiguration"/>").</para>
  69         </listitem>
  70
  71         <listitem>
  72           <para><emphasis>Benutzerinformationen speichern können</emphasis>:
  73           man benötigt mindestens eine Datenbank, in der Informationen zur
  74           Authentifizierung sowie die Nutzdaten gespeichert werden. Wie man
  75           das als Administrator macht, verrät "<xref
  76           linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>".</para>
  77         </listitem>
  78
  79         <listitem>
  80           <para><emphasis>Benutzer, Gruppen und Datenbanken
  81           anlegen</emphasis>: wie dies alles zusammenspielt erläutert "<xref
  82           linkend="Benutzer--und-Gruppenverwaltung"/>".</para>
  83         </listitem>
  84
  85         <listitem>
  86           <para><emphasis>Los geht's</emphasis>: alles soweit erledigt? Dann
  87           kann es losgehen: "<xref linkend="kivitendo-ERP-verwenden"/>"</para>
  88         </listitem>
  89       </orderedlist>
  90
  91       <para>Alle weiteren Unterkapitel in diesem Kapitel sind ebenfalls
  92       wichtig und sollten vor einer ernsthaften Inbetriebnahme gelesen
  93       werden.</para>
  94     </sect1>
  95
  96     <sect1 id="Benötigte-Software-und-Pakete">
  97       <title>Benötigte Software und Pakete</title>
  98
  99       <sect2 id="Betriebssystem">
 100         <title>Betriebssystem</title>
 101
 102         <para>kivitendo ist für Linux konzipiert, und sollte auf jedem
 103         unixoiden Betriebssystem zum Laufen zu kriegen sein. Getestet ist
 104         diese Version im speziellen auf Debian und Ubuntu, grundsätzlich wurde
 105         bei der Auswahl der Pakete aber darauf Rücksicht genommen, dass es
 106         ohne große Probleme auf den derzeit aktuellen verbreiteten
 107         Distributionen läuft.</para>
 108
 109         <para>Mitte 2020 (ab Version 3.5.6) empfehlen wir:</para>
 110
 111         <itemizedlist>
 112           <listitem>
 113             <para>Debian</para>
 114
 115             <itemizedlist>
 116               <listitem>
 117                 <para>10.0 "Buster"</para>
 118               </listitem>
 119               <listitem>
 120                 <para>11.0 "Bullseye"</para>
 121               </listitem>
 122             </itemizedlist>
 123           </listitem>
 124
 125           <listitem>
 126             <para>20.04 "Focal Fossa" LTS
 127           </para>
 128           </listitem>
 129
 130           <listitem>
 131             <para>openSUSE Leap 15.x und SUSE Linux Enterprise Server 15 GA</para>
 132           </listitem>
 133
 134           <listitem>
 135             <para>Fedora 29</para>
 136           </listitem>
 137         </itemizedlist>
 138       </sect2>
 139
 140       <sect2 id="Pakete" xreflabel="Pakete">
 141         <title>Benötigte Perl-Pakete installieren</title>
 142
 143         <para>Zum Betrieb von kivitendo werden zwingend ein Webserver (meist
 144         Apache) und ein Datenbankserver (PostgreSQL) in einer aktuellen
 145         Version (s.a. Liste der unterstützten Betriebssysteme)
 146         benötigt.</para>
 147
 148         <para>Zusätzlich benötigt kivitendo einige Perl-Pakete, die nicht
 149         Bestandteil einer Standard-Perl-Installation sind. Um zu überprüfen,
 150         ob die erforderlichen Pakete installiert und aktuell genug sind, wird
 151         ein Script mitgeliefert, das wie folgt aufgerufen wird:</para>
 152
 153         <programlisting>./scripts/installation_check.pl</programlisting>
 154
 155         <para>Die vollständige Liste der benötigten Perl-Module lautet:</para>
 156
 157         <itemizedlist>
 158           <listitem>
 159             <para><literal>Algorithm::CheckDigits</literal></para>
 160           </listitem>
 161
 162           <listitem>
 163             <para><literal>Archive::Zip</literal></para>
 164           </listitem>
 165
 166           <listitem>
 167             <para><literal>CAM::PDF</literal></para>
 168           </listitem>
 169
 170           <listitem>
 171             <para><literal>CGI</literal></para>
 172           </listitem>
 173
 174           <listitem>
 175             <para><literal>Clone</literal></para>
 176           </listitem>
 177
 178           <listitem>
 179             <para><literal>Config::Std</literal></para>
 180           </listitem>
 181
 182           <listitem>
 183             <para><literal>Daemon::Generic</literal></para>
 184           </listitem>
 185
 186           <listitem>
 187             <para><literal>DateTime</literal></para>
 188           </listitem>
 189
 190           <listitem>
 191             <para><literal>DateTime::Event::Cron</literal></para>
 192           </listitem>
 193
 194           <listitem>
 195             <para><literal>DateTime::Format::Strptime</literal></para>
 196           </listitem>
 197
 198           <listitem>
 199             <para><literal>DateTime::Set</literal></para>
 200           </listitem>
 201
 202           <listitem>
 203             <para><literal>DBI</literal></para>
 204           </listitem>
 205
 206           <listitem>
 207             <para><literal>DBD::Pg</literal></para>
 208           </listitem>
 209
 210           <listitem>
 211             <para><literal>Email::Address</literal></para>
 212           </listitem>
 213
 214           <listitem>
 215             <para><literal>Email::MIME</literal></para>
 216           </listitem>
 217
 218           <listitem>
 219             <para><literal>Exception::Class</literal></para>
 220           </listitem>
 221
 222           <listitem>
 223             <para><literal>FCGI</literal> (nicht Versionen 0.68 bis 0.71
 224             inklusive; siehe <xref
 225             linkend="Apache-Konfiguration.FCGI.WebserverUndPlugin"/>)</para>
 226           </listitem>
 227
 228           <listitem>
 229             <para><literal>File::Copy::Recursive</literal></para>
 230           </listitem>
 231
 232           <listitem>
 233             <para><literal>File::Flock</literal></para>
 234           </listitem>
 235
 236           <listitem>
 237             <para><literal>File::MimeInfo</literal></para>
 238           </listitem>
 239
 240           <listitem>
 241             <para><literal>File::Slurp</literal></para>
 242           </listitem>
 243
 244           <listitem>
 245             <para><literal>GD</literal></para>
 246           </listitem>
 247
 248           <listitem>
 249             <para><literal>HTML::Parser</literal></para>
 250           </listitem>
 251
 252           <listitem>
 253             <para><literal>HTML::Restrict</literal></para>
 254           </listitem>
 255
 256           <listitem>
 257             <para><literal>Image::Info</literal></para>
 258           </listitem>
 259
 260           <listitem>
 261             <para><literal>JSON</literal></para>
 262           </listitem>
 263
 264           <listitem>
 265             <para><literal>List::MoreUtils</literal></para>
 266           </listitem>
 267
 268           <listitem>
 269             <para><literal>List::UtilsBy</literal></para>
 270           </listitem>
 271
 272           <listitem>
 273             <para>LWP::Authen::Digest</para>
 274           </listitem>
 275
 276           <listitem>
 277             <para>LWP::UserAgent</para>
 278           </listitem>
 279
 280           <listitem>
 281             <para><literal>Net::SMTP::SSL</literal> (optional, bei
 282             E-Mail-Versand über SSL; siehe Abschnitt "<xref
 283             linkend="config.sending-email.smtp"/>")</para>
 284           </listitem>
 285
 286           <listitem>
 287             <para><literal>Net::SSLGlue</literal> (optional, bei
 288             E-Mail-Versand über TLS; siehe Abschnitt "<xref
 289             linkend="config.sending-email.smtp"/>")</para>
 290           </listitem>
 291
 292           <listitem>
 293             <para><literal>Params::Validate</literal></para>
 294           </listitem>
 295
 296           <listitem>
 297             <para><literal>PBKDF2::Tiny</literal></para>
 298           </listitem>
 299
 300           <listitem>
 301             <para><literal>PDF::API2</literal></para>
 302           </listitem>
 303
 304           <listitem>
 305             <para><literal>Regexp::IPv6</literal></para>
 306           </listitem>
 307
 308           <listitem>
 309             <para><literal>Rose::Object</literal></para>
 310           </listitem>
 311
 312           <listitem>
 313             <para><literal>Rose::DB</literal></para>
 314           </listitem>
 315
 316           <listitem>
 317             <para><literal>Rose::DB::Object</literal> Version 0.788 oder
 318             neuer</para>
 319           </listitem>
 320
 321           <listitem>
 322             <para><literal>Set::Infinite</literal></para>
 323           </listitem>
 324
 325           <listitem>
 326             <para><literal>String::ShellQuote</literal></para>
 327           </listitem>
 328
 329           <listitem>
 330             <para><literal>Sort::Naturally</literal></para>
 331           </listitem>
 332
 333           <listitem>
 334             <para><literal>Template</literal></para>
 335           </listitem>
 336
 337           <listitem>
 338             <para><literal>Text::CSV_XS</literal></para>
 339           </listitem>
 340
 341           <listitem>
 342             <para><literal>Text::Iconv</literal></para>
 343           </listitem>
 344
 345           <listitem>
 346             <para><literal>Text::Unidecode</literal></para>
 347           </listitem>
 348
 349           <listitem>
 350             <para><literal>URI</literal></para>
 351           </listitem>
 352
 353           <listitem>
 354             <para><literal>XML::Writer</literal></para>
 355           </listitem>
 356
 357           <listitem>
 358             <para><literal>XML::LibXML</literal></para>
 359           </listitem>
 360
 361           <listitem>
 362             <para><literal>YAML::XS</literal> oder <literal>YAML</literal></para>
 363           </listitem>
 364         </itemizedlist>
 365
 366
 367         <para>Seit Version größer v3.5.6 sind die folgenden Pakete hinzugekommen: <literal>XML::LibXML</literal>, <literal>CAM::PDF</literal></para>
 368         <para>Seit Version größer v3.5.3 sind die folgenden Pakete hinzugekommen: <literal>Exception::Class</literal></para>
 369
 370         <para>Seit Version größer v3.5.1 sind die folgenden Pakete hinzugekommen: <literal>Set::Infinite</literal>,
 371         <literal>List::UtilsBy</literal>, <literal>DateTime::Set</literal>, <literal>DateTime::Event::Cron</literal>
 372         <literal>Daemon::Generic</literal>, <literal>DateTime::Event::Cron</literal>, <literal>File::Flock</literal>,
 373         <literal>File::Slurp</literal></para>
 374
 375         <para>Seit Version größer v3.5.0 sind die folgenden Pakete
 376         hinzugekommen: <literal>Text::Unidecode</literal>,
 377         <literal>LWP::Authen::Digest</literal>,
 378         <literal>LWP::UserAgent</literal></para>
 379
 380         <para>Seit Version v3.4.0 sind die folgenden Pakete hinzugekommen:
 381         <literal>Algorithm::CheckDigits</literal>,
 382         <literal>PBKDF2::Tiny</literal></para>
 383
 384         <para>Seit Version v3.2.0 sind die folgenden Pakete hinzugekommen:
 385         <literal>GD</literal>, <literal>HTML::Restrict</literal>,
 386         <literal>Image::Info</literal></para>
 387
 388         <para>Seit v3.0.0 sind die folgenden Pakete hinzugekommen:
 389         <literal>File::Copy::Recursive</literal>.</para>
 390
 391         <para>Seit v2.7.0 sind die folgenden Pakete hinzugekommen:
 392         <literal>Email::MIME</literal>, <literal>Net::SMTP::SSL</literal>,
 393         <literal>Net::SSLGlue</literal>.</para>
 394
 395         <para>Gegenüber Version 2.6.0 sind zu dieser Liste 2 Pakete
 396         hinzugekommen, <literal>URI</literal> und
 397         <literal>XML::Writer</literal> sind notwendig. Ohne startet kivitendo
 398         nicht.</para>
 399
 400         <para>Gegenüber Version 2.6.1 sind <literal>parent</literal>,
 401         <literal>DateTime</literal>, <literal>Rose::Object</literal>,
 402         <literal>Rose::DB</literal> und <literal>Rose::DB::Object</literal>
 403         neu hinzugekommen. <literal>IO::Wrap</literal> wurde entfernt.</para>
 404
 405         <para>Gegenüber Version 2.6.3 ist <literal>JSON</literal> neu
 406         hinzugekommen.</para>
 407
 408         <para><literal>Email::Address</literal> und
 409         <literal>List::MoreUtils</literal> sind schon länger feste
 410         Abhängigkeiten, wurden aber bisher mit kivitendo mitgeliefert. Beide
 411         sind auch in 2.6.1 weiterhin mit ausgeliefert, wurden in einer
 412         zukünftigen Version aber aus dem Paket entfernt werden. Es wird
 413         empfohlen diese Module zusammen mit den anderen als Bibliotheken zu
 414         installieren.</para>
 415
 416         <sect3>
 417           <title>Debian und Ubuntu</title>
 418           <para>Für Debian und Ubuntu stehen die meisten der benötigten
 419           Pakete als Debian-Pakete zur Verfügung. Sie können mit
 420           folgendem Befehl installiert werden:</para>
 421
 422           <programlisting>apt install  apache2 libarchive-zip-perl libclone-perl \
 423   libconfig-std-perl libdatetime-perl libdbd-pg-perl libdbi-perl \
 424   libemail-address-perl  libemail-mime-perl libfcgi-perl libjson-perl \
 425   liblist-moreutils-perl libnet-smtp-ssl-perl libnet-sslglue-perl \
 426   libparams-validate-perl libpdf-api2-perl librose-db-object-perl \
 427   librose-db-perl librose-object-perl libsort-naturally-perl \
 428   libstring-shellquote-perl libtemplate-perl libtext-csv-xs-perl \
 429   libtext-iconv-perl liburi-perl libxml-writer-perl libyaml-perl \
 430   libimage-info-perl libgd-gd2-perl libapache2-mod-fcgid \
 431   libfile-copy-recursive-perl postgresql libalgorithm-checkdigits-perl \
 432   libcrypt-pbkdf2-perl git libcgi-pm-perl libtext-unidecode-perl libwww-perl\
 433   postgresql-contrib aqbanking-tools poppler-utils libhtml-restrict-perl\
 434   libdatetime-set-perl libset-infinite-perl liblist-utilsby-perl\
 435   libdaemon-generic-perl libfile-flock-perl libfile-slurp-perl\
 436   libfile-mimeinfo-perl libpbkdf2-tiny-perl libregexp-ipv6-perl \
 437   libdatetime-event-cron-perl libexception-class-perl libcam-pdf-perl \
 438   libxml-libxml-perl
 439 </programlisting>
 440 <para>Sollten Pakete nicht zu Verfügung stehen, so können diese auch mittels CPAN installiert werden. Ferner muss für Ubuntu das Repository "Universe" aktiv sein (s.a. Anmerkungen).</para>
 441           <note id="ubuntu-universe">
 442             <para>Die Perl Pakete für Ubuntu befinden sich im "Universe" Repository. Falls dies nicht aktiv ist, kann dies mit folgendem Aufruf aktiviert werden:
 443 <programlisting>add-apt-repository universe</programlisting></para>
 444           </note>
 445         </sect3>
 446
 447         <sect3>
 448           <title>Fedora</title>
 449
 450           <para>Für Fedora stehen die meisten der benötigten Perl-Pakete als
 451           RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl
 452           installiert werden:</para>
 453
 454           <programlisting>dnf install httpd mod_fcgid postgresql-server postgresql-contrib\
 455   perl-Algorithm-CheckDigits perl-Archive-Zip perl-CPAN perl-Class-XSAccessor \
 456   perl-Clone perl-Config-Std perl-DBD-Pg perl-DBI perl-Daemon-Generic \
 457   perl-DateTime perl-DateTime-Set perl-Email-Address perl-Email-MIME perl-FCGI \
 458   perl-File-Copy-Recursive perl-File-Flock perl-File-MimeInfo perl-File-Slurp \
 459   perl-GD perl-HTML-Restrict perl-JSON perl-List-MoreUtils perl-List-UtilsBy \
 460   perl-Net-SMTP-SSL perl-Net-SSLGlue perl-PBKDF2-Tiny perl-PDF-API2 \
 461   perl-Params-Validate perl-Regexp-IPv6 perl-Rose-DB perl-Rose-DB-Object \
 462   perl-Rose-Object perl-Sort-Naturally perl-String-ShellQuote \
 463   perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI perl-XML-Writer \
 464   perl-YAML perl-libwww-perl</programlisting>
 465         </sect3>
 466
 467         <sect3>
 468           <title>openSUSE Leap 15.x und SUSE Linux Enterprise Server 15 GA</title>
 469
 470           <para>Für openSUSE Leap 15.x stehen die meisten der benötigten Perl-Pakete als RPM-Pakete zur Verfügung.</para>
 471           <para>Damit diese installiert werden können, muß das System die erforderlichen Repositories kennen und Zugriff über das Internet darauf haben.</para>
 472           <para>Daher machen wir die Repositories dem System bekannt.</para>
 473           <para>Um die zusätzlichen Repositories für die Installation zur Verfügung zu stellen, kann man diese mit YaST oder auch in einem Terminal auf der Konsole bekannt geben. Wir beschränken uns hier mit der Eingabe auf der Konsole. In den allermeisten Fällen verwenden die Administratoren eine sichere SSH-Verbindung zum zu administrierenden Server.</para>
 474           <para>Dazu geben wir folgenden Befehl ein:</para>
 475           <programlisting>zypper addrepo -f \
 476   http://download.opensuse.org/repositories/devel:languages:perl/openSUSE_Leap_15.2/ \
 477   "devel:languages:perl"
 478           </programlisting>
 479           <programlisting>zypper addrepo -f \
 480   https://download.opensuse.org/repositories/devel:languages:haskell:lts:13/\
 481   openSUSE_Leap_15.0/ "devel:languages:haskell:lts:13"
 482           </programlisting>
 483           <programlisting>zypper addrepo -f \
 484   https://download.opensuse.org/repositories/devel:languages:haskell:lts:13/\
 485   openSUSE_Leap_15.0/ "devel:languages:haskell:lts:13"
 486           </programlisting>
 487           <para>Danach geben wir noch die beiden folgenden Befehle ein:</para>
 488           <programlisting>zypper clean</programlisting>
 489           <programlisting>zypper refresh</programlisting>
 490           <para>Sollte zypper eine Meldung ausgeben, ob der Repositorie Key abgelehnt, nicht vertraut oder für immer akzeptiert werden soll, ist die Beantwortung durch drücken der "i" Taste am besten geeignet. Wer noch mehr über zypper erfahren möchte, kann sich einmal die zypper Hilfe anschauen.</para>
 491           <programlisting>zypper --help</programlisting>
 492           <note>
 493           <para>Offiziell wird von openSUSE nur noch Versionen ab 15.2 unterstützt. Die SuSE Macher haben ab Version 15.x einen großen Umbau in der Verwaltung der Pakete vorgenommen, das heißt, der Paketumfang ist der SLES 15 als Programmunterbau angepasst. Dies gilt besonders der openSUSE Distribution. Es gibt ja einmal die openSUSE Distri und die Professionelle SLES Version. Dadurch sind viele Pakete aus dem ursprünglich nur für die openSUSE geltenen Repositorie enfernt worden, aber auch viele auf aktuellem Stand gehalten.</para>
 494           </note>
 495           <para>Ab openSUSE Leap 15.x kann man die Distribution auch als reine Text Version, also ohne KDE Oberfläche aufsetzen. Vorteil hierbei ist, dass weniger Balast und unnötige Pakte installiert werden.</para>
 496           <para>Bei openSUSE Versionen bis 15.x, also 10.x, 11.x, 12.x, 13.x hatte der Administrator die Möglichkeit, bei der Installation der Distribution die KDE Oberfläche zu aktivieren. In dieser Konstellation hat man die Möglichkeit, eine VNC Verbindung vom administrativen Client zu verwenden. Ist das nicht eingerichtet, arbeitet der Admin dann direkt am Bildschirm des Servers. Nun loggen wir uns am Server direkt ein, starten Yast2 in einer Konsole wie folgt:</para>
 497           <para>yast2 return.</para>
 498           <para>Oder über die Menüführung wie folgt: Ein Klick auf das runde Icon, ganz links unten in der Menüleiste, dann die Maus verfahren auf System und YaST.</para>
 499           <para>Im weiteren Verlauf der Installation, beschränken wir uns mit dem Installations Werkzeug zypper. Zypper ist ein Komandozeilen basiertes Installations Tool, welches bei openSUSE Standard ist. Zypper weist ein etwas eigenartiges Verhalten auf, dass sich in etwa wie folgt darstellt. Hat man die Repositories eingerichtet, kann man diese mit Yast als auch mit Zypper benutzen, setzt man einen Befehl wie etwa: zypper up ab, so findet zypper mehr neuere Programmversionen als Yast. Ich habe im allgemeinen noch keine Nachteile damit erlebt.</para>
 500           <para>Programmpakete können mit folgendem Befehl installiert werden:</para>
 501           <para>zypper install Paketname</para>
 502           <para>Es wird empfohlen zusätzliche Pakete nicht direkt mit CPAN zu installieren, da man diese auch über andere Repositories beziehen kann, die bei openSUSE zur Verfügung stehen. Dadurch hat man den Vorteil, dass die Pakete mit YaST verwaltet werden, also wieder deinstalliert oder durch neuere ersetzt werden können. Zudem kann man auch noch eventuelle Bugs an openSUSE senden und diese dem Maintainer melden.</para>
 503
 504           <programlisting>zypper install perl-threads-shared ghc-pdfinfo apache2-mod_fcgid \
 505   yast2-http-server postgresql-server postgresql-contrib perl-Algorithm-CheckDigits \
 506   perl-Archive-Zip perl-CGI perl-CGI-Ajax perl-Clone \
 507   perl-Config-Std perl-Class-XSAccessor perl-Daemon-Generic perl-DateTime \
 508   perl-DateTime-Event-Cron perl-DateTime-Format-Strptime perl-DateTime-Set \
 509   perl-DBI perl-DBD-Pg perl-Devel-REPL perl-FastCGI perl-Email-Address \
 510   perl-Email-MIME perl-Email-MIME-ContentType perl-Email-MIME-Encodings \
 511   perl-FCGI perl-File-Copy-Recursive perl-File-Flock perl-File-MimeInfo \
 512   perl-File-Slurp perl-GD perl-HTML-Restrict perl-Image-Info \
 513   perl-JSON perl-List-MoreUtils perl-List-UtilsBy perl-Log-Log4perl perl-Net-LDAP-Server \
 514   perl-Net-SSLGlue perl-Net-SMTP-SSL perl-PBKDF2-Tiny perl-PDF-API2 \
 515   perl-Params-Validate perl-Regexp-IPv6 perl-Rose-DB perl-Rose-Object \
 516   perl-Rose-DB-Object perl-MooseX-Role-Cmd perl-Set-Crontab perl-Set-Infinite \
 517   perl-Sort-Naturally perl-String-ShellQuote perl-Sys-CPU perl-Template-Toolkit \
 518   perl-Text-CSV_XS perl-Test-Deep perl-Test-Output perl-Text-Iconv \
 519   perl-Text-Unidecode perl-URI perl-URI-Find perl-XML-Writer \
 520   perl-YAML perl-libwww-perl
 521           </programlisting>
 522
 523           <para>Für die Entwickler installiert man noch die folgenden Pakete:</para>
 524
 525           <programlisting>zypper install ghc-mtl-devel ghc-old-locale-devel \
 526   ghc-process-extras-devel ghc-rpm-macros ghc-text-devel ghc-time-devel \
 527   ghc-Cabal-devel ghc-time-locale-compat-devel perl-Log-Log4perl ghc-pdfinfo \
 528   ghc-pdfinfo-devel perl-Devel-REPL perl-URI-Find perl-Class-Utils \
 529   perl-Error-Pure perl-File-Object perl-Readonly perl-Test-Warnings \
 530   perl-Test-NoWarnings perl-Test-Deep perl-Test-Output perl-Test-Strict \
 531   perl-Test-LongString perl-File-Find-Rule
 532           </programlisting>
 533
 534           <para>Zusätzlich müssen einige Pakete für den Umgang mit Latex installiert werden. Die Latex Module barcodes sind nützliche Helfer um auch Barcodes im Dokument zu platzieren, der Vollständigkeit halber hier für die Installation mit angegeben.
 535               Dazu können Sie die folgenden Befehle nutzen:</para>
 536
 537           <programlisting>zypper install texlive-wallpaper texlive-colortbl \
 538   texlive-scrlttr2copy texlive-eurosym \
 539   texlive-geometry texlive-german texlive-graphbox texlive-hyperref \
 540   texlive-xifthen texlive-luainputenc texlive-lastpage texlive-ltabptch \
 541   texlive-nomentbl texlive-threeparttablex texlive-substr texlive-tabulary \
 542   texlive-ulem texlive-wallpaper texlive-xcolor texlive-xstring \
 543   texlive-xypic texlive-mwe texlive-mweights texlive-barcodes \
 544   texlive-GS1 texlive-ean texlive-makebarcode texlive-pst-barcode \
 545   texlive-upca
 546           </programlisting>
 547
 548           <para>Zusätzlich müssen einige Pakete aus dem CPAN installiert
 549           werden. Dazu können Sie die folgenden Befehle anwenden:</para>
 550
 551           <programlisting>cpan DateTime::event::Cron DateTime::Set FCGI \
 552   HTML::Restrict PBKDF2::Tiny Rose::Db::Object Set::Infinite</programlisting>
 553         </sect3>
 554       </sect2>
 555
 556       <sect2>
 557         <title>Andere Pakete installieren</title>
 558
 559         <itemizedlist>
 560       <listitem>
 561             <para><literal>aqbanking-tools</literal> Für das Parsen des MT940 Bankformats (Version 6 oder höher)</para>
 562           </listitem>
 563           <listitem>
 564             <para><literal>poppler-utils</literal> 'pdfinfo' zum Erkennen der Seitenanzahl bei der PDF-Generierung</para>
 565           </listitem>
 566           <listitem>
 567             <para><literal>Postgres Trigram-Index</literal> Für datenbankoptimierte Suchanfragen. Bspw. im Paket <literal>postgresql-contrib</literal> enthalten</para>
 568           </listitem>
 569         </itemizedlist>
 570         <para>Debian und Ubuntu: <programlisting>apt install aqbanking-tools postgresql-contrib poppler-utils</programlisting></para>
 571         <para>Fedora: <programlisting>dnf install aqbanking poppler-utils postgresql-contrib</programlisting></para>
 572         <para>openSUSE: <programlisting>zypper install aqbanking-tools poppler-tools</programlisting></para>
 573       </sect2>
 574     </sect1>
 575
 576     <sect1 id="Manuelle-Installation-des-Programmpaketes"
 577            xreflabel="Manuelle Installation des Programmpaketes">
 578       <title>Manuelle Installation des Programmpaketes</title>
 579
 580       <para>Der aktuelle Stable-Release, bzw. beta Release wird bei github
 581       gehostet und kann <ulink
 582       url="https://github.com/kivitendo/kivitendo-erp/releases">hier</ulink>
 583       heruntergeladen werden.</para>
 584
 585       <para>Das aktuelleste kivitendo ERP-Archiv
 586       (<filename>kivitendo-erp-*.tgz</filename>) wird dann im
 587       Dokumentenverzeichnis des Webservers (z.B.
 588       <filename>/var/www/html/</filename>,
 589       <filename>/srv/www/htdocs</filename> oder
 590       <filename>/var/www/</filename>) entpackt:</para>
 591
 592       <programlisting>cd /var/www
 593 tar xvzf kivitendo-erp-*.tgz</programlisting>
 594
 595       <para>Wechseln Sie in das entpackte Verzeichnis:</para>
 596
 597       <programlisting>cd kivitendo-erp</programlisting>
 598
 599       <para>Alternativ können Sie auch einen Alias in der
 600       Webserverkonfiguration benutzen, um auf das tatsächliche
 601       Installationsverzeichnis zu verweisen.</para>
 602
 603       <para>Bei einer Neuinstallation von Version 3.1.0 oder später muß das
 604       WebDAV Verzeichnis derzeit manuell angelegt werden:</para>
 605
 606       <programlisting>mkdir webdav</programlisting>
 607
 608       <para>Die Verzeichnisse <filename>users</filename>,
 609       <filename>spool</filename> und <filename>webdav</filename> müssen für
 610       den Benutzer beschreibbar sein, unter dem der Webserver läuft. Die
 611       restlichen Dateien müssen für diesen Benutzer lesbar sein. Die Benutzer-
 612       und Gruppennamen sind bei verschiedenen Distributionen unterschiedlich
 613       (z.B. bei Debian/Ubuntu <constant>www-data</constant>, bei Fedora
 614       <constant>apache</constant> oder bei openSUSE
 615       <constant>wwwrun</constant>).</para>
 616
 617       <para>Der folgende Befehl ändert den Besitzer für die oben genannten
 618       Verzeichnisse auf einem Debian/Ubuntu-System:</para>
 619
 620       <programlisting>chown -R www-data users spool webdav</programlisting>
 621
 622       <para>Weiterhin muss der Webserver-Benutzer in den Verzeichnissen
 623       <filename>templates</filename> und <filename>users</filename>
 624       Unterverzeichnisse für jeden neuen Benutzer anlegen dürfen, der in
 625       kivitendo angelegt wird:</para>
 626
 627       <programlisting>chown www-data templates users</programlisting>
 628
 629       <note>
 630         <para>Wir empfehlen eine Installation mittels des Versionsmanagager
 631         git. Hierfür muss ein git-Client installiert sein. Damit ist man sehr
 632         viel flexibler für zukünftige Upgrades. Installations-Anleitung (bitte
 633         die Pfade anpassen) bspw. wie folgt: <programlisting>cd /var/www/
 634 git clone https://github.com/kivitendo/kivitendo-erp.git
 635 cd kivitendo-erp/
 636 git checkout `git tag -l | egrep -ve "(alpha|beta|rc)" | tail -1`</programlisting>
 637         Erläuterung: Der Befehl wechselt zur letzten Stable-Version (git tag
 638         -l listet alle Tags auf, das egrep schmeisst alle Einträge mit alpha,
 639         beta oder rc raus und das tail gibt davon den obersten Treffer
 640         zurück). Sehr sinnvoll ist es, direkt im Anschluss einen eigenen
 641         Branch zu erzeugen, um bspw. seine eigenen Druckvorlagen-Anpassungen
 642         damit zu verwalten. Hierfür reicht ein simples <programlisting>  git checkout -b meine_eigenen_änderungen</programlisting>
 643         nach dem letzten Kommando (weiterführende Informationen <ulink
 644         url="http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html">
 645         Git Magic</ulink>).</para>
 646
 647         <para>Ein beispielhafter Workflow für Druckvorlagen-Anpassungen von
 648         3.4.1 nach 3.5: <programlisting>
 649 $ git clone https://github.com/kivitendo/kivitendo-erp.git
 650 $ cd kivitendo-erp/
 651 $ git checkout release-3.4.1                # das ist ein alter release aus dem wir starten ...
 652 $ git checkout -b meine_eigene_änderungen   # unser lokaler branch - unabhängig von allen anderen
 653 $ git add templates/mein_druck              # das sind unsere druckvorlagen inkl. produktbilder
 654 $ git commit -m "juhu tolle änderungen"
 655
 656 [meine_aenderungen 1d89e41] juhu tolle ändernungen
 657  4 files changed, 380 insertions(+)
 658  create mode 100644 templates/mein_druck/img/webdav/tesla.png
 659  create mode 100644 templates/mein_druck/mahnung.tex
 660  create mode 100644 templates/mein_druck/zahlungserinnerung_zwei.tex
 661  create mode 100644 templates/mein_druck/zahlungserinnerung_zwei_invoice.tex
 662
 663 # 5 Jahre später ...
 664 # webserver abschalten!
 665
 666 $ git checkout master
 667 $ git pull                                  # oder git fetch und danach ein stable release tag auswählen (s.o.)
 668 $ git checkout meine_eigenen_änderungen
 669 $ git rebase master
 670
 671 Zunächst wird der Branch zurückgespult, um Ihre Änderungen
 672 darauf neu anzuwenden ...
 673 Wende an: juhu tolle änderungen
 674 $ service apache2 restart                   # webserver starten!
 675 </programlisting></para>
 676       </note>
 677     </sect1>
 678
 679     <sect1 id="config.config-file">
 680       <title>kivitendo-Konfigurationsdatei</title>
 681
 682       <sect2 id="config.config-file.introduction"
 683              xreflabel="Einführung in die Konfigurationsdatei">
 684         <title>Einführung</title>
 685
 686         <para>In kivitendo gibt es nur noch eine Konfigurationsdatei, die
 687         benötigt wird: <filename>config/kivitendo.conf</filename> (kurz: "die
 688         Hauptkonfigurationsdatei"). Diese muss bei der Erstinstallation von
 689         kivitendo bzw. der Migration von älteren Versionen angelegt
 690         werden.</para>
 691
 692         <para>Als Vorlage dient die Datei
 693         <filename>config/kivitendo.conf.default</filename> (kurz: "die
 694         Default-Datei"):</para>
 695
 696         <programlisting>$ cp config/kivitendo.conf.default config/kivitendo.conf</programlisting>
 697
 698         <para>Die Default-Datei wird immer zuerst eingelesen. Werte, die in
 699         der Hauptkonfigurationsdatei stehen, überschreiben die Werte aus der
 700         Default-Datei. Die Hauptkonfigurationsdatei muss also nur die
 701         Abschnitte und Werte enthalten, die von denen der Default-Datei
 702         abweichen.</para>
 703
 704         <note>
 705           <para>Vor der Umbenennung in kivitendo hieß diese Datei noch
 706           <filename>config/lx_office.conf</filename>. Aus Gründen der
 707           Kompatibilität wird diese Datei eingelesen, sofern die Datei
 708           <filename>config/kivitendo.conf</filename> nicht existiert.</para>
 709         </note>
 710
 711         <para>Diese Hauptkonfigurationsdatei ist dann eine
 712         installationsspezifische Datei, d.h. sie enthält bspw. lokale
 713         Passwörter und wird auch nicht im Versionsmanagement (git)
 714         verwaltet.</para>
 715
 716         <para>Die Konfiguration ist ferner serverabhängig, d.h. für alle
 717         Mandaten, bzw. Datenbanken gleich.</para>
 718       </sect2>
 719
 720       <sect2 id="config.config-file.sections-parameters">
 721         <title>Abschnitte und Parameter</title>
 722
 723         <para>Die Konfigurationsdatei besteht aus mehreren Teilen, die
 724         entsprechend kommentiert sind:</para>
 725
 726         <itemizedlist>
 727           <listitem>
 728             <para><literal>authentication</literal> (siehe Abschnitt "<xref
 729             linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>"
 730             in diesem Kapitel)</para>
 731           </listitem>
 732
 733           <listitem>
 734             <para><literal>authentication/database</literal></para>
 735           </listitem>
 736
 737           <listitem>
 738             <para><literal>authentication/ldap</literal></para>
 739           </listitem>
 740
 741           <listitem>
 742             <para><literal>system</literal></para>
 743           </listitem>
 744
 745           <listitem>
 746             <para><literal>paths</literal></para>
 747           </listitem>
 748
 749           <listitem>
 750             <para><literal>mail_delivery</literal> (siehe Abschnitt "<xref
 751             linkend="config.sending-email.smtp"/>)</para>
 752           </listitem>
 753
 754           <listitem>
 755             <para><literal>applications</literal></para>
 756           </listitem>
 757
 758           <listitem>
 759             <para><literal>environment</literal></para>
 760           </listitem>
 761
 762           <listitem>
 763             <para><literal>print_templates</literal></para>
 764           </listitem>
 765
 766           <listitem>
 767             <para><literal>task_server</literal></para>
 768           </listitem>
 769
 770           <listitem>
 771             <para><literal>periodic_invoices</literal></para>
 772           </listitem>
 773
 774           <listitem>
 775             <para><literal>self_tests</literal></para>
 776           </listitem>
 777
 778           <listitem>
 779             <para><literal>console</literal></para>
 780           </listitem>
 781
 782           <listitem>
 783             <para><literal>testing</literal></para>
 784           </listitem>
 785
 786           <listitem>
 787             <para><literal>testing/database</literal></para>
 788           </listitem>
 789
 790           <listitem>
 791             <para><literal>debug</literal></para>
 792           </listitem>
 793         </itemizedlist>
 794
 795         <para>Die üblicherweise wichtigsten Parameter, die am Anfang
 796         einzustellen oder zu kontrollieren sind, sind:</para>
 797
 798         <programlisting>[authentication]
 799 admin_password = geheim
 800
 801 [authentication/database]
 802 host     = localhost
 803 port     = 5432
 804 db       = kivitendo_auth
 805 user     = postgres
 806 password =
 807
 808 [system]
 809 default_manager = german</programlisting>
 810
 811         <para>Für kivitendo Installationen in der Schweiz sollte hier
 812         <varname>german</varname> durch <varname>swiss</varname> ersetzt
 813         werden.</para>
 814
 815         <para>Die Einstellung <varname>default_manager = swiss</varname>
 816         bewirkt:</para>
 817
 818         <itemizedlist>
 819           <listitem>
 820             <para>Beim Erstellen einer neuen Datenbank in der kivitendo
 821             Administration werden automatisch die Standard-Werte für die
 822             Schweiz voreingestellt: Währung CHF, 5er-Rundung, Schweizer
 823             KMU-Kontenplan, Sollversteuerung, Aufwandsmethode, Bilanzierung
 824             (die Werte können aber manuell angepasst werden).</para>
 825           </listitem>
 826
 827           <listitem>
 828             <para>Einstellen der Standardkonten für Rundungserträge und
 829             -aufwendungen (unter Mandantenkonfiguration → Standardkonten
 830             veränderbar)</para>
 831           </listitem>
 832
 833           <listitem>
 834             <para>das verwendete Zahlenformat wird auf
 835             <varname>1'000.00</varname> eingestellt (unter Programm →
 836             Benutzereinstellungen veränderbar)</para>
 837           </listitem>
 838
 839           <listitem>
 840             <para>DATEV-Automatik und UStVA werden nicht angezeigt,
 841             Erfolgsrechnung ersetzt GUV ( unter Mandantenkonfiguration →
 842             Features veränderbar)</para>
 843           </listitem>
 844         </itemizedlist>
 845
 846         <para>Nutzt man wiederkehrende Rechnungen, kann man unter
 847         <varname>[periodic_invoices]</varname> den Login eines Benutzers
 848         angeben, der nach Erstellung der Rechnungen eine entsprechende E-Mail
 849         mit Informationen über die erstellten Rechnungen bekommt.</para>
 850
 851         <para>kivitendo bringt eine eigene Komponente zur zeitgesteuerten
 852         Ausführung bestimmter Aufgaben mit, den <link
 853         linkend="config.task-server">Task-Server</link>. Er wird u.a. für
 854         Features wie die <link
 855         linkend="features.periodic-invoices">wiederkehrenden Rechnungen</link>
 856         benötigt, erledigt aber auch andere erforderliche Aufgaben und muss
 857         daher in Betrieb genommen werden. Seine Einrichtung wird im Abschnitt
 858         <link linkend="config.task-server">Task-Server</link> genauer
 859         beschrieben.</para>
 860
 861         <para>Für Entwickler finden sich unter <varname>[debug]</varname>
 862         wichtige Funktionen, um die Fehlersuche zu erleichtern.</para>
 863       </sect2>
 864
 865       <sect2 id="config.config-file.prior-versions">
 866         <title>Versionen vor 2.6.3</title>
 867
 868         <para>In älteren kivitendo Versionen gab es im Verzeichnis
 869         <filename>config</filename> die Dateien
 870         <filename>authentication.pl</filename> und
 871         <filename>lx-erp.conf</filename>, die jeweils Perl-Dateien waren. Es
 872         gab auch die Möglichkeit, eine lokale Version der Konfigurationsdatei
 873         zu erstellen (<filename>lx-erp-local.conf</filename>). Dies ist ab
 874         2.6.3 nicht mehr möglich, aber auch nicht mehr nötig.</para>
 875
 876         <para>Beim Update von einer kivitendo-Version vor 2.6.3 auf 2.6.3 oder
 877         jünger müssen die Einstellungen aus den alten Konfigurationsdateien
 878         manuell übertragen und die alten Konfigurationsdateien anschließend
 879         gelöscht oder verschoben werden. Ansonsten zeigt kivitendo eine
 880         entsprechende Fehlermeldung an.</para>
 881       </sect2>
 882     </sect1>
 883
 884     <sect1 id="Anpassung-der-PostgreSQL-Konfiguration">
 885       <title>Anpassung der PostgreSQL-Konfiguration</title>
 886
 887       <para>PostgreSQL muss auf verschiedene Weisen angepasst werden.</para>
 888       <para>Dies variert je nach eingesetzter Distribution, da distributionsabhängig unterschiedliche Strategien beim Upgrade der Postgres Version eingesetzt werden.
 889             Als Hinweis einige Links zu den drei Distribution (Stand Dezember 2018):</para>
 890           <itemizedlist>
 891             <listitem>
 892               <para><ulink url="https://fedoraproject.org/wiki/PostgreSQL">Fedora (Postgres-Installation unter Fedora)</ulink></para>
 893             </listitem>
 894             <listitem>
 895               <para><ulink url="https://help.ubuntu.com/lts/serverguide/postgresql.html">Ubuntu (Infos für Postgres für die aktuelle LTS Version)</ulink></para>
 896             </listitem>
 897             <listitem>
 898               <para><ulink url="https://de.opensuse.org/PostgreSQL">OpenSuSE (aktuell nur bis Version OpenSuSE 13 verifiziert)</ulink></para>
 899             </listitem>
 900           </itemizedlist>
 901       <sect2 id="Zeichensätze-die-Verwendung-von-UTF-8">
 902         <title>Zeichensätze/die Verwendung von Unicode/UTF-8</title>
 903
 904         <para>kivitendo setzt zwingend voraus, dass die Datenbank
 905         Unicode/UTF-8 als Encoding einsetzt. Bei aktuellen
 906         Serverinstallationen braucht man hier meist nicht einzugreifen.</para>
 907
 908         <para>Das Encoding des Datenbankservers kann überprüft werden. Ist das
 909         Encoding der Datenbank "template1" "Unicode" bzw. "UTF-8", so braucht
 910         man nichts weiteres diesbezüglich unternehmen. Zum Testen:</para>
 911
 912         <programlisting>su postgres
 913 echo '\l' | psql
 914 exit </programlisting>
 915
 916         <para>Andernfalls ist es notwendig, einen neuen Datenbankcluster mit
 917         Unicode-Encoding anzulegen und diesen zu verwenden. Unter Debian und
 918         Ubuntu kann dies z.B. für PostgreSQL 9.3 mit dem folgenden Befehl
 919         getan werden:</para>
 920
 921         <programlisting>pg_createcluster --locale=de_DE.UTF-8 --encoding=UTF-8 9.3 clustername</programlisting>
 922
 923         <para>Die Datenbankversionsnummer muss an die tatsächlich verwendete
 924         Versionsnummer angepasst werden.</para>
 925
 926         <para>Unter anderen Distributionen gibt es ähnliche Methoden.</para>
 927
 928         <para>Das Encoding einer Datenbank kann in <command>psql</command> mit
 929         <literal>\l</literal> geprüft werden.</para>
 930       </sect2>
 931
 932       <sect2 id="Änderungen-an-Konfigurationsdateien">
 933         <title>Änderungen an Konfigurationsdateien</title>
 934
 935         <para>In der Datei <filename>postgresql.conf</filename>, die je nach
 936         Distribution in verschiedenen Verzeichnissen liegen kann (z.B.
 937         <filename>/var/lib/pgsql/data/</filename> oder
 938         <filename>/etc/postgresql/</filename>), muss sichergestellt werden,
 939         dass TCP/IP-Verbindungen aktiviert sind. Das Verhalten wird über den
 940         Parameter <varname>listen_address</varname> gesteuert. Laufen
 941         PostgreSQL und kivitendo auf demselben Rechner, so kann dort der Wert
 942         <literal>localhost</literal> verwendet werden. Andernfalls müssen
 943         Datenbankverbindungen auch von anderen Rechnern aus zugelassen werden,
 944         was mit dem Wert <literal>*</literal> geschieht.</para>
 945
 946         <para>In der Datei <filename>pg_hba.conf</filename>, die im gleichen
 947         Verzeichnis wie die <filename>postgresql.conf</filename> zu finden
 948         sein sollte, müssen die Berechtigungen für den Zugriff geändert
 949         werden. Hier gibt es mehrere Möglichkeiten. Sinnvoll ist es nur die
 950         nötigen Verbindungen immer zuzulassen, für eine lokal laufende
 951         Datenbank zum Beispiel:</para>
 952
 953         <programlisting>local all kivitendo password
 954 host all kivitendo 127.0.0.1 255.255.255.255 password</programlisting>
 955       </sect2>
 956
 957       <sect2 id="Erweiterung-für-servergespeicherte-Prozeduren">
 958         <title>Erweiterung für servergespeicherte Prozeduren</title>
 959
 960         <para>In der Datenbank <literal>template1</literal> muss die
 961         Unterstützung für servergespeicherte Prozeduren eingerichet werden.
 962         Melden Sie sich dafür als Benutzer “postgres” an der Datenbank an:
 963         <programlisting>su - postgres
 964 psql template1</programlisting> führen Sie die folgenden Kommandos aus:</para>
 965
 966         <programlisting>CREATE EXTENSION IF NOT EXISTS plpgsql;
 967 \q</programlisting>
 968
 969         <note>
 970           <para><literal>CREATE EXTENSION</literal> ist seit Version 9.1 die
 971           bevorzugte Syntax um die Sprache <literal>plpgsql</literal>
 972           anzulegen. In diesen Versionen ist die Extension meist auch schon
 973           vorhanden. Sollten Sie eine ältere Version von Postgres haben,
 974           benutzen Sie stattdessen den folgenden Befehl.</para>
 975
 976           <programlisting>CREATE LANGUAGE 'plpgsql';
 977 \q</programlisting>
 978         </note>
 979       </sect2>
 980
 981       <sect2 id="Erweiterung-für-trigram">
 982         <title>Erweiterung für Trigram Prozeduren</title>
 983
 984         <para>Ab Version 3.5.1 wird die Trigram-Index-Erweiterung benötigt.
 985         Diese wird mit dem SQL-Updatescript
 986         sql/Pg-upgrade2/trigram_extension.sql und Datenbank-Super-Benutzer
 987         Rechten automatisch installiert. Dazu braucht der
 988         DatenbankSuperbenutzer "postgres" ein Passwort.</para>
 989
 990         <programlisting>su - postgres
 991 psql
 992 \password postgres
 993
 994 Eingabe Passwort
 995 \q</programlisting>
 996
 997         <para>Benutzername Postgres und Passwort können jetzt beim Anlegen
 998         einer Datenbank bzw. bei Updatescripten, die SuperuserRechte
 999         benötigen, eingegeben werden.</para>
1000
1001         <note>
1002           <para><literal>pg_trgm</literal> ist je nach Distribution nicht im
1003           Standard-Paket von Postgres enthalten. Ein <programlisting>select * from pg_available_extensions where name ='pg_trgm';</programlisting>
1004           in template1 sollte entsprechend erfolgreich sein. Andernfalls muss
1005           das Paket nachinstalliert werden, bspw. bei debian/ubuntu
1006           <programlisting>apt install postgresql-contrib</programlisting></para>
1007         </note>
1008       </sect2>
1009
1010       <sect2 id="Datenbankbenutzer-anlegen">
1011         <title>Datenbankbenutzer anlegen</title>
1012
1013         <para>Wenn Sie nicht den Datenbanksuperuser “postgres” zum Zugriff
1014         benutzen wollen, so sollten Sie bei PostgreSQL einen neuen Benutzer
1015         anlegen. Ein Beispiel, wie Sie einen neuen Benutzer anlegen
1016         können:</para>
1017
1018         <para>Die Frage, ob der neue User Superuser sein soll, können Sie mit
1019         nein beantworten, genauso ist die Berechtigung neue User (Roles) zu
1020         generieren nicht nötig.</para>
1021
1022         <programlisting>su - postgres
1023 createuser -d -P kivitendo
1024 exit</programlisting>
1025
1026         <para>Wenn Sie später einen Datenbankzugriff konfigurieren, verändern
1027         Sie den evtl. voreingestellten Benutzer “postgres” auf “kivitendo”
1028         bzw. den hier gewählten Benutzernamen.</para>
1029       </sect2>
1030     </sect1>
1031
1032     <sect1 id="Apache-Konfiguration">
1033       <title>Webserver-Konfiguration</title>
1034
1035       <sect2>
1036         <title>Grundkonfiguration mittels CGI</title>
1037
1038         <note>
1039           <para>Für einen deutlichen Performanceschub sorgt die Ausführung
1040           mittels FastCGI/FCGI. Die Einrichtung wird ausführlich im Abschnitt
1041           <xref linkend="Apache-Konfiguration.FCGI"/> beschrieben.</para>
1042         </note>
1043
1044         <para>Der Zugriff auf das Programmverzeichnis muss in der Apache
1045         Webserverkonfigurationsdatei <literal>httpd.conf</literal> eingestellt
1046         werden. Fügen Sie den folgenden Abschnitt dieser Datei oder einer
1047         anderen Datei hinzu, die beim Starten des Webservers eingelesen
1048         wird:</para>
1049
1050         <programlisting>AliasMatch ^/kivitendo-erp/[^/]+\.pl /var/www/kivitendo-erp/dispatcher.pl
1051 Alias /kivitendo-erp/ /var/www/kivitendo-erp/
1052
1053 &lt;Directory /var/www/kivitendo-erp&gt;
1054  AddHandler cgi-script .pl
1055  Options ExecCGI Includes FollowSymlinks
1056 &lt;/Directory&gt;
1057
1058 &lt;Directory /var/www/kivitendo-erp/users&gt;
1059  Require all granted
1060 &lt;/Directory&gt;</programlisting>
1061
1062         <para>Ersetzen Sie dabei die Pfade durch diejenigen, in die Sie vorher
1063         das kivitendo-Archiv entpacket haben.</para>
1064
1065         <note>
1066           <para>Vor den einzelnen Optionen muss bei einigen Distributionen ein
1067           Plus ‘<literal>+</literal>’ gesetzt werden.</para>
1068
1069           <para>Bei einigen Distribution (Ubuntu ab 14.04, Debian ab 8.2) muss
1070           noch explizit das cgi-Modul mittels <programlisting>a2enmod cgi</programlisting>
1071           aktiviert werden.</para>
1072         </note>
1073
1074         <para>Auf einigen Webservern werden manchmal die Grafiken und
1075         Style-Sheets nicht ausgeliefert. In solchen Fällen hat es oft
1076         geholfen, die folgende Option in die Konfiguration aufzunehmen:</para>
1077
1078         <programlisting>EnableSendfile Off</programlisting>
1079       </sect2>
1080
1081       <sect2 id="Apache-Konfiguration.FCGI"
1082              xreflabel="Konfiguration für FastCGI/FCGI">
1083         <title>Konfiguration für FastCGI/FCGI</title>
1084
1085         <sect3 id="Apache-Konfiguration.FCGI.WasIstEs">
1086           <title>Was ist FastCGI?</title>
1087
1088           <para>Direkt aus <ulink
1089           url="http://de.wikipedia.org/wiki/FastCGI">Wikipedia</ulink>
1090           kopiert:</para>
1091
1092           <para><citation> FastCGI ist ein Standard für die Einbindung
1093           externer Software zur Generierung dynamischer Webseiten in einem
1094           Webserver. FastCGI ist vergleichbar zum Common Gateway Interface
1095           (CGI), wurde jedoch entwickelt, um dessen Performance-Probleme zu
1096           umgehen. </citation></para>
1097         </sect3>
1098
1099         <sect3 id="Apache-Konfiguration.FCGI.Warum">
1100           <title>Warum FastCGI?</title>
1101
1102           <para>Perl Programme (wie kivitendo eines ist) werden nicht statisch
1103           kompiliert. Stattdessen werden die Quelldateien bei jedem Start
1104           übersetzt, was bei kurzen Laufzeiten einen Großteil der Laufzeit
1105           ausmacht. Während SQL Ledger einen Großteil der Funktionalität in
1106           einzelne Module kapselt, um immer nur einen kleinen Teil laden zu
1107           müssen, ist die Funktionalität von kivitendo soweit gewachsen, dass
1108           immer mehr Module auf den Rest des Programms zugreifen. Zusätzlich
1109           benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
1110           entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies
1111           führt dazu dass ein kivitendo Aufruf der Kernmasken mittlerweile
1112           deutlich länger dauert als früher, und dass davon 90% für das Laden
1113           der Module verwendet wird.</para>
1114
1115           <para>Mit FastCGI werden nun die Module einmal geladen, und danach
1116           wird nur die eigentliche Programmlogik ausgeführt.</para>
1117         </sect3>
1118
1119         <sect3 id="Apache-Konfiguration.FCGI.WebserverUndPlugin">
1120           <title>Getestete Kombinationen aus Webservern und Plugin</title>
1121
1122           <para>Folgende Kombinationen sind getestet:</para>
1123
1124           <itemizedlist>
1125             <listitem>
1126               <para>Apache 2.4.7 (Ubuntu 14.04.2 LTS) und mod_fcgid.</para>
1127             </listitem>
1128             <listitem>
1129               <para>Apache 2.4.18 (Ubuntu 16.04 LTS) und mod_fcgid</para>
1130             </listitem>
1131             <listitem>
1132               <para>Apache 2.4.29 (Ubuntu 18.04 LTS) und mod_fcgid</para>
1133             </listitem>
1134              <listitem>
1135               <para>Apache 2.4.41 (Ubuntu 20.04 LTS) und mod_fcgid</para>
1136             </listitem>
1137
1138           </itemizedlist>
1139
1140           <para>Als Perl Backend wird das Modul <filename>FCGI.pm</filename>
1141           verwendet.</para>
1142
1143           <warning>
1144             <para>FCGI-Versionen ab 0.69 und bis zu 0.71 inklusive sind extrem
1145             strict in der Behandlung von Unicode, und verweigern bestimmte
1146             Eingaben von kivitendo. Falls es Probleme mit Umlauten in Ihrer
1147             Installation gibt, muss zwingend Version 0.68 oder aber Version
1148             0.72 und neuer eingesetzt werden.</para>
1149
1150             <para>Mit <ulink url="http://www.cpan.org">CPAN</ulink> lässt sie
1151             sich die Vorgängerversion wie folgt installieren:</para>
1152
1153             <programlisting>force install M/MS/MSTROUT/FCGI-0.68.tar.gz</programlisting>
1154           </warning>
1155         </sect3>
1156
1157         <sect3 id="Apache-Konfiguration.FCGI.Konfiguration">
1158           <title>Konfiguration des Webservers</title>
1159
1160           <para>Bevor Sie versuchen, eine kivitendo Installation unter FCGI
1161           laufen zu lassen, empfiehlt es sich die Installation ersteinmal
1162           unter CGI aufzusetzen. FCGI macht es nicht einfach Fehler zu
1163           debuggen die beim ersten aufsetzen auftreten können. Sollte die
1164           Installation schon funktionieren, lesen Sie weiter.</para>
1165
1166           <para>Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann
1167           unter Debian/Ubuntu z.B. mit folgendem Befehl geschehen:</para>
1168
1169           <programlisting>a2enmod fcgid</programlisting>
1170
1171           <para>Die Konfiguration für die Verwendung von kivitendo mit FastCGI
1172           erfolgt durch Anpassung der vorhandenen <function>Alias</function>-
1173           und <function>Directory</function>-Direktiven. Dabei wird zwischen
1174           dem Installationspfad von kivitendo im Dateisystem
1175           ("<filename>/path/to/kivitendo-erp</filename>") und der URL
1176           unterschieden, unter der kivitendo im Webbrowser erreichbar ist
1177           ("<filename>/url/for/kivitendo-erp</filename>").</para>
1178
1179           <para>Folgender Konfigurationsschnipsel funktioniert mit
1180           mod_fastcgi:</para>
1181
1182           <programlisting>AliasMatch ^/url/for/kivitendo-erp/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fcgi
1183 Alias       /url/for/kivitendo-erp/          /path/to/kivitendo-erp/
1184
1185 &lt;Directory /path/to/kivitendo-erp&gt;
1186   AllowOverride All
1187   Options ExecCGI Includes FollowSymlinks
1188   Require all granted
1189 &lt;/Directory&gt;
1190
1191 &lt;DirectoryMatch /path/to/kivitendo-erp/users&gt;
1192 Require all denied
1193 &lt;/DirectoryMatch&gt;</programlisting>
1194
1195           <warning>
1196             <para>Wer einen älteren Apache als Version 2.4 im Einsatz hat,
1197             muss entsprechend die Syntax der Directorydirektiven verändert.
1198             Statt</para>
1199
1200             <programlisting>Require all granted</programlisting>
1201
1202             <para>muß man Folgendes einstellen:</para>
1203
1204             <programlisting>
1205   Order Allow,Deny
1206   Allow from All </programlisting>
1207
1208             <para>und statt</para>
1209
1210             <programlisting>Require all denied</programlisting>
1211
1212             <para>muss stehen:</para>
1213
1214             <programlisting>
1215   Order Deny,Allow
1216   Deny from All </programlisting>
1217           </warning>
1218
1219           <para>Seit mod_fcgid-Version 2.3.6 gelten sehr kleine Grenzen für
1220           die maximale Größe eines Requests. Diese sollte wie folgt
1221           hochgesetzt werden:</para>
1222
1223           <programlisting>FcgidMaxRequestLen 10485760</programlisting>
1224
1225           <para>Das Ganze sollte dann so aussehen:</para>
1226
1227           <programlisting>AddHandler fcgid-script .fpl
1228 AliasMatch ^/url/for/kivitendo-erp/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fpl
1229 Alias       /url/for/kivitendo-erp/          /path/to/kivitendo-erp/
1230 FcgidMaxRequestLen 10485760
1231
1232 &lt;Directory /path/to/kivitendo-erp&gt;
1233   AllowOverride All
1234   Options ExecCGI Includes FollowSymlinks
1235   Require all granted
1236 &lt;/Directory&gt;
1237
1238 &lt;DirectoryMatch /path/to/kivitendo-erp/users&gt;
1239 Require all denied
1240 &lt;/DirectoryMatch&gt;</programlisting>
1241
1242           <para>Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle
1243           Zugriffe auf die einzelnen Scripte werden auf diesen umgeleitet.
1244           Dadurch, dass zur Laufzeit öfter mal Scripte neu geladen werden,
1245           gibt es hier kleine Performance-Einbußen.</para>
1246
1247           <para>Es ist möglich, die gleiche kivitendo Version parallel unter
1248           CGI und FastCGI zu betreiben. Dafür bleiben die Directorydirektiven
1249           wie oben beschrieben, die URLs werden aber umgeleitet:</para>
1250
1251           <programlisting># Zugriff über CGI
1252 Alias       /url/for/kivitendo-erp                /path/to/kivitendo-erp
1253
1254 # Zugriff mit mod_fcgid:
1255 AliasMatch ^/url/for/kivitendo-erp-fcgid/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fpl
1256 Alias       /url/for/kivitendo-erp-fcgid/          /path/to/kivitendo-erp/</programlisting>
1257
1258           <para>Dann ist unter <filename>/url/for/kivitendo-erp/</filename>
1259           die normale Version erreichbar, und unter
1260           <constant>/url/for/kivitendo-erp-fcgid/</constant> die
1261           FastCGI-Version.</para>
1262         </sect3>
1263       </sect2>
1264
1265       <sect2>
1266        <title>Authentifizierung mittels HTTP Basic Authentication</title>
1267
1268        <para>
1269         Kivitendo unterstützt, dass Benutzerauthentifizierung über den Webserver mittels des »Basic«-HTTP-Authentifizierungs-Schema erfolgt
1270         (siehe <ulink url="https://tools.ietf.org/html/rfc7617">RFC 7617</ulink>). Dazu ist es aber nötig, dass der dabei vom Client
1271         mitgeschickte Header <constant>Authorization</constant> vom Webserver an Kivitendo über die Umgebungsvariable
1272         <constant>HTTP_AUTHORIZATION</constant> weitergegeben wird, was standardmäßig nicht der Fall ist. Für Apache kann dies über die
1273         folgende Konfigurationsoption aktiviert werden:
1274        </para>
1275
1276        <programlisting>SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1</programlisting>
1277       </sect2>
1278       <sect2>
1279        <title>Aktivierung von mod_rewrite/directory_match für git basierte Installationen</title>
1280
1281        <para>
1282         Aufgrund von aktuellen (Mitte 2020) Sicherheitswarnungen für git basierte Webanwendungen ist die mitausgelieferte .htaccess
1283         restriktiver geworden und verhindert somit das Auslesen von git basierten Daten.
1284         Für debian/ubuntu muss das Modul mod_rewrite einmalig so aktiviert werden:
1285         <programlisting>a2enmod rewrite</programlisting>
1286         Alternativ und für Installationen ohne Apache ist folgender Artikel interessant:
1287         <ulink url="https://www.cyberscan.io/blog/git-luecke">git-lücke</ulink>.
1288         Anstelle des dort beschriebenen DirectoryMatch für Apache2 würden wir etwas weitergehend auch noch das Verzeichnis config miteinbeziehen
1289         sowie ferner auch die Möglichkeit nicht ausschließen, dass es in Unterverzeichnissen auch noch .git Repositories geben kann.
1290         Die Empfehlung für Apache 2.4 wäre damit:
1291         <programlisting>
1292         &lt;DirectoryMatch "/(\.git|config)/"&gt;
1293           Require all denied
1294         &lt;/DirectoryMatch&gt;</programlisting>
1295        </para>
1296       </sect2>
1297
1298
1299       <sect2>
1300         <title>Weitergehende Konfiguration</title>
1301
1302         <para>Für einen deutlichen Sicherheitsmehrwert sorgt die Ausführung
1303         von kivitendo nur über https-verschlüsselten Verbindungen, sowie
1304         weiteren Zusatzmassnahmen, wie beispielsweise Basic Authenticate. Die
1305         Konfigurationsmöglichkeiten sprengen allerdings den Rahmen dieser
1306         Anleitung, hier ein Hinweis auf einen entsprechenden <ulink
1307         url="http://redmine.kivitendo-premium.de/boards/1/topics/142">Foreneintrag
1308         (Stand Sept. 2015)</ulink> und einen aktuellen (Stand Mai 2017) <ulink
1309         url="https://mozilla.github.io/server-side-tls/ssl-config-generator/">
1310         SSL-Konfigurations-Generator</ulink>.</para>
1311       </sect2>
1312       <sect3>
1313         <title>Aktivierung von Apache2 modsecurity</title>
1314
1315         <para>Aufgrund des OpenSource Charakters ist kivitendo nicht "out of the box" sicher.
1316   Organisatorisch empfehlen wir hier die enge Zusammenarbeit mit einem kivitendo Partner der auch in der
1317 Lage ist weiterführende Fragen in Bezug auf Datenschutz und Datensicherheit zu beantworten.
1318 Unabhängig davon empfehlen wir im Webserver Bereich die Aktivierung und Konfiguration des Moduls modsecurity für den Apache2, damit
1319 XSS und SQL-Injections verhindert werden.</para>
1320 <para> Als Idee hierfür sei dieser Blog-Eintrag genannt:
1321 <ulink url="https://doxsec.wordpress.com/2017/06/11/using-modsecurity-web-application-firewall-to-prevent-sql-injection-and-xss-using-blocking-rules/">
1322         Test Apache2 modsecurity for SQL Injection</ulink>.</para>
1323       </sect3>
1324
1325     </sect1>
1326
1327     <sect1 id="config.task-server">
1328       <title>Der Task-Server</title>
1329
1330       <para>Der Task-Server ist ein Prozess, der im Hintergrund läuft, in
1331       regelmäßigen Abständen nach abzuarbeitenden Aufgaben sucht und diese zu
1332       festgelegten Zeitpunkten abarbeitet (ähnlich wie Cron). Dieser Prozess
1333       wird u.a. für die Erzeugung der wiederkehrenden Rechnungen und weitere
1334       essenzielle Aufgaben benutzt.</para>
1335
1336       <para>Der Task-Server muss einmalig global in der Konfigurationsdatei
1337       konfiguriert werden. Danach wird er für jeden Mandanten, für den er
1338       laufen soll, in der Adminsitrationsmaske eingeschaltet.</para>
1339
1340       <para>Beachten Sie, dass der Task-Server in den Boot-Vorgang Ihres
1341       Servers integriert werden muss, damit er automatisch gestartet wird.
1342       Dies kann kivitendo nicht für Sie erledigen.</para>
1343
1344       <para>Da der Task-Server als Perlscript läuft, wird Arbeitsspeicher, der
1345       einmal benötigt wurde, nicht mehr an das Betriebssystem zurückgegeben,
1346       solange der Task-Server läuft. Dies kann dazu führen, dass ein länger
1347       laufender Task-Server mit der Zeit immer mehr Arbeitsspeicher für sich
1348       beansprucht. Es ist deshalb sinnvoll, dass der Task-Server in
1349       regelmässigen Abständen neu gestartet wird. Allerdings berücksichtigt der
1350       Task-Server ein Memory-Limit, wenn dieses in der Konfigurationsdatei
1351       angegeben ist. Bei Überschreiten dieses Limits beendet sich der
1352       Task-Server. Sofern der Task-Server als systemd-Service mit dem
1353       mitgelieferten Skript eingerichtet wurde, startet dieser danach
1354       automatisch erneut.</para>
1355
1356       <sect2 id="Konfiguration-des-Task-Servers">
1357         <title>Verfügbare und notwendige Konfigurationsoptionen</title>
1358
1359         <para>Die Konfiguration erfolgt über den Abschnitt
1360         <literal>[task_server]</literal> in der Datei
1361         <filename>config/kivitendo.conf</filename>. Die dort verfügbaren
1362         Optionen sind:</para>
1363
1364         <variablelist>
1365           <varlistentry>
1366             <term><varname>run_as</varname></term>
1367
1368             <listitem>
1369               <para>Wird der Server vom Systembenutzer <literal>root</literal>
1370               gestartet, so wechselt er auf den mit <literal>run_as</literal>
1371               angegebenen Systembenutzer. Der Systembenutzer muss dieselben
1372               Lese- und Schreibrechte haben, wie auch der Webserverbenutzer
1373               (siehe see <xref
1374               linkend="Manuelle-Installation-des-Programmpaketes"/>). Daher
1375               ist es erforderlich, hier denselben Systembenutzer einzutragen,
1376               unter dem auch der Webserver läuft.</para>
1377             </listitem>
1378           </varlistentry>
1379
1380           <varlistentry>
1381             <term><varname>debug</varname></term>
1382
1383             <listitem>
1384               <para>Schaltet Debug-Informationen an und aus.</para>
1385             </listitem>
1386           </varlistentry>
1387         </variablelist>
1388       </sect2>
1389
1390       <sect2 id="Konfiguration-der-Mandanten-fuer-den-Task-Servers">
1391         <title>Konfiguration der Mandanten für den Task-Server</title>
1392
1393         <para>Ist der Task-Server grundlegend konfiguriert, so muss
1394         anschließend jeder Mandant, für den der Task-Server laufen soll,
1395         einmalig konfiguriert werden. Dazu kann in der Maske zum Bearbeiten
1396         von Mandanten im Administrationsbereich eine kivitendo-Benutzerkennung
1397         ausgewählt werden, unter der der Task-Server seine Arbeit
1398         verrichtet.</para>
1399
1400         <para>Ist in dieser Einstellung keine Benutzerkennung ausgewählt, so
1401         wird der Task-Server für diesen Mandanten keine Aufgaben
1402         ausführen.</para>
1403       </sect2>
1404
1405       <sect2 id="Einbinden-in-den-Boot-Prozess">
1406         <title>Automatisches Starten des Task-Servers beim Booten</title>
1407
1408         <para>Der Task-Server verhält sich von seinen Optionen her wie ein
1409         reguläres SystemV-kompatibles Boot-Script. Außerdem wechselt er beim
1410         Starten automatisch in das kivitendo-Installationsverzeichnis.</para>
1411
1412         <para>Deshalb ist es möglich, ihn durch Setzen eines symbolischen
1413         Links aus einem der Runlevel-Verzeichnisse heraus in den Boot-Prozess
1414         einzubinden. Da das bei neueren Linux-Distributionen aber nicht
1415         zwangsläufig funktioniert, werden auch Start-Scripte mitgeliefert, die
1416         anstelle eines symbolischen Links verwendet werden können.</para>
1417
1418         <sect3>
1419           <title>SystemV-basierende Systeme (z.B. ältere Debian, ältere
1420           openSUSE, ältere Fedora)</title>
1421
1422           <para>Kopieren Sie die Datei
1423           <filename>scripts/boot/system-v/kivitendo-task-server</filename>
1424           nach <filename>/etc/init.d/kivitendo-task-server</filename>. Passen
1425           Sie in der kopierten Datei den Pfad zum Task-Server an (Zeile
1426           <literal>DAEMON=....</literal>). Binden Sie das Script in den
1427           Boot-Prozess ein. Dies ist distributionsabhängig:</para>
1428
1429           <itemizedlist>
1430             <listitem>
1431               <para>Debian-basierende Systeme:</para>
1432
1433               <programlisting>update-rc.d kivitendo-task-server defaults
1434 insserv kivitendo-task-server</programlisting>
1435             </listitem>
1436
1437             <listitem>
1438               <para>Ältere openSUSE und ältere Fedora:</para>
1439
1440               <programlisting>chkconfig --add kivitendo-task-server</programlisting>
1441             </listitem>
1442           </itemizedlist>
1443
1444           <para>Danach kann der Task-Server mit dem folgenden Befehl gestartet
1445           werden:</para>
1446
1447           <programlisting>/etc/init.d/kivitendo-task-server start</programlisting>
1448         </sect3>
1449
1450         <sect3>
1451           <title>Upstart-basierende Systeme (z.B. Ubuntu bis 14.04)</title>
1452
1453           <para>Kopieren Sie die Datei
1454           <filename>scripts/boot/upstart/kivitendo-task-server.conf</filename>
1455           nach <filename>/etc/init/kivitendo-task-server.conf</filename>.
1456           Passen Sie in der kopierten Datei den Pfad zum Task-Server an (Zeile
1457           <literal>exec ....</literal>).</para>
1458
1459           <para>Danach kann der Task-Server mit dem folgenden Befehl gestartet
1460           werden:</para>
1461
1462           <programlisting>service kivitendo-task-server start</programlisting>
1463         </sect3>
1464
1465         <sect3>
1466           <title>systemd-basierende Systeme (z.B. neure openSUSE, neuere
1467           Fedora, neuere Ubuntu und neuere Debians)</title>
1468
1469           <para>Kopieren Sie die Datei
1470           <filename>scripts/boot/systemd/kivitendo-task-server.service</filename>
1471           nach <filename>/etc/systemd/system/</filename>. Passen Sie in der
1472           kopierten Datei den Pfad zum Task-Server an (Zeilen
1473           <literal>ExecStart=....</literal> und
1474           <literal>ExecStop=...</literal>).</para>
1475
1476           <para>Machen Sie anschließend das Script systemd bekannt, und binden
1477           Sie es in den Boot-Prozess ein. Dazu führen Sie die folgenden Befehl
1478           aus:</para>
1479
1480           <programlisting>systemctl daemon-reload
1481 systemctl enable kivitendo-task-server.service</programlisting>
1482
1483           <para>Wenn Sie den Task-Server jetzt sofort starten möchten, anstatt
1484           den Server neu zu starten, so können Sie das mit dem folgenden
1485           Befehl tun:</para>
1486
1487           <programlisting>systemctl start kivitendo-task-server.service</programlisting>
1488
1489           <para>Ein so eingerichteter Task-Server startet nach Beendigung
1490           automatisch erneut. Das betrifft eine Beendigung über die Oberfläche,
1491           eine Beendingung über die Prozesskontrolle und eine Beendigung bei
1492           Überschreiten des Memory-Limits. Soll der Task-Server nicht erneut
1493           starten, so können Sie ihn mit folgendem Befehl stoppen:</para>
1494
1495           <programlisting>systemctl stop kivitendo-task-server.service</programlisting>
1496
1497         </sect3>
1498       </sect2>
1499
1500       <sect2 id="Prozesskontrolle">
1501         <title>Wie der Task-Server gestartet und beendet wird</title>
1502
1503         <para>Der Task-Server wird wie folgt kontrolliert:</para>
1504
1505         <programlisting>./scripts/task_server.pl Befehl</programlisting>
1506
1507         <para><literal>Befehl</literal> ist dabei eine der folgenden
1508         Optionen:</para>
1509
1510         <itemizedlist>
1511           <listitem>
1512             <para><literal>start</literal> startet eine neue Instanz des
1513             Task-Servers. Die Prozess-ID wird innerhalb des
1514             <filename>users</filename>-Verzeichnisses abgelegt.</para>
1515           </listitem>
1516
1517           <listitem>
1518             <para><literal>stop</literal> beendet einen laufenden
1519             Task-Server.</para>
1520           </listitem>
1521
1522           <listitem>
1523             <para><literal>restart</literal> beendet und startet ihn
1524             neu.</para>
1525           </listitem>
1526
1527           <listitem>
1528             <para><literal>status</literal> berichtet, ob der Task-Server
1529             läuft.</para>
1530           </listitem>yy
1531         </itemizedlist>
1532
1533         <para>Der Task-Server wechselt beim Starten automatisch in das
1534         kivitendo-Installationsverzeichnis.</para>
1535
1536         <para>Dieselben Optionen können auch für die SystemV-basierenden
1537         Runlevel-Scripte benutzt werden (siehe oben).</para>
1538
1539         <para>Wurde der Task-Server als systemd-Service eingerichtet (s.o.),
1540         so startet dieser nach Beendigung automatisch erneut.</para>
1541
1542       </sect2>
1543       <sect2 id="Tasks konfigurieren">
1544         <title>Exemplarische Konfiguration eines Hintergrund-Jobs, der die Jahreszahl in allen Nummernkreisen zum Jahreswechsel erhöht</title>
1545
1546         <para>Hintergrund-Jobs werden über System -> Hintergrund-Jobs und Task-Server -> Aktuelle Hintergrund-Jobs anzeigen -> Aktions-Knopf 'erfassen' angelegt. </para>
1547         <para>Nachdem wir über das Menü dort angelangt sind, legen wir unseren exemplarischen Hintergrund-Jobs "Erhöhung der Nummernkreise" mit folgenden Werten an:</para>
1548         <itemizedlist>
1549           <listitem>
1550             <para><literal>Aktiv:</literal> Hier ein 'Ja' auswählen</para>
1551           </listitem>
1552           <listitem>
1553             <para><literal>Ausführungsart:</literal> 'wiederholte Ausführung' auswählen</para>
1554           </listitem>
1555           <listitem>
1556             <para><literal>Paketname:</literal> 'SetNumberRange' auswählen</para>
1557           </listitem>
1558           <listitem>
1559             <para><literal>Ausführungszeitplan:</literal> Hier entsprechend Werte wie in der crontab eingeben.</para><para>Syntax:</para>
1560 <programlisting>* * * * *
1561 ┬ ┬ ┬ ┬ ┬
1562 │ │ │ │ │
1563 │ │ │ │ └──── Wochentag (0-7, Sonntag ist 0 oder 7)
1564 │ │ │ └────── Monat (1-12)
1565 │ │ └──────── Tag (1-31)
1566 │ └────────── Stunde (0-23)
1567 └──────────── Minute (0-59)  </programlisting>
1568             <para>Die Sterne können folgende Werte haben:</para>
1569             <programlisting>
1570 1 2 3 4 5
1571
1572 1 = Minute (0-59)
1573 2 = Stunde (0-23)
1574 3 = Tag (0-31)
1575 4 = Monat (1-12)
1576 5 = Wochentag (0-7, Sonntag ist 0 oder 7)
1577 </programlisting>
1578 <para>Um die Ausführung auf eine Minute vor Sylvester zu setzen, müssen die folgenden Werte eingetragen werden:</para>
1579 <programlisting>59 23 31 12 *</programlisting>
1580           </listitem>
1581           <listitem>
1582             <para><literal>Daten:</literal>In diesem Feld können optionale Parameter für den Hintergrund im JSON-Format gesetzt werden. Der Hintergrund-Job <literal>SetNumberRange</literal> akzeptiert zwei Variable nämlich <literal>digit_year</literal> sowieso <literal>multiplier</literal>.</para><para> <literal>digit_year</literal> kann zwei Werte haben entweder 2 oder 4, darüber wird gesteuert ob die Jahreszahl zwei oder vierstellig kodiert wird (für 2019, dann entweder 19 oder 2019). Der Standardwert ist vierstellig.</para><para> <literal>multiplier</literal> ist ein Vielfaches von 10, darüber wird die erste Nummer im Nummernkreis (die Anzahl der Stellen) wie folgt bestimmt:</para>
1583 <programlisting>
1584 multiplier     Nummernkreis 2020
1585 10        ->   20200
1586 100       ->   202000
1587 1000      ->   2020000
1588 </programlisting>
1589 <para>Wir gehen jetzt beispielhaft von einer letzten Rechnungsnummer von RE2019456 aus. Demnach sollte ab Januar 2020 die erste Nummer RE2020001 sein. Da der Task auch Präfixe berücksichtigt, kann dies mit folgenden JSON-kodierten Werten umgesetzt werden:</para>
1590 <literal>Daten:</literal><programlisting>multiplier: 100
1591 digits_year: 4</programlisting>
1592           </listitem>
1593         </itemizedlist>
1594      </sect2>
1595     </sect1>
1596     <sect1 id="Benutzerauthentifizierung-und-Administratorpasswort">
1597       <title>Benutzerauthentifizierung und Administratorpasswort</title>
1598
1599       <para>Informationen über die Einrichtung der Benutzerauthentifizierung,
1600       über die Verwaltung von Gruppen und weitere Einstellungen</para>
1601
1602       <sect2 id="Grundlagen-zur-Benutzerauthentifizierung">
1603         <title>Grundlagen zur Benutzerauthentifizierung</title>
1604
1605         <para>kivitendo verwaltet die Benutzerinformationen in einer
1606         Datenbank, die im folgenden “Authentifizierungsdatenbank” genannt
1607         wird. Für jeden Benutzer kann dort eine eigene Datenbank für die
1608         eigentlichen Finanzdaten hinterlegt sein. Diese beiden Datenbanken
1609         können, müssen aber nicht unterschiedlich sein.</para>
1610
1611         <para>Im einfachsten Fall gibt es für kivitendo nur eine einzige
1612         Datenbank, in der sowohl die Benutzerinformationen als auch die Daten
1613         abgelegt werden.</para>
1614
1615         <para>Zusätzlich ermöglicht es kivitendo, dass die Benutzerpasswörter gegen die Authentifizierungsdatenbank oder gegen einen oder
1616         mehrere LDAP-Server überprüft werden.</para>
1617
1618         <para>Welche Art der Passwortüberprüfung kivitendo benutzt und wie
1619         kivitendo die Authentifizierungsdatenbank erreichen kann, wird in der
1620         Konfigurationsdatei <filename>config/kivitendo.conf</filename>
1621         festgelegt. Diese muss bei der Installation und bei einem Upgrade von
1622         einer Version vor v2.6.0 angelegt werden. Eine
1623         Beispielkonfigurationsdatei
1624         <filename>config/kivitendo.conf.default</filename> existiert, die als
1625         Vorlage benutzt werden kann.</para>
1626       </sect2>
1627
1628       <sect2 id="Administratorpasswort">
1629         <title>Administratorpasswort</title>
1630
1631         <para>Das Passwort, das zum Zugriff auf das Administrationsinterface
1632         von kivitendo benutzt wird, wird ebenfalls in dieser Datei
1633         gespeichert. Es kann auch nur dort und nicht mehr im
1634         Administrationsinterface selber geändert werden. Der Parameter dazu
1635         heißt <varname>admin_password</varname> im Abschnitt
1636         <varname>[authentication]</varname>.</para>
1637       </sect2>
1638
1639       <sect2 id="Authentifizierungsdatenbank">
1640         <title>Authentifizierungsdatenbank</title>
1641
1642         <para>Die Verbindung zur Authentifizierungsdatenbank wird mit den
1643         Parametern in <varname>[authentication/database]</varname>
1644         konfiguriert. Hier sind die folgenden Parameter anzugeben:</para>
1645
1646         <variablelist>
1647           <varlistentry>
1648             <term><literal>host</literal></term>
1649
1650             <listitem>
1651               <para>Der Rechnername oder die IP-Adresse des
1652               Datenbankservers</para>
1653             </listitem>
1654           </varlistentry>
1655
1656           <varlistentry>
1657             <term><literal>port</literal></term>
1658
1659             <listitem>
1660               <para>Die Portnummer des Datenbankservers, meist 5432</para>
1661             </listitem>
1662           </varlistentry>
1663
1664           <varlistentry>
1665             <term><literal>db</literal></term>
1666
1667             <listitem>
1668               <para>Der Name der Authentifizierungsdatenbank</para>
1669             </listitem>
1670           </varlistentry>
1671
1672           <varlistentry>
1673             <term><literal>user</literal></term>
1674
1675             <listitem>
1676               <para>Der Benutzername, mit dem sich kivitendo beim
1677               Datenbankserver anmeldet (z.B.
1678               "<literal>postgres</literal>")</para>
1679             </listitem>
1680           </varlistentry>
1681
1682           <varlistentry>
1683             <term><literal>password</literal></term>
1684
1685             <listitem>
1686               <para>Das Passwort für den Datenbankbenutzer</para>
1687             </listitem>
1688           </varlistentry>
1689         </variablelist>
1690
1691         <para>Die Datenbank muss noch nicht existieren. kivitendo kann sie
1692         automatisch anlegen (mehr dazu siehe unten).</para>
1693       </sect2>
1694
1695       <sect2 id="Passwortüberprüfung">
1696         <title>Passwortüberprüfung</title>
1697
1698         <para>kivitendo unterstützt Passwortüberprüfung auf zwei Arten: gegen
1699         die Authentifizierungsdatenbank und gegen externe LDAP- oder
1700         Active-Directory-Server. Welche davon benutzt wird, regelt der
1701         Parameter <varname>module</varname> im Abschnitt
1702         <varname>[authentication]</varname>.</para>
1703
1704         <para>Dieser Parameter listet die zu verwendenden Authentifizierungsmodule auf. Es muss mindestens ein Modul angegeben werden, es
1705         können aber auch mehrere angegeben werden. Weiterhin ist es möglich, das LDAP-Modul mehrfach zu verwenden und für jede Verwendung
1706         eine unterschiedliche Konfiguration zu nutzen, z.B. um einen Fallback-Server anzugeben, der benutzt wird, sofern der Hauptserver
1707         nicht erreichbar ist.</para>
1708
1709         <para>Sollen die Benutzerpasswörter in der Authentifizierungsdatenbank geprüft werden, so muss der Parameter
1710         <varname>module</varname> das Modul <literal>DB</literal> enthalten. Sofern das Modul in der Liste enthalten ist, egal an welcher
1711         Position, können sowohl der Administrator als auch die Benutzer selber ihre Passwörter in kivitendo ändern.</para>
1712
1713         <para>Wenn Passwörter gegen einen oder mehrere externe LDAP- oder Active-Directory-Server geprüft werden, so muss der Parameter
1714         <varname>module</varname> den Wert <literal>LDAP</literal> enthalten. In diesem Fall müssen zusätzliche Informationen über den
1715         LDAP-Server im Abschnitt <literal>[authentication/ldap]</literal> angegeben werden. Das Modul kann auch mehrfach angegeben werden,
1716         wobei jedes Modul eine eigene Konfiguration bekommen sollte. Der Name der Konfiguration wird dabei mit einem Doppelpunkt getrennt an
1717         den Modulnamen angehängt (<literal>LDAP:Name-der-Konfiguration</literal>). Der entsprechende Abschnitt in der Konfigurationsdatei
1718         lautet dann <literal>[authentication/Name-der-Konfiguration]</literal>.</para>
1719
1720         <para>Die verfügbaren Parameter für die LDAP-Konfiguration lauten:</para>
1721
1722         <variablelist>
1723           <varlistentry>
1724             <term><literal>host</literal></term>
1725
1726             <listitem>
1727               <para>Der Rechnername oder die IP-Adresse des LDAP- oder
1728               Active-Directory-Servers. Diese Angabe ist zwingend
1729               erforderlich.</para>
1730             </listitem>
1731           </varlistentry>
1732
1733           <varlistentry>
1734             <term><literal>port</literal></term>
1735
1736             <listitem>
1737               <para>Die Portnummer des LDAP-Servers; meist 389.</para>
1738             </listitem>
1739           </varlistentry>
1740
1741           <varlistentry>
1742             <term><literal>tls</literal></term>
1743
1744             <listitem>
1745               <para>Wenn Verbindungsverschlüsselung gewünscht ist, so diesen
1746               Wert auf ‘<literal>1</literal>’ setzen, andernfalls auf
1747               ‘<literal>0</literal>’ belassen</para>
1748             </listitem>
1749           </varlistentry>
1750
1751           <varlistentry>
1752             <term><literal>verify</literal></term>
1753
1754             <listitem>
1755               <para>Wenn Verbindungsverschlüsselung gewünscht und der Parameter <parameter>tls</parameter> gesetzt ist, so gibt dieser
1756               Parameter an, ob das Serverzertifikat auf Gültigkeit geprüft wird. Mögliche Werte sind <literal>require</literal> (Zertifikat
1757               wird überprüft und muss gültig sei; dies ist der Standard) und <literal>none</literal> (Zertifikat wird nicht
1758               überpfüft).</para>
1759             </listitem>
1760           </varlistentry>
1761
1762           <varlistentry>
1763             <term><literal>attribute</literal></term>
1764
1765             <listitem>
1766               <para>Das LDAP-Attribut, in dem der Benutzername steht, den der
1767               Benutzer eingegeben hat. Für Active-Directory-Server ist dies
1768               meist ‘<literal>sAMAccountName</literal>’, für andere
1769               LDAP-Server hingegen ‘<literal>uid</literal>’. Diese Angabe ist
1770               zwingend erforderlich.</para>
1771             </listitem>
1772           </varlistentry>
1773
1774           <varlistentry>
1775             <term><literal>base_dn</literal></term>
1776
1777             <listitem>
1778               <para>Der Abschnitt des LDAP-Baumes, der durchsucht werden soll.
1779               Diese Angabe ist zwingend erforderlich.</para>
1780             </listitem>
1781           </varlistentry>
1782
1783           <varlistentry>
1784             <term><literal>filter</literal></term>
1785
1786             <listitem>
1787               <para>Ein optionaler LDAP-Filter. Enthält dieser Filter das Wort
1788               <literal>&lt;%login%&gt;</literal>, so wird dieses durch den vom
1789               Benutzer eingegebenen Benutzernamen ersetzt. Andernfalls wird
1790               der LDAP-Baum nach einem Element durchsucht, bei dem das oben
1791               angegebene Attribut mit dem Benutzernamen identisch ist.</para>
1792             </listitem>
1793           </varlistentry>
1794
1795           <varlistentry>
1796             <term><literal>bind_dn</literal> und
1797             <literal>bind_password</literal></term>
1798
1799             <listitem>
1800               <para>Wenn der LDAP-Server eine Anmeldung erfordert, bevor er
1801               durchsucht werden kann (z.B. ist dies bei
1802               Active-Directory-Servern der Fall), so kann diese hier angegeben
1803               werden. Für Active-Directory-Server kann als
1804               ‘<literal>bind_dn</literal>’ entweder eine komplette LDAP-DN wie
1805               z.B. ‘<literal>cn=Martin
1806               Mustermann,cn=Users,dc=firmendomain</literal>’ auch nur der
1807               volle Name des Benutzers eingegeben werden; in diesem Beispiel
1808               also ‘<literal>Martin Mustermann</literal>’.</para>
1809             </listitem>
1810           </varlistentry>
1811
1812           <varlistentry>
1813             <term><literal>timeout</literal></term>
1814
1815             <listitem>
1816               <para>Timeout beim Verbindungsversuch, bevor der Server als nicht erreichbar gilt; Standardwert: 10</para>
1817             </listitem>
1818           </varlistentry>
1819         </variablelist>
1820       </sect2>
1821
1822       <sect2 id="Name-des-Session-Cookies">
1823         <title>Name des Session-Cookies</title>
1824
1825         <para>Sollen auf einem Server mehrere kivitendo-Installationen
1826         aufgesetzt werden, so müssen die Namen der Session-Cookies für alle
1827         Installationen unterschiedlich sein. Der Name des Cookies wird mit dem
1828         Parameter <varname>cookie_name</varname> im Abschnitt
1829         <varname>[authentication]</varname>gesetzt.</para>
1830
1831         <para>Diese Angabe ist optional, wenn nur eine Installation auf dem
1832         Server existiert.</para>
1833       </sect2>
1834
1835       <sect2 id="Anlegen-der-Authentifizierungsdatenbank">
1836         <title>Anlegen der Authentifizierungsdatenbank</title>
1837
1838         <para>Nachdem alle Einstellungen in
1839         <filename>config/kivitendo.conf</filename> vorgenommen wurden, muss
1840         kivitendo die Authentifizierungsdatenbank anlegen. Dieses geschieht
1841         automatisch, wenn Sie sich im Administrationsmodul anmelden, das unter
1842         der folgenden URL erreichbar sein sollte:</para>
1843
1844         <para><ulink
1845         url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
1846       </sect2>
1847     </sect1>
1848
1849     <sect1 id="Benutzer--und-Gruppenverwaltung">
1850       <title>Mandanten-, Benutzer- und Gruppenverwaltung</title>
1851
1852       <para>Nach der Installation müssen Mandanten, Benutzer, Gruppen und
1853       Datenbanken angelegt werden. Dieses geschieht im Administrationsmenü,
1854       das Sie unter folgender URL finden:</para>
1855
1856       <para><ulink
1857       url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
1858
1859       <para>Verwenden Sie zur Anmeldung das Passwort, das Sie in der Datei
1860       <filename>config/kivitendo.conf</filename> eingetragen haben.</para>
1861
1862       <sect2 id="Zusammenhänge">
1863         <title>Zusammenhänge</title>
1864
1865         <para>kivitendo verwaltet zwei Sets von Daten, die je nach Einrichtung
1866         in einer oder zwei Datenbanken gespeichert werden.</para>
1867
1868         <para>Das erste Set besteht aus Anmeldeinformationen: welche Benutzer
1869         und Mandanten gibt es, welche Gruppen, welche BenutzerIn hat Zugriff
1870         auf welche Mandanten, und welche Gruppe verfügt über welche Rechte.
1871         Diese Informationen werden in der Authentifizierungsdatenbank
1872         gespeichert. Dies ist diejenige Datenbank, deren Verbindungsparameter
1873         in der Konfigurationsdatei <filename>config/kivitendo.conf</filename>
1874         gespeichert werden.</para>
1875
1876         <para>Das zweite Set besteht aus den eigentlichen Verkehrsdaten eines
1877         Mandanten, wie beispielsweise die Stammdaten (Kunden, Lieferanten,
1878         Waren) und Belege (Angebote, Lieferscheine, Rechnungen). Diese werden
1879         in einer Mandantendatenbank gespeichert. Die Verbindungsinformationen
1880         einer solchen Mandantendatenbank werden im Administrationsbereich
1881         konfiguriert, indem man einen Mandanten anlegt und dort die Parameter
1882         einträgt. Dabei hat jeder Mandant eine eigene Datenbank.</para>
1883
1884         <para>Aufgrund des Datenbankdesigns ist es für einfache Fälle möglich,
1885         die Authentifizierungsdatenbank und eine der Mandantendatenbanken in
1886         ein und derselben Datenbank zu speichern. Arbeitet man hingegen mit
1887         mehr als einem Mandanten, wird empfohlen, für die
1888         Authentifizierungsdatenbank eine eigene Datenbank zu verwenden, die
1889         nicht gleichzeitig für einen Mandanten verwendet wird.</para>
1890       </sect2>
1891
1892       <sect2 id="Mandanten-Benutzer-Gruppen">
1893         <title>Mandanten, Benutzer und Gruppen</title>
1894
1895         <para>kivitendos Administration kennt Mandanten, Benutzer und Gruppen,
1896         die sich frei zueinander zuordnen lassen.</para>
1897
1898         <para>kivitendo kann mehrere Mandaten aus einer Installation heraus
1899         verwalten. Welcher Mandant benutzt wird, kann direkt beim Login
1900         ausgewählt werden. Für jeden Mandanten wird ein eindeutiger Name
1901         vergeben, der beim Login angezeigt wird. Weiterhin benötigt der
1902         Mandant Datenbankverbindungsparameter für seine Mandantendatenbank.
1903         Diese sollte über die <link
1904         linkend="Datenbanken-anlegen">Datenbankverwaltung</link>
1905         geschehen.</para>
1906
1907         <para>Ein Benutzer ist eine Person, die Zugriff auf kivitendo erhalten
1908         soll. Sie erhält einen Loginnamen sowie ein Passwort. Weiterhin legt
1909         der Administrator fest, an welchen Mandanten sich ein Benutzer
1910         anmelden kann, was beim Login verifiziert wird.</para>
1911
1912         <para>Gruppen dienen dazu, Benutzern innerhalb eines Mandanten Zugriff
1913         auf bestimmte Funktionen zu geben. Einer Gruppe werden dafür vom
1914         Administrator gewisse Rechte zugeordnet. Weiterhin legt der
1915         Administrator fest, für welche Mandanten eine Gruppe gilt, und welche
1916         Benutzer Mitglieder in dieser Gruppe sind. Meldet sich ein Benutzer
1917         dann an einem Mandanten an, so erhält er alle Rechte von allen
1918         denjenigen Gruppen, die zum Einen dem Mandanten zugeordnet sind und in
1919         denen der Benutzer zum Anderen Mitglied ist,</para>
1920
1921         <para>Die Reihenfolge, in der Datenbanken, Mandanten, Gruppen und
1922         Benutzer angelegt werden, kann im Prinzip beliebig gewählt werden. Die
1923         folgende Reihenfolge beinhaltet die wenigsten Arbeitsschritte:</para>
1924
1925         <orderedlist numeration="arabic">
1926           <listitem>
1927             <para>Datenbank anlegen</para>
1928           </listitem>
1929
1930           <listitem>
1931             <para>Gruppen anlegen</para>
1932           </listitem>
1933
1934           <listitem>
1935             <para>Benutzer anlegen und Gruppen als Mitglied zuordnen</para>
1936           </listitem>
1937
1938           <listitem>
1939             <para>Mandanten anlegen und Gruppen sowie Benutzer zuweisen</para>
1940           </listitem>
1941         </orderedlist>
1942       </sect2>
1943
1944       <sect2 id="Datenbanken-anlegen">
1945         <title>Datenbanken anlegen</title>
1946
1947         <para>Zuerst muss eine Datenbank angelegt werden. Verwenden Sie für
1948         den Datenbankzugriff den vorhin angelegten Benutzer (in unseren
1949         Beispielen ist dies ‘<literal>kivitendo</literal>’).</para>
1950       </sect2>
1951
1952       <sect2 id="Gruppen-anlegen">
1953         <title>Gruppen anlegen</title>
1954
1955         <para>Eine Gruppe wird in der Gruppenverwaltung angelegt. Ihr muss ein
1956         Name gegeben werden, eine Beschreibung ist hingegen optional. Nach dem
1957         Anlegen können Sie die verschiedenen Bereiche wählen, auf die
1958         Mitglieder dieser Gruppe Zugriff haben sollen.</para>
1959
1960         <para>Benutzergruppen werden zwar in der Authentifizierungsdatenbank
1961         gespeichert, gelten aber nicht automatisch für alle Mandanten. Der
1962         Administrator legt vielmehr fest, für welche Mandanten eine Gruppe
1963         gültig ist. Dies kann entweder beim Bearbeiten der Gruppe geschehen
1964         ("diese Gruppe ist gültig für Mandanten X, Y und Z"), oder aber wenn
1965         man einen Mandanten bearbeitet ("für diesen Mandanten sind die Gruppen
1966         A, B und C gültig").</para>
1967
1968         <para>Wurden bereits Benutzer angelegt, so können hier die Mitglieder
1969         dieser Gruppe festgelegt werden ("in dieser Gruppe sind die Benutzer
1970         X, Y und Z Mitglieder"). Dies kann auch nachträglich beim Bearbeiten
1971         eines Benutzers geschehen ("dieser Benutzer ist Mitglied in den
1972         Gruppen A, B und C").</para>
1973       </sect2>
1974
1975       <sect2 id="Benutzer-anlegen">
1976         <title>Benutzer anlegen</title>
1977
1978         <para>Beim Anlegen von Benutzern werden für viele Parameter
1979         Standardeinstellungen vorgenommen, die den Gepflogenheiten des
1980         deutschen Raumes entsprechen.</para>
1981
1982         <para>Zwingend anzugeben ist der Loginname. Wenn die
1983         Passwortauthentifizierung über die Datenbank eingestellt ist, so kann
1984         hier auch das Benutzerpasswort gesetzt bzw. geändert werden. Ist
1985         hingegen die LDAP-Authentifizierung aktiv, so ist das Passwort-Feld
1986         deaktiviert.</para>
1987
1988         <para>Hat man bereits Mandanten und Gruppen angelegt, so kann hier
1989         auch konfiguriert werden, auf welche Mandanten der Benutzer Zugriff
1990         hat bzw. in welchen Gruppen er Mitglied ist. Beide Zuweisungen können
1991         sowohl beim Benutzer vorgenommen werden ("dieser Benutzer hat Zugriff
1992         auf Mandanten X, Y, Z" bzw. "dieser Benutzer ist Mitglied in Gruppen
1993         X, Y und Z") als auch beim Mandanten ("auf diesen Mandanten haben
1994         Benutzer A, B und C Zugriff") bzw. bei der Gruppe ("in dieser Gruppe
1995         sind Benutzer A, B und C Mitglieder").</para>
1996       </sect2>
1997
1998       <sect2 id="Mandanten-anlegen">
1999         <title>Mandanten anlegen</title>
2000
2001         <para>Ein Mandant besteht aus Administrationssicht primär aus einem
2002         eindeutigen Namen. Weiterhin wird hier hinterlegt, welche Datenbank
2003         als Mandantendatenbank benutzt wird. Hier müssen die Zugriffsdaten
2004         einer der eben angelegten Datenbanken eingetragen werden.</para>
2005
2006         <para>Hat man bereits Benutzer und Gruppen angelegt, so kann hier auch
2007         konfiguriert werden, welche Benutzer Zugriff auf den Mandanten haben
2008         bzw. welche Gruppen für den Mandanten gültig sind. Beide Zuweisungen
2009         können sowohl beim Mandanten vorgenommen werden ("auf diesen Mandanten
2010         haben Benutzer X, Y und Z Zugriff" bzw. "für diesen Mandanten sind die
2011         Gruppen X, Y und Z gültig") als auch beim Benutzer ("dieser Benutzer
2012         hat Zugriff auf Mandanten A, B und C") bzw. bei der Gruppe ("diese
2013         Gruppe ist für Mandanten A, B und C gültig").</para>
2014       </sect2>
2015     </sect1>
2016
2017     <sect1 id="Drucker--Systemverwaltung">
2018       <title>Drucker- und Systemverwaltung</title>
2019
2020       <para>Im Administrationsmenü gibt es ferner noch die beiden Menüpunkte
2021       Druckeradministration und System.</para>
2022
2023       <sect2 id="Druckeradministration">
2024         <title>Druckeradministration</title>
2025
2026         <para>Unter dem Menüpunkt Druckeradministration lassen sich beliebig
2027         viele "Druckbefehle" im System verwalten. Diese Befehle werden
2028         mandantenweise zugeordnet. Unter Druckerbeschreibung wird der Namen
2029         des Druckbefehls festgelegt, der dann in der Druckerauswahl des Belegs
2030         angezeigt wird.</para>
2031
2032         <para>Unter Druckbefehl definiert man den eigentlichen Druckbefehl,
2033         der direkt auf dem Webserver ausgeführt wird, bspw. 'lpr -P
2034         meinDrucker' oder ein kompletter Pfad zu einem Skript
2035         (/usr/local/src/kivitendo/scripts/pdf_druck_in_verzeichnis.sh). Wird
2036         ferner noch ein optionales Vorlagenkürzel verwendet, wird dieses
2037         Kürzel bei der Auswahl der Druckvorlagendatei mit einem Unterstrich
2038         ergänzt, ist bspw. das Kürzel 'epson_drucker' definiert, so wird beim
2039         Ausdruck eines Angebots folgende Vorlage geparst:
2040         sales_quotation_epson_drucker.tex.</para>
2041       </sect2>
2042
2043       <sect2 id="System">
2044         <title>System sperren / entsperren</title>
2045
2046         <para>Unter dem Menüpunkt System gibt es den Eintrag 'Installation
2047         sperren/entsperren'. Setzt man diese Sperre so ist der Zugang zu der
2048         gesamten kivitendo Installation gesperrt.</para>
2049
2050         <para>Falls die Sperre gesetzt ist, erscheint anstelle der
2051         Anmeldemaske die Information: 'kivitendo ist momentan zwecks
2052         Wartungsarbeiten nicht zugänglich.'.</para>
2053
2054         <para>Wichtig zu erwähnen ist hierbei noch, dass sich kivitendo
2055         automatisch 'sperrt', falls es bei einem Versionsupdate zu einem
2056         Datenbankfehler kam. Somit kann hier nicht aus Versehen mit einem
2057         inkonsistenten Datenbestand weitergearbeitet werden.</para>
2058       </sect2>
2059     </sect1>
2060
2061     <sect1 id="config.sending-email"
2062            xreflabel="E-Mail-Versand aus kivitendo heraus">
2063       <title>E-Mail-Versand aus kivitendo heraus</title>
2064
2065       <para>kivitendo kann direkt aus dem Programm heraus E-Mails versenden,
2066       z.B. um ein Angebot direkt an einen Kunden zu verschicken. Damit dies
2067       funktioniert, muss eingestellt werden, über welchen Server die E-Mails
2068       verschickt werden sollen. kivitendo unterstützt dabei zwei Mechanismen:
2069       Versand über einen lokalen E-Mail-Server (z.B. mit
2070       <productname>Postfix</productname> oder <productname>Exim</productname>,
2071       was auch die standardmäßig aktive Methode ist) sowie Versand über einen
2072       SMTP-Server (z.B. der des eigenen Internet-Providers).</para>
2073
2074       <para>Welche Methode und welcher Server verwendet werden, wird über die
2075       Konfigurationsdatei <filename>config/kivitendo.conf</filename>
2076       festgelegt. Dort befinden sich alle Einstellungen zu diesem Thema im
2077       Abschnitt '<literal>[mail_delivery]</literal>'.</para>
2078
2079       <sect2 id="config.sending-email.sendmail"
2080              xreflabel="E-Mail-Versand über lokalen E-Mail-Server">
2081         <title>Versand über lokalen E-Mail-Server</title>
2082
2083         <para>Diese Methode bietet sich an, wenn auf dem Server, auf dem
2084         kivitendo läuft, bereits ein funktionsfähiger E-Mail-Server wie z.B.
2085         <productname>Postfix</productname>, <productname>Exim</productname>
2086         oder <productname>Sendmail</productname> läuft.</para>
2087
2088         <para>Um diese Methode auszuwählen, muss der Konfigurationsparameter
2089         '<literal>method = sendmail</literal>' gesetzt sein. Dies ist
2090         gleichzeitig der Standardwert, falls er nicht verändert wird.</para>
2091
2092         <para>Um zu kontrollieren, wie das Programm zum Einliefern gestartet
2093         wird, dient der Parameter '<literal>sendmail = ...</literal>'. Der
2094         Standardwert verweist auf das Programm
2095         <filename>/usr/bin/sendmail</filename>, das bei allen oben genannten
2096         E-Mail-Serverprodukten für diesen Zweck funktionieren sollte.</para>
2097
2098         <para>Die Konfiguration des E-Mail-Servers selber würde den Rahmen
2099         dieses sprengen. Hierfür sei auf die Dokumentation des E-Mail-Servers
2100         verwiesen.</para>
2101       </sect2>
2102
2103       <sect2 id="config.sending-email.smtp"
2104              xreflabel="E-Mail-Versand über einen SMTP-Server">
2105         <title>Versand über einen SMTP-Server</title>
2106
2107         <para>Diese Methode bietet sich an, wenn kein lokaler E-Mail-Server
2108         vorhanden oder zwar einer vorhanden, dieser aber nicht konfiguriert
2109         ist.</para>
2110
2111         <para>Um diese Methode auszuwählen, muss der Konfigurationsparameter
2112         '<literal>method = smtp</literal>' gesetzt sein. Die folgenden
2113         Parameter dienen dabei der weiteren Konfiguration:</para>
2114
2115         <variablelist>
2116           <varlistentry>
2117             <term><varname>hostname</varname></term>
2118
2119             <listitem>
2120               <para>Name oder IP-Adresse des SMTP-Servers. Standardwert:
2121               '<literal>localhost</literal>'</para>
2122             </listitem>
2123           </varlistentry>
2124
2125           <varlistentry>
2126             <term><varname>port</varname></term>
2127
2128             <listitem>
2129               <para>Portnummer. Der Standardwert hängt von der verwendeten
2130               Verschlüsselungsmethode ab. Gilt '<literal>security =
2131               none</literal>' oder '<literal>security = tls</literal>', so ist
2132               25 die Standardportnummer. Für '<literal>security =
2133               ssl</literal>' ist 465 die Portnummer. Muss normalerweise nicht
2134               geändert werden.</para>
2135             </listitem>
2136           </varlistentry>
2137
2138           <varlistentry>
2139             <term><varname>security</varname></term>
2140
2141             <listitem>
2142               <para>Wahl der zu verwendenden Verschlüsselung der Verbindung
2143               mit dem Server. Standardwert ist '<literal>none</literal>',
2144               wodurch keine Verschlüsselung verwendet wird. Mit
2145               '<literal>tls</literal>' wird TLS-Verschlüsselung eingeschaltet,
2146               und mit '<literal>ssl</literal>' wird Verschlüsselung via SSL
2147               eingeschaltet. Achtung: Für '<literal>tls</literal>' und
2148               '<literal>ssl</literal>' werden zusätzliche Perl-Module benötigt
2149               (siehe unten).</para>
2150             </listitem>
2151           </varlistentry>
2152
2153           <varlistentry>
2154             <term><varname>login</varname> und
2155             <varname>password</varname></term>
2156
2157             <listitem>
2158               <para>Falls der E-Mail-Server eine Authentifizierung verlangt,
2159               so können mit diesen zwei Parametern der Benutzername und das
2160               Passwort angegeben werden. Wird Authentifizierung verwendet, so
2161               sollte aus Sicherheitsgründen auch eine Form von Verschlüsselung
2162               aktiviert werden.</para>
2163             </listitem>
2164           </varlistentry>
2165         </variablelist>
2166       </sect2>
2167     </sect1>
2168
2169     <sect1 id="Drucken-mit-kivitendo">
2170       <title>Drucken mit kivitendo</title>
2171
2172       <para>Das Drucksystem von kivitendo benutzt von Haus aus LaTeX-Vorlagen.
2173       Um drucken zu können, braucht der Server ein geeignetes LaTeX System. Am
2174       einfachsten ist dazu eine <literal>texlive</literal> Installation. Unter
2175       debianoiden Betriebssystemen installiert man die Pakete mit:</para>
2176
2177       <para><programlisting>apt install texlive-base-bin texlive-latex-recommended texlive-fonts-recommended \
2178   texlive-latex-extra texlive-lang-german texlive-generic-extra texlive-xetex ghostscript</programlisting></para>
2179
2180       <para>Für Fedora benötigen Sie die folgenden Pakete:</para>
2181
2182       <para><programlisting>dnf install texlive-collection-latex texlive-collection-latexextra \
2183   texlive-collection-latexrecommended texlive-collection-langgerman \
2184   texlive-collection-langenglish</programlisting></para>
2185
2186       <para>Für openSUSE benötigen Sie die folgenden Pakete:</para>
2187
2188       <para><programlisting>zypper install texlive-collection-latex texlive-collection-latexextra \
2189   texlive-collection-latexrecommended texlive-collection-langgerman \
2190   texlive-collection-langenglish</programlisting></para>
2191
2192       <note>kivitendo erwartet eine aktuelle TeX Live Umgebung, um PDF/A zu erzeugen. Aktuelle Distributionen von 2020 erfüllen diese. Überprüfbar ist dies mit dem Aufruf des installation_check.pl mit Parameter -l: <programlisting>scripts/installations_check.pl -l</programlisting> </note>
2193       <para>kivitendo bringt drei alternative Vorlagensätze mit:</para>
2194
2195       <itemizedlist>
2196         <listitem>
2197           <para>RB</para>
2198         </listitem>
2199         <listitem>
2200           <para>marei</para>
2201         </listitem>
2202         <listitem>
2203           <para>rev-odt</para>
2204         </listitem>
2205       </itemizedlist>
2206
2207       <para>Der ehemalige Druckvorlagensatz "f-tex" wurde mit der Version
2208       3.6 entfernt, da er nicht mehr gepflegt wird.</para>
2209
2210       <sect2 id="Vorlagenverzeichnis-anlegen"
2211              xreflabel="Vorlagenverzeichnis anlegen">
2212         <title>Vorlagenverzeichnis anlegen</title>
2213
2214         <para>Es lässt sich ein initialer Vorlagensatz erstellen. Die
2215         LaTeX-System-Abhängigkeiten hierfür kann man prüfen mit:</para>
2216
2217         <programlisting>./scripts/installation_check.pl -lv</programlisting>
2218
2219         <para>Der Angemeldete Benutzer muss in einer Gruppe sein, die über das
2220         Recht "Konfiguration -&gt; Mandantenverwaltung" verfügt. Siehe auch
2221         <xref linkend="Gruppen-anlegen"/>.</para>
2222
2223         <para>Im Userbereich lässt sich unter: "<guimenu>System</guimenu>
2224         -&gt; <guisubmenu>Mandantenverwaltung</guisubmenu> -&gt;
2225         <guimenuitem>Verschiedenes</guimenuitem>" die Option "Neue
2226         Druckvorlagen aus Vorlagensatz erstellen" auswählen.</para>
2227
2228         <orderedlist>
2229           <listitem>
2230             <para><option>Vorlagen auswählen</option>: Wählen Sie hier den
2231             Vorlagensatz aus, der kopiert werden soll
2232             (<filename>RB</filename>, <filename>marei</filename> oder
2233             <filename>odt-rev</filename>.)</para>
2234           </listitem>
2235
2236           <listitem>
2237             <para><option>Neuer Name</option>: Der Verzeichnisname für den
2238             neuen Vorlagensatz. Dieser kann im Rahmen der üblichen Bedingungen
2239             für Verzeichnisnamen frei gewählt werden.</para>
2240           </listitem>
2241         </orderedlist>
2242
2243         <para>Nach dem Speichern wird das Vorlagenverzeichnis angelegt und ist
2244         für den aktuellen Mandanten ausgewählt. Der gleiche Vorlagensatz kann,
2245         wenn er mal angelegt ist, bei mehreren Mandanten verwendet werden.
2246         Eventuell müssen Anpassungen (Logo, Erscheinungsbild, etc) noch
2247         vorgenommen werden. Den Ordner findet man im Dateisystem unter
2248         <filename>./templates/[Neuer Name]</filename></para>
2249       </sect2>
2250
2251       <sect2 id="Vorlagen-RB">
2252         <title>Der Druckvorlagensatz RB</title>
2253
2254         <para>Hierbei handelt es sich um einen vollständigen LaTeX
2255         Dokumentensatz mit alternativem Design. Die odt oder html-Varianten
2256         sind nicht gepflegt.</para>
2257
2258         <para>Die konzeptionelle Idee der Vorlagen wird <ulink
2259         url="http://www.kivitendo-support.de/vortraege/Lx-Office%20Anwendertreffen%20LaTeX-Druckvorlagen-Teil3-finale.pdf">hier</ulink>
2260         auf Folie 5 bis 10 vorgestellt. Informationen zur Anpassung an die
2261         eigenen Firmendaten finden sich in der Datei Readme.tex im
2262         Vorlagenverzeichnis.</para>
2263
2264         <para>Eine kurze Übersicht der Features:</para>
2265
2266         <itemizedlist>
2267           <listitem>
2268             <para>Mehrsprachenfähig, mit Deutscher und Englischer
2269             Übersetzung</para>
2270           </listitem>
2271
2272           <listitem>
2273             <para>Zentrale Konfigurationsdateien, die für alle Belege benutzt
2274             werden, z.B. für Kopf- und Fußzeilen, und Infos wie
2275             Bankdaten</para>
2276           </listitem>
2277
2278           <listitem>
2279             <para>mehrere vordefinierte Varianten für
2280             Logos/Hintergrundbilder</para>
2281           </listitem>
2282
2283           <listitem>
2284             <para>Berücksichtigung für Steuerzonen "EU mit USt-ID Nummer" oder
2285             "Außerhalb EU"</para>
2286           </listitem>
2287         </itemizedlist>
2288       </sect2>
2289
2290      <sect2 id="Vorlagen-rev-odt">
2291         <title>Der Druckvorlagensatz rev-odt</title>
2292
2293         <para>Hierbei handelt es sich um einen Dokumentensatz der mit
2294         odt-Vorlagen erstellt wurde. Es gibt in dem Verzeichnis eine
2295         Readme-Datei, die eventuell aktueller als die Dokumentation hier ist.
2296         Die odt-Vorlagen in diesem Verzeichnis "rev-odt" wurden von revamp-it,
2297         Zürich erstellt und werden laufend aktualisiert. Ein paar der
2298         Formulierungen in den Druckvorlagen entsprechen dem Schweizer
2299         Sprachgebrauch, z.B. "Offerte" oder "allfällig".</para>
2300
2301         <para>Hinweis zum Einsatz des Feldes "Land" bei den Stammdaten für
2302         KundInnen und LieferantInnen, sowie bei Lieferadressen: Die in diesem
2303         Vorlagensatz vorhandenen Vorlagen erwarten für "Land" das
2304         entsprechende Kürzel, das in Adressen vor die Postleitzahl gesetzt
2305         wird. Das Feld kann auch komplett leer bleiben. Wer dies anders
2306         handhaben möchte, muss die Vorlagen entsprechend anpassen.</para>
2307
2308         <para>odt-Vorlagen können mit LibreOffice oder OpenOffice editiert und
2309         den eigenen Bedürfnissen angepasst werden. Wichtig beim Editieren von
2310         if-Blöcken ist, dass immer der gesamte Block überschrieben werden muss
2311         und nicht nur Teile davon, da dies sonst oft zu einer odt-Datei führt,
2312         die vom Parser nicht korrekt gelesen werden kann.</para>
2313
2314         <para>Mahnungen können unter folgenden Einschränkungen mit den
2315         odt-Vorlagen im Vorlagensatz rev-odt erzeugt werden:</para>
2316
2317         <itemizedlist>
2318           <listitem>
2319             <para>als Druckoption steht nur 'PDF(OpenDocument/OASIS)' zur
2320             Verfügung, das heisst, die Mahnungen werden als PDF-Datei
2321             ausgegeben.</para>
2322           </listitem>
2323
2324           <listitem>
2325             <para>für jede Rechnung muss eine eigene Mahnung erzeugt werden
2326             (auch wenn bei einzelnen KundInnen mehrere überfällige Rechnungen
2327             vorhanden sind).</para>
2328           </listitem>
2329         </itemizedlist>
2330
2331         <para>Mehrere Mahnungen für eine Kundin / einen Kunden werden zu einer
2332         PDF-Datei zusammengefasst</para>
2333
2334         <para>Die Vorlagen zahlungserinnerung.odt sowie mahnung.odt sind für
2335         das Erstellen einer Zahlungserinnerung bzw. Mahnung selbst vorgesehen,
2336         die Vorlage mahnung_invoice.odt für das Erstellen einer Rechnung über
2337         die verrechneten Mahngebühren und Verzugszinsen.</para>
2338
2339         <para>Zur Zeit gibt es in kivitendo noch keine Möglichkeit,
2340         odt-Vorlagen bei Briefen und Pflichtenheften einzusetzen.
2341         Entsprechende Vorlagen sind deshalb nicht vorhanden.</para>
2342
2343         <para>Fehlermeldungen, Anregungen und Wünsche bitte senden an:
2344         empfang@revamp-it.ch</para>
2345       </sect2>
2346
2347       <sect2 id="allgemeine-hinweise-zu-latex">
2348         <title>Allgemeine Hinweise zu LaTeX Vorlagen</title>
2349
2350         <para>In den allermeisten Installationen sollte das Drucken jetzt
2351         schon funktionieren. Sollte ein Fehler auftreten, wirft TeX sehr lange
2352         Fehlerbeschreibungen, der eigentliche Fehler ist immer die erste
2353         Zeile, die mit einem Ausrufezeichen anfängt. Häufig auftretende Fehler
2354         sind zum Beispiel:</para>
2355
2356         <itemizedlist>
2357           <listitem>
2358             <para>! LaTeX Error: File `eurosym.sty' not found. Die
2359             entsprechende LaTeX-Bibliothek wurde nicht gefunden. Das tritt vor
2360             allem bei Vorlagen aus der Community auf. Installieren Sie die
2361             entsprechenden Pakete.</para>
2362           </listitem>
2363
2364           <listitem>
2365             <para>! Package inputenc Error: Unicode char \u8:... set up for
2366             use with LaTeX. Dieser Fehler tritt auf, wenn sie versuchen mit
2367             einer Standardinstallation exotische utf8 Zeichen zu drucken.
2368             TeXLive unterstützt von Haus nur romanische Schriften und muss mit
2369             diversen Tricks dazu gebracht werden andere Zeichen zu
2370             akzeptieren. Adere TeX Systeme wie XeTeX schaffen hier
2371             Abhilfe.</para>
2372           </listitem>
2373         </itemizedlist>
2374
2375         <para>Wird gar kein Fehler angezeigt, sondern nur der Name des
2376         Templates, heißt das normalerweise, dass das LaTeX Binary nicht
2377         gefunden wurde. Prüfen Sie den Namen in der Konfiguration (Standard:
2378         <literal>pdflatex</literal>), und stellen Sie sicher, dass pdflatex
2379         (oder das von Ihnen verwendete System) vom Webserver ausgeführt werden
2380         darf.</para>
2381
2382         <para>Wenn sich das Problem nicht auf Grund der Ausgabe im Webbrowser
2383         verifizieren lässt:</para>
2384
2385         <itemizedlist>
2386           <listitem>
2387             <para>editiere [kivitendo-home]/config/kivitendo.conf und ändere
2388             "keep_temp_files" auf 1</para>
2389
2390             <para><programlisting>keep_temp_files = 1;</programlisting></para>
2391           </listitem>
2392
2393           <listitem>
2394             <para>bei fastcgi oder mod_perl den Webserver neu Starten</para>
2395           </listitem>
2396
2397           <listitem>
2398             <para>Nochmal einen Druckversuch im Webfrontend auslösen</para>
2399           </listitem>
2400
2401           <listitem>
2402             <para>wechsel in das users Verzeichnis von kivitendo</para>
2403
2404             <para><programlisting>cd [kivitendo-home]/users</programlisting></para>
2405           </listitem>
2406
2407           <listitem>
2408             <para>LaTeX Suchpfad anpassen:</para>
2409
2410             <para><programlisting>export TEXINPUTS=".:[kivitendo-home]/templates/[aktuelles_template_verzeichniss]:"</programlisting></para>
2411           </listitem>
2412
2413           <listitem>
2414             <para>Finde heraus, welche Datei kivitendo beim letzten Durchlauf
2415             erstellt hat</para>
2416
2417             <para><programlisting>ls -lahtr ./1*.tex</programlisting></para>
2418
2419             <para>Es sollte die letzte Datei ganz unten sein</para>
2420           </listitem>
2421
2422           <listitem>
2423             <para>für besseren Hinweis auf Fehler texdatei nochmals
2424             übersetzen</para>
2425
2426             <para><programlisting>pdflatex ./1*.tex</programlisting></para>
2427
2428             <para>in der *.tex datei nach dem Fehler suchen.</para>
2429           </listitem>
2430         </itemizedlist>
2431       </sect2>
2432     </sect1>
2433
2434     <sect1 id="OpenDocument-Vorlagen">
2435       <title>OpenDocument-Vorlagen</title>
2436
2437       <para>kivitendo unterstützt die Verwendung von Vorlagen im
2438       OpenDocument-Format, wie es LibreOffice oder OpenOffice (ab Version 2)
2439       erzeugen. kivitendo kann dabei sowohl neue OpenDocument-Dokumente als
2440       auch aus diesen direkt PDF-Dateien erzeugen. Um die Unterstützung von
2441       OpenDocument-Vorlagen zu aktivieren muss in der Datei
2442       <filename>config/kivitendo.conf</filename> die Variable
2443       <literal>opendocument</literal> im Abschnitt
2444       <literal>print_templates</literal> auf ‘<literal>1</literal>’ stehen.
2445       Dieses ist die Standardeinstellung.</para>
2446
2447       <para>Während die Erzeugung von reinen OpenDocument-Dateien keinerlei
2448       weitere Software benötigt, wird zur Umwandlung dieser Dateien in PDF
2449       LibreOffice oder OpenOffice benötigt. Soll dieses Feature genutzt
2450       werden, so muss neben LibreOffice oder OpenOffice auch der “X virtual
2451       frame buffer” (xvfb) installiert werden. Bei Debian ist er im Paket
2452       “xvfb” enthalten. Andere Distributionen enthalten ihn in anderen
2453       Paketen.</para>
2454
2455       <para>Nach der Installation müssen in der Datei
2456       <filename>config/kivitendo.conf</filename> im Abschnitt
2457       <literal>applications</literal> zwei weitere Variablen angepasst
2458       werden:</para>
2459
2460       <para><literal>openofficeorg_writer</literal> muss den vollständigen
2461       Pfad zu LibreOffice oder OpenOffice enthalten. Dabei dürfen keine
2462       Anführungszeichen eingesetzt werden.</para>
2463
2464       <para>Beispiel für Debian oder Ubuntu:</para>
2465
2466       <programlisting>openofficeorg_writer = /usr/bin/libreoffice</programlisting>
2467
2468       <para><literal>xvfb</literal> muss den Pfad zum “X virtual frame buffer”
2469       enthalten.</para>
2470
2471       <para>Zusätzlich gibt es zwei verschiedene Arten, wie kivitendo mit
2472       LibreOffice bzw. OpenOffice kommuniziert. Die erste Variante, die
2473       benutzt wird, wenn die Variable <literal>$openofficeorg_daemon</literal>
2474       gesetzt ist, startet ein LibreOffice oder OpenOffice, das auch nach der
2475       Umwandlung des Dokumentes gestartet bleibt. Bei weiteren Umwandlungen
2476       wird dann diese laufende Instanz benutzt. Der Vorteil ist, dass die Zeit
2477       zur Umwandlung deutlich reduziert wird, weil nicht für jedes Dokument
2478       ein LibreOffice bzw. OpenOffice gestartet werden muss. Der Nachteil ist,
2479       dass diese Methode Python und die Python-UNO-Bindings benötigt, die
2480       Bestandteil von LibreOffice bzw. OpenOffice sind.</para>
2481
2482       <note>
2483         <para>Für die Verbindung zu LibreOffice bzw. OpenOffice wird
2484         normalerweise der Python-Interpreter
2485         <filename>/usr/bin/python</filename> benutzt. Sollte dies nicht der
2486         richtige sein, so kann man mit zwei Konfigurationsvariablen
2487         entscheiden, welcher Python-Interpreter genutzt wird. Mit der Option
2488         <literal>python_uno</literal> aus dem Abschnitt
2489         <literal>applications</literal> wird der Interpreter selber
2490         festgelegt; sie steht standardmäßig auf dem eben erwähnten Wert
2491         <literal>/usr/bin/python</literal>.</para>
2492
2493         <para>Zusätzlich ist es möglich, Pfade anzugeben, in denen Python
2494         neben seinen normalen Suchpfaden ebenfalls nach Modulen gesucht wird,
2495         z.B. falls sich diese in einem gesonderten LibreOffice- bzw.
2496         OpenOffice-Verzeichnis befinden. Diese zweite Variable heißt
2497         <literal>python_uno_path</literal> und befindet sich im Abschnitt
2498         <literal>environment</literal>. Sie ist standardmäßig leer. Werden
2499         hier mehrere Pfade angegeben, so müssen diese durch Doppelpunkte
2500         voneinander getrennt werden. Der Inhalt wird an den Python-Interpreter
2501         über die Umgebungsvariable <literal>PYTHONPATH</literal>
2502         übergeben.</para>
2503       </note>
2504
2505       <para>Ist <literal>$openofficeorg_daemon</literal> nicht gesetzt, so
2506       wird für jedes Dokument LibreOffice bzw. OpenOffice neu gestartet und
2507       die Konvertierung mit Hilfe eines Makros durchgeführt. Dieses Makro muss
2508       in der Dokumentenvorlage enthalten sein und
2509       “Standard.Conversion.ConvertSelfToPDF()” heißen. Die Beispielvorlage
2510       ‘<literal>templates/print/rev-odt/invoice.odt</literal>’ enthält ein
2511       solches Makro, das in jeder anderen Dokumentenvorlage ebenfalls
2512       enthalten sein muss.</para>
2513
2514       <para>Als letztes muss herausgefunden werden, welchen Namen OpenOffice
2515       bzw. LibreOffice dem Verzeichnis mit den Benutzereinstellungen gibt.
2516       Unter Debian ist dies momentan <literal>~/.config/libreoffice</literal>.
2517       kivitendo verwendet das Verzeichnis
2518       <literal>users/.openoffice.org2</literal>. Eventuell muss dieses
2519       Verzeichnis umbenannt werden.</para>
2520
2521       <para>Dieses Verzeichnis, wie auch das komplette
2522       <literal>users</literal>-Verzeichnis, muss vom Webserver beschreibbar
2523       sein. Dieses wurde bereits erledigt (siehe <xref
2524       linkend="Manuelle-Installation-des-Programmpaketes"/>), kann aber erneut
2525       überprüft werden, wenn die Konvertierung nach PDF fehlschlägt.</para>
2526
2527       <sect2>
2528         <title>OpenDocument (odt) Druckvorlagen mit Makros</title>
2529
2530         <para>OpenDocument Vorlagen können Makros enthalten, welche komplexere
2531         Aufgaben erfüllen.</para>
2532
2533         <para>Der Vorlagensatz "rev-odt" enthält solche Vorlagen mit <emphasis
2534         role="bold">Schweizer Bank-Einzahlungsscheinen (BESR)</emphasis>.
2535         Diese Makros haben die Aufgabe, die in den Einzahlungsscheinen
2536         benötigte Referenznummer und Kodierzeile zu erzeugen. Hier eine kurze
2537         Beschreibung, wie die Makros aufgebaut sind, und was bei ihrer Nutzung
2538         zu beachten ist (<emphasis role="bold">in fett sind nötige einmalige
2539         Anpassungen aufgeführt</emphasis>):</para>
2540
2541         <sect3>
2542           <title>Bezeichnung der Vorlagen</title>
2543
2544           <para>Rechnung: invoice_besr.odt, Auftrag:
2545           sales_order_besr.odt</para>
2546         </sect3>
2547
2548         <sect3>
2549           <title>Vorbereitungen im Adminbereich</title>
2550
2551           <para>Damit beim Erstellen von Rechnungen und Aufträgen neben der
2552           Standardvorlage ohne Einzahlungsschein weitere Vorlagen (z.B. mit
2553           Einzahlungsschein) auswählbar sind, muss für jedes Vorlagen-Suffix
2554           ein Drucker eingerichtet werden:</para>
2555
2556           <itemizedlist>
2557             <listitem>
2558               <para>Druckeradministration → Drucker hinzufügen</para>
2559             </listitem>
2560
2561             <listitem>
2562               <para>Mandant wählen</para>
2563             </listitem>
2564
2565             <listitem>
2566               <para>Druckerbeschreibung → aussagekräftiger Text: wird in der
2567               Auftrags- bzw. Rechnungsmaske als Auswahl angezeigt (z.B. mit
2568               Einzahlungsschein Bank xy)</para>
2569             </listitem>
2570
2571             <listitem>
2572               <para>Druckbefehl → beliebiger Text (hat für das Erzeugen von
2573               Aufträgen oder Rechnungen als odt-Datei keine Bedeutung, darf
2574               aber nicht leer sein)</para>
2575             </listitem>
2576
2577             <listitem>
2578               <para>Vorlagenkürzel → besr bzw. selbst gewähltes Vorlagensuffix
2579               (muss genau der Zeichenfolge entsprechen, die zwischen
2580               "invoice_" bzw. "sales_order_" und ".odt" steht.)</para>
2581             </listitem>
2582
2583             <listitem>
2584               <para>speichern</para>
2585             </listitem>
2586           </itemizedlist>
2587         </sect3>
2588
2589         <sect3>
2590           <title>Benutzereinstellungen</title>
2591
2592           <para>Wer den Ausdruck mit Einzahlungsschein als Standardeinstellung
2593           im Rechnungs- bzw. Auftragsformular angezeigt haben möchte, kann
2594           dies persönlich für sich bei den Benutzereinstellungen
2595           konfigurieren:</para>
2596
2597           <itemizedlist>
2598             <listitem>
2599               <para>Programm → Benutzereinstellungen → Druckoptionen</para>
2600             </listitem>
2601
2602             <listitem>
2603               <para>Standardvorlagenformat → OpenDocument/OASIS</para>
2604             </listitem>
2605
2606             <listitem>
2607               <para>Standardausgabekanal → Bildschirm</para>
2608             </listitem>
2609
2610             <listitem>
2611               <para>Standarddrucker → gewünschte Druckerbeschreibung auswählen
2612               (z.B. mit Einzahlungsschein Bank xy)</para>
2613             </listitem>
2614
2615             <listitem>
2616               <para>Anzahl Kopien → leer</para>
2617             </listitem>
2618
2619             <listitem>
2620               <para>speichern</para>
2621             </listitem>
2622           </itemizedlist>
2623         </sect3>
2624
2625         <sect3>
2626           <title>Aufbau und nötige Anpassungen der Vorlagen</title>
2627
2628           <para>In der Vorlage sind als Modul "BESR" 4 Makros gespeichert, die
2629           aus dem von kivitendo erzeugten odt-Dokument die korrekte
2630           Referenznummer inklusive Prüfziffer sowie die Kodierzeile in
2631           OCRB-Schrift erzeugen und am richtigen Ort ins Dokument
2632           schreiben.</para>
2633
2634           <itemizedlist>
2635             <listitem>
2636               <para>Für den Einzahlungsschein ist die letzte Seite des
2637               Dokuments reserviert</para>
2638             </listitem>
2639
2640             <listitem>
2641               <para>Direkt über dem Einzahlungsschein enthält die Vorlage eine
2642               Zeile mit folgenden Angaben (<emphasis
2643               role="bold">Bank-Konto-Identifikationsnummer und
2644               Postkonto-Nummer der Bank müssen gemäss Angaben der jeweiligen
2645               Bank angepasst werden</emphasis>):<itemizedlist>
2646                   <listitem>
2647                     <para>DDDREF: 4 Werte zum Bilden der Referenznummer
2648                     (jeweils durch einen Leerschlag getrennt): <itemizedlist>
2649                         <listitem>
2650                           <para>erster Wert: <emphasis
2651                           role="bold">Bank-Konto-Identifikation</emphasis>
2652                           (nur Ziffern, maximal 6), <emphasis role="bold">muss
2653                           angepasst werden</emphasis>.</para>
2654                         </listitem>
2655
2656                         <listitem>
2657                           <para>zweiter Wert: &lt;%customernumber%&gt;
2658                           (Kundennummer: nur Ziffern, maximal 6)</para>
2659                         </listitem>
2660
2661                         <listitem>
2662                           <para>dritter Wert: &lt;%ordnumber%&gt;
2663                           (Auftragsnummer bei Auftragsvorlage
2664                           sales_oder_besr.odt, sonst 0) maximal 7 Ziffern,
2665                           führende Buchstaben werden vom Makro entfernt</para>
2666                         </listitem>
2667
2668                         <listitem>
2669                           <para>vierter Wert: &lt;%invnumber%&gt;
2670                           (Rechnungsnummer bei Rechnungsvorlage
2671                           invoice_besr.odt, sonst 0) maximal 7 Ziffern,
2672                           führende Buchstaben werden vom Makro entfernt</para>
2673                         </listitem>
2674                       </itemizedlist></para>
2675                   </listitem>
2676
2677                   <listitem>
2678                     <para>DDDKONTO: <emphasis role="bold">Postkonto-Nummer der
2679                     Bank, muss angepasst werden</emphasis>.</para>
2680                   </listitem>
2681
2682                   <listitem>
2683                     <para>DDDBETRAG: &lt;%total%&gt; Einzahlungsbetrag oder 0,
2684                     falls Einzahlungsschein ohne Betrag</para>
2685                   </listitem>
2686
2687                   <listitem>
2688                     <para>DDDEND: muss am Ende der Zeile vorhanden sein</para>
2689                   </listitem>
2690                 </itemizedlist></para>
2691             </listitem>
2692
2693             <listitem>
2694               <para><emphasis role="bold">Im Einzahlungsschein selbst müssen
2695               der Name und die Adresse der Bank, die Postkonto-Nummer der
2696               Bank, sowie der eigene Firmenname und die Firmenadresse
2697               angepasst werden.</emphasis> Dabei ist darauf zu achten, dass
2698               sich die Positionen der Postkonto-Nummern der Bank, sowie der
2699               Zeichenfolgen dddfr, DDDREF1, DDDREF2, 609, DDDKODIERZEILE nicht
2700               verschieben.</para>
2701             </listitem>
2702           </itemizedlist>
2703
2704           <screenshot>
2705             <screeninfo>Rechnungsvorlage Schweizer Bank-Einzahlungsschein - zu
2706             ändernde Einträge in rot</screeninfo>
2707
2708             <mediaobject>
2709               <imageobject>
2710                 <imagedata fileref="images/Einzahlungsschein_Makro.png"/>
2711               </imageobject>
2712             </mediaobject>
2713           </screenshot>
2714         </sect3>
2715
2716         <sect3>
2717           <title>Auswahl der Druckvorlage in kivitendo beim Erzeugen einer
2718           odt-Rechnung (analog bei Auftrag)</title>
2719
2720           <para>Im Fussbereich der Rechnungsmaske muss neben Rechnung,
2721           OpenDocument/OASIS und Bildschirm die im Adminbereich erstellte
2722           Druckerbeschreibung ausgewählt werden, falls diese nicht bereits bei
2723           den Benutzereinstellungen als persönlicher Standard gewählt
2724           wurde.</para>
2725         </sect3>
2726
2727         <sect3>
2728           <title>Makroeinstellungen in LibreOffice anpassen</title>
2729
2730           <para>Falls beim Öffnen einer von kivitendo erzeugten odt-Rechnung
2731           die Meldung kommt, dass Makros aus Sicherheitsgründen nicht
2732           ausgeführt werden, so müssen folgende Einstellungen in LibreOffice
2733           angepasst werden:</para>
2734
2735           <itemizedlist>
2736             <listitem>
2737               <para>Extras → Optionen → Sicherheit → Makrosicherheit</para>
2738             </listitem>
2739
2740             <listitem>
2741               <para>Sicherheitslevel auf "Mittel" einstellen (Diese
2742               Einstellung muss auf jedem Computer durchgeführt werden, mit dem
2743               von kivitendo erzeugte odt-Rechnungen oder Aufträge geöffnet
2744               werden.)</para>
2745             </listitem>
2746
2747             <listitem>
2748               <para>Beim Öffnen einer odt-Rechnung oder eines odt-Auftrags bei
2749               der entsprechenden Nachfrage "Makros ausführen"
2750               auswählen.</para>
2751
2752               <para><emphasis role="bold">Wichtig</emphasis>: die Makros sind
2753               so eingestellt, dass sie beim Öffnen der Vorlagen selbst nicht
2754               ausgeführt werden. Das heisst für das Ansehen und Bearbeiten der
2755               Vorlagen sind keine speziellen Einstellungen in LibreOffice
2756               nötig.</para>
2757             </listitem>
2758           </itemizedlist>
2759         </sect3>
2760       </sect2>
2761     </sect1>
2762
2763     <sect1 id="nomenclature">
2764       <title>Nomenklatur</title>
2765
2766       <sect2 id="booking.dates">
2767         <title>Datum bei Buchungen</title>
2768
2769         <para>Seit der Version 3.5 werden für Buchungen in kivitendo
2770         einheitlich folgende Bezeichnungen verwendet:</para>
2771
2772         <itemizedlist>
2773           <listitem>
2774             <para><option>Erfassungsdatum</option> (en: <option>Entry
2775             Date</option>, code: <option>Gldate</option>)</para>
2776
2777             <para>bezeichnet das Datum, an dem die Buchung in kivitendo
2778             erfasst wurde.</para>
2779           </listitem>
2780
2781           <listitem>
2782             <para><option>Buchungsdatum</option> (en: <option>Booking
2783             Date</option>, code: <option>Transdate</option>)</para>
2784
2785             <para>bezeichnet das buchhaltungstechnisch für eine Buchung
2786             relevante Datum</para>
2787
2788             <para>Das <option>Rechnungsdatum</option> bei Verkaufs- und
2789             Einkaufsrechnungen entspricht dem Buchungsdatum. Das heisst, in
2790             Berichten wie dem Buchungsjournal, in denen eine Spalte
2791             <option>Buchungsdatum</option> angezeigt werden kann, erscheint
2792             hier im Fall von Rechnungen das Rechnungsdatum.</para>
2793           </listitem>
2794
2795           <listitem>
2796             <para>Bezieht sich ein verbuchter Beleg auf einen Zeitpunkt, der
2797             nicht mit dem Buchungsdatum übereinstimmt, so kann dieses Datum
2798             momentan in kivitendo nur unter Bemerkungen erfasst werden.</para>
2799
2800             <para>Möglicherweise wird für solche Fälle in einer späteren
2801             Version von kivitendo ein dritter Datumswert für Buchungen
2802             erstellt. (Beispiel: Einkaufsbeleg stammt aus einem früheren Jahr,
2803             das bereits buchhaltungstechnisch abgeschlossen wurde, und muss
2804             deshalb später verbucht werden.)</para>
2805           </listitem>
2806         </itemizedlist>
2807       </sect2>
2808     </sect1>
2809
2810     <sect1 id="config.eur">
2811       <title>Konfiguration zur Einnahmenüberschussrechnung/Bilanzierung:
2812       EUR</title>
2813
2814       <sect2 id="config.eur.introduction"
2815              xreflabel="Einführung in die Konfiguration zur EUR">
2816         <title>Einführung</title>
2817
2818         <para>kivitendo besaß bis inklusive Version 2.6.3 einen
2819         Konfigurationsparameter namens <varname>eur</varname>, der sich in der
2820         Konfigurationsdatei <filename>config/kivitendo.conf</filename> (damals
2821         noch <filename>config/lx_office.conf</filename>) befand. Somit galt er
2822         für alle Mandanten, die in dieser Installation benutzt wurden.</para>
2823
2824         <para>Mit der nachfolgenden Version wurde der Parameter zum Einen in
2825         die Mandantendatenbank verschoben und dabei auch gleich in drei
2826         Einzelparameter aufgeteilt, mit denen sich das Verhalten genauer
2827         steuern lässt.</para>
2828       </sect2>
2829
2830       <sect2 id="config.eur.parameters"
2831              xreflabel="Konfigurationsparameter für EUR">
2832         <title>Konfigurationsparameter</title>
2833
2834         <para>Es gibt drei Parameter, die die Gewinnermittlungsart,
2835         Versteuerungsart und die Warenbuchungsmethode regeln:</para>
2836
2837         <variablelist>
2838           <varlistentry>
2839             <term><varname>profit_determination</varname></term>
2840
2841             <listitem>
2842               <para>Dieser Parameter legt die Berechnungsmethode für die
2843               Gewinnermittlung fest. Er enthält entweder
2844               <literal>balance</literal> für
2845               Betriebsvermögensvergleich/Bilanzierung oder
2846               <literal>income</literal> für die
2847               Einnahmen-Überschuss-Rechnung.</para>
2848             </listitem>
2849           </varlistentry>
2850
2851           <varlistentry>
2852             <term><varname>accounting_method</varname></term>
2853
2854             <listitem>
2855               <para>Dieser Parameter steuert die Buchungs- und
2856               Berechnungsmethoden für die Versteuerungsart. Er enthält
2857               entweder <literal>accrual</literal> für die Soll-Versteuerung
2858               oder <literal>cash</literal> für die Ist-Versteuerung.</para>
2859             </listitem>
2860           </varlistentry>
2861
2862           <varlistentry>
2863             <term><varname>inventory_system</varname></term>
2864
2865             <listitem>
2866               <para>Dieser Parameter legt die Warenbuchungsmethode fest. Er
2867               enthält entweder <literal>perpetual</literal> für die
2868               Bestandsmethode oder <literal>periodic</literal> für die
2869               Aufwandsmethode.</para>
2870             </listitem>
2871           </varlistentry>
2872         </variablelist>
2873
2874         <para>Zum Vergleich der Funktionalität bis und nach 2.6.3:
2875         <varname>eur</varname> = 1 bedeutete Einnahmen-Überschuss-Rechnung,
2876         Ist-Versteuerung und Aufwandsmethode. <varname>eur</varname> = 0
2877         bedeutete hingegen Bilanzierung, Soll-Versteuerung und
2878         Bestandsmethode.</para>
2879
2880         <para>Die Konfiguration "<varname>eur</varname>" unter
2881         <varname>[system]</varname> in der <link
2882         linkend="config.config-file">Konfigurationsdatei</link>
2883         <filename>config/kivitendo.conf</filename> wird nun nicht mehr
2884         benötigt und kann entfernt werden. Dies muss manuell geschehen.</para>
2885       </sect2>
2886
2887       <sect2 id="config.eur.setting-parameters">
2888         <title>Festlegen der Parameter</title>
2889
2890         <para>Beim Anlegen eines neuen Mandanten bzw. einer neuen Datenbank in
2891         der Admininstration können diese Optionen nun unabhängig voneinander
2892         eingestellt werden.</para>
2893
2894         <para>Für die Schweiz sind folgende Einstellungen üblich:
2895         <itemizedlist>
2896             <listitem>
2897               <para>Sollversteuerung</para>
2898             </listitem>
2899
2900             <listitem>
2901               <para>Aufwandsmethode</para>
2902             </listitem>
2903
2904             <listitem>
2905               <para>Bilanzierung</para>
2906             </listitem>
2907           </itemizedlist> Diese Einstellungen werden automatisch beim
2908         Erstellen einer neuen Datenbank vorausgewählt, wenn in
2909         <filename>config/kivitendo.conf</filename> unter
2910         <varname>[system]</varname> <literal>default_manager = swiss</literal>
2911         eingestellt ist.</para>
2912
2913         <para>Beim Upgrade bestehender Mandanten wird eur ausgelesen und die
2914         Variablen werden so gesetzt, daß sich an der Funktionalität nichts
2915         ändert.</para>
2916
2917         <para>Die aktuelle Konfiguration wird unter Nummernkreise und
2918         Standardkonten unter dem neuen Punkt "Einstellungen" (read-only)
2919         angezeigt. Unter <guimenu>System</guimenu> →
2920         <guisubmenu>Mandantenkonfiguration</guisubmenu> können die
2921         Einstellungen auch geändert werden. Dabei ist zu beachten, dass eine
2922         Änderung vorhandene Daten so belässt und damit evtl. die Ergebnisse
2923         verfälscht. Dies gilt vor Allem für die Warenbuchungsmethode (siehe
2924         auch <link linkend="config.eur.inventory-system-perpetual">
2925         Bemerkungen zur Bestandsmethode</link>).</para>
2926       </sect2>
2927
2928       <sect2 id="config.eur.inventory-system-perpetual">
2929         <title>Bemerkungen zur Bestandsmethode</title>
2930
2931         <para>Die Bestandsmethode ist eigentlich eine sehr elegante Methode,
2932         funktioniert in kivitendo aber nur unter bestimmten Bedingungen:
2933         Voraussetzung ist, daß auch immer alle Einkaufsrechnungen gepflegt
2934         werden, und man beim Jahreswechsel nicht mit einer leeren Datenbank
2935         anfängt, da bei jedem Verkauf anhand der gesamten Rechnungshistorie
2936         der Einkaufswert der Ware nach dem FIFO-Prinzip aus den
2937         Einkaufsrechnungen berechnet wird.</para>
2938
2939         <para>Die Bestandsmethode kann vom Prinzip her also nur funktioneren,
2940         wenn man mit den Buchungen bei Null anfängt, und man kann auch nicht
2941         im laufenden Betrieb von der Aufwandsmethode zur Bestandsmethode
2942         wechseln.</para>
2943       </sect2>
2944
2945       <sect2 id="config.eur.knonw-issues">
2946         <title>Bekannte Probleme</title>
2947
2948         <para>Bei bestimmten Berichten kann man derzeit noch inviduell
2949         einstellen, ob man nach Ist- oder Sollversteuerung auswertet, und es
2950         werden im Code Variablen wie $accrual oder $cash gesetzt. Diese
2951         Codestellen wurden noch nicht angepasst, sondern nur die, wo bisher
2952         die Konfigurationsvariable
2953         <varname>$::lx_office_conf{system}-&gt;{eur}</varname> ausgewertet
2954         wurde.</para>
2955
2956         <para>Es fehlen Hilfetext beim Neuanlegen eines Mandanten, was die
2957         Optionen bewirken, z.B. mit zwei Standardfällen.</para>
2958       </sect2>
2959     </sect1>
2960
2961     <sect1 id="config.skr04-update-3804">
2962       <title>SKR04 19% Umstellung für innergemeinschaftlichen Erwerb</title>
2963
2964       <sect2 id="config.skr04-update-3804.introduction">
2965         <title>Einführung</title>
2966
2967         <para>Die Umsatzsteuerumstellung auf 19% für SKR04 für die
2968         Steuerschlüssel "EU ohne USt-ID Nummer" ist erst 2010 erfolgt.
2969         kivitendo beinhaltet ein Upgradeskript, das das Konto 3804 automatisch
2970         erstellt und die Steuereinstellungen korrekt einstellt. Hat der
2971         Benutzer aber schon selber das Konto 3804 angelegt, oder gab es schon
2972         Buchungen im Zeitraum nach dem 01.01.2007 auf das Konto 3803, wird das
2973         Upgradeskript vorsichtshalber nicht ausgeführt, da der Benutzer sich
2974         vielleicht schon selbst geholfen hat und mit seinen Änderungen
2975         zufrieden ist. Die korrekten Einstellungen kann man aber auch per Hand
2976         ausführen. Nachfolgend werden die entsprechenden Schritte anhand von
2977         Screenshots dargestellt.</para>
2978
2979         <para>Für den Fall, daß Buchungen mit der Steuerschlüssel "EU ohne
2980         USt.-IdNr." nach dem 01.01.2007 erfolgt sind, ist davon auszugehen,
2981         dass diese mit dem alten Umsatzsteuersatz von 16% gebucht worden sind,
2982         und diese Buchungen sollten entsprechend kontrolliert werden.</para>
2983       </sect2>
2984
2985       <sect2 id="config.skr04-update-3804.create-chart">
2986         <title>Konto 3804 manuell anlegen</title>
2987
2988         <para>Die folgenden Schritte sind notwendig, um das Konto manuell
2989         anzulegen und zu konfigurieren. Zuerst wird in
2990         <guimenu>System</guimenu> → <guisubmenu>Kontenübersicht</guisubmenu> →
2991         <guimenuitem>Konto erfassen</guimenuitem> das Konto angelegt.</para>
2992
2993         <screenshot>
2994           <screeninfo>Konto 3804 erfassen</screeninfo>
2995
2996           <mediaobject>
2997             <imageobject>
2998               <imagedata fileref="images/skr04-update-3804/konto3804.png"/>
2999             </imageobject>
3000           </mediaobject>
3001         </screenshot>
3002
3003         <para>Als Zweites muss Steuergruppe 13 für Konto 3803 angepasst
3004         werden. Dazu unter <guimenu>System</guimenu> →
3005         <guisubmenu>Steuern</guisubmenu> →
3006         <guimenuitem>Bearbeiten</guimenuitem> den Eintrag mit Steuerschlüssel
3007         13 auswählen und ihn wie im folgenden Screenshot angezeigt
3008         anpassen.</para>
3009
3010         <screenshot>
3011           <screeninfo>Steuerschlüssel 13 für 3803 (16%) anpassen</screeninfo>
3012
3013           <mediaobject>
3014             <imageobject>
3015               <imagedata fileref="images/skr04-update-3804/steuer3803.png"/>
3016             </imageobject>
3017           </mediaobject>
3018         </screenshot>
3019
3020         <para>Als Drittes wird ein neuer Eintrag mit Steuerschlüssel 13 für
3021         Konto 3804 (19%) angelegt. Dazu unter <guimenu>System</guimenu> →
3022         <guisubmenu>Steuern</guisubmenu> → <guimenuitem>Erfassen</guimenuitem>
3023         auswählen und die Werte aus dem Screenshot übernehmen.</para>
3024
3025         <screenshot>
3026           <screeninfo>Steuerschlüssel 13 für 3804 (19%) anlegen</screeninfo>
3027
3028           <mediaobject>
3029             <imageobject>
3030               <imagedata fileref="images/skr04-update-3804/steuer3804.png"/>
3031             </imageobject>
3032           </mediaobject>
3033         </screenshot>
3034
3035         <para>Als Nächstes sind alle Konten anzupassen, die als
3036         Steuerautomatikkonto die 3803 haben, sodass sie ab dem 1.1.2007 auch
3037         Steuerautomatik auf 3804 bekommen. Dies betrifft in der
3038         Standardkonfiguration die Konten 4315 und 4726. Als Beispiel für 4315
3039         müssen Sie dazu unter <guimenu>System</guimenu> →
3040         <guisubmenu>Kontenübersicht</guisubmenu> → <guimenuitem>Konten
3041         anzeigen</guimenuitem> das Konto 4315 anklicken und die Einstellungen
3042         wie im Screenshot gezeigt vornehmen.</para>
3043
3044         <screenshot>
3045           <screeninfo>Konto 4315 anpassen</screeninfo>
3046
3047           <mediaobject>
3048             <imageobject>
3049               <imagedata fileref="images/skr04-update-3804/konto4315.png"/>
3050             </imageobject>
3051           </mediaobject>
3052         </screenshot>
3053
3054         <para>Als Letztes sollte die Steuerliste unter
3055         <guimenu>System</guimenu> → <guisubmenu>Steuern</guisubmenu> →
3056         <guimenuitem>Bearbeiten</guimenuitem> kontrolliert werden. Zum
3057         Vergleich der Screenshot.</para>
3058
3059         <screenshot>
3060           <screeninfo>Steuerliste vergleichen</screeninfo>
3061
3062           <mediaobject>
3063             <imageobject>
3064               <imagedata fileref="images/skr04-update-3804/steuerliste.png"/>
3065             </imageobject>
3066           </mediaobject>
3067         </screenshot>
3068       </sect2>
3069     </sect1>
3070
3071     <sect1 id="config.bilanz">
3072       <title>Verhalten des Bilanzberichts</title>
3073
3074       <para>Bis Version 3.0 wurde "closedto" ("Bücher schließen zum") als
3075       Grundlage für das Startdatum benutzt. Schließt man die Bücher allerdings
3076       monatsweise führt dies zu falschen Werten.</para>
3077
3078       <para>In der Mandantenkonfiguration kann man dieses Verhalten genau
3079       einstellen indem man:</para>
3080
3081       <itemizedlist>
3082         <listitem>
3083           <para>weiterhin closed_to benutzt (Default, es ändert sich nichts zu
3084           vorher)</para>
3085         </listitem>
3086
3087         <listitem>
3088           <para>immer den Jahresanfang nimmt (1.1. relativ zum
3089           Stichtag)</para>
3090         </listitem>
3091
3092         <listitem>
3093           <para>immer die letzte Eröffnungsbuchung als Startdatum nimmt</para>
3094
3095           <para>- mit Jahresanfang als Alternative wenn es keine EB-Buchungen
3096           gibt</para>
3097
3098           <para>- oder mit "alle Buchungen" als Alternative"</para>
3099         </listitem>
3100
3101         <listitem>
3102           <para>mit Jahresanfang als Alternative wenn es keine EB-Buchungen
3103           gibt</para>
3104         </listitem>
3105
3106         <listitem>
3107           <para>immer alle Buchungen seit Beginn der Datenbank nimmt</para>
3108         </listitem>
3109       </itemizedlist>
3110
3111       <para>Folgende Hinweise zu den Optionen: Das "Bücher schließen Datum"
3112       ist sinnvoll, wenn man nur komplette Jahre schließt. Bei Wirtschaftsjahr
3113       = Kalendarjahr entspricht dies aber auch dem Jahresanfang. "Alle
3114       Buchungen" kann z.B. sinnvoll sein wenn man ohne Jahresabschluß
3115       durchbucht. Eröffnungsbuchung mit "alle Buchungen" als Fallback ist z.B.
3116       sinnvoll, wenn man am sich Anfang des zweiten Buchungsjahres befindet,
3117       und noch keinen Jahreswechsel und auch noch keine EB-Buchungen hat. Bei
3118       den Optionen mit EB-Buchungen wird vorausgesetzt, daß diese immer am 1.
3119       Tag des Wirtschaftsjahres gebucht werden. Zur Sicherheit wird das
3120       Startdatum im Bilanzbericht jetzt zusätzlich zum Stichtag mit angezeigt.
3121       Das hilft auch bei der Kontrolle für den Abgleich mit der GuV bzw.
3122       Erfolgsrechnung.</para>
3123     </sect1>
3124
3125     <sect1 id="config.erfolgsrechnung">
3126       <title>Erfolgsrechnung</title>
3127
3128       <para>Seit der Version 3.4.1 existiert in kivitendo der Bericht
3129       <emphasis role="bold"> Erfolgsrechnung</emphasis>.</para>
3130
3131       <para>Die Erfolgsrechnung kann in der Mandantenkonfiguration unter
3132       Features an- oder abgeschaltet werden. Mit der Einstellung
3133       <varname>default_manager = swiss </varname> in der
3134       <filename>config/kivitendo.conf</filename> wird beim neu Erstellen einer
3135       Datenbank automatisch die Anzeige der Erfolgsrechnung im Menü
3136       <guimenu>Berichte </guimenu> ausgewählt und ersetzt dort die GUV.</para>
3137
3138       <para>Im Gegensatz zur GUV werden bei der Erfolgsrechnung sämtliche
3139       Aufwands- und Erlöskonten einzeln aufgelistet (analog zur Bilanz),
3140       sortiert nach ERTRAG und AUFWAND.</para>
3141
3142       <para>Bei den Konteneinstellungen muss bei jedem Konto, das in der
3143       Erfolgsrechnung erscheinen soll, unter <varname>Sonstige
3144       Einstellungen/Erfolgsrechnung</varname> entweder
3145       <literal>01.Ertrag</literal> oder <literal>06.Aufwand</literal>
3146       ausgewählt werden.</para>
3147
3148       <para>Wird bei einem Erlöskonto <literal>06.Aufwand</literal>
3149       ausgewählt, so wird dieses Konto als Aufwandsminderung unter AUFWAND
3150       aufgelistet.</para>
3151
3152       <para>Wird bei einem Aufwandskonto <literal>01.Ertrag</literal>
3153       ausgewählt, so wird dieses Konto als Ertragsminderung unter ERTRAG
3154       aufgelistet.</para>
3155
3156       <para>Soll bei einer bereits bestehenden Buchhaltung in Zukunft
3157       zusätzlich die Erfolgsrechnung als Bericht verwendet werden, so müssen
3158       die Einstellungen zu allen Erlös- und Aufwandskonten unter
3159       <varname>Sonstige Einstellungen/Erfolgsrechnung</varname> überprüft und
3160       allenfalls neu gesetzt werden.</para>
3161     </sect1>
3162
3163     <sect1 id="config.rounding">
3164       <title>Rundung in Verkaufsbelegen</title>
3165
3166       <para>In der Schweiz hat die kleinste aktuell benutzte Münze den Wert
3167       von 5 Rappen (0.05 CHF).</para>
3168
3169       <para>Auch wenn im elektronischen Zahlungsverkehr Beträge mit einer
3170       Genauigkeit von 0.01 CHF verwendet werden können, ist es trotzdem nach
3171       wie vor üblich, Rechnungen mit auf 0.05 CHF gerundeten Beträgen
3172       auszustellen.</para>
3173
3174       <para>In kivitendo kann seit der Version 3.4.1 die Einstellung für eine
3175       solche Rundung pro Mandant / Datenbank festgelegt werden.</para>
3176
3177       <para>Die Einstellung wird beim Erstellen der Datenbank bei
3178       <literal>Genauigkeit</literal> festgelegt. Sie kann anschliessend über
3179       das Webinterface von kivitendo nicht mehr verändert werden.</para>
3180
3181       <para>Abhängig vom Wert für <varname>default_manager</varname> in
3182       <filename>config/kivitendo.conf</filename> werden dabei folgende Werte
3183       voreingestellt:</para>
3184
3185       <itemizedlist>
3186         <listitem>
3187           <para>0.05 (default_manager = swiss)</para>
3188         </listitem>
3189
3190         <listitem>
3191           <para>0.01 (default_manager = german)</para>
3192         </listitem>
3193       </itemizedlist>
3194
3195       <para>Der Wert wird in der Datenbank in der Tabelle <varname>defaults
3196       </varname>in der Spalte <varname>precision</varname> gespeichert.</para>
3197
3198       <para>In allen Verkaufsangeboten, Verkaufsaufträgen, Verkaufsrechnungen
3199       und Verkaufsgutschriften wird der Endbetrag inkl. MWST gerundet, wenn
3200       dieser nicht der eingestellten Genauigkeit entspricht.</para>
3201
3202       <para>Beim Buchen einer Verkaufsrechnung wird der Rundungsbetrag
3203       automatisch auf die in der Mandantenkonfiguration festgelegten
3204       Standardkonten für Rundungserträge bzw. Rundungsaufwendungen
3205       gebucht.</para>
3206
3207       <para>(Die berechnete MWST wird durch den Rundungsbetrag nicht mehr
3208       verändert.)</para>
3209
3210       <para>Die in den Druckvorlagen zur Verfügung stehenden Variablen
3211       <varname>quototal</varname>, <varname>ordtotal</varname> bzw.
3212       <varname>invtotal</varname> enthalten den gerundeten Betrag.</para>
3213
3214       <para><emphasis role="bold">Achtung:</emphasis> Werden Verkaufsbelege in
3215       anderen Währungen als der Standardwährung erstellt, so muss in kivitendo
3216       ab Version 3.4.1 die Genauigkeit 0.01 verwendet werden.</para>
3217
3218       <para>Das heisst, Firmen in der Schweiz, die teilweise
3219       Verkaufsrechnungen in Euro oder anderen Währungen erstellen wollen,
3220       müssen beim Erstellen der Datenbank als Genauigkeit 0.01 wählen und
3221       können zur Zeit die 5er Rundung noch nicht nutzen.</para>
3222     </sect1>
3223
3224     <sect1 id="config.client">
3225       <title>Einstellungen pro Mandant</title>
3226
3227       <para>Einige Einstellungen können von einem Benutzer mit dem <link
3228       linkend="Zusammenhänge">Recht</link> "Administration (Für die Verwaltung
3229       der aktuellen Instanz aus einem Userlogin heraus)" gemacht werden. Diese
3230       Einstellungen sind dann für die aktuellen Mandanten-Datenbank gültig.
3231       Die Einstellungen sind unter <guimenu>System</guimenu> →
3232       <guisubmenu>Mandantenkonfiguration</guisubmenu> erreichbar.</para>
3233
3234       <para>Bitte beachten Sie die Hinweise zu den einzelnen Einstellungen.
3235       Einige Einstellungen sollten nicht ohne Weiteres im laufenden Betrieb
3236       geändert werden (siehe auch <link
3237       linkend="config.eur.inventory-system-perpetual">Bemerkungen zu
3238       Bestandsmethode</link>).</para>
3239
3240       <para>Die Einstellungen <literal>show_bestbefore</literal> und
3241       <literal>payments_changeable</literal> aus dem Abschnitt
3242       <literal>features</literal> und die Einstellungen im Abschnitt
3243       <literal>datev_check</literal> (sofern schon vorhanden) der <link
3244       linkend="config.config-file">kivitendo-Konfigurationsdatei</link> werden
3245       bei einem Datenbankupdate einer älteren Version automatisch übernommen.
3246       Diese Einträge können danach aus der Konfigurationsdatei entfernt
3247       werden.</para>
3248     </sect1>
3249
3250     <sect1 id="kivitendo-ERP-verwenden">
3251       <title>kivitendo ERP verwenden</title>
3252
3253       <para>Nach erfolgreicher Installation ist der Loginbildschirm unter
3254       folgender URL erreichbar:</para>
3255
3256       <para><ulink
3257       url="http://localhost/kivitendo-erp/login.pl">http://localhost/kivitendo-erp/login.pl</ulink></para>
3258
3259       <para>Die Administrationsseite erreichen Sie unter:</para>
3260
3261       <para><ulink
3262       url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
3263     </sect1>
3264   </chapter>
3265
3266   <chapter id="features" xreflabel="Features und Funktionen">
3267     <title>Features und Funktionen</title>
3268
3269     <sect1 id="features.periodic-invoices"
3270            xreflabel="Wiederkehrende Rechnungen">
3271       <title>Wiederkehrende Rechnungen</title>
3272
3273       <sect2 id="features.periodic-invoices.introduction"
3274              xreflabel="Einführung in wiederkehrende Rechnungen">
3275         <title>Einführung</title>
3276
3277         <para>Wiederkehrende Rechnungen werden als normale Aufträge definiert
3278         und konfiguriert, mit allen dazugehörigen Kunden- und Artikelangaben.
3279         Die konfigurierten Aufträge werden später automatisch in Rechnungen
3280         umgewandelt, so als ob man den Workflow benutzen würde, und auch die
3281         Auftragsnummer wird übernommen, sodass alle wiederkehrenden
3282         Rechnungen, die aus einem Auftrag erstellt wurden, später leicht
3283         wiederzufinden sind.</para>
3284       </sect2>
3285
3286       <sect2 id="features.periodic-invoices.configuration"
3287              xreflabel="Konfiguration von wiederkehrenden Rechnungen">
3288         <title>Konfiguration</title>
3289
3290         <para>Um einen Auftrag für wiederkehrende Rechnung zu konfigurieren,
3291         findet sich beim Bearbeiten des Auftrags ein neuer Knopf
3292         "Konfigurieren", der ein neues Fenster öffnet, in dem man die nötigen
3293         Parameter einstellen kann. Hinter dem Knopf wird außerdem noch
3294         angezeigt, ob der Auftrag als wiederkehrende Rechnung konfiguriert ist
3295         oder nicht.</para>
3296
3297         <para>Folgende Parameter kann man konfigurieren:</para>
3298
3299         <variablelist>
3300           <varlistentry>
3301             <term>Status</term>
3302
3303             <listitem>
3304               <para>Bei aktiven Rechnungen wird automatisch eine Rechnung
3305               erstellt, wenn die Periodizität erreicht ist (z.B. am Anfang
3306               eines neuen Monats).</para>
3307
3308               <para>Ist ein Auftrag nicht aktiv, so werden für ihn auch keine
3309               wiederkehrenden Rechnungen erzeugt. Stellt man nach längerer
3310               nicht-aktiver Zeit einen Auftrag wieder auf aktiv, wird beim
3311               nächsten Periodenwechsel für alle Perioden, seit der letzten
3312               aktiven Periode, jeweils eine Rechnung erstellt. Möchte man dies
3313               verhindern, muss man vorher das Startdatum neu setzen.</para>
3314
3315               <para>Für gekündigte Aufträge werden nie mehr Rechnungen
3316               erstellt. Man kann sich diese Aufträge aber gesondert in den
3317               Berichten anzeigen lassen.</para>
3318             </listitem>
3319           </varlistentry>
3320
3321           <varlistentry>
3322             <term>Periodizität</term>
3323
3324             <listitem>
3325               <para>Ob monatlich, quartalsweise oder jährlich auf neue
3326               Rechnungen überprüft werden soll. Für jede Periode seit dem
3327               Startdatum wird überprüft, ob für die Periode (beginnend immer
3328               mit dem ersten Tag der Periode) schon eine Rechnung erstellt
3329               wurde. Unter Umständen können bei einem Startdatum in der
3330               Vergangenheit gleich mehrere Rechnungen erstellt werden.</para>
3331             </listitem>
3332           </varlistentry>
3333
3334           <varlistentry>
3335             <term>Buchen auf</term>
3336
3337             <listitem>
3338               <para>Das Forderungskonto, in der Regel "Forderungen aus
3339               Lieferungen und Leistungen". Das Gegenkonto ergibt sich aus den
3340               Buchungsgruppen der betreffenden Waren.</para>
3341             </listitem>
3342           </varlistentry>
3343
3344           <varlistentry>
3345             <term>Startdatum</term>
3346
3347             <listitem>
3348               <para>ab welchem Datum auf Rechnungserstellung geprüft werden
3349               soll</para>
3350             </listitem>
3351           </varlistentry>
3352
3353           <varlistentry>
3354             <term>Enddatum</term>
3355
3356             <listitem>
3357               <para>ab wann keine Rechnungen mehr erstellt werden
3358               sollen</para>
3359             </listitem>
3360           </varlistentry>
3361
3362           <varlistentry>
3363             <term>Automatische Verlängerung um x Monate</term>
3364
3365             <listitem>
3366               <para>Sollen die wiederkehrenden Rechnungen bei Erreichen des
3367               eingetragenen Enddatums weiterhin erstellt werden, so kann man
3368               hier die Anzahl der Monate eingeben, um die das Enddatum
3369               automatisch nach hinten geschoben wird.</para>
3370             </listitem>
3371           </varlistentry>
3372
3373           <varlistentry>
3374             <term>Drucken</term>
3375
3376             <listitem>
3377               <para>Sind Drucker konfiguriert, so kann man sich die erstellten
3378               Rechnungen auch gleich ausdrucken lassen.</para>
3379             </listitem>
3380           </varlistentry>
3381         </variablelist>
3382
3383         <para>Nach Erstellung der Rechnungen kann eine E-Mail mit
3384         Informationen zu den erstellten Rechnungen verschickt werden.
3385         Konfiguriert wird dies in der <link
3386         linkend="config.config-file.sections-parameters">Konfigurationsdatei</link>
3387         <filename>config/kivitendo.conf</filename> im Abschnitt
3388         <varname>[periodic_invoices]</varname>.</para>
3389       </sect2>
3390
3391       <sect2 id="features.periodic-invoices.variables">
3392         <title>Spezielle Variablen</title>
3393
3394         <para>Um die erzeugten Rechnungen individualisieren zu können, werden
3395         beim Umwandeln des Auftrags in eine Rechnung einige speziell
3396         formatierte Variablen durch für die jeweils aktuelle
3397         Abrechnungsperiode gültigen Werte ersetzt. Damit ist es möglich, z.B.
3398         den Abrechnungszeitraum explizit auszuweisen. Eine Variable hat dabei
3399         die Syntax <literal>&lt;%variablenname%&gt;</literal>.</para>
3400
3401         <para>Sofern es sich um eine Datumsvariable handelt, kann das
3402         Ausgabeformat weiter bestimmt werden, indem an den Variablennamen
3403         Formatoptionen angehängt werden. Die Syntax sieht dabei wie folgt aus:
3404         <literal>&lt;%variablenname FORMAT=Formatinformation%&gt;</literal>.
3405         Die zur verfügung stehenden Formatinformationen werden unten genauer
3406         beschrieben.</para>
3407
3408         <para>Diese Variablen können auch beim automatischen Versand der
3409         erzeugten Rechnungen per E-Mail genutzt werden, indem sie in den
3410         Feldern für den Betreff oder die Nachricht verwendet werden.</para>
3411
3412         <para>Diese Variablen werden in den folgenden Elementen des Auftrags
3413         ersetzt:</para>
3414
3415         <itemizedlist>
3416           <listitem>
3417             <para>Bemerkungen</para>
3418           </listitem>
3419
3420           <listitem>
3421             <para>Interne Bemerkungen</para>
3422           </listitem>
3423
3424           <listitem>
3425             <para>Vorgangsbezeichnung</para>
3426           </listitem>
3427
3428           <listitem>
3429             <para>In den Beschreibungs- und Langtextfeldern aller
3430             Positionen</para>
3431           </listitem>
3432         </itemizedlist>
3433
3434         <para>Die zur Verfügung stehenden Variablen sind die Folgenden:</para>
3435
3436         <variablelist>
3437           <varlistentry>
3438             <term><varname>&lt;%current_quarter%&gt;</varname>,
3439             <varname>&lt;%previous_quarter%&gt;</varname>,
3440             <varname>&lt;%next_quarter%&gt;</varname></term>
3441
3442             <listitem>
3443               <para>Aktuelles, vorheriges und nächstes Quartal als Zahl
3444               zwischen <literal>1</literal> und <literal>4</literal>.</para>
3445             </listitem>
3446           </varlistentry>
3447
3448           <varlistentry>
3449             <term><varname>&lt;%current_month%&gt;</varname>,
3450             <varname>&lt;%previous_month%&gt;</varname>,
3451             <varname>&lt;%next_month%&gt;</varname></term>
3452
3453             <listitem>
3454               <para>Aktueller, vorheriger und nächster Monat als Zahl zwischen
3455               <literal>1</literal> und <literal>12</literal>.</para>
3456             </listitem>
3457           </varlistentry>
3458
3459           <varlistentry>
3460             <term><varname>&lt;%current_month_long%&gt;</varname>,
3461             <varname>&lt;%previous_month_long%&gt;</varname>,
3462             <varname>&lt;%next_month_long%&gt;</varname></term>
3463
3464             <listitem>
3465               <para>Aktueller, vorheriger und nächster Monat als Name
3466               (<literal>Januar</literal>, <literal>Februar</literal>
3467               etc.).</para>
3468             </listitem>
3469           </varlistentry>
3470
3471           <varlistentry>
3472             <term><varname>&lt;%current_year%&gt;</varname>,
3473             <varname>&lt;%previous_year%&gt;</varname>,
3474             <varname>&lt;%next_year%&gt;</varname></term>
3475
3476             <listitem>
3477               <para>Aktuelles, vorheriges und nächstes Jahr als vierstellige
3478               Jahreszahl (<literal>2013</literal> etc.).</para>
3479             </listitem>
3480           </varlistentry>
3481
3482           <varlistentry>
3483             <term><varname>&lt;%period_start_date%&gt;</varname>,
3484             <varname>&lt;%period_end_date%&gt;</varname></term>
3485
3486             <listitem>
3487               <para>Formatiertes Datum des ersten und letzten Tages im
3488               Abrechnungszeitraum (z.B. bei quartalsweiser Abrechnung und im
3489               ersten Quartal von 2013 wären dies der
3490               <literal>01.01.2013</literal> und
3491               <literal>31.03.2013</literal>).</para>
3492             </listitem>
3493           </varlistentry>
3494         </variablelist>
3495
3496         <para>Die invidiuellen Formatinformationen bestehen aus Paaren von
3497         Prozentzeichen und einem Buchstaben, welche beide zusammen durch den
3498         dazugehörigen Wert ersetzt werden. So wird z.B. <literal>%Y</literal>
3499         durch das viertstellige Jahr ersetzt. Alle möglichen Platzhalter
3500         sind:</para>
3501
3502         <variablelist>
3503           <varlistentry>
3504             <term><varname>%a</varname></term>
3505
3506             <listitem>
3507               <para>Der abgekürzte Wochentagsname.</para>
3508             </listitem>
3509           </varlistentry>
3510
3511           <varlistentry>
3512             <term><varname>%A</varname></term>
3513
3514             <listitem>
3515               <para>Der ausgeschriebene Wochentagsname.</para>
3516             </listitem>
3517           </varlistentry>
3518
3519           <varlistentry>
3520             <term><varname>%b</varname></term>
3521
3522             <listitem>
3523               <para>Der abgekürzte Monatsname.</para>
3524             </listitem>
3525           </varlistentry>
3526
3527           <varlistentry>
3528             <term><varname>%B</varname></term>
3529
3530             <listitem>
3531               <para>Der ausgeschriebene Monatsname.</para>
3532             </listitem>
3533           </varlistentry>
3534
3535           <varlistentry>
3536             <term><varname>%C</varname></term>
3537
3538             <listitem>
3539               <para>Das Jahrhundert (Jahr/100) als eine zweistellige
3540               Zahl.</para>
3541             </listitem>
3542           </varlistentry>
3543
3544           <varlistentry>
3545             <term><varname>%d</varname></term>
3546
3547             <listitem>
3548               <para>Der Monatstag als Zahl zwischen 01 und 31.</para>
3549             </listitem>
3550           </varlistentry>
3551
3552           <varlistentry>
3553             <term><varname>%D</varname></term>
3554
3555             <listitem>
3556               <para>Entspricht %m/%d/%y (amerikanisches Datumsformat).</para>
3557             </listitem>
3558           </varlistentry>
3559
3560           <varlistentry>
3561             <term><varname>%e</varname></term>
3562
3563             <listitem>
3564               <para>Wie %d (Monatstag als Zahl zwischen 1 und 31), allerdings
3565               werden führende Nullen durch Leerzeichen ersetzt.</para>
3566             </listitem>
3567           </varlistentry>
3568
3569           <varlistentry>
3570             <term><varname>%F</varname></term>
3571
3572             <listitem>
3573               <para>Entspricht %Y-%m-%d (das ISO-8601-Datumsformat).</para>
3574             </listitem>
3575           </varlistentry>
3576
3577           <varlistentry>
3578             <term><varname>%j</varname></term>
3579
3580             <listitem>
3581               <para>Der Tag im Jahr als Zahl zwischen 001 und 366
3582               inklusive.</para>
3583             </listitem>
3584           </varlistentry>
3585
3586           <varlistentry>
3587             <term><varname>%m</varname></term>
3588
3589             <listitem>
3590               <para>Der Monat als Zahl zwischen 01 und 12 inklusive.</para>
3591             </listitem>
3592           </varlistentry>
3593
3594           <varlistentry>
3595             <term><varname>%u</varname></term>
3596
3597             <listitem>
3598               <para>Der Wochentag als Zahl zwischen 1 und 7 inklusive, wobei
3599               die 1 dem Montag entspricht.</para>
3600             </listitem>
3601           </varlistentry>
3602
3603           <varlistentry>
3604             <term><varname>%U</varname></term>
3605
3606             <listitem>
3607               <para>Die Wochennummer als Zahl zwischen 00 und 53 inklusive,
3608               wobei der erste Sonntag im Jahr das Startdatum von Woche 01
3609               ist.</para>
3610             </listitem>
3611           </varlistentry>
3612
3613           <varlistentry>
3614             <term><varname>%V</varname></term>
3615
3616             <listitem>
3617               <para>Die ISO-8601:1988-Wochennummer als Zahl zwischen 01 und 53
3618               inklusive, wobei Woche 01 die erste Woche, von der mindestens
3619               vier Tage im Jahr liegen; Montag ist erster Tag der
3620               Woche.</para>
3621             </listitem>
3622           </varlistentry>
3623
3624           <varlistentry>
3625             <term><varname>%w</varname></term>
3626
3627             <listitem>
3628               <para>Der Wochentag als Zahl zwischen 0 und 6 inklusive, wobei
3629               die 0 dem Sonntag entspricht.</para>
3630             </listitem>
3631           </varlistentry>
3632
3633           <varlistentry>
3634             <term><varname>%W</varname></term>
3635
3636             <listitem>
3637               <para>Die Wochennummer als Zahl zwischen 00 und 53 inklusive,
3638               wobei der erste Montag im Jahr das Startdatum von Woche 01
3639               ist.</para>
3640             </listitem>
3641           </varlistentry>
3642
3643           <varlistentry>
3644             <term><varname>%y</varname></term>
3645
3646             <listitem>
3647               <para>Das Jahr als zweistellige Zahl zwischen 00 und 99
3648               inklusive.</para>
3649             </listitem>
3650           </varlistentry>
3651
3652           <varlistentry>
3653             <term><varname>%Y</varname></term>
3654
3655             <listitem>
3656               <para>Das Jahr als vierstellige Zahl.</para>
3657             </listitem>
3658           </varlistentry>
3659
3660           <varlistentry>
3661             <term><varname>%%</varname></term>
3662
3663             <listitem>
3664               <para>Das Prozentzeichen selber.</para>
3665             </listitem>
3666           </varlistentry>
3667         </variablelist>
3668
3669         <para>Anwendungsbeispiel für die Ausgabe, von welchem Monat und Jahr
3670         bis zu welchem Monat und Jahr die aktuelle Abrechnungsperiode dauert:
3671         <literal>Abrechnungszeitrum: &lt;%period_start_date FORMAT=%m/%Y%&gt;
3672         bis &lt;%period_end_date FORMAT=%m/%Y%&gt;</literal></para>
3673       </sect2>
3674
3675       <sect2 id="features.periodic-invoices.reports">
3676         <title>Auflisten</title>
3677
3678         <para>Unter Verkauf-&gt;Berichte-&gt;Aufträge finden sich zwei neue
3679         Checkboxen, "Wiederkehrende Rechnungen aktiv" und "Wiederkehrende
3680         Rechnungen inaktiv", mit denen man sich einen Überglick über die
3681         wiederkehrenden Rechnungen verschaffen kann.</para>
3682       </sect2>
3683
3684       <sect2 id="features.periodic-invoices.task-server">
3685         <title>Erzeugung der eigentlichen Rechnungen</title>
3686
3687         <para>Die zeitliche und periodische Überprüfung, ob eine
3688         wiederkehrende Rechnung automatisch erstellt werden soll, geschieht
3689         durch den <link linkend="config.task-server">Task-Server</link>, einen
3690         externen Dienst, der automatisch beim Start des Servers gestartet
3691         werden sollte.</para>
3692       </sect2>
3693
3694       <sect2 id="features.periodic-invoices.create-for-current-month">
3695         <title>Erste Rechnung für aktuellen Monat erstellen</title>
3696
3697         <para>Will man im laufenden Monat eine monatlich wiederkehrende
3698         Rechnung inkl. des laufenden Monats starten, stellt man das Startdatum
3699         auf den Monatsanfang und wartet ein paar Minuten, bis der Task-Server
3700         den neu konfigurieren Auftrag erkennt und daraus eine Rechnung
3701         generiert hat. Alternativ setzt man das Startdatum auf den
3702         Monatsersten des Folgemonats und erstellt die erste Rechnung direkt
3703         manuell über den Workflow.</para>
3704       </sect2>
3705     </sect1>
3706
3707     <sect1 id="features.bank" xreflabel="bankerweiterung">
3708       <title>Bankerweiterung</title>
3709
3710       <sect2 id="features.bank.introduction"
3711              xreflabel="Einführung in die Bankerweiterung">
3712         <title>Einführung</title>
3713
3714         <para>Die Beschreibung der Bankerweiterung befindet sich derzeit noch
3715         im Wiki und soll von dort später hierhin übernommen werden:</para>
3716
3717         <para><ulink
3718         url="http://redmine.kivitendo-premium.de/projects/forum/wiki/Bankerweiterung">http://redmine.kivitendo-premium.de/projects/forum/wiki/Bankerweiterung</ulink></para>
3719       </sect2>
3720     </sect1>
3721
3722     <sect1 id="dokumentenvorlagen-und-variablen">
3723       <title>Dokumentenvorlagen und verfügbare Variablen</title>
3724
3725       <sect2 id="dokumentenvorlagen-und-variablen.einführung">
3726         <title>Einführung</title>
3727
3728         <para>Dies ist eine Auflistung der Standard-Dokumentenvorlagen und
3729         aller zur Bearbeitung verfügbaren Variablen. Eine Variable wird in
3730         einer Vorlage durch ihren Inhalt ersetzt, wenn sie in der Form
3731         <function>&lt;%variablenname%&gt;</function> verwendet wird. Für
3732         LaTeX- und HTML-Vorlagen kann man die Form dieser Tags auch verändern
3733         (siehe <xref
3734         linkend="dokumentenvorlagen-und-variablen.tag-style"/>).</para>
3735
3736         <para>kivitendo unterstützt LaTeX-, HTML- und OpenDocument-Vorlagen.
3737         Sofern es nicht ausdrücklich eingeschränkt wird, gilt das im Folgenden
3738         gesagte für alle Vorlagenarten.</para>
3739
3740         <para>Insgesamt sind technisch gesehen eine ganze Menge mehr Variablen
3741         verfügbar als hier aufgelistet werden. Die meisten davon können
3742         allerdings innerhalb einer solchen Vorlage nicht sinnvoll verwendet
3743         werden. Wenn eine Auflistung dieser Variablen gewollt ist, so kann
3744         diese wie folgt erhalten werden:</para>
3745
3746         <itemizedlist>
3747           <listitem>
3748             <para><filename>SL/Form.pm</filename> öffnen und am Anfang die
3749             Zeile "<command>use Data::Dumper;</command>" einfügen.</para>
3750           </listitem>
3751
3752           <listitem>
3753             <para>In <filename>Form.pm</filename> die Funktion
3754             <function>parse_template</function> suchen und hier die Zeile
3755             <command>print(STDERR Dumper($self));</command> einfügen.</para>
3756           </listitem>
3757
3758           <listitem>
3759             <para>Einmal per Browser die gewünschte Vorlage "benutzen", z.B.
3760             ein PDF für eine Rechnung erzeugen.</para>
3761           </listitem>
3762
3763           <listitem>
3764             <para>Im <filename>error.log</filename> Apache steht die Ausgabe
3765             der Variablen <varname>$self</varname> in der Form <varname>'key'
3766             =&gt; 'value',</varname>. Alle <varname>key</varname>s sind
3767             verfügbar.</para>
3768           </listitem>
3769         </itemizedlist>
3770       </sect2>
3771
3772       <sect2 id="dokumentenvorlagen-und-variablen.variablen-ausgeben">
3773         <title>Variablen ausgeben</title>
3774
3775         <para>Um eine Variable auszugeben, müssen sie einfach nur zwischen die
3776         Tags geschrieben werden, also z.B.
3777         <varname>&lt;%variablenname%&gt;</varname>.</para>
3778
3779         <para>Optional kann man auch mit Leerzeichen getrennte Flags angeben,
3780         die man aber nur selten brauchen wird. Die Syntax sieht also so aus:
3781         <varname>&lt;%variablenname FLAG1 FLAG2%&gt;</varname>. Momentan
3782         werden die folgenden Flags unterstützt:</para>
3783
3784         <itemizedlist>
3785           <listitem>
3786             <para><option>NOFORMAT</option> gilt nur für Zahlenwerte und gibt
3787             den Wert ohne Formatierung, also ohne Tausendertrennzeichen mit
3788             mit einem Punkt als Dezimaltrennzeichen aus. Nützlich z.B., wenn
3789             damit in der Vorlage z.B. von LaTeX gerechnet werden soll.</para>
3790           </listitem>
3791
3792           <listitem>
3793             <para><option>NOESCAPE</option> unterdrückt das Escapen von
3794             Sonderzeichen für die Vorlagensprache. Wenn also in einer
3795             Variablen bereits gültiger LaTeX-Code steht und dieser von LaTeX
3796             auch ausgewertet und nicht wortwörtlich angezeigt werden soll, so
3797             ist dieses Flag sinnvoll.</para>
3798           </listitem>
3799         </itemizedlist>
3800
3801         <para>Beispiel:</para>
3802
3803         <programlisting>&lt;%quototal NOFORMAT%&gt;</programlisting>
3804       </sect2>
3805
3806       <sect2 id="dokumentenvorlagen-und-variablen.verwendung-in-druckbefehlen">
3807         <title>Verwendung in Druckbefehlen</title>
3808
3809         <para>In der Admininstration können Drucker definiert werden. Auch im
3810         dort eingebbaren Druckbefehl können die hier aufgelisteten Variablen
3811         und Kontrollstrukturen verwendet werden. Ihr Inhalt wird dabei nach
3812         den Regeln der gängigen Shells formatiert, sodass Sonderzeichen wie
3813         <function>`...`</function> nicht zu unerwünschtem Verhalten
3814         führen.</para>
3815
3816         <para>Dies erlaubt z.B. die Definition eines Faxes als Druckerbefehl,
3817         für das die Telefonnummer eines Ansprechpartners als Teil der
3818         Kommandozeile verwendet wird. Für ein fiktives Kommando könnte das
3819         z.B. wie folgt aussehen:</para>
3820
3821         <programlisting>send_fax --number &lt;%if cp_phone2%&gt;&lt;%cp_phone2%&gt;&lt;%else%&gt;&lt;%cp_phone1%&gt;&lt;%end%&gt;</programlisting>
3822       </sect2>
3823
3824       <sect2 id="dokumentenvorlagen-und-variablen.tag-style"
3825              xreflabel="Anfang und Ende der Tags verändern">
3826         <title>Anfang und Ende der Tags verändern</title>
3827
3828         <para>Der Standardstil für Tags sieht vor, dass ein Tag mit dem
3829         Kleinerzeichen und einem Prozentzeichen beginnt und mit dem
3830         Prozentzeichen und dem Größerzeichen endet, beispielsweise
3831         <function>&lt;%customer%&gt;</function>. Da diese Form aber z.B. in
3832         LaTeX zu Problemen führen kann, weil das Prozentzeichen dort
3833         Kommentare einleitet, kann pro HTML- oder LaTeX-Dokumentenvorlage der
3834         Stil umgestellt werden.</para>
3835
3836         <para>Dazu werden in die Datei Zeilen geschrieben, die mit dem für das
3837         Format gültigen Kommentarzeichen anfangen, dann
3838         <function>config:</function> enthalten, die entsprechende Option
3839         setzen und bei HTML-Dokumentenvorlagen mit dem Kommentarendzeichen
3840         enden. Beispiel für LaTeX:</para>
3841
3842         <programlisting>% config: tag-style=($ $)</programlisting>
3843
3844         <para>Dies würde kivitendo dazu veranlassen, Variablen zu ersetzen,
3845         wenn sie wie folgt aussehen: <function>($customer$)</function>. Das
3846         äquivalente Beispiel für HTML-Dokumentenvorlagen sieht so aus:</para>
3847
3848         <programlisting>&lt;!-- config: tag-style=($ $) --&gt;</programlisting>
3849       </sect2>
3850
3851       <sect2 id="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">
3852         <title>Zuordnung von den Dateinamen zu den Funktionen</title>
3853
3854         <para>Diese folgende kurze Auflistung zeigt, welche Vorlage bei
3855         welcher Funktion ausgelesen wird. Dabei ist die Dateiendung
3856         "<filename>.ext</filename>" geeignet zu ersetzen:
3857         "<filename>.tex</filename>" für LaTeX-Vorlagen und
3858         "<filename>.odt</filename>" für OpenDocument-Vorlagen.</para>
3859
3860         <variablelist>
3861           <varlistentry>
3862             <term><filename>bin_list.ext</filename></term>
3863
3864             <listitem>
3865               <para>Lagerliste</para>
3866             </listitem>
3867           </varlistentry>
3868
3869           <varlistentry>
3870             <term><filename>check.ext</filename></term>
3871
3872             <listitem>
3873               <para>?</para>
3874             </listitem>
3875           </varlistentry>
3876
3877           <varlistentry>
3878             <term><filename>invoice.ext</filename></term>
3879
3880             <listitem>
3881               <para>Rechnung</para>
3882             </listitem>
3883           </varlistentry>
3884
3885           <varlistentry>
3886             <term><filename>packing_list.ext</filename></term>
3887
3888             <listitem>
3889               <para>Packliste</para>
3890             </listitem>
3891           </varlistentry>
3892
3893           <varlistentry>
3894             <term><filename>pick_list.ext</filename></term>
3895
3896             <listitem>
3897               <para>Sammelliste</para>
3898             </listitem>
3899           </varlistentry>
3900
3901           <varlistentry>
3902             <term><filename>purchase_delivery_order.ext</filename></term>
3903
3904             <listitem>
3905               <para>Lieferschein (Einkauf)</para>
3906             </listitem>
3907           </varlistentry>
3908
3909           <varlistentry>
3910             <term><filename>purcharse_order.ext</filename></term>
3911
3912             <listitem>
3913               <para>Bestellung an Lieferanten</para>
3914             </listitem>
3915           </varlistentry>
3916
3917           <varlistentry>
3918             <term><filename>request_quotation.ext</filename></term>
3919
3920             <listitem>
3921               <para>Anfrage an Lieferanten</para>
3922             </listitem>
3923           </varlistentry>
3924
3925           <varlistentry>
3926             <term><filename>sales_delivery_order.ext</filename></term>
3927
3928             <listitem>
3929               <para>Lieferschein (Verkauf)</para>
3930             </listitem>
3931           </varlistentry>
3932
3933           <varlistentry>
3934             <term><filename>sales_order.ext</filename></term>
3935
3936             <listitem>
3937               <para>Bestellung</para>
3938             </listitem>
3939           </varlistentry>
3940
3941           <varlistentry>
3942             <term><filename>sales_quotation.ext</filename></term>
3943
3944             <listitem>
3945               <para>Angebot an Kunden</para>
3946             </listitem>
3947           </varlistentry>
3948
3949           <varlistentry>
3950             <term><filename>zahlungserinnerung.ext</filename></term>
3951
3952             <listitem>
3953               <para>Mahnung (Dateiname im Programm konfigurierbar)</para>
3954             </listitem>
3955           </varlistentry>
3956
3957           <varlistentry>
3958             <term><filename>zahlungserinnerung_invoice.ext</filename></term>
3959
3960             <listitem>
3961               <para>Rechnung über Mahngebühren (Dateiname im Programm
3962               konfigurierbar)</para>
3963             </listitem>
3964           </varlistentry>
3965         </variablelist>
3966       </sect2>
3967
3968       <sect2 id="dokumentenvorlagen-und-variablen.dateinamen-erweitert">
3969         <title>Sprache, Drucker und E-Mail</title>
3970
3971         <para>Angeforderte Sprache und Druckerkürzel in den Dateinamen mit
3972         eingearbeitet. So wird aus der Vorlage
3973         <filename>sales_order.ext</filename> bei Sprache
3974         <function>de</function> und Druckerkürzel <function>lpr2</function>
3975         der Vorlagenname <filename>sales_order_de_lpr2.ext</filename>.
3976         Zusätzlich können für E-Mails andere Vorlagen erstellt werden, diese
3977         bekommen dann noch das Kürzel <filename>_email</filename>, der
3978         vollständige Vorlagenname wäre dann
3979         <filename>sales_order_email_de_lpr2.ext</filename>. In allen Fällen
3980         kann eine Standarddatei <filename>default.ext</filename> hinterlegt
3981         werden. Diese wird verwendet, wenn keine der anderen Varianten
3982         gefunden wird.</para>
3983
3984         <para>Die vollständige Suchreihenfolge für einen Verkaufsauftrag mit
3985         der Sprache "de" und dem Drucker "lpr2", der per E-Mail im Format PDF
3986         verschickt wird, ist:</para>
3987
3988         <orderedlist>
3989           <listitem>
3990             <para><filename>sales_order_email_de_lpr2.tex</filename></para>
3991           </listitem>
3992
3993           <listitem>
3994             <para><filename>sales_order_de_lpr2.tex</filename></para>
3995           </listitem>
3996
3997           <listitem>
3998             <para><filename>sales_order.tex</filename></para>
3999           </listitem>
4000
4001           <listitem>
4002             <para><filename>default.tex</filename></para>
4003           </listitem>
4004         </orderedlist>
4005
4006         <para>Die kurzen Varianten dieser Vorlagentitel müssen dann entweder
4007         Standardwerte anzeigen, oder die angeforderten Werte selbst auswerten,
4008         siehe dazu <xref
4009         linkend="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta"/>.</para>
4010       </sect2>
4011
4012       <sect2 id="dokumentenvorlagen-und-variablen.allgemeine-variablen">
4013         <title>Allgemeine Variablen, die in allen Vorlagen vorhanden
4014         sind</title>
4015
4016         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta"
4017                xreflabel="Metainformationen zur angeforderten Vorlage">
4018           <title>Metainformationen zur angeforderten Vorlage</title>
4019
4020           <para>Diese Variablen liefern Informationen darüber welche Variante
4021           einer Vorlage der Benutzer angefragt hat. Sie sind nützlich für
4022           Vorlagenautoren, die aus einer zentralen Layoutvorlage die einzelnen
4023           Formulare einbinden möchten.</para>
4024
4025           <variablelist>
4026             <varlistentry>
4027               <term><varname>template_meta.formname</varname></term>
4028
4029               <listitem>
4030                 <para>Basisname der Vorlage. Identisch mit der <link
4031                 linkend="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">Zurordnung
4032                 zu den Dateinamen</link> ohne die Erweiterung. Ein
4033                 Verkaufsauftrag enthält hier
4034                 <constant>sales_order</constant>.</para>
4035               </listitem>
4036             </varlistentry>
4037
4038             <varlistentry>
4039               <term><varname>template_meta.language.description</varname></term>
4040
4041               <listitem>
4042                 <para>Beschreibung der verwendeten Sprache</para>
4043               </listitem>
4044             </varlistentry>
4045
4046             <varlistentry>
4047               <term><varname>template_meta.language.template_code</varname></term>
4048
4049               <listitem>
4050                 <para>Vorlagenkürzel der verwendeten Sprache, identisch mit
4051                 dem Kürzel das im Dateinamen verwendetet wird.</para>
4052               </listitem>
4053             </varlistentry>
4054
4055             <varlistentry>
4056               <term><varname>template_meta.language.output_numberformat</varname></term>
4057
4058               <listitem>
4059                 <para>Zahlenformat der verwendeten Sprache in der Form
4060                 "<constant>1.000,00</constant>". Experimentell! Nur
4061                 interessant für Vorlagen die mit unformatierten Werten
4062                 arbeiten.</para>
4063               </listitem>
4064             </varlistentry>
4065
4066             <varlistentry>
4067               <term><varname>template_meta.language.output_dateformat</varname></term>
4068
4069               <listitem>
4070                 <para>Datumsformat der verwendeten Sprache in der Form
4071                 "<constant>dd.mm.yyyy</constant>". Experimentell! Nur
4072                 interessant für Vorlagen die mit unformatierten Werten
4073                 arbeiten.</para>
4074               </listitem>
4075             </varlistentry>
4076
4077             <varlistentry>
4078               <term><varname>template_meta.format</varname></term>
4079
4080               <listitem>
4081                 <para>Das angeforderte Format. Kann im Moment die Werte
4082                 <constant>pdf</constant>, <constant>postscript</constant>,
4083                 <constant>html</constant>, <constant>opendocument</constant>,
4084                 <constant>opendocument_pdf</constant> und
4085                 <constant>excel</constant> enthalten.</para>
4086               </listitem>
4087             </varlistentry>
4088
4089             <varlistentry>
4090               <term><varname>template_meta.extension</varname></term>
4091
4092               <listitem>
4093                 <para>Dateierweiterung, wie im Dateinamen. Wird aus
4094                 <constant>format</constant> entschieden.</para>
4095               </listitem>
4096             </varlistentry>
4097
4098             <varlistentry>
4099               <term><varname>template_meta.media</varname></term>
4100
4101               <listitem>
4102                 <para>Ausgabemedium. Kann zur Zeit die Werte
4103                 <constant>screen</constant> für Bildschirm,
4104                 <constant>email</constant> für E-Mail (triggert das
4105                 <constant>_email</constant> Kürzel im Dateinamen),
4106                 <constant>printer</constant> für Drucker, und
4107                 <constant>queue</constant> für Warteschlange enthalten.</para>
4108               </listitem>
4109             </varlistentry>
4110
4111             <varlistentry>
4112               <term><varname>template_meta.printer.description</varname></term>
4113
4114               <listitem>
4115                 <para>Beschreibung des ausgewählten Druckers</para>
4116               </listitem>
4117             </varlistentry>
4118
4119             <varlistentry>
4120               <term><varname>template_meta.printer.template_code</varname></term>
4121
4122               <listitem>
4123                 <para>Vorlagenürzel des ausgewählten Druckers, identisch mit
4124                 dem Kürzel das im Dateinamen verwendetet wird.</para>
4125               </listitem>
4126             </varlistentry>
4127
4128             <varlistentry>
4129               <term><varname>template_meta.tmpfile</varname></term>
4130
4131               <listitem>
4132                 <para>Datei-Prefix für temporäre Dateien.</para>
4133               </listitem>
4134             </varlistentry>
4135           </variablelist>
4136         </sect3>
4137
4138         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.kunden-lieferanten">
4139           <title>Stammdaten von Kunden und Lieferanten</title>
4140
4141           <variablelist>
4142             <varlistentry>
4143               <term><varname>account_number</varname></term>
4144
4145               <listitem>
4146                 <para>Kontonummer</para>
4147               </listitem>
4148             </varlistentry>
4149
4150             <varlistentry>
4151               <term><varname>bank</varname></term>
4152
4153               <listitem>
4154                 <para>Name der Bank</para>
4155               </listitem>
4156             </varlistentry>
4157
4158             <varlistentry>
4159               <term><varname>bank_code</varname></term>
4160
4161               <listitem>
4162                 <para>Bankleitzahl</para>
4163               </listitem>
4164             </varlistentry>
4165
4166             <varlistentry>
4167               <term><varname>bic</varname></term>
4168
4169               <listitem>
4170                 <para>Bank-Identifikations-Code (Bank Identifier Code,
4171                 BIC)</para>
4172               </listitem>
4173             </varlistentry>
4174
4175             <varlistentry>
4176               <term><varname>business</varname></term>
4177
4178               <listitem>
4179                 <para>Kunden-/Lieferantentyp</para>
4180               </listitem>
4181             </varlistentry>
4182
4183             <varlistentry>
4184               <term><varname>city</varname></term>
4185
4186               <listitem>
4187                 <para>Stadt</para>
4188               </listitem>
4189             </varlistentry>
4190
4191             <varlistentry>
4192               <term><varname>contact</varname></term>
4193
4194               <listitem>
4195                 <para>Kontakt</para>
4196               </listitem>
4197             </varlistentry>
4198
4199             <varlistentry>
4200               <term><varname>country</varname></term>
4201
4202               <listitem>
4203                 <para>Land</para>
4204               </listitem>
4205             </varlistentry>
4206
4207             <varlistentry>
4208               <term><varname>c_vendor_id</varname></term>
4209
4210               <listitem>
4211                 <para>Lieferantennummer beim Kunden (nur Kunden)</para>
4212               </listitem>
4213             </varlistentry>
4214
4215             <varlistentry>
4216               <term><varname>v_customer_id</varname></term>
4217
4218               <listitem>
4219                 <para>Kundennummer beim Lieferanten (nur Lieferanten)</para>
4220               </listitem>
4221             </varlistentry>
4222
4223             <varlistentry>
4224               <term><varname>cp_email</varname></term>
4225
4226               <listitem>
4227                 <para>Email des Ansprechpartners</para>
4228               </listitem>
4229             </varlistentry>
4230
4231             <varlistentry>
4232               <term><varname>cp_givenname</varname></term>
4233
4234               <listitem>
4235                 <para>Vorname des Ansprechpartners</para>
4236               </listitem>
4237             </varlistentry>
4238
4239             <varlistentry>
4240               <term><varname>cp_greeting</varname></term>
4241
4242               <listitem>
4243                 <para>Anrede des Ansprechpartners</para>
4244               </listitem>
4245             </varlistentry>
4246
4247             <varlistentry>
4248               <term><varname>cp_name</varname></term>
4249
4250               <listitem>
4251                 <para>Name des Ansprechpartners</para>
4252               </listitem>
4253             </varlistentry>
4254
4255             <varlistentry>
4256               <term><varname>cp_phone1</varname></term>
4257
4258               <listitem>
4259                 <para>Telefonnummer 1 des Ansprechpartners</para>
4260               </listitem>
4261             </varlistentry>
4262
4263             <varlistentry>
4264               <term><varname>cp_phone2</varname></term>
4265
4266               <listitem>
4267                 <para>Telefonnummer 2 des Ansprechpartners</para>
4268               </listitem>
4269             </varlistentry>
4270
4271             <varlistentry>
4272               <term><varname>cp_title</varname></term>
4273
4274               <listitem>
4275                 <para>Titel des Ansprechpartners</para>
4276               </listitem>
4277             </varlistentry>
4278
4279             <varlistentry>
4280               <term><varname>creditlimit</varname></term>
4281
4282               <listitem>
4283                 <para>Kreditlimit</para>
4284               </listitem>
4285             </varlistentry>
4286
4287             <varlistentry>
4288               <term><varname>customeremail</varname></term>
4289
4290               <listitem>
4291                 <para>Email des Kunden; nur für Kunden</para>
4292               </listitem>
4293             </varlistentry>
4294
4295             <varlistentry>
4296               <term><varname>customerfax</varname></term>
4297
4298               <listitem>
4299                 <para>Faxnummer des Kunden; nur für Kunden</para>
4300               </listitem>
4301             </varlistentry>
4302
4303             <varlistentry>
4304               <term><varname>customernotes</varname></term>
4305
4306               <listitem>
4307                 <para>Bemerkungen beim Kunden; nur für Kunden</para>
4308               </listitem>
4309             </varlistentry>
4310
4311             <varlistentry>
4312               <term><varname>customernumber</varname></term>
4313
4314               <listitem>
4315                 <para>Kundennummer; nur für Kunden</para>
4316               </listitem>
4317             </varlistentry>
4318
4319             <varlistentry>
4320               <term><varname>customerphone</varname></term>
4321
4322               <listitem>
4323                 <para>Telefonnummer des Kunden; nur für Kunden</para>
4324               </listitem>
4325             </varlistentry>
4326
4327             <varlistentry>
4328               <term><varname>discount</varname></term>
4329
4330               <listitem>
4331                 <para>Rabatt</para>
4332               </listitem>
4333             </varlistentry>
4334
4335             <varlistentry>
4336               <term><varname>email</varname></term>
4337
4338               <listitem>
4339                 <para>Emailadresse</para>
4340               </listitem>
4341             </varlistentry>
4342
4343             <varlistentry>
4344               <term><varname>fax</varname></term>
4345
4346               <listitem>
4347                 <para>Faxnummer</para>
4348               </listitem>
4349             </varlistentry>
4350
4351             <varlistentry>
4352               <term><varname>gln</varname></term>
4353
4354               <listitem>
4355                 <para>GLN (Globale Lokationsnummer)</para>
4356               </listitem>
4357             </varlistentry>
4358
4359             <varlistentry>
4360               <term><varname>greeting</varname></term>
4361
4362               <listitem>
4363                 <para>Anrede</para>
4364               </listitem>
4365             </varlistentry>
4366
4367             <varlistentry>
4368               <term><varname>homepage</varname></term>
4369
4370               <listitem>
4371                 <para>Homepage</para>
4372               </listitem>
4373             </varlistentry>
4374
4375             <varlistentry>
4376               <term><varname>iban</varname></term>
4377
4378               <listitem>
4379                 <para>Internationale Kontonummer (International Bank Account
4380                 Number, IBAN)</para>
4381               </listitem>
4382             </varlistentry>
4383
4384             <varlistentry>
4385               <term><varname>language</varname></term>
4386
4387               <listitem>
4388                 <para>Sprache</para>
4389               </listitem>
4390             </varlistentry>
4391
4392             <varlistentry>
4393               <term><varname>name</varname></term>
4394
4395               <listitem>
4396                 <para>Firmenname</para>
4397               </listitem>
4398             </varlistentry>
4399
4400             <varlistentry>
4401               <term><varname>natural_person</varname></term>
4402
4403               <listitem>
4404                 <para>Flag "natürliche Person"; Siehe auch
4405                 <xref linkend="dokumentenvorlagen-und-variablen.anrede"/></para>
4406               </listitem>
4407             </varlistentry>
4408
4409             <varlistentry>
4410               <term><varname>payment_description</varname></term>
4411
4412               <listitem>
4413                 <para>Name der Zahlart</para>
4414               </listitem>
4415             </varlistentry>
4416
4417             <varlistentry>
4418               <term><varname>payment_terms</varname></term>
4419
4420               <listitem>
4421                 <para>Zahlungskonditionen</para>
4422               </listitem>
4423             </varlistentry>
4424
4425             <varlistentry>
4426               <term><varname>phone</varname></term>
4427
4428               <listitem>
4429                 <para>Telefonnummer</para>
4430               </listitem>
4431             </varlistentry>
4432
4433             <varlistentry>
4434               <term><varname>shiptocity</varname></term>
4435
4436               <listitem>
4437                 <para>Stadt (Lieferadresse) <link
4438                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4439               </listitem>
4440             </varlistentry>
4441
4442             <varlistentry>
4443               <term><varname>shiptocontact</varname></term>
4444
4445               <listitem>
4446                 <para>Kontakt (Lieferadresse) <link
4447                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4448               </listitem>
4449             </varlistentry>
4450
4451             <varlistentry>
4452               <term><varname>shiptocountry</varname></term>
4453
4454               <listitem>
4455                 <para>Land (Lieferadresse) <link
4456                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4457               </listitem>
4458             </varlistentry>
4459
4460             <varlistentry>
4461               <term><varname>shiptodepartment_1</varname></term>
4462
4463               <listitem>
4464                 <para>Abteilung 1 (Lieferadresse) <link
4465                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4466               </listitem>
4467             </varlistentry>
4468
4469             <varlistentry>
4470               <term><varname>shiptodepartment_2</varname></term>
4471
4472               <listitem>
4473                 <para>Abteilung 2 (Lieferadresse) <link
4474                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4475               </listitem>
4476             </varlistentry>
4477
4478             <varlistentry>
4479               <term><varname>shiptoemail</varname></term>
4480
4481               <listitem>
4482                 <para>Email (Lieferadresse) <link
4483                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4484               </listitem>
4485             </varlistentry>
4486
4487             <varlistentry>
4488               <term><varname>shiptofax</varname></term>
4489
4490               <listitem>
4491                 <para>Fax (Lieferadresse) <link
4492                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4493               </listitem>
4494             </varlistentry>
4495
4496             <varlistentry>
4497               <term><varname>shiptogln</varname></term>
4498
4499               <listitem>
4500                 <para>GLN (Globale Lokationsnummer) (Lieferadresse) <link
4501                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4502               </listitem>
4503             </varlistentry>
4504
4505             <varlistentry>
4506               <term><varname>shiptoname</varname></term>
4507
4508               <listitem>
4509                 <para>Firmenname (Lieferadresse) <link
4510                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4511               </listitem>
4512             </varlistentry>
4513
4514             <varlistentry>
4515               <term><varname>shiptophone</varname></term>
4516
4517               <listitem>
4518                 <para>Telefonnummer (Lieferadresse) <link
4519                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4520               </listitem>
4521             </varlistentry>
4522
4523             <varlistentry>
4524               <term><varname>shiptostreet</varname></term>
4525
4526               <listitem>
4527                 <para>Straße und Hausnummer (Lieferadresse) <link
4528                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4529               </listitem>
4530             </varlistentry>
4531
4532             <varlistentry>
4533               <term><varname>shiptozipcode</varname></term>
4534
4535               <listitem>
4536                 <para>Postleitzahl (Lieferadresse) <link
4537                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
4538               </listitem>
4539             </varlistentry>
4540
4541             <varlistentry>
4542               <term><varname>street</varname></term>
4543
4544               <listitem>
4545                 <para>Straße und Hausnummer</para>
4546               </listitem>
4547             </varlistentry>
4548
4549             <varlistentry>
4550               <term><varname>taxnumber</varname></term>
4551
4552               <listitem>
4553                 <para>Steuernummer</para>
4554               </listitem>
4555             </varlistentry>
4556
4557             <varlistentry>
4558               <term><varname>ustid</varname></term>
4559
4560               <listitem>
4561                 <para>Umsatzsteuer-Identifikationsnummer</para>
4562               </listitem>
4563             </varlistentry>
4564
4565             <varlistentry>
4566               <term><varname>vendoremail</varname></term>
4567
4568               <listitem>
4569                 <para>Email des Lieferanten; nur für Lieferanten</para>
4570               </listitem>
4571             </varlistentry>
4572
4573             <varlistentry>
4574               <term><varname>vendorfax</varname></term>
4575
4576               <listitem>
4577                 <para>Faxnummer des Lieferanten; nur für Lieferanten</para>
4578               </listitem>
4579             </varlistentry>
4580
4581             <varlistentry>
4582               <term><varname>vendornotes</varname></term>
4583
4584               <listitem>
4585                 <para>Bemerkungen beim Lieferanten; nur für Lieferanten</para>
4586               </listitem>
4587             </varlistentry>
4588
4589             <varlistentry>
4590               <term><varname>vendornumber</varname></term>
4591
4592               <listitem>
4593                 <para>Lieferantennummer; nur für Lieferanten</para>
4594               </listitem>
4595             </varlistentry>
4596
4597             <varlistentry>
4598               <term><varname>vendorphone</varname></term>
4599
4600               <listitem>
4601                 <para>Telefonnummer des Lieferanten; nur für
4602                 Lieferanten</para>
4603               </listitem>
4604             </varlistentry>
4605
4606             <varlistentry>
4607               <term><varname>zipcode</varname></term>
4608
4609               <listitem>
4610                 <para>Postleitzahl</para>
4611               </listitem>
4612             </varlistentry>
4613           </variablelist>
4614
4615           <note id="dokumentenvorlagen-und-variablen.anmerkung-shipto">
4616             <para>Anmerkung: Sind die <varname>shipto*</varname>-Felder in den
4617             Stammdaten nicht eingetragen, so haben die Variablen
4618             <varname>shipto*</varname> den gleichen Wert wie die die
4619             entsprechenden Variablen der Lieferdaten. Das bedeutet, dass sich
4620             einige <varname>shipto*</varname>-Variablen so nicht in den
4621             Stammdaten wiederfinden sondern schlicht Kopien der
4622             Lieferdatenvariablen sind (z.B.
4623             <varname>shiptocontact</varname>).</para>
4624           </note>
4625         </sect3>
4626
4627         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-bearbeiter">
4628           <title>Informationen über den Bearbeiter</title>
4629
4630           <variablelist>
4631             <varlistentry>
4632               <term><varname>employee_address</varname></term>
4633
4634               <listitem>
4635                 <para>Adressfeld</para>
4636               </listitem>
4637             </varlistentry>
4638
4639             <varlistentry>
4640               <term><varname>employee_businessnumber</varname></term>
4641
4642               <listitem>
4643                 <para>Firmennummer</para>
4644               </listitem>
4645             </varlistentry>
4646
4647             <varlistentry>
4648               <term><varname>employee_company</varname></term>
4649
4650               <listitem>
4651                 <para>Firmenname</para>
4652               </listitem>
4653             </varlistentry>
4654
4655             <varlistentry>
4656               <term><varname>employee_co_ustid</varname></term>
4657
4658               <listitem>
4659                 <para>Usatzsteuer-Identifikationsnummer</para>
4660               </listitem>
4661             </varlistentry>
4662
4663             <varlistentry>
4664               <term><varname>employee_duns</varname></term>
4665
4666               <listitem>
4667                 <para>DUNS-Nummer</para>
4668               </listitem>
4669             </varlistentry>
4670
4671             <varlistentry>
4672               <term><varname>employee_email</varname></term>
4673
4674               <listitem>
4675                 <para>Email</para>
4676               </listitem>
4677             </varlistentry>
4678
4679             <varlistentry>
4680               <term><varname>employee_fax</varname></term>
4681
4682               <listitem>
4683                 <para>Fax</para>
4684               </listitem>
4685             </varlistentry>
4686
4687             <varlistentry>
4688               <term><varname>employee_name</varname></term>
4689
4690               <listitem>
4691                 <para>voller Name</para>
4692               </listitem>
4693             </varlistentry>
4694
4695             <varlistentry>
4696               <term><varname>employee_signature</varname></term>
4697
4698               <listitem>
4699                 <para>Signatur</para>
4700               </listitem>
4701             </varlistentry>
4702
4703             <varlistentry>
4704               <term><varname>employee_taxnumber</varname></term>
4705
4706               <listitem>
4707                 <para>Steuernummer</para>
4708               </listitem>
4709             </varlistentry>
4710
4711             <varlistentry>
4712               <term><varname>employee_tel</varname></term>
4713
4714               <listitem>
4715                 <para>Telefonnummer</para>
4716               </listitem>
4717             </varlistentry>
4718           </variablelist>
4719         </sect3>
4720
4721         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-verkaeufer">
4722           <title>Informationen über den Verkäufer</title>
4723
4724           <variablelist>
4725             <varlistentry>
4726               <term><varname>salesman_address</varname></term>
4727
4728               <listitem>
4729                 <para>Adressfeld</para>
4730               </listitem>
4731             </varlistentry>
4732
4733             <varlistentry>
4734               <term><varname>salesman_businessnumber</varname></term>
4735
4736               <listitem>
4737                 <para>Firmennummer</para>
4738               </listitem>
4739             </varlistentry>
4740
4741             <varlistentry>
4742               <term><varname>salesman_company</varname></term>
4743
4744               <listitem>
4745                 <para>Firmenname</para>
4746               </listitem>
4747             </varlistentry>
4748
4749             <varlistentry>
4750               <term><varname>salesman_co_ustid</varname></term>
4751
4752               <listitem>
4753                 <para>Usatzsteuer-Identifikationsnummer</para>
4754               </listitem>
4755             </varlistentry>
4756
4757             <varlistentry>
4758               <term><varname>salesman_duns</varname></term>
4759
4760               <listitem>
4761                 <para>DUNS-Nummer</para>
4762               </listitem>
4763             </varlistentry>
4764
4765             <varlistentry>
4766               <term><varname>salesman_email</varname></term>
4767
4768               <listitem>
4769                 <para>Email</para>
4770               </listitem>
4771             </varlistentry>
4772
4773             <varlistentry>
4774               <term><varname>salesman_fax</varname></term>
4775
4776               <listitem>
4777                 <para>Fax</para>
4778               </listitem>
4779             </varlistentry>
4780
4781             <varlistentry>
4782               <term><varname>salesman_name</varname></term>
4783
4784               <listitem>
4785                 <para>voller Name</para>
4786               </listitem>
4787             </varlistentry>
4788
4789             <varlistentry>
4790               <term><varname>salesman_signature</varname></term>
4791
4792               <listitem>
4793                 <para>Signatur</para>
4794               </listitem>
4795             </varlistentry>
4796
4797             <varlistentry>
4798               <term><varname>salesman_taxnumber</varname></term>
4799
4800               <listitem>
4801                 <para>Steuernummer</para>
4802               </listitem>
4803             </varlistentry>
4804
4805             <varlistentry>
4806               <term><varname>salesman_tel</varname></term>
4807
4808               <listitem>
4809                 <para>Telefonnummer</para>
4810               </listitem>
4811             </varlistentry>
4812           </variablelist>
4813         </sect3>
4814
4815         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-steuern">
4816           <title>Variablen für die einzelnen Steuern</title>
4817
4818           <variablelist>
4819             <varlistentry>
4820               <term><varname>tax</varname></term>
4821
4822               <listitem>
4823                 <para>Steuer</para>
4824               </listitem>
4825             </varlistentry>
4826
4827             <varlistentry>
4828               <term><varname>taxbase</varname></term>
4829
4830               <listitem>
4831                 <para>zu versteuernder Betrag</para>
4832               </listitem>
4833             </varlistentry>
4834
4835             <varlistentry>
4836               <term><varname>taxdescription</varname></term>
4837
4838               <listitem>
4839                 <para>Name der Steuer</para>
4840               </listitem>
4841             </varlistentry>
4842
4843             <varlistentry>
4844               <term><varname>taxrate</varname></term>
4845
4846               <listitem>
4847                 <para>Steuersatz</para>
4848               </listitem>
4849             </varlistentry>
4850           </variablelist>
4851         </sect3>
4852
4853         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-lieferbedingungen">
4854           <title>Variablen für Lieferbedingungen</title>
4855
4856           <variablelist>
4857             <varlistentry>
4858               <term><varname>delivery_term</varname></term>
4859
4860               <listitem>
4861                 <para>Datenbank-Objekt der Lieferbedingung</para>
4862               </listitem>
4863             </varlistentry>
4864
4865             <varlistentry>
4866               <term><varname>delivery_term.description</varname></term>
4867
4868               <listitem>
4869                 <para>Beschreibung der Lieferbedingung</para>
4870               </listitem>
4871             </varlistentry>
4872
4873             <varlistentry>
4874               <term><varname>delivery_term.description_long</varname></term>
4875
4876               <listitem>
4877                 <para>Langtext bzw. übersetzter Langtext der
4878                 Lieferbedingung</para>
4879               </listitem>
4880             </varlistentry>
4881           </variablelist>
4882         </sect3>
4883       </sect2>
4884
4885       <sect2 id="dokumentenvorlagen-und-variablen.invoice">
4886         <title>Variablen in Rechnungen</title>
4887
4888         <sect3 id="dokumentenvorlagen-und-variablen.invoice-allgemein">
4889           <title>Allgemeine Variablen</title>
4890
4891           <variablelist>
4892             <varlistentry>
4893               <term><varname>creditremaining</varname></term>
4894
4895               <listitem>
4896                 <para>Verbleibender Kredit</para>
4897               </listitem>
4898             </varlistentry>
4899
4900             <varlistentry>
4901               <term><varname>currency</varname></term>
4902
4903               <listitem>
4904                 <para>Währung</para>
4905               </listitem>
4906             </varlistentry>
4907
4908             <varlistentry>
4909               <term><varname>cusordnumber</varname></term>
4910
4911               <listitem>
4912                 <para>Bestellnummer beim Kunden</para>
4913               </listitem>
4914             </varlistentry>
4915
4916             <varlistentry>
4917               <term><varname>deliverydate</varname></term>
4918
4919               <listitem>
4920                 <para>Lieferdatum</para>
4921               </listitem>
4922             </varlistentry>
4923
4924             <varlistentry>
4925               <term><varname>duedate</varname></term>
4926
4927               <listitem>
4928                 <para>Fälligkeitsdatum</para>
4929               </listitem>
4930             </varlistentry>
4931
4932             <varlistentry>
4933               <term><varname>globalprojectnumber</varname></term>
4934
4935               <listitem>
4936                 <para>Projektnummer des ganzen Beleges</para>
4937               </listitem>
4938             </varlistentry>
4939
4940             <varlistentry>
4941               <term><varname>globalprojectdescription</varname></term>
4942
4943               <listitem>
4944                 <para>Projekbeschreibung des ganzen Beleges</para>
4945               </listitem>
4946             </varlistentry>
4947
4948             <varlistentry>
4949               <term><varname>intnotes</varname></term>
4950
4951               <listitem>
4952                 <para>Interne Bemerkungen</para>
4953               </listitem>
4954             </varlistentry>
4955
4956             <varlistentry>
4957               <term><varname>invdate</varname></term>
4958
4959               <listitem>
4960                 <para>Rechnungsdatum</para>
4961               </listitem>
4962             </varlistentry>
4963
4964             <varlistentry>
4965               <term><varname>invnumber</varname></term>
4966
4967               <listitem>
4968                 <para>Rechnungsnummer</para>
4969               </listitem>
4970             </varlistentry>
4971
4972             <varlistentry>
4973               <term><varname>invtotal</varname></term>
4974
4975               <listitem>
4976                 <para>gesamter Rechnungsbetrag</para>
4977               </listitem>
4978             </varlistentry>
4979
4980             <varlistentry>
4981               <term><varname>notes</varname></term>
4982
4983               <listitem>
4984                 <para>Bemerkungen der Rechnung</para>
4985               </listitem>
4986             </varlistentry>
4987
4988             <varlistentry>
4989               <term><varname>orddate</varname></term>
4990
4991               <listitem>
4992                 <para>Auftragsdatum</para>
4993               </listitem>
4994             </varlistentry>
4995
4996             <varlistentry>
4997               <term><varname>ordnumber</varname></term>
4998
4999               <listitem>
5000                 <para>Auftragsnummer, wenn die Rechnung aus einem Auftrag
5001                 erstellt wurde</para>
5002               </listitem>
5003             </varlistentry>
5004
5005             <varlistentry>
5006               <term><varname>payment_description</varname></term>
5007
5008               <listitem>
5009                 <para>Name der Zahlart</para>
5010               </listitem>
5011             </varlistentry>
5012
5013             <varlistentry>
5014               <term><varname>payment_terms</varname></term>
5015
5016               <listitem>
5017                 <para>Zahlungskonditionen</para>
5018               </listitem>
5019             </varlistentry>
5020
5021             <varlistentry>
5022               <term><varname>quodate</varname></term>
5023
5024               <listitem>
5025                 <para>Angebotsdatum</para>
5026               </listitem>
5027             </varlistentry>
5028
5029             <varlistentry>
5030               <term><varname>quonumber</varname></term>
5031
5032               <listitem>
5033                 <para>Angebotsnummer</para>
5034               </listitem>
5035             </varlistentry>
5036
5037             <varlistentry>
5038               <term><varname>rounding</varname></term>
5039
5040               <listitem>
5041                 <para>Betrag, um den <varname>invtotal</varname> gerundet
5042                 wurde (kann positiv oder negativ sein)</para>
5043               </listitem>
5044             </varlistentry>
5045
5046             <varlistentry>
5047               <term><varname>shippingpoint</varname></term>
5048
5049               <listitem>
5050                 <para>Versandort</para>
5051               </listitem>
5052             </varlistentry>
5053
5054             <varlistentry>
5055               <term><varname>shipvia</varname></term>
5056
5057               <listitem>
5058                 <para>Transportmittel</para>
5059               </listitem>
5060             </varlistentry>
5061
5062             <varlistentry>
5063               <term><varname>subtotal</varname></term>
5064
5065               <listitem>
5066                 <para>Zwischensumme aller Posten ohne Steuern</para>
5067               </listitem>
5068             </varlistentry>
5069
5070             <varlistentry>
5071               <term><varname>total</varname></term>
5072
5073               <listitem>
5074                 <para>Restsumme der Rechnung (Summe abzüglich bereits
5075                 bezahlter Posten)</para>
5076               </listitem>
5077             </varlistentry>
5078
5079             <varlistentry>
5080               <term><varname>transaction_description</varname></term>
5081
5082               <listitem>
5083                 <para>Vorgangsbezeichnung</para>
5084               </listitem>
5085             </varlistentry>
5086
5087             <varlistentry>
5088               <term><varname>transdate</varname></term>
5089
5090               <listitem>
5091                 <para>Auftragsdatum wenn die Rechnung aus einem Auftrag
5092                 erstellt wurde</para>
5093               </listitem>
5094             </varlistentry>
5095           </variablelist>
5096         </sect3>
5097
5098         <sect3 id="dokumentenvorlagen-und-variablen.invoice-posten">
5099           <title>Variablen für jeden Posten auf der Rechnung</title>
5100
5101           <variablelist>
5102             <varlistentry>
5103               <term><varname>bin</varname></term>
5104
5105               <listitem>
5106                 <para>Stellage</para>
5107               </listitem>
5108             </varlistentry>
5109
5110             <varlistentry>
5111               <term><varname>description</varname></term>
5112
5113               <listitem>
5114                 <para>Artikelbeschreibung</para>
5115               </listitem>
5116             </varlistentry>
5117
5118             <varlistentry>
5119               <term><varname>cusordnumber_oe</varname></term>
5120
5121               <listitem>
5122                 <para>Bestellnummer des Kunden aus dem Auftrag, aus dem der
5123                 Posten ursprünglich stammt (nur Verkauf)</para>
5124               </listitem>
5125             </varlistentry>
5126
5127             <varlistentry>
5128               <term><varname>discount</varname></term>
5129
5130               <listitem>
5131                 <para>Rabatt als Betrag</para>
5132               </listitem>
5133             </varlistentry>
5134
5135             <varlistentry>
5136               <term><varname>discount_sub</varname></term>
5137
5138               <listitem>
5139                 <para>Zwischensumme mit Rabatt</para>
5140               </listitem>
5141             </varlistentry>
5142
5143             <varlistentry>
5144               <term><varname>donumber_do</varname></term>
5145
5146               <listitem>
5147                 <para>Lieferscheinnummer des Lieferscheins, aus dem die
5148                 Position ursprünglich stammt, wenn die Rechnung im Rahmen des
5149                 Workflows aus einem Lieferschein erstellt wurde.</para>
5150               </listitem>
5151             </varlistentry>
5152
5153             <varlistentry>
5154               <term><varname>drawing</varname></term>
5155
5156               <listitem>
5157                 <para>Zeichnung</para>
5158               </listitem>
5159             </varlistentry>
5160
5161             <varlistentry>
5162               <term><varname>ean</varname></term>
5163
5164               <listitem>
5165                 <para>EAN-Code</para>
5166               </listitem>
5167             </varlistentry>
5168
5169             <varlistentry>
5170               <term><varname>image</varname></term>
5171
5172               <listitem>
5173                 <para>Grafik</para>
5174               </listitem>
5175             </varlistentry>
5176
5177             <varlistentry>
5178               <term><varname>linetotal</varname></term>
5179
5180               <listitem>
5181                 <para>Zeilensumme (Anzahl * Einzelpreis)</para>
5182               </listitem>
5183             </varlistentry>
5184
5185             <varlistentry>
5186               <term><varname>longdescription</varname></term>
5187
5188               <listitem>
5189                 <para>Langtext, vorbelegt mit dem Feld Bemerkungen der entsprechenden Ware</para>
5190               </listitem>
5191             </varlistentry>
5192
5193             <varlistentry>
5194               <term><varname>microfiche</varname></term>
5195
5196               <listitem>
5197                 <para>Mikrofilm</para>
5198               </listitem>
5199             </varlistentry>
5200
5201             <varlistentry>
5202               <term><varname>netprice</varname></term>
5203
5204               <listitem>
5205                 <para>Alternative zu <varname>sellprice</varname>, aber
5206                 <varname>netprice</varname> entspricht dem effektiven
5207                 Einzelpreis und beinhaltet Zeilenrabatt und Preisfaktor.
5208                 <varname>netprice</varname> wird rückgerechnet aus Zeilensumme
5209                 / Menge. Diese Variable ist nützlich, wenn man den gewährten
5210                 Rabatt in der Druckvorlage nicht anzeigen möchte, aber Menge *
5211                 Einzelpreis trotzdem die angezeigte Zeilensumme ergeben soll.
5212                 <varname>netprice</varname> hat nichts mit Netto/Brutto im
5213                 Sinne von Steuern zu tun.</para>
5214               </listitem>
5215             </varlistentry>
5216
5217             <varlistentry>
5218               <term><varname>nodiscount_linetotal</varname></term>
5219
5220               <listitem>
5221                 <para>Zeilensumme ohne Rabatt</para>
5222               </listitem>
5223             </varlistentry>
5224
5225             <varlistentry>
5226               <term><varname>nodiscount_sub</varname></term>
5227
5228               <listitem>
5229                 <para>Zwischensumme ohne Rabatt</para>
5230               </listitem>
5231             </varlistentry>
5232
5233             <varlistentry>
5234               <term><varname>number</varname></term>
5235
5236               <listitem>
5237                 <para>Artikelnummer</para>
5238               </listitem>
5239             </varlistentry>
5240
5241             <varlistentry>
5242               <term><varname>ordnumber_oe</varname></term>
5243
5244               <listitem>
5245                 <para>Auftragsnummer des Originalauftrags, aus dem der Posten
5246                 ursprünglich stammt. Nützlich, wenn die Rechnung aus mehreren
5247                 Lieferscheinen zusammengefasst wurde, oder wenn zwischendurch
5248                 eine Sammelauftrag aus mehreren Aufträgen erstellt wurde. In
5249                 letzterem Fall wird die unsprüngliche Auftragsnummer
5250                 angezeigt.</para>
5251               </listitem>
5252             </varlistentry>
5253
5254             <varlistentry>
5255               <term><varname>p_discount</varname></term>
5256
5257               <listitem>
5258                 <para>Rabatt in Prozent</para>
5259               </listitem>
5260             </varlistentry>
5261
5262             <varlistentry>
5263               <term><varname>partnotes</varname></term>
5264
5265               <listitem>
5266                 <para>Die beim Artikel gespeicherten Bemerkungen</para>
5267               </listitem>
5268             </varlistentry>
5269
5270             <varlistentry>
5271               <term><varname>partsgroup</varname></term>
5272
5273               <listitem>
5274                 <para>Warengruppe</para>
5275               </listitem>
5276             </varlistentry>
5277
5278             <varlistentry>
5279               <term><varname>price_factor</varname></term>
5280
5281               <listitem>
5282                 <para>Der Preisfaktor als Zahl, sofern einer eingestellt
5283                 ist</para>
5284               </listitem>
5285             </varlistentry>
5286
5287             <varlistentry>
5288               <term><varname>price_factor_name</varname></term>
5289
5290               <listitem>
5291                 <para>Der Name des Preisfaktors, sofern einer eingestellt
5292                 ist</para>
5293               </listitem>
5294             </varlistentry>
5295
5296             <varlistentry>
5297               <term><varname>projectnumber</varname></term>
5298
5299               <listitem>
5300                 <para>Projektnummer</para>
5301               </listitem>
5302             </varlistentry>
5303
5304             <varlistentry>
5305               <term><varname>projectdescription</varname></term>
5306
5307               <listitem>
5308                 <para>Projektbeschreibung</para>
5309               </listitem>
5310             </varlistentry>
5311
5312             <varlistentry>
5313               <term><varname>qty</varname></term>
5314
5315               <listitem>
5316                 <para>Anzahl</para>
5317               </listitem>
5318             </varlistentry>
5319
5320             <varlistentry>
5321               <term><varname>reqdate</varname></term>
5322
5323               <listitem>
5324                 <para>Lieferdatum</para>
5325               </listitem>
5326             </varlistentry>
5327
5328             <varlistentry>
5329               <term><varname>runningnumber</varname></term>
5330
5331               <listitem>
5332                 <para>Position auf der Rechnung (1, 2, 3...)</para>
5333               </listitem>
5334             </varlistentry>
5335
5336             <varlistentry>
5337               <term><varname>sellprice</varname></term>
5338
5339               <listitem>
5340                 <para>Verkaufspreis</para>
5341               </listitem>
5342             </varlistentry>
5343
5344             <varlistentry>
5345               <term><varname>serialnumber</varname></term>
5346
5347               <listitem>
5348                 <para>Seriennummer</para>
5349               </listitem>
5350             </varlistentry>
5351
5352             <varlistentry>
5353               <term><varname>tax_rate</varname></term>
5354
5355               <listitem>
5356                 <para>Steuersatz</para>
5357               </listitem>
5358             </varlistentry>
5359
5360             <varlistentry>
5361               <term><varname>transdate_do</varname></term>
5362
5363               <listitem>
5364                 <para>Datum des Lieferscheins, wenn die Rechnung im Rahmen des
5365                 Workflows aus einem Lieferschein stammte.</para>
5366               </listitem>
5367             </varlistentry>
5368
5369             <varlistentry>
5370               <term><varname>transdate_oe</varname></term>
5371
5372               <listitem>
5373                 <para>Datum des Auftrags, wenn die Rechnung im Rahmen des
5374                 Workflows aus einem Auftrag erstellt wurde. Wenn es
5375                 Sammelaufträge gab wird das Datum des ursprünglichen Auftrags
5376                 genommen.</para>
5377               </listitem>
5378             </varlistentry>
5379
5380             <varlistentry>
5381               <term><varname>transdate_quo</varname></term>
5382
5383               <listitem>
5384                 <para>Datum des Angebots, wenn die Position im Rahmen des
5385                 Workflows aus einem Angebot stammte.</para>
5386               </listitem>
5387             </varlistentry>
5388
5389             <varlistentry>
5390               <term><varname>unit</varname></term>
5391
5392               <listitem>
5393                 <para>Einheit</para>
5394               </listitem>
5395             </varlistentry>
5396
5397             <varlistentry>
5398               <term><varname>weight</varname></term>
5399
5400               <listitem>
5401                 <para>Gewicht</para>
5402               </listitem>
5403             </varlistentry>
5404           </variablelist>
5405
5406           <para>Für jeden Posten gibt es ein Unterarray mit den Informationen
5407           über Lieferanten und Lieferantenartikelnummer. Diese müssen mit
5408           einer <function>foreach</function>-Schleife ausgegeben werden, da
5409           für jeden Artikel mehrere Lieferanteninformationen hinterlegt sein
5410           können. Die Variablen dafür lauten:</para>
5411
5412           <variablelist>
5413             <varlistentry>
5414               <term><varname>make</varname></term>
5415
5416               <listitem>
5417                 <para>Lieferant</para>
5418               </listitem>
5419             </varlistentry>
5420
5421             <varlistentry>
5422               <term><varname>model</varname></term>
5423
5424               <listitem>
5425                 <para>Lieferantenartikelnummer</para>
5426               </listitem>
5427             </varlistentry>
5428           </variablelist>
5429         </sect3>
5430
5431         <sect3 id="dokumentenvorlagen-und-variablen.invoice-zahlungen">
5432           <title>Variablen für die einzelnen Zahlungseingänge</title>
5433
5434           <variablelist>
5435             <varlistentry>
5436               <term><varname>payment</varname></term>
5437
5438               <listitem>
5439                 <para>Betrag</para>
5440               </listitem>
5441             </varlistentry>
5442
5443             <varlistentry>
5444               <term><varname>paymentaccount</varname></term>
5445
5446               <listitem>
5447                 <para>Konto</para>
5448               </listitem>
5449             </varlistentry>
5450
5451             <varlistentry>
5452               <term><varname>paymentdate</varname></term>
5453
5454               <listitem>
5455                 <para>Datum</para>
5456               </listitem>
5457             </varlistentry>
5458
5459             <varlistentry>
5460               <term><varname>paymentmemo</varname></term>
5461
5462               <listitem>
5463                 <para>Memo</para>
5464               </listitem>
5465             </varlistentry>
5466
5467             <varlistentry>
5468               <term><varname>paymentsource</varname></term>
5469
5470               <listitem>
5471                 <para>Beleg</para>
5472               </listitem>
5473             </varlistentry>
5474           </variablelist>
5475         </sect3>
5476
5477         <sect3 id="dokumentenvorlagen-und-variablen.benutzerdefinierte-variablen-vc">
5478           <title>Benutzerdefinierte Kunden- und Lieferantenvariablen</title>
5479
5480           <para>Die vom Benutzer definierten Variablen für Kunden und
5481           Lieferanten stehen beim Ausdruck von Einkaufs- und Verkaufsbelegen
5482           ebenfalls zur Verfügung. Ihre Namen setzen sich aus dem Präfix
5483           <varname>vc_cvar_</varname> und dem vom Benutzer festgelegten
5484           Variablennamen zusammen.</para>
5485
5486           <para>Beispiel: Der Benutzer hat eine Variable namens
5487           <varname>number_of_employees</varname> definiert, die die Anzahl der
5488           Mitarbeiter des Unternehmens enthält. Diese Variable steht dann
5489           unter dem Namen <varname>vc_cvar_number_of_employees</varname> zur
5490           Verfügung.</para>
5491
5492           <para>Die benutzerdefinierten Variablen der Lieferadressen stehen
5493           unter einem ähnlichen Namensschema zur Verfügung. Hier lautet der
5494           Präfix <varname>shiptocvar_</varname>.</para>
5495
5496           <para>Analog stehen die benutzerdefinierten Variablen für
5497           Ansprechpersonen mit dem Namenspräfix <varname>cp_cvar_</varname>
5498           zur Verfügung.</para>
5499         </sect3>
5500       </sect2>
5501
5502       <sect2 id="dokumentenvorlagen-und-variablen.dunning">
5503         <title>Variablen in Mahnungen und Rechnungen über Mahngebühren</title>
5504
5505         <sect3 id="dokumentenvorlagen-und-variablen.dunning-vorlagennamen">
5506           <title>Namen der Vorlagen</title>
5507
5508           <para>Die Namen der Vorlagen werden im System-Menü vom Benutzer
5509           eingegeben. Wird für ein Mahnlevel die Option zur automatischen
5510           Erstellung einer Rechnung über die Mahngebühren und Zinsen
5511           aktiviert, so wird der Name der Vorlage für diese Rechnung aus dem
5512           Vorlagenname für diese Mahnstufe mit dem Zusatz
5513           <constant>_invoice</constant> gebildet. Weiterhin werden die Kürzel
5514           für die ausgewählte Sprache und den ausgewählten Drucker
5515           angehängt.</para>
5516         </sect3>
5517
5518         <sect3 id="dokumentenvorlagen-und-variablen.dunning-allgemein">
5519           <title>Allgemeine Variablen in Mahnungen</title>
5520
5521           <para>Die Variablen des Bearbeiters, bzw. Verkäufers stehen wie
5522           gewohnt als <varname>employee_...</varname> bzw.
5523           <varname>salesman_...</varname> zur Verfügung. Werden mehrere
5524           Rechnungen in einer Mahnung zusammengefasst, so werden die Metadaten
5525           (Bearbeiter, Abteilung, etc) der ersten angemahnten Rechnung im
5526           Ausdruck genommen.</para>
5527
5528           <para>Die Adressdaten des Kunden stehen als Variablen
5529           <varname>name</varname>, <varname>street</varname>,
5530           <varname>zipcode</varname>, <varname>city</varname>,
5531           <varname>country</varname>, <varname>department_1</varname>,
5532           <varname>department_2</varname>, und <varname>email</varname> zur
5533           Verfügung. Der Ansprechpartner <varname>cp_...</varname> steht auch
5534           zu Verfügung, wird allerdings auch nur von der ersten angemahnten
5535           Rechnung (s.o.) genommen.</para>
5536
5537           <para>Weitere Variablen beinhalten:</para>
5538
5539           <variablelist>
5540             <varlistentry>
5541               <term><varname>dunning_date</varname></term>
5542
5543               <listitem>
5544                 <para>Datum der Mahnung</para>
5545               </listitem>
5546             </varlistentry>
5547
5548             <varlistentry>
5549               <term><varname>dunning_duedate</varname></term>
5550
5551               <listitem>
5552                 <para>Fälligkeitsdatum für diese Mahhnung</para>
5553               </listitem>
5554             </varlistentry>
5555
5556             <varlistentry>
5557               <term><varname>dunning_id</varname></term>
5558
5559               <listitem>
5560                 <para>Mahnungsnummer</para>
5561               </listitem>
5562             </varlistentry>
5563
5564             <varlistentry>
5565               <term><varname>fee</varname></term>
5566
5567               <listitem>
5568                 <para>Kumulative Mahngebühren</para>
5569               </listitem>
5570             </varlistentry>
5571
5572             <varlistentry>
5573               <term><varname>interest_rate</varname></term>
5574
5575               <listitem>
5576                 <para>Zinssatz per anno in Prozent</para>
5577               </listitem>
5578             </varlistentry>
5579
5580             <varlistentry>
5581               <term><varname>total_amount</varname></term>
5582
5583               <listitem>
5584                 <para>Gesamter noch zu zahlender Betrag als
5585                 <function>fee</function> + <function>total_interest</function>
5586                 + <function>total_open_amount</function></para>
5587               </listitem>
5588             </varlistentry>
5589
5590             <varlistentry>
5591               <term><varname>total_interest</varname></term>
5592
5593               <listitem>
5594                 <para>Zinsen per anno über alle Rechnungen</para>
5595               </listitem>
5596             </varlistentry>
5597
5598             <varlistentry>
5599               <term><varname>total_open_amount</varname></term>
5600
5601               <listitem>
5602                 <para>Summe über alle offene Beträge der Rechnungen</para>
5603               </listitem>
5604             </varlistentry>
5605           </variablelist>
5606         </sect3>
5607
5608         <sect3 id="dokumentenvorlagen-und-variablen.dunning-details">
5609           <title>Variablen für jede gemahnte Rechnung in einer Mahnung</title>
5610
5611           <variablelist>
5612             <varlistentry>
5613               <term><varname>dn_amount</varname></term>
5614
5615               <listitem>
5616                 <para>Rechnungssumme (brutto)</para>
5617               </listitem>
5618             </varlistentry>
5619
5620             <varlistentry>
5621               <term><varname>dn_duedate</varname></term>
5622
5623               <listitem>
5624                 <para>Originales Fälligkeitsdatum der Rechnung</para>
5625               </listitem>
5626             </varlistentry>
5627
5628             <varlistentry>
5629               <term><varname>dn_dunning_date</varname></term>
5630
5631               <listitem>
5632                 <para>Datum der Mahnung</para>
5633               </listitem>
5634             </varlistentry>
5635
5636             <varlistentry>
5637               <term><varname>dn_dunning_duedate</varname></term>
5638
5639               <listitem>
5640                 <para>Fälligkeitsdatum der Mahnung</para>
5641               </listitem>
5642             </varlistentry>
5643
5644             <varlistentry>
5645               <term><varname>dn_fee</varname></term>
5646
5647               <listitem>
5648                 <para>Kummulative Mahngebühr</para>
5649               </listitem>
5650             </varlistentry>
5651
5652             <varlistentry>
5653               <term><varname>dn_interest</varname></term>
5654
5655               <listitem>
5656                 <para>Zinsen per anno für diese Rechnung</para>
5657               </listitem>
5658             </varlistentry>
5659
5660             <varlistentry>
5661               <term><varname>dn_invnumber</varname></term>
5662
5663               <listitem>
5664                 <para>Rechnungsnummer</para>
5665               </listitem>
5666             </varlistentry>
5667
5668             <varlistentry>
5669               <term><varname>dn_linetotal</varname></term>
5670
5671               <listitem>
5672                 <para>Noch zu zahlender Betrag (ergibt sich aus
5673                 <varname>dn_open_amount</varname> + <varname>dn_fee</varname>
5674                 + <varname>dn_interest</varname>)</para>
5675               </listitem>
5676             </varlistentry>
5677
5678             <varlistentry>
5679               <term><varname>dn_netamount</varname></term>
5680
5681               <listitem>
5682                 <para>Rechnungssumme (netto)</para>
5683               </listitem>
5684             </varlistentry>
5685
5686             <varlistentry>
5687               <term><varname>dn_open_amount</varname></term>
5688
5689               <listitem>
5690                 <para>Offener Rechnungsbetrag</para>
5691               </listitem>
5692             </varlistentry>
5693
5694             <varlistentry>
5695               <term><varname>dn_ordnumber</varname></term>
5696
5697               <listitem>
5698                 <para>Bestellnummer</para>
5699               </listitem>
5700             </varlistentry>
5701
5702             <varlistentry>
5703               <term><varname>dn_transdate</varname></term>
5704
5705               <listitem>
5706                 <para>Rechnungsdatum</para>
5707               </listitem>
5708             </varlistentry>
5709
5710             <varlistentry>
5711               <term><varname>dn_curr</varname></term>
5712
5713               <listitem>
5714                 <para>Währung, in der die Rechnung erstellt wurde. (Die
5715                 Rechnungsbeträge sind aber immer in der Hauptwährung)</para>
5716               </listitem>
5717             </varlistentry>
5718           </variablelist>
5719         </sect3>
5720
5721         <sect3 id="dokumentenvorlagen-und-variablen.dunning-invoice">
5722           <title>Variablen in automatisch erzeugten Rechnungen über
5723           Mahngebühren</title>
5724
5725           <para>Die Variablen des Verkäufers stehen wie gewohnt als
5726           <varname>employee_...</varname> zur Verfügung. Die Adressdaten des
5727           Kunden stehen als Variablen <varname>name</varname>,
5728           <varname>street</varname>, <varname>zipcode</varname>,
5729           <varname>city</varname>, <varname>country</varname>,
5730           <varname>department_1</varname>, <varname>department_2</varname>,
5731           und <varname>email</varname> zur Verfügung.</para>
5732
5733           <para>Weitere Variablen beinhalten:</para>
5734
5735           <variablelist>
5736             <varlistentry>
5737               <term><varname>duedate</varname></term>
5738
5739               <listitem>
5740                 <para>Fälligkeitsdatum der Rechnung</para>
5741               </listitem>
5742             </varlistentry>
5743
5744             <varlistentry>
5745               <term><varname>dunning_id</varname></term>
5746
5747               <listitem>
5748                 <para>Mahnungsnummer</para>
5749               </listitem>
5750             </varlistentry>
5751
5752             <varlistentry>
5753               <term><varname>fee</varname></term>
5754
5755               <listitem>
5756                 <para>Mahngebühren</para>
5757               </listitem>
5758             </varlistentry>
5759
5760             <varlistentry>
5761               <term><varname>interest</varname></term>
5762
5763               <listitem>
5764                 <para>Zinsen</para>
5765               </listitem>
5766             </varlistentry>
5767
5768             <varlistentry>
5769               <term><varname>invamount</varname></term>
5770
5771               <listitem>
5772                 <para>Rechnungssumme (ergibt sich aus <varname>fee</varname> +
5773                 <varname>interest</varname>)</para>
5774               </listitem>
5775             </varlistentry>
5776
5777             <varlistentry>
5778               <term><varname>invdate</varname></term>
5779
5780               <listitem>
5781                 <para>Rechnungsdatum</para>
5782               </listitem>
5783             </varlistentry>
5784
5785             <varlistentry>
5786               <term><varname>invnumber</varname></term>
5787
5788               <listitem>
5789                 <para>Rechnungsnummer</para>
5790               </listitem>
5791             </varlistentry>
5792           </variablelist>
5793         </sect3>
5794       </sect2>
5795
5796       <sect2 id="dokumentenvorlagen-und-variablen.andere-vorlagen">
5797         <title>Variablen in anderen Vorlagen</title>
5798
5799         <sect3>
5800           <title>Einführung</title>
5801
5802           <para>Die Variablen in anderen Vorlagen sind ähnlich wie in der
5803           Rechnung. Allerdings heißen die Variablen, die mit
5804           <varname>inv</varname> beginnen, jetzt anders. Bei den Angeboten
5805           fangen sie mit <varname>quo</varname> für "quotation" an:
5806           <varname>quodate</varname> für Angebotsdatum etc. Bei Bestellungen
5807           wiederum fangen sie mit <varname>ord</varname> für "order" an:
5808           <varname>ordnumber</varname> für Bestellnummer etc.</para>
5809
5810           <para>Manche Variablen sind in anderen Vorlagen hingegen gar nicht
5811           vorhanden wie z.B. die für bereits verbuchte Zahlungseingänge. Dies
5812           sind Variablen, die vom Geschäftsablauf her in der entsprechenden
5813           Vorlage keine Bedeutung haben oder noch nicht belegt sein
5814           können.</para>
5815
5816           <para>Im Folgenden werden nur wichtige Unterschiede zu den Variablen
5817           in Rechnungen aufgeführt.</para>
5818         </sect3>
5819
5820         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-quotations">
5821           <title>Angebote und Preisanfragen</title>
5822
5823           <variablelist>
5824             <varlistentry>
5825               <term><varname>quonumber</varname></term>
5826
5827               <listitem>
5828                 <para>Angebots- bzw. Anfragenummer</para>
5829               </listitem>
5830             </varlistentry>
5831
5832             <varlistentry>
5833               <term><varname>reqdate</varname></term>
5834
5835               <listitem>
5836                 <para>Gültigkeitsdatum (bei Angeboten) bzw. Lieferdatum (bei
5837                 Preisanfragen)</para>
5838               </listitem>
5839             </varlistentry>
5840
5841             <varlistentry>
5842               <term><varname>transdate</varname></term>
5843
5844               <listitem>
5845                 <para>Angebots- bzw. Anfragedatum</para>
5846               </listitem>
5847             </varlistentry>
5848           </variablelist>
5849         </sect3>
5850
5851         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-orders">
5852           <title>Auftragsbestätigungen und Lieferantenaufträge</title>
5853
5854           <variablelist>
5855             <varlistentry>
5856               <term><varname>ordnumber</varname></term>
5857
5858               <listitem>
5859                 <para>Auftragsnummer</para>
5860               </listitem>
5861             </varlistentry>
5862
5863             <varlistentry>
5864               <term><varname>reqdate</varname></term>
5865
5866               <listitem>
5867                 <para>Lieferdatum</para>
5868               </listitem>
5869             </varlistentry>
5870
5871             <varlistentry>
5872               <term><varname>transdate</varname></term>
5873
5874               <listitem>
5875                 <para>Auftragsdatum</para>
5876               </listitem>
5877             </varlistentry>
5878           </variablelist>
5879         </sect3>
5880
5881         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-delivery-orders">
5882           <title>Lieferscheine (Verkauf und Einkauf)</title>
5883
5884           <variablelist>
5885             <varlistentry>
5886               <term><varname>cusordnumber</varname></term>
5887
5888               <listitem>
5889                 <para>Bestellnummer des Kunden (im Verkauf) bzw. Bestellnummer
5890                 des Lieferanten (im Einkauf)</para>
5891               </listitem>
5892             </varlistentry>
5893
5894             <varlistentry>
5895               <term><varname>donumber</varname></term>
5896
5897               <listitem>
5898                 <para>Lieferscheinnummer</para>
5899               </listitem>
5900             </varlistentry>
5901
5902             <varlistentry>
5903               <term><varname>transdate</varname></term>
5904
5905               <listitem>
5906                 <para>Lieferscheindatum</para>
5907               </listitem>
5908             </varlistentry>
5909           </variablelist>
5910
5911           <para>Für jede Position eines Lieferscheines gibt es ein Unterarray
5912           mit den Informationen darüber, von welchem Lager und Lagerplatz aus
5913           die Waren verschickt wurden (Verkaufslieferscheine) bzw. auf welchen
5914           Lagerplatz sie eingelagert wurden. Diese müssen mittels einer
5915           <function>foreach</function>-Schleife ausgegeben werden. Diese
5916           Variablen sind:</para>
5917
5918           <variablelist>
5919             <varlistentry>
5920               <term><varname>si_bin</varname></term>
5921
5922               <listitem>
5923                 <para>Lagerplatz</para>
5924               </listitem>
5925             </varlistentry>
5926
5927             <varlistentry>
5928               <term><varname>si_chargenumber</varname></term>
5929
5930               <listitem>
5931                 <para>Chargennummer</para>
5932               </listitem>
5933             </varlistentry>
5934
5935             <varlistentry>
5936               <term><varname>si_bestbefore</varname></term>
5937
5938               <listitem>
5939                 <para>Mindesthaltbarkeit</para>
5940               </listitem>
5941             </varlistentry>
5942
5943             <varlistentry>
5944               <term><varname>si_number</varname></term>
5945
5946               <listitem>
5947                 <para>Artikelnummer</para>
5948               </listitem>
5949             </varlistentry>
5950
5951             <varlistentry>
5952               <term><varname>si_qty</varname></term>
5953
5954               <listitem>
5955                 <para>Anzahl bzw. Menge</para>
5956               </listitem>
5957             </varlistentry>
5958
5959             <varlistentry>
5960               <term><varname>si_runningnumber</varname></term>
5961
5962               <listitem>
5963                 <para>Positionsnummer (1, 2, 3 etc)</para>
5964               </listitem>
5965             </varlistentry>
5966
5967             <varlistentry>
5968               <term><varname>si_unit</varname></term>
5969
5970               <listitem>
5971                 <para>Einheit</para>
5972               </listitem>
5973             </varlistentry>
5974
5975             <varlistentry>
5976               <term><varname>si_warehouse</varname></term>
5977
5978               <listitem>
5979                 <para>Lager</para>
5980               </listitem>
5981             </varlistentry>
5982           </variablelist>
5983         </sect3>
5984
5985         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-statement">
5986           <title>Variablen für Sammelrechnung</title>
5987
5988           <variablelist>
5989             <varlistentry>
5990               <term><varname>c0total</varname></term>
5991
5992               <listitem>
5993                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &lt; 30
5994                 Tage</para>
5995               </listitem>
5996             </varlistentry>
5997
5998             <varlistentry>
5999               <term><varname>c30total</varname></term>
6000
6001               <listitem>
6002                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 30
6003                 und &lt; 60 Tage</para>
6004               </listitem>
6005             </varlistentry>
6006
6007             <varlistentry>
6008               <term><varname>c60total</varname></term>
6009
6010               <listitem>
6011                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 60
6012                 und &lt; 90 Tage</para>
6013               </listitem>
6014             </varlistentry>
6015
6016             <varlistentry>
6017               <term><varname>c90total</varname></term>
6018
6019               <listitem>
6020                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 90
6021                 Tage</para>
6022               </listitem>
6023             </varlistentry>
6024
6025             <varlistentry>
6026               <term><varname>total</varname></term>
6027
6028               <listitem>
6029                 <para>Gesamtbetrag aller Rechnungen</para>
6030               </listitem>
6031             </varlistentry>
6032           </variablelist>
6033
6034           <para>Variablen für jede Rechnungsposition in Sammelrechnung:</para>
6035
6036           <variablelist>
6037             <varlistentry>
6038               <term><varname>invnumber</varname></term>
6039
6040               <listitem>
6041                 <para>Rechnungsnummer</para>
6042               </listitem>
6043             </varlistentry>
6044
6045             <varlistentry>
6046               <term><varname>invdate</varname></term>
6047
6048               <listitem>
6049                 <para>Rechnungsdatum</para>
6050               </listitem>
6051             </varlistentry>
6052
6053             <varlistentry>
6054               <term><varname>duedate</varname></term>
6055
6056               <listitem>
6057                 <para>Fälligkeitsdatum</para>
6058               </listitem>
6059             </varlistentry>
6060
6061             <varlistentry>
6062               <term><varname>amount</varname></term>
6063
6064               <listitem>
6065                 <para>Summe der Rechnung</para>
6066               </listitem>
6067             </varlistentry>
6068
6069             <varlistentry>
6070               <term><varname>open</varname></term>
6071
6072               <listitem>
6073                 <para>Noch offener Betrag der Rechnung</para>
6074               </listitem>
6075             </varlistentry>
6076
6077             <varlistentry>
6078               <term><varname>c0</varname></term>
6079
6080               <listitem>
6081                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &lt; 30
6082                 Tage</para>
6083               </listitem>
6084             </varlistentry>
6085
6086             <varlistentry>
6087               <term><varname>c30</varname></term>
6088
6089               <listitem>
6090                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 30 und
6091                 &lt; 60 Tage</para>
6092               </listitem>
6093             </varlistentry>
6094
6095             <varlistentry>
6096               <term><varname>c60</varname></term>
6097
6098               <listitem>
6099                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 60 und
6100                 &lt; 90 Tage</para>
6101               </listitem>
6102             </varlistentry>
6103
6104             <varlistentry>
6105               <term><varname>c90</varname></term>
6106
6107               <listitem>
6108                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 90
6109                 Tage</para>
6110               </listitem>
6111             </varlistentry>
6112           </variablelist>
6113         </sect3>
6114       </sect2>
6115
6116       <sect2 id="dokumentenvorlagen-und-variablen.bloecke">
6117         <title>Blöcke, bedingte Anweisungen und Schleifen</title>
6118
6119         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.einfuehrung">
6120           <title>Einführung</title>
6121
6122           <para>Der Parser kennt neben den Variablen einige weitere
6123           Konstrukte, die gesondert behandelt werden. Diese sind wie
6124           Variablennamen in spezieller Weise markiert:
6125           <command>&lt;%anweisung%&gt; ... &lt;%end%&gt;</command></para>
6126
6127           <para>Anmerkung zum <command>&lt;%end%&gt;</command>: Der besseren
6128           Verständlichkeit halber kann man nach dem <command>end</command>
6129           noch beliebig weitere Wörter schreiben, um so zu markieren, welche
6130           Anweisung (z.B. <command>if</command> oder
6131           <command>foreach</command>) damit abgeschlossen wird.</para>
6132
6133           <para>Beispiel: Lautet der Beginn eines Blockes z.B.
6134           <command>&lt;%if type == "sales_quotation"%&gt;</command>, so könnte
6135           er mit <command>&lt;%end%&gt;</command> genauso abgeschlossen werden
6136           wie mit <command>&lt;%end if%&gt;</command> oder auch
6137           <command>&lt;%end type == "sales_quotation"%&gt;</command>.</para>
6138         </sect3>
6139
6140         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.if">
6141           <title>Der if-Block</title>
6142
6143           <programlisting>&lt;%if variablenname%&gt;
6144 ...
6145 &lt;%end%&gt;</programlisting>
6146
6147           <para>Eine normale "if-then"-Bedingung. Die Zeilen zwischen dem "if"
6148           und dem "end" werden nur ausgegeben, wenn die Variable
6149           <varname>variablenname</varname> gesetzt und ungleich 0 ist.</para>
6150
6151           <para>Handelt es sich bei der benannten Variable um ein Array, also
6152           um einen Variablennamen, über den man mit <command>&lt;%foreach
6153           variablenname%&gt;</command> iteriert, so wird mit diesem Konstrukt
6154           darauf getestet, ob das Array Elemente enthält. Somit würde im
6155           folgenden Beispiel nur dann eine Liste von Zahlungseingängen samt
6156           ihrer Überschrift "Zahlungseingänge" ausgegeben, wenn tatsächlich
6157           welche getätigt wurden:</para>
6158
6159           <programlisting>&lt;%if payment%&gt;
6160 Zahlungseingänge:
6161  &lt;%foreach payment%&gt;
6162    Am &lt;%paymentdate%&gt;: &lt;%payment%&gt; €
6163  &lt;%end foreach%&gt;
6164 &lt;%end if%&gt;</programlisting>
6165
6166           <para>Die Bedingung kann auch negiert werden, indem das Wort
6167           <function>not</function> nach dem <filename>if</filename> verwendet
6168           wird. Beispiel:</para>
6169
6170           <programlisting>&lt;%if not cp_greeting%&gt;
6171 ...
6172 &lt;%end%&gt;</programlisting>
6173
6174           <para>Zusätzlich zu dem einfachen Test, ob eine Variable gesetzt ist
6175           oder nicht, bietet dieser Block auch die Möglichkeit, den Inhalt
6176           einer Variablen mit einer festen Zeichenkette oder einer anderen
6177           Variablen zu vergleichen. Ob der Vergleich mit einer Zeichenkette
6178           oder einer anderen Variablen vorgenommen wird, hängt davon ab, ob
6179           die rechte Seite des Vergleichsoperators in Anführungszeichen
6180           gesetzt wird (Vergleich mit Zeichenkette) oder nicht (Vergleich mit
6181           anderer Variablen). Zwei Beispiele, die beide Vergleiche
6182           zeigen:</para>
6183
6184           <programlisting>&lt;%if var1 == "Wert"%&gt;</programlisting>
6185
6186           <para>Testet die Variable <varname>var1</varname> auf
6187           übereinstimmung mit der Zeichenkette <constant>Wert</constant>.
6188           Mittels <function>!=</function> anstelle von <function>==</function>
6189           würde auf Ungleichheit getestet.</para>
6190
6191           <programlisting>&lt;%if var1 == var2%&gt;</programlisting>
6192
6193           <para>Testet die Variable <varname>var1</varname> auf
6194           übereinstimmung mit der Variablen <varname>var2</varname>. Mittel
6195           <function>!=</function> anstelle von <function>==</function> würde
6196           auf Ungleichheit getestet.</para>
6197
6198           <para>Erfahrere Benutzer können neben der Tests auf (Un-)Gleichheit
6199           auch Tests auf Übereinstimmung mit regulären Ausdrücken ohne
6200           Berücksichtung der Groß- und Kleinschreibung durchführen. Dazu dient
6201           dieselbe Syntax wie oben nur mit <function>=~</function> und
6202           <function>!~</function> als Vergleichsoperatoren.</para>
6203
6204           <para>Beispiel für einen Test, ob die Variable
6205           <varname>intnotes</varname> (interne Bemerkungen) das Wort
6206           <constant>schwierig</constant> enthält:</para>
6207
6208           <programlisting>&lt;%if intnotes =~ "schwierig"%&gt;</programlisting>
6209         </sect3>
6210
6211         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.foreach">
6212           <title>Der foreach-Block</title>
6213
6214           <programlisting>&lt;%foreach variablenname%&gt;
6215 ...
6216 &lt;%end%&gt;</programlisting>
6217
6218           <para>Fügt die Zeilen zwischen den beiden Anweisungen so oft ein,
6219           wie das Perl-Array der Variablen <varname>variablenname</varname>
6220           Elemente enthät. Dieses Konstrukt wird zur Ausgabe der einzelnen
6221           Posten einer Rechnung / eines Angebots sowie zur Ausgabe der Steuern
6222           benutzt. In jedem Durchlauf werden die <link
6223           linkend="dokumentenvorlagen-und-variablen.invoice-posten">zeilenbezogenen
6224           Variablen</link> jeweils auf den Wert für die aktuelle Position
6225           gesetzt.</para>
6226
6227           <para>Die Syntax sieht normalerweise wie folgt aus:</para>
6228
6229           <programlisting>&lt;%foreach number%&gt;
6230 Position: &lt;%runningnumber%&gt;
6231 Anzahl: &lt;%qty%&gt;
6232 Artikelnummer: &lt;%number%&gt;
6233 Beschreibung: &lt;%description%&gt;
6234 ...
6235 &lt;%end%&gt;</programlisting>
6236
6237           <para>Besonderheit in OpenDocument-Vorlagen: Tritt ein
6238           <function>&lt;%foreach%&gt;</function>-Block innerhalb einer
6239           Tabellenzelle auf, so wird die komplette Tabellenzeile so oft
6240           wiederholt wie notwendig. Tritt er außerhalb auf, so wird nur der
6241           Inhalt zwischen <function>&lt;%foreach%&gt;</function> und
6242           <function>&lt;%end%&gt;</function> wiederholt, nicht aber die
6243           komplette Zeile, in der er steht.</para>
6244         </sect3>
6245       </sect2>
6246
6247       <sect2 id="dokumentenvorlagen-und-variablen.markup">
6248         <title>Markup-Code zur Textformatierung innerhalb von
6249         Formularen</title>
6250
6251         <para>Wenn der Benutzer innhalb von Formularen in kivitendo Text
6252         anders formatiert haben möchte, so ist dies begrenzt möglich.
6253         kivitendo unterstützt die Textformatierung mit HTML-ähnlichen Tags.
6254         Der Benutzer kann z.B. bei der Artikelbeschreibung auf einer Rechnung
6255         Teile des Texts zwischen Start- und Endtags setzen. Dieser Teil wird
6256         dann automatisch in Anweisungen für das ausgewählte Vorlagenformat
6257         (HTML oder PDF über LaTeX) umgesetzt.</para>
6258
6259         <para>Die unterstützen Formatierungen sind:</para>
6260
6261         <variablelist>
6262           <varlistentry>
6263             <term>&lt;b&gt;Text&lt;/b&gt;</term>
6264
6265             <listitem>
6266               <para>Text wird in Fettdruck gesetzt.</para>
6267             </listitem>
6268           </varlistentry>
6269
6270           <varlistentry>
6271             <term>&lt;i&gt;Text&lt;/i&gt;</term>
6272
6273             <listitem>
6274               <para>Text wird kursiv gesetzt.</para>
6275             </listitem>
6276           </varlistentry>
6277
6278           <varlistentry>
6279             <term>&lt;u&gt;Text&lt;/u&gt;</term>
6280
6281             <listitem>
6282               <para>Text wird unterstrichen.</para>
6283             </listitem>
6284           </varlistentry>
6285
6286           <varlistentry>
6287             <term>&lt;s&gt;Text&lt;/s&gt;</term>
6288
6289             <listitem>
6290               <para>Text wird durchgestrichen. Diese Formatierung ist nicht
6291               bei der Ausgabe als PDF über LaTeX verfügbar.</para>
6292             </listitem>
6293           </varlistentry>
6294
6295           <varlistentry>
6296             <term>&lt;bullet&gt;</term>
6297
6298             <listitem>
6299               <para>Erzeugt einen ausgefüllten Kreis für Aufzählungen (siehe
6300               unten).</para>
6301             </listitem>
6302           </varlistentry>
6303         </variablelist>
6304
6305         <para>Der Befehl <command>&lt;bullet&gt;</command> funktioniert
6306         momentan auch nur in Latex-Vorlagen.</para>
6307       </sect2>
6308
6309       <sect2 id="dokumentenvorlagen-und-variablen.anrede"
6310              xreflabel="Hinweise zur Anrede">
6311         <title>Hinweise zur Anrede</title>
6312
6313         <para>Das Flag "natürliche Person"
6314         (<varname>natural_person</varname>) aus den Kunden- oder
6315         Lieferantenstammdaten kann in den Druckvorlagen zusammen mit
6316         dem Feld "Anrede" (<varname>greeting</varname>) z.B. dafür
6317         verwendet werden, die Anrede zwischen einer allgemeinen und
6318         einer persönlichen Anrede zu unterscheiden.
6319         <programlisting>&lt;%if natural_person%&gt;&lt;%greeting%&gt; &lt;%name%&gt;&lt;%else%&gt;Sehr geehrte Damen und Herren&lt;%end if%&gt;</programlisting>
6320         </para>
6321       </sect2>
6322
6323     </sect1>
6324
6325     <sect1 id="excel-templates">
6326       <title>Excel-Vorlagen</title>
6327
6328       <sect2 id="excel-templates.summary">
6329         <title>Zusammenfassung</title>
6330
6331         <para>Dieses Dokument beschreibt den Mechanismus, mit dem
6332         Exceltemplates abgearbeitet werden, und die Einschränkungen, die damit
6333         einhergehen.</para>
6334       </sect2>
6335
6336       <sect2 id="excel-templates.usage">
6337         <title>Bedienung</title>
6338
6339         <para>Der Excel Mechanismus muss in der Konfigurationsdatei aktiviert
6340         werden. Die Konfigurationsoption heißt <varname>excel_templates =
6341         1</varname> im Abschnitt <varname>[print_templates]</varname>.</para>
6342
6343         <para>Eine Excelvorlage kann dann unter dem Namen einer beliebigen
6344         anderen Vorlage mit der Endung <filename>.xls</filename> gespeichert
6345         werden. In den normalen Verkaufsmasken taucht nun
6346         <constant>Excel</constant> als auswählbares Format auf und kann von da
6347         an wie LaTeX- oder OpenOffice-Vorlagen benutzt werden.</para>
6348
6349         <para>Der Sonderfall der Angebote aus der Kundenmaske ist ebenfalls
6350         eine Angebotsvorlage und wird unter dem internen Namen der Angebote
6351         <filename>sales_quotation.xls</filename> gespeichert.</para>
6352       </sect2>
6353
6354       <sect2 id="excel-templates.syntax">
6355         <title>Variablensyntax</title>
6356
6357         <para>Einfache Syntax:
6358         <command>&lt;&lt;varname&gt;&gt;</command></para>
6359
6360         <para>Dabei sind <constant>&lt;&lt;</constant> und
6361         <constant>&gt;&gt;</constant> die Delimiter. Da Excel auf festen
6362         Breiten besteht, kann der Tag künstlich verlängert werden, indem
6363         weitere <constant>&lt;</constant> oder <constant>&gt;</constant>
6364         eingefügt werden. Der Tag muss nicht symmetrisch sein.
6365         Beispiel:</para>
6366
6367         <programlisting>&lt;&lt;&lt;&lt;&lt;varname&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
6368
6369         <para>Um die Limitierung der festen Breite zu reduzieren, können
6370         weitere Variablen in einem Block interpoliert werden. Whitespace wird
6371         dazwishen dann erhalten. Beispiel:</para>
6372
6373         <programlisting>&lt;&lt;&lt;&lt;&lt;varname1 varname2   varname3&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
6374
6375         <para>Die Variablen werden interpoliert, und linksbündig mit
6376         Leerzeichen auf die gewünschte Länge aufgefüllt. Ist der String zu
6377         lang, werden überzählige Zeichen abgeschnitten.</para>
6378
6379         <para>Es ist ausserdem möglich, Daten rechtsbündig darzustellen, wenn
6380         der Block mit einem Leerzeichen anfängt. Beispiel:</para>
6381
6382         <programlisting>&lt;&lt;&lt;&lt;&lt;&lt;            varname&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
6383
6384         <para>Dies würde rechtsbündig triggern. Wenn bei rechtsbündiger
6385         Ausrichtung Text abgeschnitten werden muss, wird er vom linken Ende
6386         entfernt.</para>
6387       </sect2>
6388
6389       <sect2 id="excel-templates.limitations">
6390         <title>Einschränkungen</title>
6391
6392         <para>Das Excelformat bis 2002 ist ein binäres Format, und kann nicht
6393         mit vertretbarem Aufwand editiert werden. Der Templatemechanismus
6394         beschränkt sich daher darauf, Textstellen exakt durch einen anderen
6395         Text zu ersetzen.</para>
6396
6397         <para>Aus dem gleichen Grund sind die Kontrolllstrukturen
6398         <command>&lt;%if%&gt;</command> und
6399         <command>&lt;%foreach%&gt;</command> nicht vorhanden. Der Delimiter
6400         <constant>&lt;% %&gt;</constant> kommt in den Headerinformationen
6401         evtl. vor. Deshalb wurde auf den sichereren Delimiter
6402         <constant>&lt;&lt;</constant> und <constant>&gt;&gt;</constant>
6403         gewechselt.</para>
6404       </sect2>
6405     </sect1>
6406
6407     <sect1 id="features.warehouse">
6408       <title>Mandantenkonfiguration Lager</title>
6409
6410       <para>Die Lagerverwaltung in kivitendo funktioniert standardmässig wie
6411       folgt: Wird ein Lager mit einem Lagerplatz angelegt, so gibt es die
6412       Möglichkeit hier über den Menüpunkt Lager entsprechende Warenbewegungen
6413       durchzuführen. Ferner kann jede Position eines Lieferscheins ein-, bzw.
6414       ausgelagert werden (Einkauf-, bzw. Verkauf). Es können beliebig viele
6415       Lager mit beliebig vielen Lagerplätzen abgebildet werden. Die
6416       Lagerbewegungen über einen Lieferschein erfolgt durch Anklicken jeder
6417       Einzelposition und das Auswählen dieser Position zu einem Lager mit
6418       Lagerplatz. Dieses Verfahren lässt sich schrittweise vereinfachen, je
6419       nachdem wie die Einstellungen in der Mandatenkonfiguration gesetzt
6420       werden.</para>
6421
6422       <itemizedlist>
6423         <listitem>
6424           <para><option>Auslagern über Standardlagerplatz</option> Hier wird
6425           ein zusätzlicher Knopf (Auslagern über Standard-Lagerplatz) in dem
6426           Lieferschein-Beleg hinzugefügt, der dann alle Lagerbewegungen über
6427           den Standardlagerplatz (konfigurierbar pro Ware) durchführt.</para>
6428         </listitem>
6429
6430         <listitem>
6431           <para><option>Auslagern ohne Bestandsprüfung</option> Das obige
6432           Auslagern schlägt fehl, wenn die entsprechende Menge für die
6433           Lagerbewegung nicht vorhanden ist, möchte man dies auch ignorieren
6434           und ggf. dann nachpflegen, so kann man eine Negativ-Warenmenge mit
6435           dieser Option erlauben. Hierfür muss ein entsprechender Lagerplatz
6436           (Fehlbestand, o.ä.) konfiguriert sein.</para>
6437         </listitem>
6438       </itemizedlist>
6439
6440       <para>Zusätzliche Funktionshinweise:</para>
6441
6442       <itemizedlist>
6443         <listitem>
6444           <para><option>Standard-Lagerplatz</option> Ist dieser konfiguriert,
6445           wird dies auch als Standard-Voreinstellung bei der Neuerfassung von
6446           Stammdaten → Waren / Dienstleistung / Erzeugnis verwendet.</para>
6447         </listitem>
6448
6449         <listitem>
6450           <para><option>Standard-Lagerplatz verwenden, falls keiner in
6451           Stammdaten definiert</option> Wird beim 'Auslagern über
6452           Standardlagerplatz' keine Standardlagerplatz zu der Ware gefunden,
6453           so wird mit dieser Option einfach der Standardlagerplatz
6454           verwendet.</para>
6455         </listitem>
6456       </itemizedlist>
6457     </sect1>
6458
6459     <sect1 id="features.swiss-charts-of-accounts">
6460       <title>Schweizer Kontenpläne</title>
6461
6462       <para>Seit der Version 3.5 stehen in kivitendo 3 Kontenpläne für den
6463       Einsatz in der Schweiz zur Verfügung, einer für Firmen und
6464       Organisationen, die nicht mehrwertsteuerpflichtig sind, einer für
6465       Firmen, die mehrwertsteuerpflichtig sind und einer speziell für
6466       Vereine.</para>
6467
6468       <para>Die Kontenpläne orientieren sich am in der Schweiz üblicherweise
6469       verwendeten KMU-Kontenrahmen und sind mit der Revision des
6470       Schweizerischen Obligationenrechts (OR) vom 1.1.2013 kompatibel,
6471       insbesondere <literal>Art.957a Abs.2</literal>.</para>
6472
6473       <para>Beim Vereinskontenplan sind standardmässig nur die Konten 1100
6474       (Debitoren CHF) und 1101 (Debitoren EUR) als Buchungskonten im Verkauf
6475       sowie die Konten 2000 (Kreditoren CHF) und 2001 (Kreditoren EUR) als
6476       Buchungskonten im Einkauf vorgesehen. Weitere Konten können bei Bedarf
6477       in den Konto-Detaileinstellungen als Einkaufs- oder Verkaufskonten
6478       konfiguriert werden.</para>
6479
6480       <para>Die Möglichkeit, Saldosteuersätze zu verwenden ist in der
6481       aktuellen Version von kivitendo noch nicht integriert.</para>
6482
6483       <para>Trotzdem können auch Firmen, die per Saldosteuersatz mit der
6484       Eidgenössischen Steuerverwaltung abrechnen, kivitendo bereits nutzen.
6485       Dazu wird der Kontenplan mit MWST ausgewählt. Anschliessend müssen alle
6486       Aufwandskonten editiert werden und dort der Steuersatz auf 0% gesetzt
6487       werden.</para>
6488
6489       <para>So werden bei Kreditorenbuchungen keine Vorsteuern
6490       verbucht.</para>
6491
6492       <para>Bezugssteuern für aus dem Ausland bezogene Dienstleistungen müssen
6493       manuell verbucht werden.</para>
6494
6495       <para>Wünsche für Anpassungen an den Schweizer Kontenplänen sowie
6496       Vorschläge für weitere (z.B. branchenspezifische) Kontenpläne bitte an
6497       <literal>empfang@revamp-it.ch</literal> senden.</para>
6498     </sect1>
6499
6500     <sect1 id="features.part_classification">
6501       <title>Artikelklassifizierung</title>
6502
6503       <sect2>
6504         <title>Übersicht</title>
6505
6506         <para>Die Klassifizierung von Artikeln dient einer weiteren
6507         Gliederung, um zum Beispiel den Einkauf vom Verkauf zu trennen,
6508         gekennzeichnet durch eine Beschreibung (z.B. "Einkauf") und ein Kürzel
6509         (z.B. "E"). Für jede Klassifizierung besteht eine Beschreibung und
6510         eine Abkürzung die normalerweise aus einem Zeichen besteht, kann aber
6511         auf mehrere Zeichen erweitert werden, falls zur Unterscheidung
6512         notwendig. Sinnvoll sind jedoch nur maximal 2 Zeichen.</para>
6513       </sect2>
6514
6515       <sect2>
6516         <title>Basisklassifizierung</title>
6517
6518         <para>Als Basisklassifizierungen gibt es</para>
6519
6520         <itemizedlist>
6521           <listitem>
6522             <para>Einkauf</para>
6523           </listitem>
6524
6525           <listitem>
6526             <para>Verkauf</para>
6527           </listitem>
6528
6529           <listitem>
6530             <para>Handelsware</para>
6531           </listitem>
6532
6533           <listitem>
6534             <para>Produktion</para>
6535           </listitem>
6536
6537           <listitem>
6538             <para>- keine - (diese wird bei einer Aktualisierung für alle
6539             existierenden Artikel verwendet und ist gültig für Verkauf und
6540             Einkauf)</para>
6541           </listitem>
6542         </itemizedlist>
6543
6544         <para>Es können weitere Klassifizierungen angelegt werden. So kann es
6545         z.B. für separat auszuweisende Artikel folgende Klassen geben:</para>
6546
6547         <itemizedlist>
6548           <listitem>
6549             <para>Lieferung (Logistik, Transport) mit Kürzel L</para>
6550           </listitem>
6551
6552           <listitem>
6553             <para>Material (Verpackungsmaterial) mit Kürzel M</para>
6554           </listitem>
6555         </itemizedlist>
6556       </sect2>
6557
6558       <sect2>
6559         <title>Attribute</title>
6560
6561         <para>Bisher haben die Klassifizierungen folgende Attribute, die auch
6562         alle gleichzeitg gültig sein können</para>
6563
6564         <itemizedlist>
6565           <listitem>
6566             <para>gültig für Verkauf - dieser Artikel kann im Verkauf genutzt
6567             werden</para>
6568           </listitem>
6569
6570           <listitem>
6571             <para>gültig für Einkauf - dieser Artikel kann im Einkauf genutzt
6572             werden</para>
6573           </listitem>
6574
6575           <listitem>
6576             <para>separat ausweisen - hierzu gibt es zur Dokumentengenerierung
6577             (LaTeX) eine zusätzliche Variable</para>
6578           </listitem>
6579         </itemizedlist>
6580
6581         <para>Für das Attribut "separat ausweisen" stehen in den
6582         LaTeX-Vorlagen die Variable <emphasis
6583         role="bold">&lt;%non_separate_subtotal%&gt; </emphasis>zur Verfügung,
6584         die alle nicht separat auszuweisenden Artikelkosten saldiert, sowie
6585         pro separat auszuweisenden Klassifizierungen die Variable<emphasis
6586         role="bold">&lt; %separate_X_subtotal%&gt;</emphasis>, wobei X das
6587         Kürzel der Klassifizierung ist.</para>
6588
6589         <para>Im obigen Beispiel wäre das für Lieferkosten <emphasis
6590         role="bold">&lt;%separate_L_subtotal%&gt;</emphasis> und für
6591         Verpackungsmaterial <emphasis role="bold">
6592         &lt;%separate_M_subtotal%&gt;</emphasis>.</para>
6593       </sect2>
6594
6595       <sect2>
6596         <title>Zwei-Zeichen Abkürzung</title>
6597
6598         <para>Der Typ des Artikels und die Klassifizierung werden durch zwei
6599         Buchstaben dargestellt. Der erste Buchstabe ist eine Lokalisierung des
6600         Artikel-Typs ('P','A','S'), deutsch 'W', 'E', und 'D' für Ware
6601         Erzeugnis oder Dienstleistung und ggf. weiterer Typen.</para>
6602
6603         <para>Der zweite Buchstabe (und ggf. auch ein dritter, falls nötig)
6604         entspricht der lokalisierten Abkürzung der Klassifizierung.</para>
6605
6606         <para>Diese Abkürzung wird überall beim Auflisten von Artikeln zur
6607         Erleichterung mit dargestellt.</para>
6608       </sect2>
6609     </sect1>
6610
6611     <sect1 id="features.file_managment">
6612       <title>Dateiverwaltung (Mini-DMS)</title>
6613
6614       <sect2>
6615         <title>Übersicht</title>
6616
6617         <para>Parallel zum alten WebDAV gibt es ein Datei-Management-System,
6618         das Dateien verschiedenen Typs verwaltet. Dies können</para>
6619
6620         <orderedlist>
6621           <listitem>
6622             <para>aus ERP-Daten per LaTeX Template erzeugte
6623             PDF-Dokumente,</para>
6624           </listitem>
6625
6626           <listitem>
6627             <para>zu bestimmten ERP-Daten gehörende Anhangdateien
6628             unterschiedlichen Formats,</para>
6629           </listitem>
6630
6631           <listitem>
6632             <para>per Scanner eingelesene PDF-Dateien,</para>
6633           </listitem>
6634
6635           <listitem>
6636             <para>per E-Mail empfangene Dateianhänge unterschiedlichen
6637             Formats,</para>
6638           </listitem>
6639
6640           <listitem>
6641             <para>sowie speziel für Artikel hochgeladene Bilder sein.</para>
6642           </listitem>
6643         </orderedlist>
6644
6645         <screenshot>
6646           <screeninfo>Übersicht</screeninfo>
6647
6648           <mediaobject>
6649             <imageobject>
6650               <imagedata contentwidth="600" fileref="images/DMS-Overview.png"/>
6651             </imageobject>
6652           </mediaobject>
6653         </screenshot>
6654       </sect2>
6655
6656       <sect2>
6657         <title>Struktur</title>
6658
6659         <para>Über eine vom Speichermedium unabhängige Zwischenschicht werden
6660         die Dateien und ihre Versionen in der Datenbank verwaltet. Darunter
6661         können verschiedene Implementierungen (Backends) gleichzeitig
6662         existieren:</para>
6663
6664         <itemizedlist>
6665           <listitem>
6666             <para>Dateisystem</para>
6667           </listitem>
6668
6669           <listitem>
6670             <para>WebDAV</para>
6671           </listitem>
6672
6673           <listitem>
6674             <para>Schnittstelle zu externen
6675             Dokumenten-Management-Systemen</para>
6676           </listitem>
6677
6678           <listitem>
6679             <para>andere Datenbank</para>
6680           </listitem>
6681
6682           <listitem>
6683             <para>etc ...</para>
6684           </listitem>
6685         </itemizedlist>
6686
6687         <para>Es gibt unterschiedliche Typen von Dateien. Jedem Typ läßt sich
6688         in der Mandantenkonfiguration ein bestimmtes Backend zuordnen.</para>
6689
6690         <itemizedlist>
6691           <listitem>
6692             <para>"document": Das sind entweder generierte, eingescannte oder
6693             hochgeladene PDF-Dateien, die zu bestimmten ERP-Daten
6694             (ERP-Objekte, wie z.B. Rechnung, Lieferschein) gehören.</para>
6695           </listitem>
6696
6697           <listitem>
6698             <para>"attachment": zusätzlich hochgeladene Dokumente, die an
6699             bestimmte ERP-Objekte angehängt werden, z.B. technische
6700             Zeichnungen, Aufmaße. Diese können auch für Artikel, Lieferanten
6701             und Kunden hinterlegt sein.</para>
6702           </listitem>
6703
6704           <listitem>
6705             <para>"image": Bilder für Artikel. Diese können auch verkleinert
6706             in einer Vorschau (Thumbnail) angezeigt werden.</para>
6707           </listitem>
6708         </itemizedlist>
6709
6710         <para>Zusätzlich werden in der Datenbank zu den Dateien neben der
6711         Zuordnung zu ERP-Objekten, Dateityp Dateinamen und Backend, in dem die
6712         Datei gespeichert ist, auch die Quelle der Datei notiert:</para>
6713
6714         <itemizedlist>
6715           <listitem>
6716             <para>"created": vom System erzeugte Dokumente"</para>
6717           </listitem>
6718
6719           <listitem>
6720             <para>"uploaded": hochgeladene Dokumente</para>
6721           </listitem>
6722
6723           <listitem>
6724             <para>"email": vom Mail-System empfangene Dateien</para>
6725           </listitem>
6726
6727           <listitem>
6728             <para>"scanner[1]": von einem oder mehreren Scannern erzeugte
6729             Dateien. Existieren mehrere Scanner, so sind diese durch
6730             unterschiedliche Quellennamen zu definieren.</para>
6731           </listitem>
6732         </itemizedlist>
6733
6734         <para>Je nach Dateityp sind nur bestimmte Quellen zulässig. So gibt es
6735         für "attachment" und "image" nur die Quelle "uploaded". Für "document"
6736         gibt es auf jeden Fall die Quelle "created". Die Quellen "scanner" und
6737         "email" müssen derzeit in der Datenbank konfiguriert werden (siehe
6738         <xref linkend="file_management.dbconfig"/>).</para>
6739       </sect2>
6740
6741       <sect2>
6742         <title>Anwendung</title>
6743
6744         <para>Die Daten werden bei den ERP-Objekten als extra Reiter
6745         dargestellt. Eine Verkaufsrechnung z.B. hat die Reiter "Dokumente" und
6746         "Dateianhänge".</para>
6747
6748         <screenshot>
6749           <screeninfo>Reiter "Dateianhänge"</screeninfo>
6750
6751           <mediaobject>
6752             <imageobject>
6753               <imagedata fileref="images/DMS-Anhaenge.png" scale="50"/>
6754             </imageobject>
6755           </mediaobject>
6756         </screenshot>
6757
6758         <para>Bei den Dateianhängen wird immer nur die aktuelle Version einer
6759         Datei angezeigt. Wird eine Datei mit gleichem Namen hochgeladen, so
6760         wird eine neue Version der Datei erstellt. Vorher wird der Anwender
6761         durch einen Dialog gefragt, ob er eine neue Version anlegen will oder
6762         ob er die Datei umbenennen will, falls es eine neue Datei sein
6763         soll.</para>
6764
6765         <screenshot>
6766           <screeninfo>Reiter "Dateianhänge"</screeninfo>
6767
6768           <mediaobject>
6769             <imageobject>
6770               <imagedata contentwidth="40"
6771                          fileref="images/DMS-Anhaenge-hochladen.png"
6772                          width="100"/>
6773             </imageobject>
6774           </mediaobject>
6775         </screenshot>
6776
6777         <para>Es können mehrere Dateien gleichzeitig hochgeladen werden,
6778         solange in Summe die maximale Größe nicht überschritten wird (siehe
6779         <xref linkend="file_management.clientconfig"/>).</para>
6780
6781         <screenshot>
6782           <screeninfo>Reiter "Dokumente"</screeninfo>
6783
6784           <mediaobject>
6785             <imageobject>
6786               <imagedata fileref="images/DMS-Dokumente.png" width="500"/>
6787             </imageobject>
6788           </mediaobject>
6789         </screenshot>
6790
6791         <para>Sind keine weiteren Quellen für Dokumente konfiguriert, so gibt
6792         es nur "erzeugte Dokumente". Es werden alle Versionen der generierten
6793         Datei angezeigt. Für Verkaufsrechnungen kommen keine anderen Quellen
6794         zur Geltung. Werden entsprechend der <xref
6795         linkend="file_management.dbconfig"/> zusätzliche Quellen konfiguriert,
6796         so sind diese z.B. bei Einkaufsrechnungen sichtbar:</para>
6797
6798         <screenshot>
6799           <screeninfo>Reiter "Dokumente"</screeninfo>
6800
6801           <mediaobject>
6802             <imageobject>
6803               <imagedata contentwidth="600"
6804                          fileref="images/DMS-Dokumente-Scanner.png"/>
6805             </imageobject>
6806           </mediaobject>
6807         </screenshot>
6808
6809         <para>Statt des Löschens wird hier die Datei zurück zur Quelle
6810         verschoben. Somit kann die Datei anschließend an ein anderes
6811         ERP-Objekt angehängt werden.</para>
6812
6813         <para>Derzeit sind "Titel" und "Beschreibung" noch nicht genutzt. Sie
6814         sind bisher nur bei Bildern relevant.</para>
6815       </sect2>
6816
6817       <sect2>
6818         <title>Konfigurierung</title>
6819
6820         <sect3 id="file_management.clientconfig"
6821                xreflabel="Mandantenkonfigurierung">
6822           <title>Mandantenkonfiguration</title>
6823
6824           <sect4>
6825             <title>Reiter "Features"</title>
6826
6827             <para>Unter dem Reiter <emphasis role="bold">Features</emphasis>
6828             im Abschnitt Dateimanagement ist neben dem "alten" WebDAV das
6829             Dateimangement generell zu- und abschaltbar, sowie die Zuordnung
6830             der Dateitypen zu Backends. Die Löschbarkeit von Dateien, sowie
6831             die maximale Uploadgröße sind Backend-unabhängig</para>
6832
6833             <screenshot>
6834               <screeninfo>Mandantenkonfig Reiter "Features"</screeninfo>
6835
6836               <mediaobject>
6837                 <imageobject>
6838                   <imagedata fileref="images/DMS-ClientConfig.png" width="500"/>
6839                 </imageobject>
6840               </mediaobject>
6841             </screenshot>
6842
6843             <para>Die einzelnen Backends sind einzeln einschaltbar.
6844             Spezifische Backend-Konfigurierungen sind hier noch
6845             ergänzbar.</para>
6846           </sect4>
6847
6848           <sect4>
6849             <title>Reiter "Allgemeine Dokumentenanhänge"</title>
6850
6851             <para>Unter dem Reiter <emphasis role="bold">Allgemeine
6852             Dokumentenanhänge</emphasis> kann für alle ERP-Dokumente (
6853             Angebote, Aufträge, Lieferscheine, Rechnungen im Verkauf und
6854             Einkauf ) allgemeingültige Anhänge hochgeladen werden.</para>
6855
6856             <screenshot>
6857               <screeninfo>Mandantenkonfig Reiter "Allgemeine
6858               Dokumentenanhänge"</screeninfo>
6859
6860               <mediaobject>
6861                 <imageobject>
6862                   <imagedata fileref="images/DMS-Allgemeine-Dokumentenanhaenge.png"
6863                              width="500"/>
6864                 </imageobject>
6865               </mediaobject>
6866             </screenshot>
6867
6868             <para>Diese Anhänge werden beim Generieren von PDF-Dateien an die
6869             ERP-Dokumente angehängt, z.B. AGBs oder aktuelle Angebote. Es
6870             werden in dem Fall die Daten kopiert, sodass an den ERP-Dokumenten
6871             immer die Anhänge zum Generierungszeitpunkt eingebettet
6872             sind.</para>
6873           </sect4>
6874         </sect3>
6875
6876         <sect3 id="file_management.dbconfig"
6877                xreflabel="Datenbank-Konfigurierung">
6878           <title>Datenbank-Konfigurierung</title>
6879
6880           <para>Die zusätzlichen Quellen für "email" oder ein oder mehrere
6881           Scanner sind derzeit vom Administrator direkt in der
6882           Datenbanktabelle "user_preferences" einzurichten. Die "value" ist im
6883           JSON-Format mit den jeweiligen Werten des Verzeichnisses und der
6884           Beschreibung der Quelle.</para>
6885
6886           <programlisting>
6887  id |  login    |  namespace   | version |   key    |          value
6888 ----+-----------+--------------+---------+----------+---------------------------
6889   1 | #default# | file_sources | 0.00000 | scanner1 |
6890                              {"dir":"/var/tmp/scanner1","desc":"Scanner Einkauf"}
6891   2 | #default# | file_sources | 0.00000 | scanner2 |
6892                              {"dir":"/var/tmp/scanner2","desc":"Scanner Verkauf"}
6893   3 | #default# | file_sources | 0.00000 | emails   |
6894                              {"dir":"/var/tmp/emails","desc":"Empfangene Mails" }
6895           </programlisting>
6896
6897           <para>Es ist daran gedacht, statt dem Default-Eintrag später für
6898           bestimmte Benutzer ('login') bestimmte Quellen zuzulassen. Dies wird
6899           nach Bedarf implementiert.</para>
6900         </sect3>
6901
6902         <sect3 id="file_management.kiviconfig"
6903                xreflabel="kivitendo-Konfigurationsdatei">
6904           <title>kivitendo-Konfigurationsdatei</title>
6905
6906           <para>Dort ist im Abschnitt [paths] der relative oder absolute Pfad
6907           zum Dokumentenwurzelverzeichnis einzutragen. Dieser muss für den
6908           Webserver schreib- und lesbar sein, jedoch nicht ausführbar.</para>
6909
6910           <programlisting>
6911 [paths]
6912 document_path = /var/local/kivi_documents
6913           </programlisting>
6914
6915           <para>Unter diesem Wurzelverzeichnis wird pro Mandant automatisch
6916           ein Unterverzeichnis mit der ID des Mandanten angelegt.</para>
6917         </sect3>
6918       </sect2>
6919     </sect1>
6920
6921     <sect1>
6922       <title>Webshop-Api</title>
6923
6924       <para>Das Shopmodul bietet die Möglichkeit Onlineshopartikel und
6925       Onlineshopbestellungen zu verwalten und zu bearbeiten.</para>
6926
6927       <para>Es ist Multishopfähig, d.h. Artikel können mehreren oder
6928       unterschiedlichen Shops zugeordnet werden. Bestellungen können aus
6929       mehreren Shops geholt werden.</para>
6930
6931       <para>Zur Zeit bietet das Modul nur einen Connector zur REST-Api von
6932       Shopware. Weitere Connectoren können dazu programmiert und eingerichtet
6933       werden.</para>
6934
6935       <sect2>
6936         <title>Rechte für die Webshopapi</title>
6937
6938         <para>In der Administration können folgende Rechte vergeben
6939         werden</para>
6940
6941         <itemizedlist>
6942           <listitem>
6943             <para>Webshopartikel anlegen und bearbeiten</para>
6944           </listitem>
6945
6946           <listitem>
6947             <para>Shopbestellungen holen und bearbeiten</para>
6948           </listitem>
6949
6950           <listitem>
6951             <para>Shop anlegen und bearbeiten</para>
6952           </listitem>
6953         </itemizedlist>
6954       </sect2>
6955
6956       <sect2>
6957         <title>Konfiguration</title>
6958
6959         <para>Unter System-&gt;Webshops können Shops angelegt und konfiguriert
6960         werden</para>
6961
6962         <mediaobject>
6963           <imageobject>
6964             <imagedata contentdepth="500" contentwidth="700"
6965                        fileref="images/Shop_Listing.png"/>
6966           </imageobject>
6967         </mediaobject>
6968       </sect2>
6969
6970       <sect2>
6971         <title>Webshopartikel</title>
6972
6973         <sect3>
6974           <title>Shopvariablenreiter in Artikelstammdaten</title>
6975
6976           <para>Mit dem Recht "Shopartikel anlegen und bearbeiten" und des
6977           Markers <emphasis role="bold">"Shopartikel" in den Basisdaten
6978           </emphasis>zeigt sich der Reiter "Shopvariablen" in den
6979           Artikelstammdaten. Hier können jetzt die Artikel mit
6980           unterschiedlichen Beschreibung und/oder Preisen für die
6981           konfigutierten Shops angelegt und bearbeitet werden. An dieser
6982           Stelle können auch beliebig viele Bilder dem Shopartikel zugeordnet
6983           werden. Artikelbilder gelten für alle Shops.</para>
6984
6985           <mediaobject>
6986             <imageobject>
6987               <imagedata contentdepth="500" contentwidth="600"
6988                          fileref="images/Shop_Artikel.png"/>
6989             </imageobject>
6990           </mediaobject>
6991
6992           <para>Die Artikelgruppen werden direkt vom Shopsystem geholt somit
6993           ist es möglich einen Artikel auch mehreren Gruppen
6994           zuzuordenen</para>
6995         </sect3>
6996
6997         <sect3>
6998           <title>Shopartikelliste</title>
6999
7000           <para>Unter dem Menu Webshop-&gt;Webshop Artikel hat man nochmal
7001           eine Gesamtübersicht. Von hier aus ist es möglich Artikel im Stapel
7002           unter verschiedenen Kriterien &lt;alles&gt;&lt;nur Preis&gt;&lt;nur
7003           Bestand&gt;&lt;Preis und Bestand&gt; an die jeweiligen Shops
7004           hochzuladen.</para>
7005
7006           <mediaobject>
7007             <imageobject>
7008               <imagedata fileref="images/Shop_Artikel_Listing.png"/>
7009             </imageobject>
7010           </mediaobject>
7011         </sect3>
7012       </sect2>
7013
7014       <sect2>
7015         <title>Bestellimport</title>
7016
7017         <para>Unter dem Menupunkt Webshop-&gt;Webshop Import öffnet sich die
7018         Bestellimportsliste. Hier ist sind Möglichkeiten gegeben Neue
7019         Bestellungen vom Shop abzuholen, geholte Bestellungen im Stapel oder
7020         einzeln als Auftrag zu transferieren. Die Liste kann nach
7021         verschiedenen Kriterien gefiltert werden.</para>
7022
7023         <mediaobject>
7024           <imageobject>
7025             <imagedata fileref="images/Shop_Bestell.png"/>
7026           </imageobject>
7027         </mediaobject>
7028
7029         <para>Bei Einträgen in der Liste.</para>
7030
7031         <itemizedlist>
7032           <listitem>
7033             <para>keine Kundennummer: Es gibt ähnliche Kundendatensätze und
7034             der Datensatz konnte nicht eindeutig zugewiesen werden.</para>
7035           </listitem>
7036
7037           <listitem>
7038             <para>Kundennummer und Rechnungen rot hinterlegt: Der Kunde hat
7039             offene Posten und kann deswegen nicht im Stapel übernommen
7040             werden.</para>
7041           </listitem>
7042
7043           <listitem>
7044             <para>Rechnungsadresse grün hinterlegt: Der Kunde konnte eindeutig
7045             einem Datensatz zugeordnet werden. Die Shopbestellung kann im
7046             Stapel mit dem Button "Anwenden" und wenn markiert als Auftrag
7047             übernommen werden.</para>
7048           </listitem>
7049
7050           <listitem>
7051             <para>Kundennummer vorhanden, aber die Checkbox "Auftrag
7052             erstellen" fehlt. Der Kunde hat vermutlich eine
7053             Shopauftragssperre.</para>
7054           </listitem>
7055
7056           <listitem>
7057             <para>Lieferadresse grau hinterlegt: Optische Anzeige, dass es
7058             sich um eine unterschiedliche Lieferadresse handelt.
7059             Lieferadressen werden aber grundsätzlich beim Transferieren zu
7060             Aufträgen mit übernommen.</para>
7061           </listitem>
7062
7063           <listitem>
7064             <para>In der Spalte Positionen/Betrag/Versandkosten zeigt sich ein
7065             tooltip zu den Positionen.</para>
7066           </listitem>
7067         </itemizedlist>
7068
7069         <para>Maske Auftrag erstellen</para>
7070
7071         <para>Viele Shopsysteme haben drei verschieden Adresstypen Kunden-,
7072         Rechnungs-, und Lieferadresse, die sich auch alle unterscheiden
7073         können. Diese werden im oberen Bereich angezeigt. Es ist möglich jede
7074         dieser Adresse einzeln in kivitendo als Kunde zu übernehmen. Es werden
7075         die Werte Formulareingabe übernommen. Es wird bei einer Änderung
7076         allerdings nur diese in die kivitendo Kundenstammdaten übernommen, die
7077         Shopbestellung bleibt bestehen.</para>
7078
7079         <para>Mit der mittleren Adresse(Rechnungsadresse) im oberen Bereich,
7080         kann ich den ausgewählten kivitendodatensatz des mittleren Bereich
7081         überschreiben. Das ist sinnvoll, wenn ich erkenne, das der Kunde z.B.
7082         umgezogen ist.</para>
7083
7084         <para>Im mittleren Bereich das Adresslisting zeigt:</para>
7085
7086         <itemizedlist>
7087           <listitem>
7088             <para>Rot hinterlegt: Kunde hat eine Shopauftragssperre, diese
7089             muss zuerst deaktiviert werden bevor ich diesem Kunden eine
7090             Shopbestellung zuordnen kann.</para>
7091           </listitem>
7092
7093           <listitem>
7094             <para>Kundenname fett und rot: Hier hat der Kunde eine Bemerkung
7095             in den Stammdaten. Ein Tooltip zeigt diese Bemerkung. Das kann dan
7096             auch der Grund für die Auftragssperre sein.</para>
7097           </listitem>
7098
7099           <listitem>
7100             <para>Die Buttons "Auftrag erstellen" und "Kunde mit
7101             Rechnungsadresse überschreiben" zeigen sich erst, wenn ein Kunde
7102             aus dem Listing ausgewählt ist.</para>
7103           </listitem>
7104
7105           <listitem>
7106             <para>Es ist aber möglich die Shopbestellung zu löschen.</para>
7107           </listitem>
7108
7109           <listitem>
7110             <para>Ist eine Bestellung schon übernommen, zeigen sich an dieser
7111             Stelle, die dazugehörigen Belegverknüpfungen.</para>
7112           </listitem>
7113         </itemizedlist>
7114       </sect2>
7115
7116       <sect2>
7117         <title>Mapping der Daten</title>
7118
7119         <para>Das Mapping der kivitendo Daten mit den Shopdaten geschieht in
7120         der Datei SL/ShopConnector/&lt;SHOPCONNECTORNAME&gt;.pm
7121         z.B.:SL/ShopConnector/Shopware.pm</para>
7122
7123         <para>In dieser Datei gibt es einen Bereich wo die Bestellpostionen,
7124         die Bestellkopfdaten und die Artikeldaten gemapt werden. In dieser
7125         Datei kann ein individelles Mapping dann gemacht werden. Zu Shopware
7126         gibt es hier eine sehr gute Dokumentation: <ulink
7127         url="https://developers.shopware.com/developers-guide/rest-api/">https://developers.shopware.com/developers-guide/rest-api/</ulink></para>
7128       </sect2>
7129     </sect1>
7130         <sect1 id="features.zugferd">
7131                 <title>ZUGFeRD Rechnungen</title>
7132                 <sect2 id="features.zugferd.preamble">
7133                         <title>Vorbedingung</title>
7134          <para>
7135           Für die Erstellung von ZUGFeRD PDFs wird TexLive2018 oder höher benötigt.
7136          </para>
7137         <note>
7138          <para>
7139           Wer kein TexLive2018 oder höher installieren kann, kann eine lokale Umgebung nur für kivitendo wie folgt erzeugen:
7140          </para>
7141         <programlisting>
7142         1. Download des offiziellen Installers von https://www.tug.org/texlive/quickinstall.html
7143
7144         2. Installer ausführen, Standard-Ort für Installation belassen, evtl. ein paar Pakete abwählen, installieren lassen
7145
7146         3. Ein kleine Script »run_pdflatex.sh« anlegen, das den PATH auf das  Installationsverezichnis setzt und pdflatex ausführt:
7147
7148         ------------------------------------------------------------
7149         #!/bin/bash
7150
7151         export PATH=/usr/local/texlive/2020/bin/x86_64-linux:$PATH
7152         hash -r
7153
7154         exec pdflatex &quot;$@&quot;
7155         ------------------------------------------------------------
7156
7157         4. In config/kivitendo.conf den Parameter »latex« auf den Pfad zu »run_pdflatex.sh« setzen
7158
7159         5. Webserver neu starten
7160         </programlisting>
7161       </note>
7162     </sect2>
7163                 <sect2 id="features.zugferd.summary">
7164                         <title>Übersicht</title>
7165
7166                         <para>Mit der Version 3.5.6 bietet kivitendo die Möglichkeit ZUGFeRD
7167                         Rechnungen zu erstellen, sowie auch  ZUGFeRD Rechnungen direkt in
7168                         kivitendo einzulesen. </para>
7169
7170                         <para>Bei  ZUGFeRD Rechnungen handelt es sich um eine PDF Datei in
7171                         der eine XML-Datei eingebettet ist. Der Aufbau der XML-Datei ist
7172                         standardisiert und ermöglicht so den Austausch zwischen
7173                         den verschiedenen Softwareprodukten. Kivitendo setzt mit der
7174                         Version 3.5.6 den ZUGFeRD 2.1 Standard um.</para>
7175
7176                         <para>Weiter Details zu ZUGFeRD sind unter diesem Link zu finden:
7177                         <ulink>https://www.ferd-net.de/standards/was-ist-zugferd/index.html</ulink>
7178       </para>
7179                 </sect2>
7180
7181                 <sect2 id="features.zugferd.create_zugferd_bills">
7182
7183                         <title>Erstellen von ZUGFeRD Rechnungen in Kivitendo</title>
7184                         <para>Für die Erstellung von ZUGFeRD Rechnungen bedarf es in
7185                         kivitendo zwei Dinge:</para>
7186
7187                         <orderedlist>
7188
7189                                 <listitem>
7190                                         <para>Die Erstellung muss in der Mandantenkonfiguration
7191                                         aktiviert sein</para>
7192                                 </listitem>
7193
7194                                 <listitem>
7195                                         <para>Beim mindestens einem Bankkonto muss die Option
7196                                         „Nutzung von ZUGFeRD“ aktiviert sein</para>
7197                                 </listitem>
7198
7199                         </orderedlist>
7200                         <sect3>
7201                                 <title>Mandantenkonfiguration</title>
7202
7203                                 <para>Die Einstellung für die Erstellung von ZUGFeRD Rechnungen
7204                                 erfolgt unter „System“ → „Mandatenkonfiguration“ → „Features“.
7205                                 Im Abschnitt „Einkauf und Verkauf“ finden Sie die Einstellung
7206                                 „Verkaufsrechnungen mit ZUGFeRD-Daten erzeugen“.
7207                                 Hier besteht die Auswahl zwischen:</para>
7208
7209                                 <itemizedlist>
7210                                         <listitem>
7211                                                 <para>ZUGFeRD-Rechnungen erzeugen</para>
7212                                         </listitem>
7213
7214                                         <listitem>
7215                                                 <para>ZUGFeRD-Rechnungen im Testmodus erzeugen</para>
7216                                         </listitem>
7217
7218                                         <listitem>
7219                                                 <para>Keine ZUGFeRD Rechnungen erzeugen</para>
7220                                         </listitem>
7221
7222                                 </itemizedlist>
7223
7224                                 <para>Rechnungen die als PDF erzeugt werden, werden je nach
7225                                 Einstellung nun im ZUGFeRD Format ausgegeben.</para>
7226
7227                         </sect3>
7228
7229                         <sect3>
7230                                 <title>Konfiguration der Bankkonten</title>
7231
7232                                 <para>Unter „System → Bankkonten“ muss bei mindestens einem
7233                                 Bankkonto die Option „Nutzung mit ZUGFeRD“ auf „Ja“ gestellt
7234                                 werden.</para>
7235                         </sect3>
7236
7237                 </sect2>
7238
7239                 <sect2 id="features.zugferd.read_zugferd_bills">
7240
7241                         <title>Einlesen von ZUGFeRD Rechnungen in Kivitendo</title>
7242
7243                         <para>Es lassen sich auch Rechnungen von Kreditoren, die im
7244                         ZUGFeRD Format erstellt wurden, nach Kivitendo importieren.
7245                         Hierfür müssen auch zwei Voraussetzungen erfüllt werden:
7246                         </para>
7247
7248                         <orderedlist>
7249
7250                                 <listitem>
7251                                         <para>Beim Lieferanten muss die Umsatzsteuer-ID und das
7252                                         Bankkonto hinterlegt sein</para>
7253                                 </listitem>
7254
7255                                 <listitem>
7256                                         <para>Für den Kreditoren muss eine Buchungsvorlage existieren.</para>
7257                                 </listitem>
7258
7259                         </orderedlist>
7260
7261                         <para>Wenn diese Voraussetzungen erfüllt sind, kann die Rechnung
7262                         über „Finanzbuchhaltung“ → „ZUGFeRD Import“ über die „Durchsuchen“
7263                         Schaltfläche ausgewählt werden und über die Schaltfläche „Import“
7264                         eingeladen werden. Es öffnet sich daraufhin die Kreditorenbuchung.
7265                         Die auslesbaren Daten aus dem eingebetteten XML der PDF Datei
7266                         werden in der Kreditorenbuchung ergänzt.</para>
7267
7268                 </sect2>
7269
7270         </sect1>
7271
7272   </chapter>
7273
7274   <chapter>
7275     <title>Entwicklerdokumentation</title>
7276
7277     <sect1 id="devel.globals" xreflabel="Globale Variablen">
7278       <title>Globale Variablen</title>
7279
7280       <sect2>
7281         <title>Wie sehen globale Variablen in Perl aus?</title>
7282
7283         <para>Globale Variablen liegen in einem speziellen namespace namens
7284         "main", der von überall erreichbar ist. Darüber hinaus sind bareword
7285         globs global und die meisten speziellen Variablen sind...
7286         speziell.</para>
7287
7288         <para>Daraus ergeben sich folgende Formen:</para>
7289
7290         <variablelist>
7291           <varlistentry>
7292             <term><literal>$main::form</literal></term>
7293
7294             <listitem>
7295               <para>expliziter Namespace "main"</para>
7296             </listitem>
7297           </varlistentry>
7298
7299           <varlistentry>
7300             <term><literal>$::form</literal></term>
7301
7302             <listitem>
7303               <para>impliziter Namespace "main"</para>
7304             </listitem>
7305           </varlistentry>
7306
7307           <varlistentry>
7308             <term><literal>open FILE, "file.txt"</literal></term>
7309
7310             <listitem>
7311               <para><varname>FILE</varname> ist global</para>
7312             </listitem>
7313           </varlistentry>
7314
7315           <varlistentry>
7316             <term><literal>$_</literal></term>
7317
7318             <listitem>
7319               <para>speziell</para>
7320             </listitem>
7321           </varlistentry>
7322         </variablelist>
7323
7324         <para>Im Gegensatz zu <productname>PHP</productname> gibt es kein
7325         Schlüsselwort wie "<function>global</function>", mit dem man
7326         importieren kann. <function>my</function>, <function>our</function>
7327         und <function>local</function> machen was anderes.</para>
7328
7329         <variablelist>
7330           <varlistentry>
7331             <term><literal>my $form</literal></term>
7332
7333             <listitem>
7334               <para>lexikalische Variable, gültig bis zum Ende des
7335               Scopes</para>
7336             </listitem>
7337           </varlistentry>
7338
7339           <varlistentry>
7340             <term><literal>our $form</literal></term>
7341
7342             <listitem>
7343               <para><varname>$form</varname> referenziert ab hier
7344               <varname>$PACKAGE::form</varname>.</para>
7345             </listitem>
7346           </varlistentry>
7347
7348           <varlistentry>
7349             <term><literal>local $form</literal></term>
7350
7351             <listitem>
7352               <para>Alle Änderungen an <varname>$form</varname> werden am Ende
7353               des scopes zurückgesetzt</para>
7354             </listitem>
7355           </varlistentry>
7356         </variablelist>
7357       </sect2>
7358
7359       <sect2>
7360         <title>Warum sind globale Variablen ein Problem?</title>
7361
7362         <para>Das erste Problem ist <productname>FCGI</productname>.</para>
7363
7364         <para><productname>SQL-Ledger</productname> hat fast alles im globalen
7365         namespace abgelegt, und erwartet, dass es da auch wiederzufinden ist.
7366         Unter <productname>FCGI</productname> müssen diese Sachen aber wieder
7367         aufgeräumt werden, damit sie nicht in den nächsten Request kommen.
7368         Einige Sachen wiederum sollen nicht gelöscht werden, wie zum Beispiel
7369         Datenbankverbindungen, weil die sehr lange zum Initialisieren
7370         brauchen.</para>
7371
7372         <para>Das zweite Problem ist <function>strict</function>. Unter
7373         <function>strict</function> werden alle Variablen die nicht explizit
7374         mit <function>Package</function>, <function>my</function> oder
7375         <function>our</function> angegeben werden als Tippfehler angemarkert,
7376         dies hat, seit der Einführung, u.a. schon so manche langwierige
7377         Bug-Suche verkürzt. Da globale Variablen aber implizit mit Package
7378         angegeben werden, werden die nicht geprüft, und somit kann sich
7379         schnell ein Tippfehler einschleichen.</para>
7380       </sect2>
7381
7382       <sect2>
7383         <title>Kanonische globale Variablen</title>
7384
7385         <para>Um dieses Problem im Griff zu halten gibt es einige wenige
7386         globale Variablen, die kanonisch sind, d.h. sie haben bestimmte
7387         vorgegebenen Eigenschaften, und alles andere sollte anderweitig
7388         umhergereicht werden.</para>
7389
7390         <para>Diese Variablen sind im Moment die folgenden neun:</para>
7391
7392         <itemizedlist>
7393           <listitem>
7394             <para><varname>$::form</varname></para>
7395           </listitem>
7396
7397           <listitem>
7398             <para><varname>%::myconfig</varname></para>
7399           </listitem>
7400
7401           <listitem>
7402             <para><varname>$::locale</varname></para>
7403           </listitem>
7404
7405           <listitem>
7406             <para><varname>$::lxdebug</varname></para>
7407           </listitem>
7408
7409           <listitem>
7410             <para><varname>$::auth</varname></para>
7411           </listitem>
7412
7413           <listitem>
7414             <para><varname>$::lx_office_conf</varname></para>
7415           </listitem>
7416
7417           <listitem>
7418             <para><varname>$::instance_conf</varname></para>
7419           </listitem>
7420
7421           <listitem>
7422             <para><varname>$::dispatcher</varname></para>
7423           </listitem>
7424
7425           <listitem>
7426             <para><varname>$::request</varname></para>
7427           </listitem>
7428         </itemizedlist>
7429
7430         <para>Damit diese nicht erneut als Müllhalde missbraucht werden, im
7431         Folgenden eine kurze Erläuterung der bestimmten vorgegebenen
7432         Eigenschaften (Konventionen):</para>
7433
7434         <sect3>
7435           <title>$::form</title>
7436
7437           <itemizedlist>
7438             <listitem>
7439               <para>Ist ein Objekt der Klasse
7440               "<classname>Form</classname>"</para>
7441             </listitem>
7442
7443             <listitem>
7444               <para>Wird nach jedem Request gelöscht</para>
7445             </listitem>
7446
7447             <listitem>
7448               <para>Muss auch in Tests und Konsolenscripts vorhanden
7449               sein.</para>
7450             </listitem>
7451
7452             <listitem>
7453               <para>Enthält am Anfang eines Requests die Requestparameter vom
7454               User</para>
7455             </listitem>
7456
7457             <listitem>
7458               <para>Kann zwar intern über Requestgrenzen ein Datenbankhandle
7459               cachen, das wird aber momentan absichtlich zerstört</para>
7460             </listitem>
7461           </itemizedlist>
7462
7463           <para><varname>$::form</varname> wurde unter <productname>SQL
7464           Ledger</productname> als Gottobjekt für alles missbraucht. Sämtliche
7465           alten Funktionen unter SL/ mutieren <varname>$::form</varname>, das
7466           heißt, alles was einem lieb ist (alle Variablen die einem ans Herz
7467           gewachsen sind), sollte man vor einem Aufruf (!) von zum Beispiel
7468           <function>IS-&gt;retrieve_customer()</function> in Sicherheit
7469           bringen.</para>
7470
7471           <para>Z.B. das vom Benutzer eingestellte Zahlenformat, bevor man
7472           Berechnung in einem bestimmten Format durchführt (SL/Form.pm Zeile
7473           3552, Stand version 2.7beta), um dies hinterher wieder auf den
7474           richtigen Wert zu setzen:</para>
7475
7476           <programlisting>  my $saved_numberformat    = $::myconfig{numberformat};
7477   $::myconfig{numberformat} = $numberformat;
7478   # (...) div Berechnungen
7479   $::myconfig{numberformat} = $saved_numberformat;</programlisting>
7480
7481           <para>Das Objekt der Klasse Form hat leider im Moment noch viele
7482           zentrale Funktionen die vom internen Zustand abhängen, deshalb bitte
7483           nie einfach zerstören oder überschreiben (zumindestens nicht kurz
7484           vor einem Release oder in Absprache über bspw. die devel-Liste ;-).
7485           Es geht ziemlich sicher etwas kaputt.</para>
7486
7487           <para><varname>$::form</varname> ist gleichzeitig der Standard Scope
7488           in den <productname>Template::Toolkit</productname> Templates
7489           außerhalb der Controller: der Ausdruck <function>[% var
7490           %]</function> greift auf <varname>$::form-&gt;{var}</varname> zu.
7491           Unter Controllern ist der Standard Scope anders, da lautet der
7492           Zugriff <function>[% FORM.var %]</function>. In Druckvorlagen sind
7493           normale Variablen ebenfall im <varname>$::form</varname> Scope, d.h.
7494           <function>&lt;%var%&gt;</function> zeigt auf
7495           <varname>$::form-&gt;{var}</varname>. Nochmal von der anderen Seite
7496           erläutert, innerhalb von (Web-)Templates sieht man häufiger solche
7497           Konstrukte:</para>
7498
7499           <programlisting>[%- IF business %]
7500 # (... Zeig die Auswahlliste Kunden-/Lieferantentyp an)
7501 [%- END %]</programlisting>
7502
7503           <para>Entweder wird hier dann $::form-&gt;{business} ausgewertet
7504           oder aber der Funktion
7505           <function>$form-&gt;parse_html_template</function> wird explizit
7506           noch ein zusätzlicher Hash übergeben, der dann auch in den
7507           (Web-)Templates zu Verfügung steht, bspw. so:</para>
7508
7509           <programlisting>$form-&gt;parse_html_template("is/form_header", \%TMPL_VAR);</programlisting>
7510
7511           <para>Innerhalb von Schleifen wird
7512           <varname>$::form-&gt;{TEMPLATE_ARRAYS}{var}[$index]</varname>
7513           bevorzugt, wenn vorhanden. Ein Beispiel findet sich in SL/DO.pm,
7514           welches über alle Positionen eines Lieferscheins in Schleife
7515           läuft:</para>
7516
7517           <programlisting>for $i (1 .. $form-&gt;{rowcount}) {
7518   # ...
7519   push @{ $form-&gt;{TEMPLATE_ARRAYS}{runningnumber} },   $position;
7520   push @{ $form-&gt;{TEMPLATE_ARRAYS}{number} },          $form-&gt;{"partnumber_$i"};
7521   push @{ $form-&gt;{TEMPLATE_ARRAYS}{description} },     $form-&gt;{"description_$i"};
7522   # ...
7523 }</programlisting>
7524         </sect3>
7525
7526         <sect3>
7527           <title>%::myconfig</title>
7528
7529           <itemizedlist>
7530             <listitem>
7531               <para>Das einzige Hash unter den globalen Variablen</para>
7532             </listitem>
7533
7534             <listitem>
7535               <para>Wird spätestens benötigt wenn auf die Datenbank
7536               zugegriffen wird</para>
7537             </listitem>
7538
7539             <listitem>
7540               <para>Wird bei jedem Request neu erstellt.</para>
7541             </listitem>
7542
7543             <listitem>
7544               <para>Enthält die Userdaten des aktuellen Logins</para>
7545             </listitem>
7546
7547             <listitem>
7548               <para>Sollte nicht ohne Filterung irgendwo gedumpt werden oder
7549               extern serialisiert werden, weil da auch der Datenbankzugriff
7550               für diesen user drinsteht.</para>
7551             </listitem>
7552
7553             <listitem>
7554               <para>Enthält unter anderem Datumsformat dateformat und
7555               Nummernformat numberformat</para>
7556             </listitem>
7557
7558             <listitem>
7559               <para>Enthält Datenbankzugriffinformationen</para>
7560             </listitem>
7561           </itemizedlist>
7562
7563           <para><varname>%::myconfig</varname> ist im Moment der Ersatz für
7564           ein Userobjekt. Die meisten Funktionen, die etwas anhand des
7565           aktuellen Users entscheiden müssen, befragen
7566           <varname>%::myconfig</varname>. Innerhalb der Anwendungen sind dies
7567           überwiegend die Daten, die sich unter <guimenu>Programm</guimenu>
7568           -&gt; <guimenuitem>Einstellungen</guimenuitem> befinden, bzw. die
7569           Informationen über den Benutzer die über die
7570           Administrator-Schnittstelle eingegeben wurden.</para>
7571         </sect3>
7572
7573         <sect3>
7574           <title>$::locale</title>
7575
7576           <itemizedlist>
7577             <listitem>
7578               <para>Objekt der Klasse "Locale"</para>
7579             </listitem>
7580
7581             <listitem>
7582               <para>Wird pro Request erstellt</para>
7583             </listitem>
7584
7585             <listitem>
7586               <para>Muss auch für Tests und Scripte immer verfügbar
7587               sein.</para>
7588             </listitem>
7589
7590             <listitem>
7591               <para>Cached intern über Requestgrenzen hinweg benutzte
7592               Locales</para>
7593             </listitem>
7594           </itemizedlist>
7595
7596           <para>Lokalisierung für den aktuellen User. Alle Übersetzungen,
7597           Zahlen- und Datumsformatierungen laufen über dieses Objekt.</para>
7598         </sect3>
7599
7600         <sect3>
7601           <title>$::lxdebug</title>
7602
7603           <itemizedlist>
7604             <listitem>
7605               <para>Objekt der Klasse "LXDebug"</para>
7606             </listitem>
7607
7608             <listitem>
7609               <para>Wird global gecached</para>
7610             </listitem>
7611
7612             <listitem>
7613               <para>Muss immer verfügbar sein, in nahezu allen
7614               Funktionen</para>
7615             </listitem>
7616           </itemizedlist>
7617
7618           <para><varname>$::lxdebug</varname> stellt Debuggingfunktionen
7619           bereit, wie "<function>enter_sub</function>" und
7620           "<function>leave_sub</function>", mit denen in den alten Modulen ein
7621           brauchbares Tracing gebaut ist, "<function>log_time</function>", mit
7622           der man die Wallclockzeit seit Requeststart loggen kann, sowie
7623           "<function>message</function>" und "<function>dump</function>" mit
7624           denen man flott Informationen ins Log (tmp/kivitendo-debug.log)
7625           packen kann.</para>
7626
7627           <para>Beispielsweise so:</para>
7628
7629           <programlisting>$main::lxdebug-&gt;message(0, 'Meine Konfig:' . Dumper (%::myconfig));
7630 $main::lxdebug-&gt;message(0, 'Wer bin ich? Kunde oder Lieferant:' . $form-&gt;{vc});</programlisting>
7631         </sect3>
7632
7633         <sect3>
7634           <title>$::auth</title>
7635
7636           <itemizedlist>
7637             <listitem>
7638               <para>Objekt der Klasse "SL::Auth"</para>
7639             </listitem>
7640
7641             <listitem>
7642               <para>Wird global gecached</para>
7643             </listitem>
7644
7645             <listitem>
7646               <para>Hat eine permanente DB Verbindung zur Authdatenbank</para>
7647             </listitem>
7648
7649             <listitem>
7650               <para>Wird nach jedem Request resettet.</para>
7651             </listitem>
7652           </itemizedlist>
7653
7654           <para><varname>$::auth</varname> stellt Funktionen bereit um die
7655           Rechte des aktuellen Users abzufragen. Obwohl diese Informationen
7656           vom aktuellen User abhängen wird das Objekt aus
7657           Geschwindigkeitsgründen nur einmal angelegt und dann nach jedem
7658           Request kurz resettet.</para>
7659
7660           <para>Dieses Objekt kapselt auch den gerade aktiven Mandanten.
7661           Dessen Einstellungen können über
7662           <literal>$::auth-&gt;client</literal> abgefragt werden; Rückgabewert
7663           ist ein Hash mit den Werten aus der Tabelle
7664           <literal>auth.clients</literal>.</para>
7665         </sect3>
7666
7667         <sect3>
7668           <title>$::lx_office_conf</title>
7669
7670           <itemizedlist>
7671             <listitem>
7672               <para>Objekt der Klasse
7673               "<classname>SL::LxOfficeConf</classname>"</para>
7674             </listitem>
7675
7676             <listitem>
7677               <para>Global gecached</para>
7678             </listitem>
7679
7680             <listitem>
7681               <para>Repräsentation der
7682               <filename>config/kivitendo.conf[.default]</filename>-Dateien</para>
7683             </listitem>
7684           </itemizedlist>
7685
7686           <para>Globale Konfiguration. Configdateien werden zum Start gelesen
7687           und danach nicht mehr angefasst. Es ist derzeit nicht geplant, dass
7688           das Programm die Konfiguration ändern kann oder sollte.</para>
7689
7690           <para>Beispielsweise ist über den Konfigurationseintrag [debug] die
7691           Debug- und Trace-Log-Datei wie folgt konfiguriert und
7692           verfügbar:</para>
7693
7694           <programlisting>[debug]
7695 file_name = /tmp/kivitendo-debug.log</programlisting>
7696
7697           <para>ist der Key <varname>file</varname> im Programm als
7698           <varname>$::lx_office_conf-&gt;{debug}{file}</varname>
7699           erreichbar.</para>
7700
7701           <warning>
7702             <para>Zugriff auf die Konfiguration erfolgt im Moment über
7703             Hashkeys, sind also nicht gegen Tippfehler abgesichert.</para>
7704           </warning>
7705         </sect3>
7706
7707         <sect3>
7708           <title>$::instance_conf</title>
7709
7710           <itemizedlist>
7711             <listitem>
7712               <para>Objekt der Klasse
7713               "<classname>SL::InstanceConfiguration</classname>"</para>
7714             </listitem>
7715
7716             <listitem>
7717               <para>wird pro Request neu erstellt</para>
7718             </listitem>
7719           </itemizedlist>
7720
7721           <para>Funktioniert wie <varname>$::lx_office_conf</varname>,
7722           speichert aber Daten die von der Instanz abhängig sind. Eine Instanz
7723           ist hier eine Mandantendatenbank. Beispielsweise überprüft
7724           <programlisting>$::instance_conf-&gt;get_inventory_system eq 'perpetual'</programlisting>
7725           ob die berüchtigte Bestandsmethode zur Anwendung kommt.</para>
7726         </sect3>
7727
7728         <sect3>
7729           <title>$::dispatcher</title>
7730
7731           <itemizedlist>
7732             <listitem>
7733               <para>Objekt der Klasse
7734               "<varname>SL::Dispatcher</varname>"</para>
7735             </listitem>
7736
7737             <listitem>
7738               <para>wird pro Serverprozess erstellt.</para>
7739             </listitem>
7740
7741             <listitem>
7742               <para>enthält Informationen über die technische Verbindung zum
7743               Server</para>
7744             </listitem>
7745           </itemizedlist>
7746
7747           <para>Der dritte Punkt ist auch der einzige Grund warum das Objekt
7748           global gespeichert wird. Wird vermutlich irgendwann in einem anderen
7749           Objekt untergebracht.</para>
7750         </sect3>
7751
7752         <sect3>
7753           <title>$::request</title>
7754
7755           <itemizedlist>
7756             <listitem>
7757               <para>Hashref (evtl später Objekt)</para>
7758             </listitem>
7759
7760             <listitem>
7761               <para>Wird pro Request neu initialisiert.</para>
7762             </listitem>
7763
7764             <listitem>
7765               <para>Keine Unterstruktur garantiert.</para>
7766             </listitem>
7767           </itemizedlist>
7768
7769           <para><varname>$::request</varname> ist ein generischer Platz um
7770           Daten "für den aktuellen Request" abzulegen. Sollte nicht für action
7771           at a distance benutzt werden, sondern um lokales memoizing zu
7772           ermöglichen, das garantiert am Ende des Requests zerstört
7773           wird.</para>
7774
7775           <para>Vieles von dem, was im moment in <varname>$::form</varname>
7776           liegt, sollte eigentlich hier liegen. Die groben
7777           Differentialkriterien sind:</para>
7778
7779           <itemizedlist>
7780             <listitem>
7781               <para>Kommt es vom User, und soll unverändert wieder an den
7782               User? Dann <varname>$::form</varname>, steht da eh schon</para>
7783             </listitem>
7784
7785             <listitem>
7786               <para>Sind es Daten aus der Datenbank, die nur bis zum Ende des
7787               Requests gebraucht werden? Dann
7788               <varname>$::request</varname></para>
7789             </listitem>
7790
7791             <listitem>
7792               <para>Muss ich von anderen Teilen des Programms lesend drauf
7793               zugreifen? Dann <varname>$::request</varname>, aber Zugriff über
7794               Wrappermethode</para>
7795             </listitem>
7796           </itemizedlist>
7797         </sect3>
7798       </sect2>
7799
7800       <sect2>
7801         <title>Ehemalige globale Variablen</title>
7802
7803         <para>Die folgenden Variablen waren einmal im Programm, und wurden
7804         entfernt.</para>
7805
7806         <sect3>
7807           <title>$::cgi</title>
7808
7809           <itemizedlist>
7810             <listitem>
7811               <para>war nötig, weil cookie Methoden nicht als
7812               Klassenfunktionen funktionieren</para>
7813             </listitem>
7814
7815             <listitem>
7816               <para>Aufruf als Klasse erzeugt Dummyobjekt was im
7817               Klassennamespace gehalten wird und über Requestgrenzen
7818               leaked</para>
7819             </listitem>
7820
7821             <listitem>
7822               <para>liegt jetzt unter
7823               <varname>$::request-&gt;{cgi}</varname></para>
7824             </listitem>
7825           </itemizedlist>
7826         </sect3>
7827
7828         <sect3>
7829           <title>$::all_units</title>
7830
7831           <itemizedlist>
7832             <listitem>
7833               <para>war nötig, weil einige Funktionen in Schleifen zum Teil
7834               ein paar hundert mal pro Request eine Liste der Einheiten
7835               brauchen, und de als Parameter durch einen Riesenstack von
7836               Funktionen geschleift werden müssten.</para>
7837             </listitem>
7838
7839             <listitem>
7840               <para>Liegt jetzt unter
7841               <varname>$::request-&gt;{cache}{all_units}</varname></para>
7842             </listitem>
7843
7844             <listitem>
7845               <para>Wird nur in
7846               <function>AM-&gt;retrieve_all_units()</function> gesetzt oder
7847               gelesen.</para>
7848             </listitem>
7849           </itemizedlist>
7850         </sect3>
7851
7852         <sect3>
7853           <title>%::called_subs</title>
7854
7855           <itemizedlist>
7856             <listitem>
7857               <para>wurde benutzt um callsub deep recursions
7858               abzufangen.</para>
7859             </listitem>
7860
7861             <listitem>
7862               <para>Wurde entfernt, weil callsub nur einen Bruchteil der
7863               möglichen Rekursioenen darstellt, und da nie welche
7864               auftreten.</para>
7865             </listitem>
7866
7867             <listitem>
7868               <para>komplette recursion protection wurde entfernt.</para>
7869             </listitem>
7870           </itemizedlist>
7871         </sect3>
7872       </sect2>
7873     </sect1>
7874
7875     <sect1 id="devel.fcgi">
7876       <title>Entwicklung unter FastCGI</title>
7877
7878       <sect2 id="devel.fcgi.general">
7879         <title>Allgemeines</title>
7880
7881         <para>Wenn Änderungen in der Konfiguration von kivitendo gemacht
7882         werden, muss der Webserver neu gestartet werden.</para>
7883
7884         <para>Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu
7885         achten. Dadurch, dass das Programm in einer Endlosschleife läuft,
7886         müssen folgende Aspekte beachtet werden.</para>
7887       </sect2>
7888
7889       <sect2 id="devel.fcgi.exiting">
7890         <title>Programmende und Ausnahmen</title>
7891
7892         <para>Betrifft die Funktionen <function>warn</function>,
7893         <function>die</function>, <function>exit</function>,
7894         <function>carp</function> und <function>confess</function>.</para>
7895
7896         <para>Fehler, die dass Programm normalerweise sofort beenden (fatale
7897         Fehler), werden mit dem FastCGI Dispatcher abgefangen, um das Programm
7898         am Laufen zu halten. Man kann mit <function>die</function>,
7899         <function>confess</function> oder <function>carp</function> Fehler
7900         ausgeben, die dann vom Dispatcher angezeigt werden. Die kivitendo
7901         eigene <function>$::form-</function>error()&gt; tut im Prinzip das
7902         Gleiche, mit ein paar Extraoptionen. <function>warn</function> und
7903         <function>exit</function> hingegen werden nicht abgefangen.
7904         <function>warn</function> wird direkt nach STDERR, also in Server Log
7905         eine Nachricht schreiben (sofern in der Konfiguration nicht die
7906         Warnungen in das kivitendo Log umgeleitet wurden), und
7907         <function>exit</function> wird die Ausführung beenden.</para>
7908
7909         <para>Prinzipiell ist es kein Beinbruch, wenn sich der Prozess
7910         beendet, fcgi wird ihn sofort neu starten. Allerdings sollte das die
7911         Ausnahme sein. Quintessenz: Bitte kein <function>exit</function>
7912         benutzen, alle anderen Exceptionmechanismen sind ok.</para>
7913       </sect2>
7914
7915       <sect2 id="devel.fcgi.globals">
7916         <title>Globale Variablen</title>
7917
7918         <para>Um zu vermeiden, dass Informationen von einem Request in einen
7919         anderen gelangen, müssen alle globalen Variablen vor einem Request
7920         sauber initialisiert werden. Das ist besonders wichtig im
7921         <varname>$::cgi</varname> und <varname>$::auth</varname> Objekt, weil
7922         diese nicht gelöscht werden pro Instanz, sondern persistent gehalten
7923         werden.</para>
7924
7925         <para>In <classname>SL::Dispatcher</classname> gibt es einen sauber
7926         abgetrennten Block, der alle kanonischen globalen Variablen listet und
7927         erklärt. Bitte keine anderen einführen ohne das sauber zu
7928         dokumentieren.</para>
7929
7930         <para>Datenbankverbindungen wird noch ein Guide verfasst werden, wie
7931         man sicher geht, dass man die richtige erwischt.</para>
7932       </sect2>
7933
7934       <sect2 id="devel.fcgi.performance">
7935         <title>Performance und Statistiken</title>
7936
7937         <para>Die kritischen Pfade des Programms sind die Belegmasken, und
7938         unter diesen ganz besonders die Verkaufsrechnungsmaske. Ein Aufruf der
7939         Rechnungsmaske in kivitendo 2.4.3 stable dauert auf einem Core2duo mit
7940         4GB Arbeitsspeicher und Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0
7941         sind es je nach Menge der definierten Variablen 1-2s. Ab der
7942         Moose/Rose::DB Version sind es 5-6s.</para>
7943
7944         <para>Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in
7945         den kritischen Pfaden, unter 0,15 sonst.</para>
7946       </sect2>
7947     </sect1>
7948
7949     <sect1 id="dev-programmatic-api-calls" xreflabel="Programmatische API-Aufrufe">
7950       <title>Programmatische API-Aufrufe</title>
7951
7952       <sect2 id="dev-programmatic-api-calls.introduction" xreflabel="Einführung in programmatische API-Aufrufe">
7953         <title>Einführung</title>
7954
7955         <para>
7956          Es ist möglich, Funktionen in kivitendo programmatisch aus anderen Programmen aufzurufen. Dazu ist nötig, dass
7957          Authentifizierungsinformationen in jedem Aufruf mitgegeben werden. Dafür gibt es zwei Methoden: die HTTP-»Basic«-Authentifizierung
7958          oder die Übergabe als spziell benannte GET-Parameter. Neben den Authentifizierungsinformationen muss auch der zu verwendende Mandant
7959          übergeben werden.
7960         </para>
7961       </sect2>
7962
7963       <sect2 id="dev-programmatic-api-calls.client_selection" xreflabel="Mandantenauswahl bei programmatischen API-Aufrufen">
7964         <title>Wahl des Mandanten</title>
7965
7966         <para>
7967          Der zu verwendende Mandant kann als Parameter <varname>{AUTH}client_id</varname> mit jedem Request mitgeschickt werden. Der Wert
7968          muss dabei die Datenbank-ID des Mandanten sein. kivitendo prüft, ob der Account, der über die Authentifizierungsinformationen
7969          übergeben wurde, Zugriff auf den angegebenen Mandanten hat.
7970         </para>
7971
7972         <para>
7973          Wird in einem Request kein Mandant mitgegeben, so wird derjenige Mandant genommen, wer als Standardmandant markiert wurde. Gibt es
7974          keinen solchen, kommt es zu einer Fehlermeldung.
7975         </para>
7976       </sect2>
7977
7978       <sect2 id="dev-programmatic-api-calls.http_basic_authentication" xreflabel="Programmatische API-Aufrufe mit HTTP-»Basic« authentifizieren">
7979         <title>HTTP-»Basic«-Authentifizierung</title>
7980
7981         <para>
7982          Für diese Methode muss jedem Request der bekannte HTTP-Header <constant>Authorization</constant> mitgeschickt werden (siehe <ulink
7983          url="https://tools.ietf.org/html/rfc7617">RFC 7617</ulink>). Unterstützt wird ausschließlich die »Basic«-Methode. Loginname und
7984          Passwort werden bei dieser Methode durch einen Doppelpunkt getrennt und Base64-encodiert im genannten HTTP-Header übertragen.
7985         </para>
7986
7987         <para>
7988          Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei Benutzung über den Webbrowser, ob
7989          dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.
7990         </para>
7991
7992         <para>
7993          Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt
7994          erfolgen.
7995         </para>
7996       </sect2>
7997
7998       <sect2 id="dev-programmatic-api-calls.authentication_via_parameters" xreflabel="Programmatische API-Aufrufe mit Parametern authentifizieren">
7999         <title>Authentifizierung mit Parametern</title>
8000
8001         <para>
8002          Für diese Methode müssen jedem Request zwei Parameter mitgegeben werden: <varname>{AUTH}login</varname> und
8003          <varname>{AUTH}password</varname>. Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei
8004          Benutzung über den Webbrowser, ob dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.
8005         </para>
8006
8007         <para>
8008          Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt
8009          erfolgen.
8010         </para>
8011
8012         <note>
8013          <para>
8014           Die Verwendung dieser Methode ist veraltet. Statt dessen sollte die oben erwähnte HTTP-»Basic«-Authentifizierung verwendet werden.
8015          </para>
8016         </note>
8017       </sect2>
8018
8019       <sect2 id="dev-programmatic-api-calls.examples">
8020         <title>Beispiele</title>
8021
8022         <para>
8023          Das folgende Beispiel nutzt das Kommandozeilenprogramm »curl« und ruft die Funktion auf, die eine vorhandene Telefonnummer in den
8024          Ansprechpersonen sucht und dazu Informationen zurückliefert. Dabei wird die HTTP-»Basic«-Authentifizierung genutzt.
8025         </para>
8026
8027         <programlisting>$ curl --silent --user 'jdoe:SecretPassword!' \
8028   'https://…/controller.pl?action=PhoneNumber/look_up&amp;number=053147110815'</programlisting>
8029       </sect2>
8030     </sect1>
8031
8032     <sect1 id="db-upgrade-files" xreflabel="Datenbank-Upgradedateien">
8033       <title>SQL-Upgradedateien</title>
8034
8035       <sect2 id="db-upgrade-files.introduction"
8036              xreflabel="Einführung in die Datenbank-Upgradedateien">
8037         <title>Einführung</title>
8038
8039         <para>Datenbankupgrades werden über einzelne Upgrade-Scripte
8040         gesteuert, die sich im Verzeichnis
8041         <filename>sql/Pg-upgrade2</filename> befinden. In diesem Verzeichnis
8042         muss pro Datenbankupgrade eine Datei existieren, die neben den
8043         eigentlich auszuführenden SQL- oder Perl-Befehlen einige
8044         Kontrollinformationen enthält.</para>
8045
8046         <para>Kontrollinformationen definieren Abhängigkeiten und Prioritäten,
8047         sodass Datenbankscripte zwar in einer sicheren Reihenfolge ausgeführt
8048         werden (z.B. darf ein <literal>ALTER TABLE</literal> erst ausgeführt
8049         werden, wenn die Tabelle mit <literal>CREATE TABLE</literal> angelegt
8050         wurde), diese Reihenfolge aber so flexibel ist, dass man keine
8051         Versionsnummern braucht.</para>
8052
8053         <para>kivitendo merkt sich dabei, welches der Upgradescripte in
8054         <filename>sql/Pg-upgrade2</filename> bereits durchgeführt wurde und
8055         führt diese nicht erneut aus. Dazu dient die Tabelle
8056         "<literal>schema_info</literal>", die bei der Anmeldung automatisch
8057         angelegt wird.</para>
8058       </sect2>
8059
8060       <sect2 id="db-upgrade-files.format"
8061              xreflabel="Format der Upgradedateien">
8062         <title>Format der Kontrollinformationen</title>
8063
8064         <para>Die Kontrollinformationen sollten sich am Anfang der jeweiligen
8065         Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
8066         hat dabei das folgende Format:</para>
8067
8068         <para>Für SQL-Upgradedateien:</para>
8069
8070         <programlisting>-- @key: value</programlisting>
8071
8072         <para>Für Perl-Upgradedateien:</para>
8073
8074         <programlisting># @key: value</programlisting>
8075
8076         <para>Leerzeichen vor "<varname>value</varname>" werden
8077         entfernt.</para>
8078
8079         <para>Die folgenden Schlüsselworte werden verarbeitet:</para>
8080
8081         <variablelist>
8082           <varlistentry>
8083             <term><varname>tag</varname></term>
8084
8085             <listitem>
8086               <para>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
8087               Dieser "tag" kann von anderen Kontrolldateien in ihren
8088               Abhängigkeiten verwendet werden (Schlüsselwort
8089               "<varname>depends</varname>"). Der "tag" ist auch der Name, der
8090               in der Datenbank eingetragen wird.</para>
8091
8092               <para>Normalerweise sollte die Kontrolldatei genau so heißen wie
8093               der "tag", nur mit der Endung ".sql" bzw. "pl".</para>
8094
8095               <para>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
8096               Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
8097               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
8098               werden.</para>
8099             </listitem>
8100           </varlistentry>
8101
8102           <varlistentry>
8103             <term><varname>charset</varname></term>
8104
8105             <listitem>
8106               <para>Empfohlen. Gibt den Zeichensatz an, in dem das Script
8107               geschrieben wurde, z.B. "<literal>UTF-8</literal>". Aus
8108               Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
8109               Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
8110               "<literal>ISO-8859-15</literal>" angenommen. Perl-Upgradescripte
8111               hingegen müssen immer in UTF-8 encodiert sein und sollten
8112               demnach auch ein "<literal>use utf8;</literal>"
8113               enthalten.</para>
8114             </listitem>
8115           </varlistentry>
8116
8117           <varlistentry>
8118             <term><varname>description</varname></term>
8119
8120             <listitem>
8121               <para>Benötigt. Eine Beschreibung, was in diesem Update
8122               passiert. Diese wird dem Benutzer beim eigentlichen
8123               Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
8124               sein sollte, sollte die Beschreibung auf Deutsch
8125               erfolgen.</para>
8126             </listitem>
8127           </varlistentry>
8128
8129           <varlistentry>
8130             <term><varname>depends</varname></term>
8131
8132             <listitem>
8133               <para>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
8134               von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
8135               dass die in dieser Liste aufgeführten Scripte bereits
8136               durchgeführt wurden, bevor dieses Script ausgeführt wird.</para>
8137
8138               <para>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
8139               Script "b" existiert, das von Änderungen in "a" abhängt, und
8140               eine neue Kontrolldatei für "c" erstellt wird, die von
8141               Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
8142               Tag "b" als Abhängigkeit zu definieren.</para>
8143
8144               <para>Es ist nicht erlaubt, sich selbst referenzierende
8145               Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
8146               und "c" -&gt; "a").</para>
8147             </listitem>
8148           </varlistentry>
8149
8150           <varlistentry>
8151             <term><varname>priority</varname></term>
8152
8153             <listitem>
8154               <para>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
8155               der Scripte ausgeführt werden, die die gleichen
8156               Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
8157               der Wert 1000 benutzt.</para>
8158
8159               <para>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
8160               "depends" benutzt werden. kivitendo sortiert die auszuführenden
8161               Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
8162               abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
8163               2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
8164               dann "y", dann "z"), dann nach der Priorität und bei gleicher
8165               Priorität alphabetisch nach dem "tag".</para>
8166             </listitem>
8167           </varlistentry>
8168
8169           <varlistentry>
8170             <term><varname>ignore</varname></term>
8171
8172             <listitem>
8173               <para>Optional. Falls der Wert auf 1 (true) steht, wird das
8174               Skript bei der Anmeldung ignoriert und entsprechend nicht
8175               ausgeführt.</para>
8176             </listitem>
8177           </varlistentry>
8178         </variablelist>
8179       </sect2>
8180
8181       <sect2 id="db-upgrade-files.format-perl-files"
8182              xreflabel="Format von Perl-Upgradedateien">
8183         <title>Format von in Perl geschriebenen
8184         Datenbankupgradescripten</title>
8185
8186         <para>In Perl geschriebene Datenbankscripte werden nicht einfach so
8187         ausgeführt sondern müssen sich an gewisse Konventionen halten. Dafür
8188         bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</para>
8189
8190         <para>Ein Upgradescript stellt dabei eine vollständige Objektklasse
8191         dar, die vom Elternobjekt "<literal>SL::DBUpgrade2::Base</literal>"
8192         erben und eine Funktion namens "<literal>run</literal>" zur Verfügung
8193         stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser
8194         Klasse erzeugt und darauf die erwähnte "<literal>run</literal>"
8195         aufgerufen wird.</para>
8196
8197         <para>Zu beachten ist, dass sich der Paketname der Datei aus dem Wert
8198         für "<literal>@tag</literal>" ableitet. Dabei werden alle Zeichen, die
8199         in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche
8200         ersetzt. Insgesamt sieht der Paketname wie folgt aus:
8201         "<literal>SL::DBUpgrade2::tag</literal>".</para>
8202
8203         <para>Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in
8204         der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
8205         "<command>perldoc SL/DBUpgrade2/Base.pm</command>".</para>
8206
8207         <para>Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie
8208         folgt aus:</para>
8209
8210         <programlisting># @tag: beispiel-upgrade-file42
8211 # @description: Ein schönes Beispielscript
8212 # @depends: release_3_1_0
8213 package SL::DBUpgrade2::beispiel_upgrade_file42;
8214
8215 use strict;
8216 use utf8;
8217
8218 use parent qw(SL::DBUpgrade2::Base);
8219
8220 sub run {
8221   my ($self) = @_;
8222
8223   # hier Aktionen ausführen
8224
8225   return 1;
8226 }
8227
8228 1;
8229 </programlisting>
8230       </sect2>
8231
8232       <sect2 id="db-upgrade-files.dbupgrade-tool"
8233              xreflabel="Hilfsscript dbupgrade2_tool.pl">
8234         <title>Hilfsscript dbupgrade2_tool.pl</title>
8235
8236         <para>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
8237         existiert ein Hilfsscript namens
8238         "<filename>scripts/dbupgrade2_tool.pl</filename>". Es muss aus dem
8239         kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
8240         liest alle Datenbankupgradescripte aus dem Verzeichnis
8241         <filename>sql/Pg-upgrade2</filename> aus. Es benutzt dafür die
8242         gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
8243         von der Kommandozeile überprüft werden können.</para>
8244
8245         <para>Wird dem Script kein weiterer Parameter übergeben, so wird nur
8246         eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
8247         sich aber auch Informationen auf verschiedene Art ausgeben
8248         lassen:</para>
8249
8250         <itemizedlist>
8251           <listitem>
8252             <para>Listenform: "<command>./scripts/dbupgrade2_tool.pl
8253             --list</command>"</para>
8254
8255             <para>Gibt eine Liste aller Scripte aus. Die Liste ist in der
8256             Reihenfolge sortiert, in der kivitendo die Scripte ausführen
8257             würde. Es werden neben der Listenposition der Tag, die
8258             Abhängigkeitstiefe und die Priorität ausgegeben.</para>
8259           </listitem>
8260
8261           <listitem>
8262             <para>Baumform: "<command>./scripts/dbupgrade2_tool.pl
8263             --tree</command>"</para>
8264
8265             <para>Listet alle Tags in Baumform basierend auf den
8266             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
8267             denen keine anderen abhängen. Die Unterknoten sind Scripte, die
8268             beim übergeordneten Script als Abhängigkeit eingetragen
8269             sind.</para>
8270           </listitem>
8271
8272           <listitem id="db-upgrade-files.dbupgrade-tool.reverse-tree">
8273             <para>Umgekehrte Baumform: "<command>./scripts/dbupgrade2_tool.pl
8274             --rtree</command>"</para>
8275
8276             <para>Listet alle Tags in Baumform basierend auf den
8277             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
8278             der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
8279             die das übergeordnete Script als Abhängigkeit eingetragen
8280             haben.</para>
8281           </listitem>
8282
8283           <listitem>
8284             <para>Baumform mit Postscriptausgabe:
8285             "<command>./scripts/dbupgrade2_tool.pl
8286             --graphviz</command>"</para>
8287
8288             <para>Benötigt das Tool "<command>graphviz</command>", um mit
8289             seiner Hilfe die <link
8290             linkend="db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
8291             Baumform</link> in eine Postscriptdatei namens
8292             "<filename>db_dependencies.ps</filename>" auszugeben. Dies ist
8293             vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
8294             nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
8295             können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
8296             werden.</para>
8297           </listitem>
8298
8299           <listitem>
8300             <para>Scripte, von denen kein anderes Script abhängt:
8301             "<command>./scripts/dbupgrade2_tool.pl --nodeps</command>"</para>
8302
8303             <para>Listet die Tags aller Scripte auf, von denen keine anderen
8304             Scripte abhängen.</para>
8305           </listitem>
8306         </itemizedlist>
8307       </sect2>
8308     </sect1>
8309
8310     <sect1 id="translations-languages" xreflabel="Translations and languages">
8311       <title>Translations and languages</title>
8312
8313       <sect2 id="translations-languages.introduction"
8314              xreflabel="Introduction to translations and languages">
8315         <title>Introduction</title>
8316
8317         <note>
8318           <para>Dieser Abschnitt ist in Englisch geschrieben, um
8319           internationalen Übersetzern die Arbeit zu erleichtern.</para>
8320         </note>
8321
8322         <para>This section describes how localization packages in kivitendo
8323         are built. Currently the only language fully supported is German, and
8324         since most of the internal messages are held in English the English
8325         version is usable too.</para>
8326       </sect2>
8327
8328       <sect2 id="translations-languages.character-set"
8329              xreflabel="Character set">
8330         <title>Character set</title>
8331
8332         <para>All files included in a language pack must use UTF-8 as their
8333         encoding.</para>
8334       </sect2>
8335
8336       <sect2 id="translations-languages.file-structure"
8337              xreflabel="File structure">
8338         <title>File structure</title>
8339
8340         <para>The structure of locales in kivitendo is:</para>
8341
8342         <programlisting>kivitendo/locale/&lt;langcode&gt;/</programlisting>
8343
8344         <para>where &lt;langcode&gt; stands for an abbreviation of the
8345         language package. The builtin packages use two letter <ulink
8346         url="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1</ulink> codes,
8347         but the actual name is not relevant for the program and can easily be
8348         extended to <ulink
8349         url="http://en.wikipedia.org/wiki/IETF_language_tag">IETF language
8350         tags</ulink> (i.e. "en_GB"). In fact the original language packages
8351         from SQL Ledger are named in this way.</para>
8352
8353         <para>In such a language directory the following files are
8354         recognized:</para>
8355
8356         <variablelist>
8357           <varlistentry>
8358             <term>LANGUAGE</term>
8359
8360             <listitem>
8361               <para>This file is mandatory.</para>
8362
8363               <para>The <filename>LANGUAGE</filename> file contains the self
8364               descripted name of the language. It should contain a native
8365               representation first, and in parenthesis an english translation
8366               after that. Example:</para>
8367
8368               <programlisting>Deutsch (German)</programlisting>
8369             </listitem>
8370           </varlistentry>
8371
8372           <varlistentry>
8373             <term>all</term>
8374
8375             <listitem>
8376               <para>This file is mandatory.</para>
8377
8378               <para>The central translation file. It is essentially an inline
8379               Perl script autogenerated by <command>locales.pl</command>. To
8380               generate it, generate the directory and the two files mentioned
8381               above, and execute the following command:</para>
8382
8383               <programlisting>scripts/locales.pl &lt;langcode&gt;</programlisting>
8384
8385               <para>Otherwise you can simply copy one of the other languages.
8386               You will be told how many are missing like this:</para>
8387
8388               <programlisting>$ scripts/locales.pl en
8389 English - 0.6% - 2015/2028 missing</programlisting>
8390
8391               <para>A file named "<filename>missing</filename>" will be
8392               generated and can be edited. You can also edit the
8393               "<filename>all</filename>" file directly. Edit everything you
8394               like to fit the target language and execute
8395               <command>locales.pl</command> again. See how the missing words
8396               get fewer.</para>
8397             </listitem>
8398           </varlistentry>
8399
8400           <varlistentry>
8401             <term>Num2text</term>
8402
8403             <listitem>
8404               <para>Legacy code from SQL Ledger. It provides a means for
8405               numbers to be converted into natural language, like
8406               <literal>1523 =&gt; one thousand five hundred twenty
8407               three</literal>. If you want to provide it, it must be inlinable
8408               Perl code which provides a <function>num2text</function> sub. If
8409               an <function>init</function> sub exists it will be executed
8410               first.</para>
8411
8412               <para>Only used in the check and receipt printing module.</para>
8413             </listitem>
8414           </varlistentry>
8415
8416           <varlistentry>
8417             <term>special_chars</term>
8418
8419             <listitem>
8420               <para>kivitendo comes with a lot of interfaces to different
8421               formats, some of which are rather picky with their accepted
8422               charset. The <filename>special_chars</filename> file contains a
8423               listing of chars not suited for different file format and
8424               provides substitutions. It is written in "Simple Ini" style,
8425               containing a block for every file format.</para>
8426
8427               <para>First entry should be the order of substitution for
8428               entries as a whitespace separated list. All entries are
8429               interpolated, so <literal>\n</literal>, <literal>\x20</literal>
8430               and <literal>\\</literal> all work.</para>
8431
8432               <para>After that every entry is a special char that should be
8433               translated when writing text into such a file.</para>
8434
8435               <para>Example:</para>
8436
8437               <programlisting>[Template/XML]
8438 order=&amp; &lt; &gt; \n
8439 &amp;=&amp;amp;
8440 &lt;=&amp;lt;
8441 &gt;=&amp;gt;
8442 \n=&lt;br&gt;</programlisting>
8443
8444               <para>Note the importance of the order in this example.
8445               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
8446               &amp;amp;gt;</para>
8447
8448               <para>For a list of valid formats, see the German
8449               <filename>special_chars</filename> entry. As of this writing the
8450               following are recognized:</para>
8451
8452               <programlisting>HTML
8453 URL@HTML
8454 Template/HTML
8455 Template/XML
8456 Template/LaTeX
8457 Template/OpenDocument
8458 filenames</programlisting>
8459
8460               <para>The last of which is very machine dependent. Remember that
8461               a lot of characters are forbidden by some filesystems, for
8462               example MS Windows doesn't like ':' in its files where Linux
8463               doesn't mind that. If you want the files created with your
8464               language pack to be portable, find all chars that could cause
8465               trouble.</para>
8466             </listitem>
8467           </varlistentry>
8468
8469           <varlistentry>
8470             <term>missing</term>
8471
8472             <listitem>
8473               <para>This file is not a part of the language package
8474               itself.</para>
8475
8476               <para>This is a file generated by
8477               <command>scripts/locales.pl</command> while processing your
8478               locales. It's only to have the missing entries singled out and
8479               does not belong to a language package.</para>
8480             </listitem>
8481           </varlistentry>
8482
8483           <varlistentry>
8484             <term>lost</term>
8485
8486             <listitem>
8487               <para>This file is not a part of the language package
8488               itself.</para>
8489
8490               <para>Another file generated by
8491               <command>scripts/locales.pl</command>. If for any reason a
8492               translation does not appear anymore and can be deleted, it gets
8493               moved here. The last 50 or so entries deleted are saved here in
8494               case you made a typo, so that you don't have to translate
8495               everything again. If a tranlsation is missing, the lost file is
8496               checked first. If you maintain a language package, you might
8497               want to keep this safe somewhere.</para>
8498             </listitem>
8499           </varlistentry>
8500
8501           <varlistentry>
8502             <term>more/all</term>
8503
8504             <listitem>
8505               <para>This subdir and file is not a part of the language package
8506               itself.</para>
8507
8508               <para>If the directory more exists and contains a file called
8509               all it will be parsed in addition to the mandatory all (see
8510               above). The file is useful if you want to change some
8511               translations for the current installation without conflicting
8512               further upgrades. The file is not autogenerated and has the same
8513               format as the all, but needs another key (more_texts). See the
8514               german translation for an example or copy the following code:
8515               <programlisting>
8516 #!/usr/bin/perl
8517 # -*- coding: utf-8; -*-
8518 # vim: fenc=utf-8
8519
8520 use utf8;
8521
8522 # These are additional texts for custom translations.
8523 # The format is the same as for the normal file all, only
8524 # with another key (more_texts instead of texts).
8525 # The file has the form of 'english text'  =&gt; 'foreign text',
8526
8527 $self-&gt;{more_texts} = {
8528
8529   'Ship via'                    =&gt; 'Terms of delivery',
8530   'Shipping Point'              =&gt; 'Delivery time',
8531 }
8532               </programlisting></para>
8533             </listitem>
8534           </varlistentry>
8535         </variablelist>
8536       </sect2>
8537     </sect1>
8538
8539     <sect1 id="devel.testsuite">
8540       <title>Die kivitendo-Test-Suite</title>
8541
8542       <sect2 id="devel.testsuite.intro">
8543         <title>Einführung</title>
8544
8545         <para>kivitendo enthält eine Suite für automatisierte Tests. Sie
8546         basiert auf dem Standard-Perl-Modul
8547         <literal>Test::More</literal>.</para>
8548
8549         <para>Die grundlegenden Fakten sind:</para>
8550
8551         <itemizedlist>
8552           <listitem>
8553             <para>Alle Tests liegen im Unterverzeichnis
8554             <filename>t/</filename>.</para>
8555           </listitem>
8556
8557           <listitem>
8558             <para>Ein Script (bzw. ein Test) in <filename>t/</filename>
8559             enthält einen oder mehrere Testfälle.</para>
8560           </listitem>
8561
8562           <listitem>
8563             <para>Alle Dateinamen von Tests enden auf <literal>.t</literal>.
8564             Es sind selbstständig ausführbare Perl-Scripte.</para>
8565           </listitem>
8566
8567           <listitem>
8568             <para>Die Test-Suite besteht aus der Gesamtheit aller Tests,
8569             sprich aller Scripte in <filename>t/</filename>, deren Dateiname
8570             auf <literal>.t</literal> endet.</para>
8571           </listitem>
8572         </itemizedlist>
8573       </sect2>
8574
8575       <sect2 id="devel.testsuite.prerequisites">
8576         <title>Voraussetzungen</title>
8577
8578         <para>Für die Ausführung werden neben den für kivitendo eh schon
8579         benötigten Module noch weitere Perl-Module benötigt. Diese
8580         sind:</para>
8581
8582         <itemizedlist>
8583           <listitem>
8584             <para><literal>Test::Deep</literal> (Debian-Paketname:
8585             <literal>libtest-deep-perl</literal>; Fedora:
8586             <literal>perl-Test-Deep</literal>; openSUSE:
8587             <literal>perl-Test-Deep</literal>)</para>
8588           </listitem>
8589
8590           <listitem>
8591             <para><literal>Test::Exception</literal> (Debian-Paketname:
8592             <literal>libtest-exception-perl</literal>; Fedora:
8593             <literal>perl-Test-Exception</literal>; openSUSE:
8594             <literal>perl-Test-Exception</literal>)</para>
8595           </listitem>
8596
8597           <listitem>
8598             <para><literal>Test::Output</literal> (Debian-Paketname:
8599             <literal>libtest-output-perl</literal>; Fedora:
8600             <literal>perl-Test-Output</literal>; openSUSE:
8601             <literal>perl-Test-Output</literal>)</para>
8602           </listitem>
8603
8604           <listitem>
8605             <para><literal>Test::Harness</literal> 3.0.0 oder höher. Dieses
8606             Modul ist ab Perl 5.10.1 Bestandteil der Perl-Distribution und
8607             kann für frühere Versionen aus dem <ulink
8608             url="http://www.cpan.org">CPAN</ulink> bezogen werden.</para>
8609           </listitem>
8610
8611           <listitem>
8612             <para><literal>LWP::Simple</literal> aus dem Paket
8613             <literal>libwww-perl</literal> (Debian-Panetname:
8614             <literal>libwww-perl</literal>; Fedora:
8615             <literal>perl-libwww-perl</literal>; openSUSE:
8616             <literal>perl-libwww-perl</literal>)</para>
8617           </listitem>
8618
8619           <listitem>
8620             <para><literal>URI::Find</literal> (Debian-Panetname:
8621             <literal>liburi-find-perl</literal>; Fedora:
8622             <literal>perl-URI-Find</literal>; openSUSE:
8623             <literal>perl-URI-Find</literal>)</para>
8624           </listitem>
8625
8626           <listitem>
8627             <para><literal>Sys::CPU</literal> (Debian-Panetname:
8628             <literal>libsys-cpu-perl</literal>; Fedora und openSUSE: nicht
8629             vorhanden)</para>
8630           </listitem>
8631
8632           <listitem>
8633             <para><literal>Thread::Pool::Simple</literal> (Debian-Panetname:
8634             <literal>libthread-pool-simple-perl</literal>; Fedora und
8635             openSUSE: nicht vorhanden)</para>
8636           </listitem>
8637         </itemizedlist>
8638
8639         <para>Weitere Voraussetzung ist, dass die Testsuite ihre eigene
8640         Datenbank anlegen kann, um Produktivdaten nicht zu gefährden. Dazu
8641         müssen in der Konfigurationsdatei im Abschnit
8642         <literal>testing/database</literal> Datenbankverbindungsparameter
8643         angegeben werden. Der hier angegebene Benutzer muss weiterhin das
8644         Recht haben, Datenbanken anzulegen und zu löschen.</para>
8645
8646         <para>Der so angegebene Benutzer muss nicht zwingend über
8647         Super-User-Rechte verfügen. Allerdings gibt es einige
8648         Datenbank-Upgrades, die genau diese Rechte benötigen. Für den Fall
8649         kann man in diesem Konfigurationsabschnitt einen weiteren
8650         Benutzeraccount angeben, der dann über Super-User-Rechte verfügt, und
8651         mit dem die betroffenen Upgrades durchgeführt werden. In der
8652         Beispiel-Konfigurationsdatei finden Sie die benötigten
8653         Parameter.</para>
8654       </sect2>
8655
8656       <sect2 id="devel.testsuite.execution">
8657         <title>Existierende Tests ausführen</title>
8658
8659         <para>Es gibt mehrere Möglichkeiten zum Ausführen der Tests: entweder,
8660         man lässt alle Tests auf einmal ausführen, oder man führt gezielt
8661         einzelne Scripte aus. Für beide Fälle gibt es das Helferscript
8662         <filename>t/test.pl</filename>.</para>
8663
8664         <para>Will man die komplette Test-Suite ausführen, so muss man einfach
8665         nur <filename>t/test.pl</filename> ohne weitere Parameter aus dem
8666         kivitendo-Basisverzeichnis heraus ausführen.</para>
8667
8668         <para>Um einzelne Test-Scripte auszuführen, übergibt man deren Namen
8669         an <filename>t/test.pl</filename>. Beispielsweise:</para>
8670
8671         <programlisting>t/test.pl t/form/format_amount.t t/background_job/known_jobs.t</programlisting>
8672       </sect2>
8673
8674       <sect2 id="devel.testsuite.meaning_of_scripts">
8675         <title>Bedeutung der verschiedenen Test-Scripte</title>
8676
8677         <para>Die Test-Suite umfasst Tests sowohl für Funktionen als auch für
8678         Programmierstil. Einige besonders zu erwähnende, weil auch während der
8679         Entwicklung nützliche Tests sind:</para>
8680
8681         <itemizedlist>
8682           <listitem>
8683             <para><filename>t/001compile.t</filename> -- compiliert alle
8684             Quelldateien und bricht bei Fehlern sofort ab</para>
8685           </listitem>
8686
8687           <listitem>
8688             <para><filename>t/002goodperl.t</filename> -- überprüft alle
8689             Perl-Dateien auf Anwesenheit von '<literal>use
8690             strict</literal>'-Anweisungen</para>
8691           </listitem>
8692
8693           <listitem>
8694             <para><filename>t/003safesys.t</filename> -- überprüft Aufrufe von
8695             <function>system()</function> und <function>exec()</function> auf
8696             Gültigkeit</para>
8697           </listitem>
8698
8699           <listitem>
8700             <para><filename>t/005no_tabs.t</filename> -- überprüft, ob Dateien
8701             Tab-Zeichen enthalten</para>
8702           </listitem>
8703
8704           <listitem>
8705             <para><filename>t/006spelling.t</filename> -- sucht nach häufigen
8706             Rechtschreibfehlern</para>
8707           </listitem>
8708
8709           <listitem>
8710             <para><filename>t/011pod.t</filename> -- überprüft die Syntax von
8711             Dokumentation im POD-Format auf Gültigkeit</para>
8712           </listitem>
8713         </itemizedlist>
8714
8715         <para>Weitere Test-Scripte überprüfen primär die Funktionsweise
8716         einzelner Funktionen und Module.</para>
8717       </sect2>
8718
8719       <sect2 id="devel.testsuite.create_new">
8720         <title>Neue Test-Scripte erstellen</title>
8721
8722         <para>Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich
8723         mit einem Test-Script abgesichert wird. Auch bestehende Funktion darf
8724         und soll ausdrücklich nachträglich mit Test-Scripten abgesichert
8725         werden.</para>
8726
8727         <sect3 id="devel.testsuite.ideas_for_non_function_tests">
8728           <title>Ideen für neue Test-Scripte, die keine konkreten Funktionen
8729           testen</title>
8730
8731           <para>Ideen, die abgesehen von Funktionen noch nicht umgesetzt
8732           wurden:</para>
8733
8734           <itemizedlist>
8735             <listitem>
8736               <para>Überprüfung auf fehlende symbolische Links</para>
8737             </listitem>
8738
8739             <listitem>
8740               <para>Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit
8741               gewissen Einschränkungen wie das Erlauben von deutschen
8742               Umlauten)</para>
8743             </listitem>
8744
8745             <listitem>
8746               <para>Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)</para>
8747             </listitem>
8748
8749             <listitem>
8750               <para>Überprüfung auf Leerzeichen am Ende von Zeilen</para>
8751             </listitem>
8752
8753             <listitem>
8754               <para>Test, ob alle zu übersetzenden Strings in
8755               <filename>locale/de/all</filename> vorhanden sind</para>
8756             </listitem>
8757
8758             <listitem>
8759               <para>Test, ob alle Webseiten-Templates in
8760               <filename>templates/webpages</filename> mit vom Perl-Modul
8761               <literal>Template</literal> compiliert werden können</para>
8762             </listitem>
8763           </itemizedlist>
8764         </sect3>
8765
8766         <sect3 id="devel.testsuite.directory_and_test_names">
8767           <title>Konvention für Verzeichnis- und Dateinamen</title>
8768
8769           <para>Es gibt momentan eine wenige Richtlinien, wie Test-Scripte zu
8770           benennen sind. Bitte die folgenden Punkte als Richtlinie betrachten
8771           und ihnen soweit es geht folgen:</para>
8772
8773           <itemizedlist>
8774             <listitem>
8775               <para>Die Dateiendung muss <filename>.t</filename>
8776               lauten.</para>
8777             </listitem>
8778
8779             <listitem>
8780               <para>Namen sind englisch, komplett klein geschrieben und
8781               einzelne Wörter mit Unterstrichten getrennt (beispielsweise
8782               <filename>bad_function_params.t</filename>).</para>
8783             </listitem>
8784
8785             <listitem>
8786               <para>Unterverzeichnisse sollten grob nach dem Themenbereich
8787               benannt sein, mit dem sich die Scripte darin befassen
8788               (beispielsweise <filename>background_jobs</filename> für Tests
8789               rund um Hintergrund-Jobs).</para>
8790             </listitem>
8791
8792             <listitem>
8793               <para>Test-Scripte sollten einen überschaubaren Bereich von
8794               Funktionalität testen, der logisch zusammenhängend ist (z.B. nur
8795               Tests für eine einzelne Funktion in einem Modul). Lieber mehrere
8796               Test-Scripte schreiben.</para>
8797             </listitem>
8798           </itemizedlist>
8799         </sect3>
8800
8801         <sect3 id="devel.testsuite.minimal_example">
8802           <title>Minimales Skelett für eigene Scripte</title>
8803
8804           <para>Der folgenden Programmcode enthält das kleinstmögliche
8805           Testscript und kann als Ausgangspunkt für eigene Tests verwendet
8806           werden:</para>
8807
8808           <programlisting>use Test::More tests =&gt; 0;
8809
8810 use lib 't';
8811
8812 use Support::TestSetup;
8813
8814 Support::TestSetup::login();</programlisting>
8815
8816           <para>Wird eine vollständig initialisierte kivitendo-Umgebung
8817           benötigt (Stichwort: alle globalen Variablen wie
8818           <varname>$::auth</varname>, <varname>$::form</varname> oder
8819           <varname>$::lxdebug</varname>), so muss in der Konfigurationsdatei
8820           <filename>config/kivitendo.conf</filename> im Abschnitt
8821           <literal>testing.login</literal> ein gültiger Login-Name eingetragen
8822           sein. Dieser wird für die Datenbankverbindung benötigt.</para>
8823
8824           <para>Wir keine vollständig initialisierte Umgebung benötigt, so
8825           kann die letzte Zeile <programlisting>Support::TestSetup::login();</programlisting>
8826           weggelassen werden, was die Ausführungszeit des Scripts leicht
8827           verringert.</para>
8828         </sect3>
8829       </sect2>
8830     </sect1>
8831
8832     <sect1 id="devel.style-guide">
8833       <title>Stil-Richtlinien</title>
8834
8835       <para>Die folgenden Regeln haben das Ziel, den Code möglichst gut les-
8836       und wartbar zu machen. Dazu gehört zum Einen, dass der Code einheitlich
8837       eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden
8838       wird (Stichworte "Klammern" oder "Hash-Keys").</para>
8839
8840       <para>Diese Regeln sind keine Schikane sondern erleichtern allen das
8841       Leben!</para>
8842
8843       <para>Jeder, der einen Patch schickt, sollte seinen Code vorher
8844       überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
8845       nicht.</para>
8846
8847       <orderedlist>
8848         <listitem>
8849           <para>Es werden keine echten Tabs sondern Leerzeichen
8850           verwendet.</para>
8851         </listitem>
8852
8853         <listitem>
8854           <para>Die Einrückung beträgt zwei Leerzeichen. Beispiel:</para>
8855
8856           <programlisting>foreach my $row (@data) {
8857   if ($flag) {
8858     # do something with $row
8859   }
8860
8861   if ($use_modules) {
8862     $row-&gt;{modules} = MODULE-&gt;retrieve(
8863       id   =&gt; $row-&gt;{id},
8864       date =&gt; $use_now ? localtime() : $row-&gt;{time},
8865     );
8866   }
8867
8868   $report-&gt;add($row);
8869 }</programlisting>
8870         </listitem>
8871
8872         <listitem>
8873           <para>Öffnende geschweifte Klammern befinden sich auf der gleichen
8874           Zeile wie der letzte Befehl. Beispiele:</para>
8875
8876           <programlisting>sub debug {
8877   ...
8878 }</programlisting>
8879
8880           <para>oder</para>
8881
8882           <programlisting>if ($form-&gt;{item_rows} &gt; 0) {
8883   ...
8884 }</programlisting>
8885         </listitem>
8886
8887         <listitem>
8888           <para>Schließende geschweifte Klammern sind so weit eingerückt wie
8889           der Befehl / die öffnende schließende Klammer, die den Block
8890           gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen
8891           Beispiele wie bei 3. gelten.</para>
8892         </listitem>
8893
8894         <listitem>
8895           <para>Die Wörter "<function>else</function>",
8896           "<function>elsif</function>", "<function>while</function>" befinden
8897           sich auf der gleichen Zeile wie schließende geschweifte Klammern.
8898           Beispiele:</para>
8899
8900           <programlisting>if ($form-&gt;{sum} &gt; 1000) {
8901   ...
8902 } elsif ($form-&gt;{sum} &gt; 0) {
8903   ...
8904 } else {
8905   ...
8906 }
8907
8908 do {
8909   ...
8910 } until ($a &gt; 0);</programlisting>
8911         </listitem>
8912
8913         <listitem>
8914           <para>Parameter von Funktionsaufrufen müssen mit runden Klammern
8915           versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
8916           und grep-ähnliche Operatoren. Beispiel:</para>
8917
8918           <programlisting>$main::lxdebug-&gt;message("Could not find file.");
8919 %options = map { $_ =&gt; 1 } grep { !/^#/ } @config_file;</programlisting>
8920         </listitem>
8921
8922         <listitem>
8923           <para>Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:</para>
8924
8925           <para>Generell gilt: Hashkeys und Arrayindices sollten nicht durch
8926           Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
8927           Blöcke schon. Beispiel:</para>
8928
8929           <programlisting>if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
8930   ...
8931 }
8932
8933 $array[$i + 1]             = 4;
8934 $form-&gt;{sum}              += $form-&gt;{"row_$i"};
8935 $form-&gt;{ $form-&gt;{index} } += 1;
8936
8937 map { $form-&gt;{sum} += $form-&gt;{"row_$_"} } 1..$rowcount;</programlisting>
8938         </listitem>
8939
8940         <listitem>
8941           <para>Mehrzeilige Befehle</para>
8942
8943           <orderedlist>
8944             <listitem>
8945               <para>Werden die Parameter eines Funktionsaufrufes auf mehrere
8946               Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt
8947               werden, in der die ersten Funktionsparameter in der ersten Zeile
8948               stehen. Beispiel:</para>
8949
8950               <programlisting>$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
8951                     $form-&gt;{some_col_value});</programlisting>
8952             </listitem>
8953
8954             <listitem>
8955               <para>Ein Spezialfall ist der ternäre Operator "?:", der am
8956               besten in einer übersichtlichen Tabellenstruktur organisiert
8957               wird. Beispiel:</para>
8958
8959               <programlisting>my $rowcount = $form-&gt;{"row_$i"} ? $i
8960              : $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
8961              :                     $form-&gt;{rowcount} - $form-&gt;{rowbase};</programlisting>
8962             </listitem>
8963           </orderedlist>
8964         </listitem>
8965
8966         <listitem>
8967           <para>Kommentare</para>
8968
8969           <orderedlist>
8970             <listitem>
8971               <para>Kommentare, die alleine in einer Zeile stehen, sollten
8972               soweit wie der Code eingerückt sein.</para>
8973             </listitem>
8974
8975             <listitem>
8976               <para>Seitliche hängende Kommentare sollten einheitlich
8977               formatiert werden.</para>
8978             </listitem>
8979
8980             <listitem>
8981               <para>Sämtliche Kommentare und Sonstiges im Quellcode ist bitte
8982               auf Englisch zu verfassen. So wie ich keine Lust habe,
8983               französischen Quelltext zu lesen, sollte auch der kivitendo
8984               Quelltext für nicht-Deutschsprachige lesbar sein.
8985               Beispiel:</para>
8986
8987               <programlisting>my $found = 0;
8988 while (1) {
8989   last if $found;
8990
8991   # complicated check
8992   $found = 1 if //
8993 }
8994
8995 $i  = 0        # initialize $i
8996 $n  = $i;      # save $i
8997 $i *= $const;  # do something crazy
8998 $i  = $n;      # recover $i</programlisting>
8999             </listitem>
9000           </orderedlist>
9001         </listitem>
9002
9003         <listitem>
9004           <para>Hashkeys sollten nur in Anführungszeichen stehen, wenn die
9005           Interpolation gewünscht ist. Beispiel:</para>
9006
9007           <programlisting>$form-&gt;{sum}      = 0;
9008 $form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
9009 $some_hash{42}    = 54;</programlisting>
9010         </listitem>
9011
9012         <listitem>
9013           <para>Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen
9014           unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
9015           wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in
9016           grossen Tabellen), dann ist Lesbarkeit vorzuziehen.</para>
9017
9018           <para>Als Beispiel sei die Funktion
9019           <function>print_options</function> aus
9020           <filename>bin/mozilla/io.pl</filename> angeführt.</para>
9021         </listitem>
9022
9023         <listitem>
9024           <para>Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind
9025           unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die diffs
9026           verfälschen.</para>
9027
9028           <para>Emacs und vim haben beide recht einfache Methoden zur
9029           Entfernung von trailing whitespace. Emacs kennt das Kommande
9030           <command>nuke-trailing-whitespace</command>, vim macht das gleiche
9031           manuell über <literal>:%s/\s\+$//e</literal> Mit <literal>:au
9032           BufWritePre * :%s/\s\+$//e</literal> wird das an Speichern
9033           gebunden.</para>
9034         </listitem>
9035
9036         <listitem>
9037           <para>Es wird kein <command>perltidy</command> verwendet.</para>
9038
9039           <para>In der Vergangenheit wurde versucht,
9040           <command>perltidy</command> zu verwenden, um einen einheitlichen
9041           Stil zu erlangen. Es hat sich aber gezeigt, dass
9042           <command>perltidy</command>s sehr eigenwilliges Verhalten, was
9043           Zeilenumbrüche angeht, oftmals gut formatierten Code zerstört. Für
9044           den Interessierten sind hier die
9045           <command>perltidy</command>-Optionen, die grob den beschriebenen
9046           Richtlinien entsprechen:</para>
9047
9048           <programlisting>-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
9049 -aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
9050 -lp -vt=1 -vtc=1</programlisting>
9051         </listitem>
9052
9053         <listitem>
9054           <para><varname>STDERR</varname> ist tabu. Unkonditionale
9055           Debugmeldungen auch.</para>
9056
9057           <para>kivitendo bietet mit dem Modul <classname>LXDebug</classname>
9058           einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
9059           Grund, nach <varname>STDERR</varname> zu schreiben.</para>
9060
9061           <para>Die <classname>LXDebug</classname>-Methode
9062           "<function>message</function>" nimmt als ersten Paramter außerdem
9063           eine Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer
9064           angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden
9065           und werden in den meisten Fällen auch vom Repository
9066           zurückgewiesen.</para>
9067         </listitem>
9068
9069         <listitem>
9070           <para>Alle neuen Module müssen use strict verwenden.</para>
9071
9072           <para><varname>$form</varname>, <varname>$auth</varname>,
9073           <varname>$locale</varname>, <varname>$lxdebug</varname> und
9074           <varname>%myconfig</varname> werden derzeit aus dem main package
9075           importiert (siehe <xref linkend="devel.globals"/>. Alle anderen
9076           Konstrukte sollten lexikalisch lokal gehalten werden.</para>
9077         </listitem>
9078       </orderedlist>
9079     </sect1>
9080
9081     <sect1 id="devel.build-doc" xreflabel="Dokumentation erstellen">
9082       <title>Dokumentation erstellen</title>
9083
9084       <sect2 id="devel.build-doc.introduction">
9085         <title>Einführung</title>
9086
9087         <para>Diese Dokumentation ist in <productname>DocBook</productname>
9088         XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor.
9089         Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen
9090         Editor nutzt, der spezielle Unterstützung für
9091         <productname>DocBook</productname> mitbringt. Wir empfehlen dafür den
9092         <ulink url="http://www.xmlmind.com/xmleditor/">XMLmind XML
9093         Editor</ulink>, der bei nicht kommerzieller Nutzung kostenlos
9094         ist.</para>
9095       </sect2>
9096
9097       <sect2 id="devel.build-doc.required-software">
9098         <title>Benötigte Software</title>
9099
9100         <para>Bei <productname>DocBook</productname> ist Prinzip, dass
9101         ausschließlich die XML-Quelldatei bearbeitet wird. Aus dieser werden
9102         dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML
9103         erzeugt. Bei kivitendo übernimmt diese Aufgabe das Shell-Script
9104         <command>scripts/build_doc.sh</command>.</para>
9105
9106         <para>Das Script benötigt zur Konvertierung verschiedene
9107         Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benötigt
9108         werden:</para>
9109
9110         <itemizedlist>
9111           <listitem>
9112             <para><ulink
9113             url="http://www.oracle.com/technetwork/java/index.html">Java</ulink>
9114             in einer halbwegs aktuellen Version</para>
9115           </listitem>
9116
9117           <listitem>
9118             <para>Das Java-Build-System <ulink
9119             url="http://ant.apache.org/">Apache Ant</ulink></para>
9120           </listitem>
9121
9122           <listitem>
9123             <para>Das Dokumentations-System Dobudish für
9124             <productname>DocBook</productname> 4.5, eine Zusammenstellung
9125             diverser Stylesheets und Grafiken zur Konvertierung von
9126             <productname>DocBook</productname> XML in andere Formate. Das
9127             Paket, das benötigt wird, ist zum Zeitpunkt der
9128             Dokumentationserstellung
9129             <filename>dobudish-nojre-1.1.4.zip</filename>, aus auf <ulink
9130             url="http://code.google.com/p/dobudish/downloads/list">code.google.com</ulink>
9131             bereitsteht.</para>
9132           </listitem>
9133         </itemizedlist>
9134
9135         <para>Apache Ant sowie ein dazu passendes Java Runtime Environment
9136         sind auf allen gängigen Plattformen verfügbar. Beispiel für
9137         Debian/Ubuntu:</para>
9138
9139         <programlisting>apt-get install ant openjdk-7-jre</programlisting>
9140
9141         <para>Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis
9142         <filename>doc/build</filename> entpackt werden. Beispiel unter der
9143         Annahme, das <productname>Dobudish</productname> in
9144         <filename>$HOME/Downloads</filename> heruntergeladen wurde:</para>
9145
9146         <programlisting>cd doc/build
9147 unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip</programlisting>
9148       </sect2>
9149
9150       <sect2 id="devel.build-doc.build">
9151         <title>PDFs und HTML-Seiten erstellen</title>
9152
9153         <para>Die eigentliche Konvertierung erfolgt nach Installation der
9154         benötigten Software mit einem einfachen Aufruf direkt aus dem
9155         kivitendo-Installationsverzeichnis heraus:</para>
9156
9157         <programlisting>./scripts/build_doc.sh</programlisting>
9158       </sect2>
9159
9160       <sect2 id="devel.build-doc.repository">
9161         <title>Einchecken in das Git-Repository</title>
9162
9163         <para>Sowohl die XML-Datei als auch die erzeugten PDF- und
9164         HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass
9165         nach Änderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut
9166         und alles zusammen in einem Commit eingecheckt werden sollten.</para>
9167
9168         <para>Die "<filename>dobudish</filename>"-Verzeichnisse bzw.
9169         symbolischen Links gehören hingegen nicht in das Repository.</para>
9170       </sect2>
9171     </sect1>
9172   </chapter>
9173 </book>