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