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