Make the description reflect all functionality

We import more than CSVs, and more than just tickets. The description in
the docs should reflect that.

bin/rt-extension-import-csv.in

@@ -189,7 +189,7 @@ __END__
 
 =head1 NAME
 
-rt-extension-csv-importer - Import data and create tickets in RT
+rt-extension-csv-importer - Import data into RT
 
 =head1 SYNOPSIS
 
@@ -201,8 +201,8 @@ rt-extension-csv-importer - Import data and create tickets in RT
 
 =head1 DESCRIPTION
 
-This script will import/update RT from data in a CSV file. See
-L<RT::Extension::Import::CSV> for configuration.
+This script will import/update RT from data in a CSV and other types of
+delimted files. See L<RT::Extension::Import::CSV> for configuration.
 
 =head1 OPTIONS
 
@@ -217,11 +217,11 @@ that may get merged with per-import settings. This option is required.
 
 =item C<--type> I<user|ticket|transaction|article> or C<-t> I<user|ticket|transaction|article>
 
-Specify which type of data we shall import
+Specify which type of data shall be imported. This is required.
 
 =item C<--article-class> I<article class name>
 
-Specify the article class when type is article.
+Specify the article class. Required when type is article.
 
 =item C<--update>
 
@@ -251,13 +251,17 @@ ticket if not found.
 By default, tickets containing not-existing users will be skipped; with this
 flag, they will be created without those users.
 
-This also allows the script to continue processing even errors are found
-when parsing csv.
+This also allows the script to continue processing even if errors are found
+when parsing the CSV file.
 
 =item C<--run-scrips>
 
-By default, scrips are temporarily deactivated on C<Transaction> creation. Use
-this flag to allow RT to run scrips accordingly.
+When importing transactions, the default behavior is to deactivate scrips
+on transaction creation. Use this flag to allow RT to run scrips
+accordingly.
+
+This flag only affects transaction import; scrips are always run for
+all other import types.
 
 =item C<--mdy>, C<--dmy>
 

lib/RT/Extension/Import/CSV.pm

@@ -1050,6 +1050,8 @@ sub load_or_create_user {
     my $class = shift;
     my %args  = @_;
     my $user  = RT::User->new( delete $args{CurrentUser} );
+    $user->Load( $args{EmailAddress} );
+    return $user if $user->id;
     $user->LoadByEmail( $args{EmailAddress} );
     return $user if $user->id;
 
@@ -1322,6 +1324,13 @@ it on tickets without having to copy/paste from a KMS.
 
 =back
 
+This guide explains how to configure the import tool, and includes
+examples of how to run the import with different options. The actual
+import is run by L<rt-extension-import-csv> - there is no web-based
+component for the import process. Please see the documentation for
+L<rt-extension-import-csv> for more in-depth documentation about
+the options that the importer can be run with.
+
 =head1 RT VERSION
 
 Works with RT 5.
@@ -1422,6 +1431,42 @@ underscores with spaces.
 Using computed columns may cause false-positive "unused column"
 warnings during the import; these can be ignored.
 
+=head2 Dates and Date Formatting
+
+When importing tickets, the importer will automatically populate Created
+for you, provided there isn't a column in the source data already
+mapped to it. Other date fields must be provided in the source data.
+
+The importer expects incoming date values to conform to L<ISO|https://en.wikipedia.org/wiki/ISO_8601>
+datetime format (yyyy-mm-dd hh:mm::ss and other accepted variants). If
+your source data can't produce this formatting, Perl can help you out.
+
+For example, if the source data has dates in C<YYYY-MM-DD> format, we
+can write a function to append a default time to produce an ISO-formatted
+result:
+
+    Set( %TicketsImportFieldMapping,
+        'id'               => 'Ticket No',
+        'Owner'            => 'Assigned To',
+        'Status'           => 'Status',
+        'Subject'          => 'Title',
+        'Queue'            => \'General',
+        'CF.Delivery Date' => sub { return $_[0]->{ 'Delivery Date' } . ' 00:00:00'; },
+    );
+
+If you have other date columns you'd like to default to the date/time
+the import was run, Perl can help out there, too:
+
+    use POSIX qw(strftime);
+    Set( %TicketsImportFieldMapping,
+        'id'               => 'Ticket No',
+        'Owner'            => 'Assigned To',
+        'Status'           => 'Status',
+        'Subject'          => 'Title',
+        'Queue'            => \'General',
+        'CF.Project Start' => sub { return strftime "%Y-%m-%d %H:%M:%S", localtime; }
+    );
+
 =head2 Mandatory fields
 
 To mark some ticket fields mandatory:
@@ -1452,6 +1497,18 @@ Available options are described in the documentation for L<Text::CSV_XS/"new"|Te
 
 =over
 
+=item Roles and Custom Roles
+
+For RT's built-in roles (Owner, Cc, AdminCc, Requestor) and any custom
+roles, the import will first assume the value provided is a user name,
+and will attempt to look up a user with that name, followed by email
+address. Failing that, the importer will try to create a privileged
+user with the provided name.
+
+Should a user exist with the name provided and the target RT has external
+auth configured, the import will attempt to update the user with the
+latest information from the auth provider.
+
 =item Comment or Correspond
 
 To add a comment or correspond (reply) to a ticket, you can map a CSV column
@@ -1579,11 +1636,10 @@ in the callback. It expects no return value.
 
 =head1 RUNNING THE IMPORT WITH A NON-DEFAULT CONFIGURATION
 
-You can explicitly pass a configuration file to the importer. This is
-often used in conjunction when specifying an import type other than
-ticket. Use the C<--config> option to specify the path and filename
-to the configuration file to use; C<--type> indicates the type of
-import to run (article, ticket, transation, or article):
+You must explicitly pass a configuration file to the importer. Use the
+C<--config> option to specify the path and filename to the
+configuration file to use; C<--type> indicates the type of import to
+run (article, ticket, transation, or article):
 
     rt-extension-csv-importer --config /path/to/config.pm --type user /path/to/user-data.csv
     rt-extension-csv-importer --config /path/to/config.pm --type ticket /path/to/ticket-data.csv