NAME

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

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.

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 $theme arrayref is a hashref with three keys. The first key, 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, spops_class, tells the installer what type of object should be created. The third key, field_order, describes how the succeeding data arrayrefs get mapped to fields in the object.

Other information you can use in the initial hashref:

• transform_default (\@)

  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.

• transform_now (\@)

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

Learn more about this whole process by reading the docs for 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 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

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 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.

COPYRIGHT

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

AUTHORS

Chris Winters <chris@cwinters.com>