doc/dokumentation.xml

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