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