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