doc/dokumentation.xml

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