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