[Openinteract-commits] CVS: OpenInteract/doc data_import.html,NONE,1.1

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/openinteract/OpenInteract/doc
In directory usw-pr-cvs1:/tmp/cvs-serv1203

Added Files:
	data_import.html 
Log Message:
added brief data import guide -- shows how to setup an import file to
batch create SPOPS objects, and also how to setup security on those
objects many at a time.


--- NEW FILE: data_import.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Importing Data into OpenInteract</title>
  </head>

  <body>
<!-- <template_status>no_parse</template_status> -->

    <h1>Importing Data into OpenInteract</h1>

    <p>Many times you can use OpenInteract to frame an existing data
    source with a web interface, and you can do this without any
    changes to the datasource at all.</p>

    <p>But sometimes you may need to bring data from somewhere else
    into a datasource for use with OpenInteract. This short guide
    tells you how to do that.</p>

    <h2>Data Import File</h2>

    <p>Data import files are used by OpenInteract to have a
    datasource-independent way to install data. The format is fairly
    simple: an arrayref with the first element being a hashref
    describing what's to come, and then any number of arrayrefs
    containing actual data to be installed. Here's a simple example
    that we use in OpenInteract for themes:</p>

<pre>
$theme = [ 
  { spops_class => 'OpenInteract::Theme',
    field_order => [ qw/ theme_id title description parent credit / ] },
  [ 1, 'main', 'Your basic, parent of all themes. Main.', 0,
    'OpenInteract Developers <in...@op...>' ],
];
</pre>

    <p>So the first element in the <tt>$theme</tt> arrayref is a
    hashref with two keys. The first key, <tt>spops_class</tt>, tells
    the installer what type of object should be created. The second
    key, <tt>field_order</tt>, describes how the succeeding data
    arrayrefs get mapped to fields in the object.</p>

    <p>Other information you can use in the initial hashref:</p>

    <ul>

        <li><b>transform_class_to_website</b> <tt>(\@)</tt><br>
           Specify a list of fields that should have the value
           transformed to replace 'OpenInteract' with the website
           name.</li>

        <li><b>transform_class_to_oi</b> <tt>(\@)</tt><br>
           Specify a list of fields that should have the value
           transformed to replace the current website namespace
           with 'OpenInteract'. (Reversing the previous.)</li>

        <li><b>transform_default_to_id</b> <tt>(\@)</tt><br>
           Specify a list of fields for which we need to use the
           value specified lookup as a lookup in the
           'default_objects' server configuration key. This is
           often used when specifying security -- if you are
           using LDAP, then your group ID is soemething like
           'site admin' rather than '3', so you want to ensure
           that the security is set appropriately.</li>

        <li><b>transform_to_now</b> <tt>(\@)</tt><br>
           Specify a list of fields for which we need to set the
           value to a date string representing right now.</li>

    </ul>

    <p>Learn more about this whole process by reading the docs for
    <tt>OpenInteract::SQLInstall</tt>.</p>

    <p>The easiest way to build an import file is to open an existing
    one and edit what you need in the initial hashref item. The data
    record arrayrefs are easily generated by some automated means --
    you could even use <tt>Data::Dumper</tt> if you were so
    inclined.</p>

    <p>The import file can then be run using oi_manage:</p>

<pre>
 $ export OIWEBSITE=/path/to/mysite
 $ oi_manage install_sql --package=mypackage
</pre>

    <p>Or just to run the data import alone without structures:</p>

<pre>
 $ oi_manage install_sql --package=mypackage --sql_action=data
</pre>

    <h2>Setting Security on the Data</h2>

    <p>If you're not using per-object security on your data, then you
    can skip this section -- you're done!</p>

    <p>If you need to set security, there's a script that will do just
    about everything you need. It comes with the 'base_security'
    package and is located in:</p>

<pre>
   $WEBSITE_DIR/pkg/base_security-x.xx/script/create_object_security.pl
</pre>

    <p>For example, here's a run that gives WRITE permission to the
    group with ID 3 (usually the 'site admin' group):</p>

<pre>
  $ export OIWEBSITE=/path/to/mysite
  $ perl create_object_security.pl --class=MySite::News \
                                   --level=write
                                   --scope=group \
                                   --scope_id=3
</pre>

    <p>To learn more about its operation:</p>

<pre>
  $ perl create_object_security.pl --help
</pre>

    <p>If you need to setup security to distribute along with your
    package, follow one of the examples as distributed with
    OpenInteract, such as in the 'base_theme' or 'base_group'
    packages.</p>

    <hr>
    <address><a href="mailto:ch...@cw...">Chris Winters</a></address>
<!-- Created: Mon Oct  8 12:39:23 EDT 2001 -->
<!-- hhmts start -->
Last modified: Sat Oct 13 16:23:06 EDT 2001
<!-- hhmts end -->
  </body>
</html>