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