doc/dokumentation.xml

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