doc/dokumentation.xml

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