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