FS/FS/part_export.pm

   1 package FS::part_export;
   2
   3 use strict;
   4 use vars qw( @ISA @EXPORT_OK %exports );
   5 use Exporter;
   6 use Tie::IxHash;
   7 use FS::Record qw( qsearch qsearchs dbh );
   8 use FS::part_svc;
   9 use FS::part_export_option;
  10 use FS::export_svc;
  11
  12 @ISA = qw(FS::Record);
  13 @EXPORT_OK = qw(export_info);
  14
  15 =head1 NAME
  16
  17 FS::part_export - Object methods for part_export records
  18
  19 =head1 SYNOPSIS
  20
  21   use FS::part_export;
  22
  23   $record = new FS::part_export \%hash;
  24   $record = new FS::part_export { 'column' => 'value' };
  25
  26   #($new_record, $options) = $template_recored->clone( $svcpart );
  27
  28   $error = $record->insert( { 'option' => 'value' } );
  29   $error = $record->insert( \%options );
  30
  31   $error = $new_record->replace($old_record);
  32
  33   $error = $record->delete;
  34
  35   $error = $record->check;
  36
  37 =head1 DESCRIPTION
  38
  39 An FS::part_export object represents an export of Freeside data to an external
  40 provisioning system.  FS::part_export inherits from FS::Record.  The following
  41 fields are currently supported:
  42
  43 =over 4
  44
  45 =item exportnum - primary key
  46
  47 =item machine - Machine name
  48
  49 =item exporttype - Export type
  50
  51 =item nodomain - blank or "Y" : usernames are exported to this service with no domain
  52
  53 =back
  54
  55 =head1 METHODS
  56
  57 =over 4
  58
  59 =item new HASHREF
  60
  61 Creates a new export.  To add the export to the database, see L<"insert">.
  62
  63 Note that this stores the hash reference, not a distinct copy of the hash it
  64 points to.  You can ask the object for a copy with the I<hash> method.
  65
  66 =cut
  67
  68 # the new method can be inherited from FS::Record, if a table method is defined
  69
  70 sub table { 'part_export'; }
  71
  72 =cut
  73
  74 #=item clone SVCPART
  75 #
  76 #An alternate constructor.  Creates a new export by duplicating an existing
  77 #export.  The given svcpart is assigned to the new export.
  78 #
  79 #Returns a list consisting of the new export object and a hashref of options.
  80 #
  81 #=cut
  82 #
  83 #sub clone {
  84 #  my $self = shift;
  85 #  my $class = ref($self);
  86 #  my %hash = $self->hash;
  87 #  $hash{'exportnum'} = '';
  88 #  $hash{'svcpart'} = shift;
  89 #  ( $class->new( \%hash ),
  90 #    { map { $_->optionname => $_->optionvalue }
  91 #        qsearch('part_export_option', { 'exportnum' => $self->exportnum } )
  92 #    }
  93 #  );
  94 #}
  95
  96 =item insert HASHREF
  97
  98 Adds this record to the database.  If there is an error, returns the error,
  99 otherwise returns false.
 100
 101 If a hash reference of options is supplied, part_export_option records are
 102 created (see L<FS::part_export_option>).
 103
 104 =cut
 105
 106 #false laziness w/queue.pm
 107 sub insert {
 108   my $self = shift;
 109   my $options = shift;
 110   local $SIG{HUP} = 'IGNORE';
 111   local $SIG{INT} = 'IGNORE';
 112   local $SIG{QUIT} = 'IGNORE';
 113   local $SIG{TERM} = 'IGNORE';
 114   local $SIG{TSTP} = 'IGNORE';
 115   local $SIG{PIPE} = 'IGNORE';
 116
 117   my $oldAutoCommit = $FS::UID::AutoCommit;
 118   local $FS::UID::AutoCommit = 0;
 119   my $dbh = dbh;
 120
 121   my $error = $self->SUPER::insert;
 122   if ( $error ) {
 123     $dbh->rollback if $oldAutoCommit;
 124     return $error;
 125   }
 126
 127   foreach my $optionname ( keys %{$options} ) {
 128     my $part_export_option = new FS::part_export_option ( {
 129       'exportnum'   => $self->exportnum,
 130       'optionname'  => $optionname,
 131       'optionvalue' => $options->{$optionname},
 132     } );
 133     $error = $part_export_option->insert;
 134     if ( $error ) {
 135       $dbh->rollback if $oldAutoCommit;
 136       return $error;
 137     }
 138   }
 139
 140   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 141
 142   '';
 143
 144 }
 145
 146 =item delete
 147
 148 Delete this record from the database.
 149
 150 =cut
 151
 152 #foreign keys would make this much less tedious... grr dumb mysql
 153 sub delete {
 154   my $self = shift;
 155   local $SIG{HUP} = 'IGNORE';
 156   local $SIG{INT} = 'IGNORE';
 157   local $SIG{QUIT} = 'IGNORE';
 158   local $SIG{TERM} = 'IGNORE';
 159   local $SIG{TSTP} = 'IGNORE';
 160   local $SIG{PIPE} = 'IGNORE';
 161
 162   my $oldAutoCommit = $FS::UID::AutoCommit;
 163   local $FS::UID::AutoCommit = 0;
 164   my $dbh = dbh;
 165
 166   my $error = $self->SUPER::delete;
 167   if ( $error ) {
 168     $dbh->rollback if $oldAutoCommit;
 169     return $error;
 170   }
 171
 172   foreach my $part_export_option ( $self->part_export_option ) {
 173     my $error = $part_export_option->delete;
 174     if ( $error ) {
 175       $dbh->rollback if $oldAutoCommit;
 176       return $error;
 177     }
 178   }
 179
 180   foreach my $export_svc ( $self->export_svc ) {
 181     my $error = $export_svc->delete;
 182     if ( $error ) {
 183       $dbh->rollback if $oldAutoCommit;
 184       return $error;
 185     }
 186   }
 187
 188   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 189
 190   '';
 191
 192 }
 193
 194 =item replace OLD_RECORD HASHREF
 195
 196 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 197 returns the error, otherwise returns false.
 198
 199 If a hash reference of options is supplied, part_export_option records are
 200 created or modified (see L<FS::part_export_option>).
 201
 202 =cut
 203
 204 sub replace {
 205   my $self = shift;
 206   my $old = shift;
 207   my $options = shift;
 208   local $SIG{HUP} = 'IGNORE';
 209   local $SIG{INT} = 'IGNORE';
 210   local $SIG{QUIT} = 'IGNORE';
 211   local $SIG{TERM} = 'IGNORE';
 212   local $SIG{TSTP} = 'IGNORE';
 213   local $SIG{PIPE} = 'IGNORE';
 214
 215   my $oldAutoCommit = $FS::UID::AutoCommit;
 216   local $FS::UID::AutoCommit = 0;
 217   my $dbh = dbh;
 218
 219   my $error = $self->SUPER::replace($old);
 220   if ( $error ) {
 221     $dbh->rollback if $oldAutoCommit;
 222     return $error;
 223   }
 224
 225   foreach my $optionname ( keys %{$options} ) {
 226     my $old = qsearchs( 'part_export_option', {
 227         'exportnum'   => $self->exportnum,
 228         'optionname'  => $optionname,
 229     } );
 230     my $new = new FS::part_export_option ( {
 231         'exportnum'   => $self->exportnum,
 232         'optionname'  => $optionname,
 233         'optionvalue' => $options->{$optionname},
 234     } );
 235     $new->optionnum($old->optionnum) if $old;
 236     my $error = $old ? $new->replace($old) : $new->insert;
 237     if ( $error ) {
 238       $dbh->rollback if $oldAutoCommit;
 239       return $error;
 240     }
 241   }
 242
 243   #remove extraneous old options
 244   foreach my $opt (
 245     grep { !exists $options->{$_->optionname} } $old->part_export_option
 246   ) {
 247     my $error = $opt->delete;
 248     if ( $error ) {
 249       $dbh->rollback if $oldAutoCommit;
 250       return $error;
 251     }
 252   }
 253
 254   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 255
 256   '';
 257
 258 };
 259
 260 =item check
 261
 262 Checks all fields to make sure this is a valid export.  If there is
 263 an error, returns the error, otherwise returns false.  Called by the insert
 264 and replace methods.
 265
 266 =cut
 267
 268 sub check {
 269   my $self = shift;
 270   my $error =
 271     $self->ut_numbern('exportnum')
 272     || $self->ut_domain('machine')
 273     || $self->ut_alpha('exporttype')
 274   ;
 275   return $error if $error;
 276
 277   warn $self->machine. "!!!\n";
 278
 279   $self->machine =~ /^([\w\-\.]*)$/
 280     or return "Illegal machine: ". $self->machine;
 281   $self->machine($1);
 282
 283   $self->nodomain =~ /^(Y?)$/ or return "Illegal nodomain: ". $self->nodomain;
 284   $self->nodomain($1);
 285
 286   $self->deprecated(1); #BLAH
 287
 288   #check exporttype?
 289
 290   ''; #no error
 291 }
 292
 293 #=item part_svc
 294 #
 295 #Returns the service definition (see L<FS::part_svc>) for this export.
 296 #
 297 #=cut
 298 #
 299 #sub part_svc {
 300 #  my $self = shift;
 301 #  qsearchs('part_svc', { svcpart => $self->svcpart } );
 302 #}
 303
 304 sub part_svc {
 305   use Carp;
 306   croak "FS::part_export::part_svc deprecated";
 307   #confess "FS::part_export::part_svc deprecated";
 308 }
 309
 310 =item export_svc
 311
 312 Returns a list of associated FS::export_svc records.
 313
 314 =cut
 315
 316 sub export_svc {
 317   my $self = shift;
 318   qsearch('export_svc', { 'exportnum' => $self->exportnum } );
 319 }
 320
 321 =item part_export_option
 322
 323 Returns all options as FS::part_export_option objects (see
 324 L<FS::part_export_option>).
 325
 326 =cut
 327
 328 sub part_export_option {
 329   my $self = shift;
 330   qsearch('part_export_option', { 'exportnum' => $self->exportnum } );
 331 }
 332
 333 =item options
 334
 335 Returns a list of option names and values suitable for assigning to a hash.
 336
 337 =cut
 338
 339 sub options {
 340   my $self = shift;
 341   map { $_->optionname => $_->optionvalue } $self->part_export_option;
 342 }
 343
 344 =item option OPTIONNAME
 345
 346 Returns the option value for the given name, or the empty string.
 347
 348 =cut
 349
 350 sub option {
 351   my $self = shift;
 352   my $part_export_option =
 353     qsearchs('part_export_option', {
 354       exportnum  => $self->exportnum,
 355       optionname => shift,
 356   } );
 357   $part_export_option ? $part_export_option->optionvalue : '';
 358 }
 359
 360 =item rebless
 361
 362 Reblesses the object into the FS::part_export::EXPORTTYPE class, where
 363 EXPORTTYPE is the object's I<exporttype> field.  There should be better docs
 364 on how to create new exports (and they should live in their own files and be
 365 autoloaded-on-demand), but until then, see L</NEW EXPORT CLASSES>.
 366
 367 =cut
 368
 369 sub rebless {
 370   my $self = shift;
 371   my $exporttype = $self->exporttype;
 372   my $class = ref($self). "::$exporttype";
 373   eval "use $class;" or die $@;
 374   bless($self, $class);
 375 }
 376
 377 =item export_insert SVC_OBJECT
 378
 379 =cut
 380
 381 sub export_insert {
 382   my $self = shift;
 383   $self->rebless;
 384   $self->_export_insert(@_);
 385 }
 386
 387 #sub AUTOLOAD {
 388 #  my $self = shift;
 389 #  $self->rebless;
 390 #  my $method = $AUTOLOAD;
 391 #  #$method =~ s/::(\w+)$/::_$1/; #infinite loop prevention
 392 #  $method =~ s/::(\w+)$/_$1/; #infinite loop prevention
 393 #  $self->$method(@_);
 394 #}
 395
 396 =item export_replace NEW OLD
 397
 398 =cut
 399
 400 sub export_replace {
 401   my $self = shift;
 402   $self->rebless;
 403   $self->_export_replace(@_);
 404 }
 405
 406 =item export_delete
 407
 408 =cut
 409
 410 sub export_delete {
 411   my $self = shift;
 412   $self->rebless;
 413   $self->_export_delete(@_);
 414 }
 415
 416 #fallbacks providing useful error messages intead of infinite loops
 417 sub _export_insert {
 418   my $self = shift;
 419   return "_export_insert: unknown export type ". $self->exporttype;
 420 }
 421
 422 sub _export_replace {
 423   my $self = shift;
 424   return "_export_replace: unknown export type ". $self->exporttype;
 425 }
 426
 427 sub _export_delete {
 428   my $self = shift;
 429   return "_export_delete: unknown export type ". $self->exporttype;
 430 }
 431
 432 =back
 433
 434 =head1 SUBROUTINES
 435
 436 =over 4
 437
 438 =item export_info [ SVCDB ]
 439
 440 Returns a hash reference of the exports for the given I<svcdb>, or if no
 441 I<svcdb> is specified, for all exports.  The keys of the hash are
 442 I<exporttype>s and the values are again hash references containing information
 443 on the export:
 444
 445   'desc'     => 'Description',
 446   'options'  => {
 447                   'option'  => { label=>'Option Label' },
 448                   'option2' => { label=>'Another label' },
 449                 },
 450   'nodomain' => 'Y', #or ''
 451   'notes'    => 'Additional notes',
 452
 453 =cut
 454
 455 sub export_info {
 456   #warn $_[0];
 457   return $exports{$_[0]} if @_;
 458   #{ map { %{$exports{$_}} } keys %exports };
 459   my $r = { map { %{$exports{$_}} } keys %exports };
 460 }
 461
 462 =item exporttype2svcdb EXPORTTYPE
 463
 464 Returns the applicable I<svcdb> for an I<exporttype>.
 465
 466 =cut
 467
 468 # This subroutine should be modified or removed.  In its present form, it
 469 # imposes the arbitrary restriction that no export type can be associated
 470 # with more than one svcdb.  The only place it's used is in edit/part_svc.cgi
 471 # to generate the list of allowed exports, which can be done more cleanly by
 472 # export_info anyway.
 473
 474 sub exporttype2svcdb {
 475   my $exporttype = $_[0];
 476   foreach my $svcdb ( keys %exports ) {
 477     return $svcdb if grep { $exporttype eq $_ } keys %{$exports{$svcdb}};
 478   }
 479   '';
 480 }
 481
 482 tie my %shellcommands_options, 'Tie::IxHash',
 483   #'machine' => { label=>'Remote machine' },
 484   'user' => { label=>'Remote username', default=>'root' },
 485   'useradd' => { label=>'Insert command',
 486                  default=>'useradd -d $dir -m -s $shell -u $uid $username'
 487                 #default=>'cp -pr /etc/skel $dir; chown -R $uid.$gid $dir'
 488                },
 489   'userdel' => { label=>'Delete command',
 490                  default=>'userdel $username',
 491                  #default=>'rm -rf $dir',
 492                },
 493   'usermod' => { label=>'Modify command',
 494                  default=>'usermod -d $new_dir -l $new_username -s $new_shell -u $new_uid $old_username',
 495                 #default=>'[ -d $old_dir ] && mv $old_dir $new_dir || ( '.
 496                  #  'chmod u+t $old_dir; mkdir $new_dir; cd $old_dir; '.
 497                  #  'find . -depth -print | cpio -pdm $new_dir; '.
 498                  #  'chmod u-t $new_dir; chown -R $uid.$gid $new_dir; '.
 499                  #  'rm -rf $old_dir'.
 500                  #')'
 501                },
 502 ;
 503
 504 tie my %sqlradius_options, 'Tie::IxHash',
 505   'datasrc'  => { label=>'DBI data source ' },
 506   'username' => { label=>'Database username' },
 507   'password' => { label=>'Database password' },
 508 ;
 509
 510 tie my %cyrus_options, 'Tie::IxHash',
 511   'server' => { label=>'IMAP server' },
 512   'username' => { label=>'Admin username' },
 513   'password' => { label=>'Admin password' },
 514 ;
 515
 516 tie my %cp_options, 'Tie::IxHash',
 517   'host'      => { label=>'Hostname' },
 518   'port'      => { label=>'Port number' },
 519   'username'  => { label=>'Username' },
 520   'password'  => { label=>'Password' },
 521   'domain'    => { label=>'Domain' },
 522   'workgroup' => { label=>'Default Workgroup' },
 523 ;
 524
 525 tie my %infostreet_options, 'Tie::IxHash',
 526   'url'      => { label=>'XML-RPC Access URL', },
 527   'login'    => { label=>'InfoStreet login', },
 528   'password' => { label=>'InfoStreet password', },
 529   'groupID'  => { label=>'InfoStreet groupID', },
 530 ;
 531
 532 tie my %vpopmail_options, 'Tie::IxHash',
 533   'machine' => { label=>'vpopmail machine', },
 534   'dir'     => { label=>'directory', }, # ?more info? default?
 535   'uid'     => { label=>'vpopmail uid' },
 536   'gid'     => { label=>'vpopmail gid' },
 537 ;
 538
 539 tie my %bind_options, 'Tie::IxHash',
 540   #'machine'    => { label=>'named machine' },
 541   'named_conf' => { label  => 'named.conf location',
 542                     default=> '/etc/bind/named.conf' },
 543   'zonepath'   => { label => 'path to zone files',
 544                     default=> '/etc/bind/', },
 545 ;
 546
 547 tie my %bind_slave_options, 'Tie::IxHash',
 548   #'machine'    => { label=> 'Slave machine' },
 549   'master'      => { label=> 'Master IP address(s) (semicolon-separated)' },
 550   'named_conf'  => { label   => 'named.conf location',
 551                      default => '/etc/bind/named.conf' },
 552 ;
 553
 554 tie my %sqlmail_options, 'Tie::IxHash',
 555   'datasrc'  => { label=>'DBI data source' },
 556   'username' => { label=>'Database username' },
 557   'password' => { label=>'Database password' },
 558 ;
 559
 560
 561 #export names cannot have dashes...
 562 %exports = (
 563   'svc_acct' => {
 564     'sysvshell' => {
 565       'desc' =>
 566         'Batch export of /etc/passwd and /etc/shadow files (Linux/SysV)',
 567       'options' => {},
 568     },
 569     'bsdshell' => {
 570       'desc' =>
 571         'Batch export of /etc/passwd and /etc/master.passwd files (BSD)',
 572       'options' => {},
 573     },
 574 #    'nis' => {
 575 #      'desc' =>
 576 #        'Batch export of /etc/global/passwd and /etc/global/shadow for NIS ',
 577 #      'options' => {},
 578 #    },
 579     'textradius' => {
 580       'desc' => 'Batch export of a text /etc/raddb/users file (Livingston, Cistron)',
 581       'options' => {},
 582     },
 583
 584     'shellcommands' => {
 585       'desc' => 'Real-time export via remote SSH (i.e. useradd, userdel, etc.)',
 586       'options' => \%shellcommands_options,
 587       'nodomain' => 'Y',
 588       'notes' => 'shellcommandsnotes... (this one is the nodomain one)',
 589     },
 590
 591     'sqlradius' => {
 592       'desc' => 'Real-time export to SQL-backed RADIUS (ICRADIUS, FreeRADIUS)',
 593       'options' => \%sqlradius_options,
 594       'nodomain' => 'Y',
 595       'notes' => 'Real-time export of radcheck, radreply and usergroup tables to any SQL database for <a href="http://www.freeradius.org/">FreeRADIUS</a> or <a href="http://radius.innercite.com/">ICRADIUS</a>.  Use <a href="../docs/man/bin/freeside-sqlradius-reset">freeside-sqlradius-reset</a> to delete and repopulate the tables from the Freeside database.  See the <a href="http://search.cpan.org/doc/TIMB/DBI-1.23/DBI.pm">DBI documentation</a> and the <a href="http://search.cpan.org/search?mode=module&query=DBD%3A%3A">documentation for your DBD</a> for the exact syntax of a DBI data source.  If using <a href="http://www.freeradius.org/">FreeRADIUS</a> 0.5 or above, make sure your <b>op</b> fields are set to allow NULL values.',
 596     },
 597
 598     'sqlmail' => {
 599       'desc' => 'Real-time export to SQL-backed mail server',
 600       'options' => \%sqlmail_options,
 601       'nodomain' => 'Y',
 602       'notes' => 'Database schema can be made to work with Courier IMAP and
 603  Exim.  Others could work but are untested.',
 604     },
 605
 606     'cyrus' => {
 607       'desc' => 'Real-time export to Cyrus IMAP server',
 608       'options' => \%cyrus_options,
 609       'nodomain' => 'Y',
 610       'notes' => 'Integration with <a href="http://asg.web.cmu.edu/cyrus/imapd/">Cyrus IMAP Server</a>.  Cyrus::IMAP::Admin should be installed locally and the connection to the server secured.  <B>svc_acct.quota</B>, if available, is used to set the Cyrus quota. '
 611     },
 612
 613     'cp' => {
 614       'desc' => 'Real-time export to Critical Path Account Provisioning Protocol',
 615       'options' => \%cp_options,
 616       'notes' => 'Real-time export to <a href="http://www.cp.net/">Critial Path Account Provisioning Protocol</a>.  Requires installation of <a href="http://search.cpan.org/search?dist=Net-APP">Net::APP</a> from CPAN.',
 617     },
 618
 619     'infostreet' => {
 620       'desc' => 'Real-time export to InfoStreet streetSmartAPI',
 621       'options' => \%infostreet_options,
 622       'nodomain' => 'Y',
 623       'notes' => 'Real-time export to <a href="http://www.infostreet.com/">InfoStreet</a> streetSmartAPI.  Requires installation of <a href="http://search.cpan.org/search?dist=Frontier-Client">Frontier::Client</a> from CPAN.',
 624     },
 625
 626     'vpopmail' => {
 627       'desc' => 'Real-time export to vpopmail text files',
 628       'options' => \%vpopmail_options,
 629
 630       'notes' => 'Real time export to <a href="http://inter7.com/vpopmail/">vpopmail</a> text files (...extended description from jeff?...)',
 631     },
 632
 633   },
 634
 635   'svc_domain' => {
 636
 637     'bind' => {
 638       'desc' =>'Batch export to BIND named',
 639       'options' => \%bind_options,
 640       'notes' => 'bind export notes File::Rsync dependancy, run bind.export',
 641     },
 642
 643     'bind_slave' => {
 644       'desc' =>'Batch export to slave BIND named',
 645       'options' => \%bind_slave_options,
 646       'notes' => 'bind export notes (secondary munge) File::Rsync dependancy, run bind.export',
 647     },
 648
 649     'sqlmail' => {
 650       'desc' => 'Real-time export to SQL-backed mail server',
 651       'options' => \%sqlmail_options,
 652       'nodomain' => 'Y',
 653       'notes' => 'Database schema can be made to work with Courier IMAP and
 654  Exim.  Others could work but are untested.',
 655     },
 656
 657
 658   },
 659
 660   'svc_acct_sm' => {},
 661
 662   'svc_forward' => {
 663     'sqlmail' => {
 664       'desc' => 'Real-time export to SQL-backed mail server',
 665       'options' => \%sqlmail_options,
 666       'nodomain' => 'Y',
 667       'notes' => 'Database schema can be made to work with Courier IMAP and
 668  Exim.  Others could work but are untested.',
 669     },
 670   },
 671
 672   'svc_www' => {},
 673
 674 );
 675
 676 =back
 677
 678 =head1 NEW EXPORT CLASSES
 679
 680 Should be added to the %export hash here, and a module should be added in
 681 FS/FS/part_export/ (an example may be found in eg/export_template.pm)
 682
 683 =head1 BUGS
 684
 685 Probably.
 686
 687 Hmm... cust_export class (not necessarily a database table...) ... ?
 688
 689 deprecated column...
 690
 691 =head1 SEE ALSO
 692
 693 L<FS::part_export_option>, L<FS::export_svc>, L<FS::svc_acct>,
 694 L<FS::svc_domain>,
 695 L<FS::svc_forward>, L<FS::Record>, schema.html from the base documentation.
 696
 697 =cut
 698
 699 1;
 700