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