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