doc/dokumentation.xml

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