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