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