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