doc/dokumentation.xml

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