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