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