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