root / pykota / trunk / docs / dumpykota.sgml @ 2229

<!-- $Id$ -->

<chapter>
  <title>Export datas to other software with dumpykota</title>
  <para>Last modified on $Date$</para>
  
  <para>
    If you want to reuse <application>PyKota</application> datas from another
    software, but don't want to modify your existing application to
    have it connect to <application>PyKota</application>'s database, your
    best option is the new <command>dumpykota</command> command.
  </para>
  
  <para>
    <command>dumpykota</command> can export <application>PyKota</application>
    datas in a number of formats. The supported output formats are
    comma separated values, semicolon separated values, tab separated values, and <acronym>XML</acronym>.
  </para>  
  
  <para>
    For the print job history's datas, a special format identical to <application>CUPS</application>' <literal>page_log</literal>
    format is also supported.
    This allows you to interface <application>PyKota</application> with third party tools like
    <application>phpPrintAnalyzer</application> which is a logfile analyzer for <application>CUPS</application>,
    even in the case where you use <application>LPRng</application> instead of <application>CUPS</application>.
  </para>  
  
  <para>
    More formats may be added in the future. In particular, 
    <acronym>SQL</acronym> and <acronym>LDIF</acronym> are planned, but 
    are currently not implemented. 
  </para>
  
  <para>
    <command>dumpykota</command> can't dump all datas at once though, you have
    to specify which type of datas you want. The possible types are :
    <itemizedlist>
      <listitem><para>Users</para></listitem>
      <listitem><para>Users groups</para></listitem>
      <listitem><para>Printers</para></listitem>
      <listitem><para>Printers groups membership</para></listitem>
      <listitem><para>Users groups membership</para></listitem>
      <listitem><para>Users print quota entries</para></listitem>
      <listitem><para>Users groups print quota entries</para></listitem>
      <listitem><para>History of payments</para></listitem>
      <listitem><para>History of print jobs</para></listitem>
    </itemizedlist>  
  </para>
  
  <para>
    You can then import the dumped datas into a spreadsheet for example, 
    if you want to create complex reports with nice looking graphs and
    the like.
  </para>
  
  <para>
    This command could also be used if you plan to write your own management
    tools : just write wrappers around the <command>pkprinters</command>,
    <command>edpykota</command>, and <command>dumpykota</command>
    tools, and your own tools will automatically benefit from <application>PyKota</application>
    database backend independance layer.
    This is exactly what the third party software <application>phpPykotaAdmin</application> does.
  </para>
  
  <para>
    Finally, <command>dumpykota</command>'s functionnality is now also available remotely through
    the use of the <filename>dumpykota.cgi</filename> <acronym>CGI</acronym> script.
  </para>
  
  <warning>
    <title>Warning</title>
    <para>
      Only <application>PyKota</application> administrators can dump PyKota's datas.
    </para>
  </warning>  
        
  <sect1>
    <title>Reference</title>
    <para>
      <cmdsynopsis>
        <command>dumpykota</command>
        <group choice="opt"><arg>-v</arg><arg>--version</arg></group>
        <group choice="opt"><arg>-h</arg><arg>--help</arg></group>
        <group choice="opt">
          <arg>-f <replaceable>outputformat</replaceable></arg>
          <arg>--format <replaceable>outputformat</replaceable></arg>
        </group>
        <group choice="opt">
          <arg>-o <replaceable>filename</replaceable></arg>
          <arg>--output <replaceable>filename</replaceable></arg>
        </group>
        <group choice="req">
          <arg>-d <replaceable>datatype</replaceable></arg>
          <arg>--data <replaceable>datatype</replaceable></arg>
        </group>
      </cmdsynopsis>
    </para>
  </sect1>
</chapter>