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