doc/dokumentation.xml

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