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