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