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