doc/dokumentation.xml

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