lib/Net/Indosoft/QSuite.pm

   1 package Net::Indosoft::QSuite;
   2
   3 use strict;
   4 use warnings;
   5 use vars qw( $AUTOLOAD );
   6 use JSON;
   7 use Net::HTTPS::Any qw( https_post );
   8
   9 =head1 NAME
  10
  11 Net::Indosoft::QSuite - Interface to Indosoft Q-Suite API
  12
  13 =head1 VERSION
  14
  15 Version 0.01
  16
  17 =cut
  18
  19 our $VERSION = '0.01';
  20
  21
  22 =head1 SYNOPSIS
  23
  24     use Net::Indosoft::QSuite;
  25
  26     my $qsuite = Net::Indosoft::QSuite->new(
  27       host        => 'server.example.com',
  28       gateway_key => '09ad8f6b692717316913809f9903fd08',
  29     );
  30
  31
  32     ###
  33     # Manage Tenant
  34     ###
  35
  36     my $uuid = $qsuite->editTenant(
  37                                    mode            => 'create',
  38                                    name            => 'Tenant One',
  39                                    shortname       => 'one',
  40                                    hostname        => 'one.tenant.com',
  41                                    callerid_name   => 'Tenant One',
  42                                    callerid_number => '5551112222',
  43                                   )
  44       or die "can't create tenant: ". $qsuite->errstr;
  45
  46     my $uuid = $qsuite->editTenant(
  47                                    mode            => 'edit',
  48                                    uuid            => 'Tenant UUID',
  49                                    name            => 'Tenant Name',
  50                                    shortname       => 'Tenant shortname',
  51                                    hostname        => 'Tenant hostname',
  52                                    callerid_name   => 'Nailup caller ID name',
  53                                    callerid_number => 'Nailup caller ID number',
  54                                   )
  55       or die "can't edit tenant: ". $qsuite->errstr;
  56
  57     $qsuite->editTenant(
  58                          mode        => 'delete',
  59                          uuid        => 'Tenant UUID',
  60                        )
  61       or die "can't delete tenant: ". $qsuite->errstr;
  62
  63
  64     ###
  65     # Manage Trunk Assignments
  66     ###
  67
  68     my $uuid = $qsuite->assignTrunkToTenant(
  69                             mode        => 'assign',
  70                             tenant_uuid => 'f269fa3480e739d77e4fee61f94575e2',
  71                             trunk_id    => '1', #provided by indosoft
  72                )
  73       or die  "can't assign trunk to tenant ". $qsuite->errstr;
  74
  75     my $uuid = $qsuite->assignTrunkToTenant(
  76                             mode        => 'unassign',
  77                             tenant_uuid => 'Tenant UUID',
  78                             trunk_id    => 'trunk ID,     #provided by indosoft
  79                )
  80       or die  "can't trunk from tenant: ". $qsuite->errstr;
  81
  82
  83     ###
  84     # Manage DID
  85     ###
  86
  87     my $number = $qsuite->editDID(
  88                    mode                => 'create',
  89                    tenant_uuid         => 'f269fa3480e739d77e4fee61f94575e2',
  90                    number              => '4445550011',
  91                    auto_attendant_uuid => 'c4367c52bf45525bfbb7614b167a5335',
  92                  )
  93       or die "can't create DID: ". $qsuite->errstr;
  94
  95
  96     my $number = $qsuite->editDID(
  97                    mode                => 'edit'
  98                    tenant_uuid         => 'Tenant UUID',
  99                    number              => 'The DID number',
 100                    auto_attendant_uuid => 'UUID of the assigned auto attendant',
 101                  )
 102       or die "can't edit DID: ". $qsuite->errstr;
 103
 104     my $number = $qsuite->editDID(
 105                    mode                => 'delete'
 106                    tenant_uuid         => 'Tenant UUID',
 107                  )
 108       or die "can't delete DID: ". $qsuite->errstr;
 109
 110
 111     ###
 112     # Manage Auto Attendant
 113     ###
 114
 115     my $uuid = $qsuite->editAutoAttendant(
 116                   mode                    => 'create',
 117                   tenant_uuid             => 'f269fa3480e739d77e4fee61f94575e2',
 118                   name                    => 'Auto F. Atttendant',
 119                   repeat_limit            => 54,
 120                   response_limit          => 32,
 121                   allow_extension_dialing => 0, # 0 or 1
 122                )
 123       or die "can't create auto attendant: ". $qsuite->errstr;
 124
 125     my $uuid = $qsuite->editAutoAttendant(
 126                   mode                    => 'edit'
 127                   tenant_uuid             => 'Tenant UUID',
 128                   uuid                    => 'UUID of the assigned auto attendant',
 129                   name                    => 'Auto Attenant name',
 130                   repeat_limit            => 54, # The number of time to attempt to gather input
 131                   response_limit          => 32, # The timeout on the response
 132                   allow_extension_dialing => 0, # "Allow the caller to dial extensions with the menu
 133                )
 134       or die "can't edit auto attendant: ". $qsuite->errstr;
 135
 136     my $uuid = $qsuite->editAutoAttendant(
 137                   mode                => 'delete'
 138                   tenant_uuid         => 'Tenant UUID',
 139                   uuid                => 'UUID of the assigned auto attendant',
 140                )
 141       or die "can't delete auto attendant: ". $qsuite->errstr;
 142
 143
 144     ###
 145     # Manage Ring Group
 146     ###
 147
 148     my $uuid = $qsuite->editRingGroup(
 149                   mode            => 'create',
 150                   tenant_uuid     => 'f269fa3480e739d77e4fee61f94575e2',
 151                   #docs say uuid ('ring group uuid') for create, but prob. wrong
 152                   name            => 'Ring Group',
 153                   timeout         => 54,
 154                   extension_uuids => '432789473febdf00fe1ee77777777777,ab98342efabc43',
 155                )
 156       or die "can't create ring group: ". $qsuite->errstr;
 157
 158     my $uuid = $qsuite->editRingGroup(
 159                   mode            => 'edit'
 160                   tenant_uuid     => 'Tenant UUID',
 161                   uuid            => 'Ring group UUID',
 162                   name            => 'Ring group name',
 163                   timeout         => 54, # Ring group timeout
 164                   extension_uuids => '1234abc,999fefefefe', # Comma-separated list of extension UUIDs that make up the ring group
 165                )
 166       or die "can't edit ring group: ". $qsuite->errstr;
 167
 168     my $uuid = $qsuite->editRingGroup(
 169                   mode            => 'delete'
 170                   tenant_uuid     => 'Tenant UUID',
 171                   uuid            => 'Ring group UUID',
 172                )
 173       or die "can't delete ring group: ". $qsuite->errstr;
 174
 175
 176     ###
 177     # Manage Employee/User
 178     ###
 179
 180     my $uuid = $qsuite->editEmployee(
 181                   mode        => 'create',
 182                   tenant_uuid => 'f269fa3480e739d77e4fee61f94575e2',
 183                   #docs say uuid ('employee uuid') for create, but prob. wrong
 184                   username    => 'tofub',
 185                   password    => 'beast1',
 186                   firstname   => 'Tofu',
 187                   lastname    => 'Beast',
 188                )
 189       or die "can't create employee: ". $qsuite->errstr;
 190
 191     my $uuid = $qsuite->editEmployee(
 192                   mode        => 'edit'
 193                   tenant_uuid => 'Tenant UUID',
 194                   uuid        => 'Employee UUID',
 195                   username    => 'tofub',
 196                   password    => 'beast1',
 197                   firstname   => 'Tofu',
 198                   lastname    => 'Beast',
 199                )
 200       or die "can't edit employee: ". $qsuite->errstr;
 201
 202     my $uuid = $qsuite->editEmployee(
 203                   mode            => 'delete'
 204                   tenant_uuid     => 'Tenant UUID',
 205                   uuid            => 'Employee UUID',
 206                )
 207       or die "can't delete employee: ". $qsuite->errstr;
 208
 209
 210     ###
 211     # Manage Extension
 212     ###
 213
 214     #or does this return an "extension uuid"?  its wanted for devices...
 215     my $number = $qsuite->editExtension(
 216                    mode        => 'create',
 217                    tenant_uuid => 'f269fa3480e739d77e4fee61f94575e2',
 218                    number      => '101',
 219                  )
 220       or die "can't create extension: ". $qsuite->errstr;
 221
 222     #this is documented but seems to make no sense
 223     #my $number = $qsuite->editExtension(
 224     #               mode        => 'edit'
 225     #               tenant_uuid => 'Tenant UUID',
 226     #               number      => '101',
 227     #             )
 228     #  or die "can't edit extension: ". $qsuite->errstr;
 229
 230     #or does this want an "extension uuid"?
 231     my $number = $qsuite->editExtension(
 232                    mode        => 'delete'
 233                    tenant_uuid => 'Tenant UUID',
 234                    number      => '101',
 235                 )
 236       or die "can't delete extension: ". $qsuite->errstr;
 237
 238
 239     ###
 240     # Manage Device
 241     ###
 242
 243     my $uuid = $qsuite->editDevice(
 244                    mode           => 'create',
 245                    tenant_uuid    => 'f269fa3480e739d77e4fee61f94575e2',
 246                    employee_uuid  => 'f269fa3480e739d77e4fee61f94575e2',
 247                    extension_uuid => 'f269fa3480e739d77e4fee61f94575e2',
 248                    #docs say "device uuid" for create, but i doubt it
 249                    protocol       => 'sip', #sip iax or dahdi
 250                  )
 251       or die "can't create device: ". $qsuite->errstr;
 252
 253     my $uuid = $qsuite->editDevice(
 254                    mode           => 'edit'
 255                    tenant_uuid    => 'Tenant UUID',
 256                    employee_uuid  => 'Employee UUID',
 257                    extension_uuid => 'Extension UUID',
 258                    uuid           => 'Device UUID',
 259                    protocol       => 'sip', #sip iax or dahdi
 260                )
 261       or die "can't edit device: ". $qsuite->errstr;
 262
 263     #docs for required fields here appear to be on crack (tenant_uuid only?),
 264     # so my best guess
 265     my $uuid = $qsuite->editDevice(
 266                    mode           => 'delete'
 267                    #perhaps? tenant_uuid    => 'Tenant UUID',
 268                    #perhaps? employee_uuid  => 'Employee UUID',
 269                    #perhaps? extension_uuid => 'Extension UUID',
 270                    uuid           => 'Device UUID',
 271                )
 272       or die "can't delete device: ". $qsuite->errstr;
 273
 274
 275     ###
 276     # Manage Voicemail Settings
 277     ###
 278
 279     my $uuid = $qsuite->editVoicemailSettings(
 280                    extension_uuid => 'f269fa3480e739d77e4fee61f94575e2',
 281                    pin            => '5454',
 282                )
 283       or die "can't edit voicemail: ". $qsuite->errstr;
 284
 285
 286     ###
 287     # Manage Extension Forwarding Settings
 288     ###
 289
 290     my $uuid = $qsuite->editForwardingSettings(
 291                    #perhaps? docs say yes, exampe no tenant_uuid    => 'f269fa3480e739d77e4fee61f94575e2',
 292                    extension_uuid => 'f269fa3480e739d77e4fee61f94575e2',
 293                    number         => '555-888-2222',
 294                )
 295       or die "can't edit forwarding: ". $qsuite->errstr;
 296
 297
 298 =head1 METHODS
 299
 300 =head2 new
 301
 302 Creates a new Net::Indosoft:QSuite object.  Options may be passed
 303 as a hash reference or a flat list of names and values.
 304
 305 =over 4
 306
 307 =item host (required)
 308
 309 =item gateway_key - A valid API gateway key (required)
 310
 311 =item debug (optional)
 312
 313 =back
 314
 315 =cut
 316
 317 sub new {
 318   my $proto = shift;
 319   my $class = ref($proto) || $proto;
 320   my $self = ref($_[0]) ? shift : { @_ };
 321   $self->{'debug'} ||= 0;
 322   bless($self, $class);
 323 }
 324
 325 =head2 errstr
 326
 327 =cut
 328
 329 sub errstr {
 330   #my $class = shift;
 331   #return $errstr
 332   #  unless ref($class) && $class->isa('Net::VoIP_Innovations');
 333
 334   my $self = shift; #$class;
 335   $self->{errstr};
 336 }
 337
 338 =head2 editTenant
 339
 340 =head2 assignTrunkToTenant
 341
 342 =head2 editDID
 343
 344 =head2 editAutoAttendant
 345
 346 =cut
 347
 348 #our %return = (
 349 #  'Tenant'             => 'uuid',
 350 #  'DID'                => 'number',
 351 #  'AutoAttendant'      => 'uuid',
 352 #  'RingGroup'          => 'uuid', #?  its undocumented
 353 #  'Employee'           => 'uuid',
 354 #  'Extension'          => 'number',
 355 #  'Device'             => 'uuid',
 356 #  'VoicemailSettings'  => 'uuid',
 357 #  'ForwardingSettings' => 'uuid',
 358 #);
 359
 360 sub AUTOLOAD {
 361   my $self = shift;
 362   my $opts = ref($_[0]) ? shift : { @_ };
 363
 364   $AUTOLOAD =~ /(^|::)(\w+)$/ or die "unparsable AUTOLOAD: $AUTOLOAD";
 365   my $func = $2;
 366   my $path = "/cti/api/external/$func.json";
 367
 368   my ( $page, $https_response, %reply_headers ) =
 369     https_post({ host => $self->{host},
 370                  port => 443,
 371                  path => $path,
 372               });
 373
 374   unless ( $https_response =~ /^200/i ) {
 375     #this is a lower-layer communication error, so it warrants an exception
 376     die "Error POSTing to https://". $self->{host}. "$path : $https_response\n";
 377     #$self->{'errstr'} = $https_response;
 378     #return '';
 379   }
 380
 381   my $response = decode_json( $page );
 382
 383   #use Data::Dumper;
 384   #warn Dumper($response); #if $self->{debug};
 385
 386   unless ( $response->{success} ) { # == 1
 387     $self->{errstr} = $response->{error};
 388     return '';
 389   }
 390
 391   $self->{errstr} = '';
 392
 393   # use %return if it gets more complicated
 394   if ( $func =~ /(DID|Extension)$/ ) {
 395     return $response->{data}{number};
 396   } else {
 397     return $response->{data}{uuid};
 398   }
 399
 400 }
 401
 402 =head1 AUTHOR
 403
 404 Ivan Kohler, C<< <ivan-indosoft at freeside.biz> >>
 405
 406 =head1 BUGS
 407
 408 Please report any bugs or feature requests to C<bug-net-indosoft-qsuite at rt.cpan.org>, or through
 409 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Indosoft-QSuite>.  I will be notified, and then you'll
 410 automatically be notified of progress on your bug as I make changes.
 411
 412 =head1 SUPPORT
 413
 414 You can find documentation for this module with the perldoc command.
 415
 416     perldoc Net::Indosoft::QSuite
 417
 418
 419 You can also look for information at:
 420
 421 =over 4
 422
 423 =item * RT: CPAN's request tracker (report bugs here)
 424
 425 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Indosoft-QSuite>
 426
 427 =item * AnnoCPAN: Annotated CPAN documentation
 428
 429 L<http://annocpan.org/dist/Net-Indosoft-QSuite>
 430
 431 =item * CPAN Ratings
 432
 433 L<http://cpanratings.perl.org/d/Net-Indosoft-QSuite>
 434
 435 =item * Search CPAN
 436
 437 L<http://search.cpan.org/dist/Net-Indosoft-QSuite/>
 438
 439 =back
 440
 441
 442 =head1 ACKNOWLEDGEMENTS
 443
 444
 445 =head1 LICENSE AND COPYRIGHT
 446
 447 Copyright (C) 2014 Freeside Internet Services, Inc. (http://freeside.biz/)
 448
 449 This program is free software; you can redistribute it and/or modify it
 450 under the same terms as Perl itself.
 451
 452 =head1 ADVERTISEMENT
 453
 454 Need a complete, open-source back-office and customer self-service solution?
 455 The Freeside software includes support for Indosoft integration, CDR
 456 rating, invoicing, credit card and electronic check processing, integrated
 457 trouble ticketing, and customer signup and self-service web interfaces.
 458
 459 http://freeside.biz/freeside/
 460
 461 =cut
 462
 463 1;