doc/dokumentation.xml

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