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