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