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