=head1 NAME

OpenInteract2::Manual::DataImport - Importing Data into OpenInteract

=head1 DESCRIPTION

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.

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.

=head2 Data Import File

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
OpenInteract2 for themes:

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


So the first element in the C<$theme> arrayref is a hashref with three
keys. The first key, C<import_type>, tells the import process what
type of data it can expect. Most of the time you'll be specifying
SPOPS objects so you can leave this as 'object'. The second,
C<spops_class>, tells the installer what B<type> of object should be
created. The third key, C<field_order>, describes how the succeeding
data arrayrefs get mapped to fields in the object.

Other information you can use in the initial hashref:

=over

=item *

B<transform_default> C<(\@)>

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.

=item *

B<transform_now> C<(\@)>

Specify a list of fields for which we need to set the value to a date
string representing right now.

=back

Learn more about this whole process by reading the docs for
L<OpenInteract2::SQLInstall|OpenInteract2::SQLInstall>.

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 L<Data::Dumper|Data::Dumper> if you were so inclined.

The import file can then be run using oi_manage:

  $ export OPENINTERACT2=/path/to/mysite
  $ oi2_manage install_sql --package=mypackage
     # ALT: just run data import, no structures
  $ oi2_manage install_sql_data --package=mypackage
  


=head2 Setting Security on the Data

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

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 its C<script/> directory. For example, here's a run that
gives WRITE permission to the group with ID 3 (usually the 'site
admin' group):

  $ export OPENINTERACT2=/path/to/mysite
  $ perl create_object_security.pl --class=OpenInteract2::News \
                                   --level=write \
                                   --scope=group \
                                   --scope_id=3


To learn more about its operation just run the script with the
'--help' argument.

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.

=head1 COPYRIGHT

Copyright (c) 2002-2004 Chris Winters. All rights reserved.

=head1 AUTHORS

Chris Winters E<lt>chris@cwinters.comE<gt>
