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