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