doc/dokumentation.xml

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