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