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