doc/dokumentation.xml

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