1 package FS::part_export::saisei;
4 use vars qw( @ISA %info );
5 use base qw( FS::part_export );
6 use Date::Format 'time2str';
17 FS::part_export::saisei
21 Saisei integration for Freeside
25 This export offers basic svc_broadband provisioning for Saisei.
27 This is a customer integration with Saisei. This will set up a rate plan and tie
28 the rate plan to a host and the access point via the Saisei API when the broadband service is provisioned.
29 It will also untie the host from the rate plan, setting it to the default rate plan via the API upon unprovisioning of the broadband service.
31 This will create and modify the rate plans at Saisei as soon as the broadband service attached to this export is created or modified.
32 This will also create and modify an access point at Saisei as soon as the tower is created or modified.
34 To use this export, follow the below instructions:
36 Create a new service definition and set the table to svc_broadband. The service name will become the Saisei rate plan name.
37 Set the upload and download speed for the service. This is required to be able to export the service to Saisei.
38 Attach this Saisei export to this service.
40 Create a tower and add a sector to that tower. The sector name will be the name of the access point,
41 Make sure you have set the up and down rate limit for the tower and the sector. This is required to be able to export the access point.
42 The tower and sector will be set up as access points at Saisei upon the creation of the tower or sector. They will be modified at Saisei when modified in freeside.
43 Each sector will be attached to its tower access point using the Saisei uplink field.
45 Create a package for the above created service, and order this package for a customer.
47 Provision the service, making sure to enter the IP address associated with this service and select the tower and sector for it's access point.
48 This provisioned service will then be exported as a host to Saisei.
50 Unprovisioning this service will set the host entry at Saisei to the default rate plan with the user and access point set to <none>.
52 After this export is set up and attached to a service, you can export the already provisioned services by clicking the link Export provisioned services attached to this export.
53 Clicking on this link will export all services attached to this export not currently exported to Saisei.
55 This module also provides generic methods for working through the L</Saisei API>.
59 tie my %scripts, 'Tie::IxHash',
60 'export_provisioned_services' => { component => '/elements/popup_link.html',
61 label => 'Export provisioned services',
62 description => 'will export provisioned services of part service with Saisei export attached.',
63 html_label => '<b>Export provisioned services attached to this export.</b>',
67 tie my %options, 'Tie::IxHash',
68 'port' => { label => 'Port',
70 'username' => { label => 'Saisei API User Name',
72 'password' => { label => 'Saisei API Password',
74 'debug' => { type => 'checkbox',
75 label => 'Enable debug warnings' },
79 'svc' => 'svc_broadband',
80 'desc' => 'Export broadband service/account to Saisei',
81 'options' => \%options,
82 'scripts' => \%scripts,
84 This is a customer integration with Saisei. This will set up a rate plan and tie
85 the rate plan to a host and the access point via the Saisei API when the broadband service is provisioned.
86 It will also untie the host from the rate plan, setting it to the default rate plan via the API upon unprovisioning of the broadband service.
88 This will create and modify the rate plans at Saisei as soon as the broadband service attached to this export is created or modified.
89 This will also create and modify an access point at Saisei as soon as the tower is created or modified.
91 To use this export, follow the below instructions:
95 Create a new service definition and set the table to svc_broadband. The service name will become the Saisei rate plan name.
96 Set the upload and download speed for the service. This is required to be able to export the service to Saisei.
97 Attach this Saisei export to this service.
101 Create a tower and add a sector to that tower. The sector name will be the name of the access point,
102 Make sure you have set the up and down rate limit for the tower and the sector. This is required to be able to export the access point.
103 The tower and sector will be set up as access points at Saisei upon the creation of the tower or sector. They will be modified at Saisei when modified in freeside.
104 Each sector will be attached to its tower access point using the Saisei uplink field.
108 Create a package for the above created service, and order this package for a customer.
112 Provision the service, making sure to enter the IP address associated with this service and select the tower and sector for it's access point.
113 This provisioned service will then be exported as a host to Saisei.
115 Unprovisioning this service will set the host entry at Saisei to the default rate plan with the user and access point set to <i>none</i>.
119 After this export is set up and attached to a service, you can export the already provisioned services by clicking the link <b>Export provisioned services attached to this export</b>.
120 Clicking on this link will export all services attached to this export not currently exported to Saisei.
129 my ($self, $svc_broadband) = @_;
131 my $rateplan_name = $self->get_rateplan_name($svc_broadband);
133 # check for existing rate plan
134 my $existing_rateplan;
135 $existing_rateplan = $self->api_get_rateplan($rateplan_name) unless $self->{'__saisei_error'};
137 # if no existing rate plan create one and modify it.
138 $self->api_create_rateplan($svc_broadband, $rateplan_name) unless $existing_rateplan;
139 $self->api_modify_rateplan($svc_broadband, $rateplan_name) unless ($self->{'__saisei_error'} || $existing_rateplan);
140 return $self->api_error if $self->{'__saisei_error'};
142 # set rateplan to existing one or newly created one.
143 my $rateplan = $existing_rateplan ? $existing_rateplan : $self->api_get_rateplan($rateplan_name);
145 my $username = $svc_broadband->{Hash}->{svcnum};
146 my $description = $svc_broadband->{Hash}->{description};
149 $self->{'__saisei_error'} = 'no username - can not export';
150 return $self->api_error;
153 # check for existing user.
155 $existing_user = $self->api_get_user($username) unless $self->{'__saisei_error'};
157 # if no existing user create one.
158 $self->api_create_user($username, $description) unless $existing_user;
159 return $self->api_error if $self->{'__saisei_error'};
161 # set user to existing one or newly created one.
162 my $user = $existing_user ? $existing_user : $self->api_get_user($username);
165 my $tower_sector = FS::Record::qsearchs({
166 'table' => 'tower_sector',
167 'select' => 'tower.towername,
168 tower.up_rate_limit as tower_upratelimit,
169 tower.down_rate_limit as tower_downratelimit,
170 tower_sector.sectorname,
171 tower_sector.up_rate_limit as sector_upratelimit,
172 tower_sector.down_rate_limit as sector_downratelimit ',
173 'addl_from' => 'LEFT JOIN tower USING ( towernum )',
175 'sectornum' => $svc_broadband->{Hash}->{sectornum},
179 my $tower_name = $tower_sector->{Hash}->{towername};
180 $tower_name =~ s/\s/_/g;
183 'tower_name' => $tower_name,
184 'tower_uprate_limit' => $tower_sector->{Hash}->{tower_upratelimit},
185 'tower_downrate_limit' => $tower_sector->{Hash}->{tower_downratelimit},
188 my $tower_ap = process_tower($self, $tower_opt);
189 return $self->api_error if $self->{'__saisei_error'};
191 my $sector_name = $tower_sector->{Hash}->{sectorname};
192 $sector_name =~ s/\s/_/g;
195 'tower_name' => $tower_name,
196 'sector_name' => $sector_name,
197 'sector_uprate_limit' => $tower_sector->{Hash}->{sector_upratelimit},
198 'sector_downrate_limit' => $tower_sector->{Hash}->{sector_downratelimit},
200 my $accesspoint = process_sector($self, $sector_opt);
201 return $self->api_error if $self->{'__saisei_error'};
203 ## tie host to user add sector name as access point.
204 $self->api_add_host_to_user(
205 $user->{collection}->[0]->{name},
206 $rateplan->{collection}->[0]->{name},
207 $svc_broadband->{Hash}->{ip_addr},
208 $accesspoint->{collection}->[0]->{name},
209 ) unless $self->{'__saisei_error'};
212 return $self->api_error;
216 sub _export_replace {
217 my ($self, $svc_broadband) = @_;
218 $self->_export_insert($svc_broadband);
223 my ($self, $svc_broadband) = @_;
225 my $rateplan_name = $self->get_rateplan_name($svc_broadband);
227 my $username = $svc_broadband->{Hash}->{svcnum};
229 ## untie host to user
230 $self->api_delete_host_to_user($username, $rateplan_name, $svc_broadband->{Hash}->{ip_addr}) unless $self->{'__saisei_error'};
235 sub _export_suspend {
236 my ($self, $svc_broadband) = @_;
240 sub _export_unsuspend {
241 my ($self, $svc_broadband) = @_;
246 my ($self, $svc_part) = @_;
249 if ($svc_part->{Hash}->{svc_broadband__speed_down} eq "down" || $svc_part->{Hash}->{svc_broadband__speed_up} eq "up") {
250 for my $type (qw( down up )) {
251 my $speed_type = "broadband_".$type."stream";
252 foreach my $pkg_svc (FS::Record::qsearch({
253 'table' => 'pkg_svc',
254 'select' => 'pkg_svc.*, part_pkg_fcc_option.fccoptionname, part_pkg_fcc_option.optionvalue',
255 'addl_from' => ' LEFT JOIN part_pkg_fcc_option USING (pkgpart) ',
256 'extra_sql' => " WHERE pkg_svc.svcpart = ".$svc_part->{Hash}->{svcpart}." AND pkg_svc.quantity > 0 AND part_pkg_fcc_option.fccoptionname = '".$speed_type."'",
257 })) { $fcc_477_speeds->{
258 $pkg_svc->{Hash}->{pkgpart}}->{$speed_type} = $pkg_svc->{Hash}->{optionvalue} * 1000 unless !$pkg_svc->{Hash}->{optionvalue}; }
262 $fcc_477_speeds->{1}->{broadband_downstream} = $svc_part->{Hash}->{"svc_broadband__speed_down"};
263 $fcc_477_speeds->{1}->{broadband_upstream} = $svc_part->{Hash}->{"svc_broadband__speed_up"};
266 foreach my $key (keys %$fcc_477_speeds) {
268 $svc_part->{Hash}->{speed_down} = $fcc_477_speeds->{$key}->{broadband_downstream};
269 $svc_part->{Hash}->{speed_up} = $fcc_477_speeds->{$key}->{broadband_upstream};
270 $svc_part->{Hash}->{svc_broadband__speed_down} = $fcc_477_speeds->{$key}->{broadband_downstream};
271 $svc_part->{Hash}->{svc_broadband__speed_up} = $fcc_477_speeds->{$key}->{broadband_upstream};
273 my $temp_svc = $svc_part->{Hash};
274 my $svc_broadband = {};
275 map { if ($_ =~ /^svc_broadband__(.*)$/) { $svc_broadband->{Hash}->{$1} = $temp_svc->{$_}; } } keys %$temp_svc;
277 my $rateplan_name = $self->get_rateplan_name($svc_broadband, $svc_part->{Hash}->{svc});
279 # check for existing rate plan
280 my $existing_rateplan;
281 $existing_rateplan = $self->api_get_rateplan($rateplan_name) unless $self->{'__saisei_error'};
283 # Modify the existing rate plan with new service data.
284 $self->api_modify_existing_rateplan($svc_broadband, $rateplan_name) unless ($self->{'__saisei_error'} || !$existing_rateplan);
286 # if no existing rate plan create one and modify it.
287 $self->api_create_rateplan($svc_broadband, $rateplan_name) unless $existing_rateplan;
288 $self->api_modify_rateplan($svc_part, $rateplan_name) unless ($self->{'__saisei_error'} || $existing_rateplan);
292 return $self->api_error;
296 sub export_tower_sector {
297 my ($self, $tower) = @_;
299 #modify tower or create it.
300 my $tower_name = $tower->{Hash}->{towername};
301 $tower_name =~ s/\s/_/g;
303 'tower_name' => $tower_name,
304 'tower_uprate_limit' => $tower->{Hash}->{up_rate_limit},
305 'tower_downrate_limit' => $tower->{Hash}->{down_rate_limit},
306 'modify_existing' => '1', # modify an existing access point with this info
309 my $tower_access_point = process_tower($self, $tower_opt);
311 #get list of all access points
313 'table' => 'tower_sector',
315 'hashref' => { 'towernum' => $tower->{Hash}->{towernum}, },
318 #for each one modify or create it.
319 foreach my $tower_sector ( FS::Record::qsearch($hash_opt) ) {
320 my $sector_name = $tower_sector->{Hash}->{sectorname};
321 $sector_name =~ s/\s/_/g;
323 'tower_name' => $tower_name,
324 'sector_name' => $sector_name,
325 'sector_uprate_limit' => $tower_sector->{Hash}->{up_rate_limit},
326 'sector_downrate_limit' => $tower_sector->{Hash}->{down_rate_limit},
327 'modify_existing' => '1', # modify an existing access point with this info
329 my $sector_access_point = process_sector($self, $sector_opt);
332 return $self->api_error;
335 ## creates the rateplan name
336 sub get_rateplan_name {
337 my ($self, $svc_broadband, $svc_name) = @_;
339 my $service_part = FS::Record::qsearchs( 'part_svc', { 'svcpart' => $svc_broadband->{Hash}->{svcpart} } ) unless $svc_name;
340 my $service_name = $svc_name ? $svc_name : $service_part->{Hash}->{svc};
342 my $rateplan_name = $service_name . " " . $svc_broadband->{Hash}->{speed_down} . "-" . $svc_broadband->{Hash}->{speed_up};
343 $rateplan_name =~ s/\s/_/g;
345 return $rateplan_name;
350 These methods allow access to the Saisei API using the credentials
351 set in the export options.
357 Accepts I<$method>, I<$path>, I<$params> hashref and optional.
358 Places an api call to the specified path and method with the specified params.
359 Returns the decoded json object returned by the api call.
360 Returns empty on failure; retrieve error messages using L</api_error>.
365 my ($self,$method,$path,$params) = @_;
367 $self->{'__saisei_error'} = '';
368 my $auth_info = $self->option('username') . ':' . $self->option('password');
371 warn "Calling $method on http://"
372 .$self->{Hash}->{machine}.':'.$self->option('port')
373 ."/rest/stm/configurations/running/$path\n" if $self->option('debug');
375 my $data = encode_json($params) if keys %{ $params };
377 my $client = REST::Client->new();
378 $client->addHeader("Authorization", "Basic ".encode_base64($auth_info));
379 $client->setHost('http://'.$self->{Hash}->{machine}.':'.$self->option('port'));
380 $client->$method('/rest/stm/configurations/running'.$path, $data, { "Content-type" => 'application/json'});
382 warn "Response Code is ".$client->responseCode()."\n" if $self->option('debug');
386 if ($client->responseCode() eq '200' || $client->responseCode() eq '201') {
387 eval { $result = decode_json($client->responseContent()) };
389 $self->{'__saisei_error'} = "Error decoding json: $@";
394 $self->{'__saisei_error'} = "Bad response from server during $method: " . $client->responseContent()
395 unless ($method eq "GET");
396 warn "Response Content is\n".$client->responseContent."\n" if $self->option('debug');
406 Returns the error string set by L</Saisei API> methods,
407 or a blank string if most recent call produced no errors.
413 return $self->{'__saisei_error'} || '';
416 =head2 api_get_policies
418 Gets a list of global policies.
422 sub api_get_policies {
425 my $get_policies = $self->api_call("GET", '/policies/?token=1&order=name&start=0&limit=20&select=name%2Cpercent_rate%2Cassured%2C');
426 return if $self->api_error;
427 $self->{'__saisei_error'} = "Did not receive any global policies"
428 unless $get_policies;
430 return $get_policies->{collection};
433 =head2 api_get_rateplan
435 Gets rateplan info for specific rateplan.
439 sub api_get_rateplan {
441 my $rateplan = shift;
443 my $get_rateplan = $self->api_call("GET", "/rate_plans/$rateplan");
444 return if $self->api_error;
446 return $get_rateplan;
451 Gets user info for specific user.
459 my $get_user = $self->api_call("GET", "/users/$user");
460 return if $self->api_error;
465 =head2 api_get_accesspoint
467 Gets user info for specific access point.
471 sub api_get_accesspoint {
473 my $accesspoint = shift;
475 my $get_accesspoint = $self->api_call("GET", "/access_points/$accesspoint");
476 return if $self->api_error;
478 return $get_accesspoint;
483 Gets user info for specific host.
491 my $get_host = $self->api_call("GET", "/hosts/$ip");
493 return if $self->api_error;
498 =head2 api_create_rateplan
504 sub api_create_rateplan {
505 my ($self, $svc, $rateplan) = @_;
507 $self->{'__saisei_error'} = "No downrate listed for service $rateplan" if !$svc->{Hash}->{speed_down};
508 $self->{'__saisei_error'} = "No uprate listed for service $rateplan" if !$svc->{Hash}->{speed_up};
510 my $new_rateplan = $self->api_call(
512 "/rate_plans/$rateplan",
514 'downstream_rate' => $svc->{Hash}->{speed_down},
515 'upstream_rate' => $svc->{Hash}->{speed_up},
517 ) unless $self->{'__saisei_error'};
519 $self->{'__saisei_error'} = "Rate Plan not created"
520 unless ($new_rateplan || $self->{'__saisei_error'});
522 return $new_rateplan;
526 =head2 api_modify_rateplan
528 Modify a new rateplan.
532 sub api_modify_rateplan {
533 my ($self,$svc,$rateplan_name) = @_;
536 my $policies = $self->api_get_policies();
538 foreach my $policy (@$policies) {
539 my $policyname = $policy->{name};
540 my $rate_multiplier = '';
541 if ($policy->{background}) { $rate_multiplier = ".01"; }
542 my $modified_rateplan = $self->api_call(
544 "/rate_plans/$rateplan_name/partitions/$policyname",
546 'restricted' => $policy->{assured}, # policy_assured_flag
547 'rate_multiplier' => $rate_multiplier, # policy_background 0.1
548 'rate' => $policy->{percent_rate}, # policy_percent_rate
552 $self->{'__saisei_error'} = "Rate Plan not modified after create"
553 unless ($modified_rateplan || $self->{'__saisei_error'}); # should never happen
561 =head2 api_modify_existing_rateplan
563 Modify a existing rateplan.
567 sub api_modify_existing_rateplan {
568 my ($self,$svc,$rateplan_name) = @_;
570 my $modified_rateplan = $self->api_call(
572 "/rate_plans/$rateplan_name",
574 'downstream_rate' => $svc->{Hash}->{speed_down},
575 'upstream_rate' => $svc->{Hash}->{speed_up},
579 $self->{'__saisei_error'} = "Rate Plan not modified"
580 unless ($modified_rateplan || $self->{'__saisei_error'}); # should never happen
586 =head2 api_create_user
592 sub api_create_user {
593 my ($self,$user, $description) = @_;
595 my $new_user = $self->api_call(
599 'description' => $description,
603 $self->{'__saisei_error'} = "User not created"
604 unless ($new_user || $self->{'__saisei_error'}); # should never happen
610 =head2 api_create_accesspoint
612 Creates a access point.
616 sub api_create_accesspoint {
617 my ($self,$accesspoint, $upratelimit, $downratelimit) = @_;
619 # this has not been tested, but should work, if needed.
620 my $new_accesspoint = $self->api_call(
622 "/access_points/$accesspoint",
624 'downstream_rate_limit' => $downratelimit,
625 'upstream_rate_limit' => $upratelimit,
629 $self->{'__saisei_error'} = "Access point not created"
630 unless ($new_accesspoint || $self->{'__saisei_error'}); # should never happen
635 =head2 api_modify_accesspoint
637 Modify a new access point.
641 sub api_modify_accesspoint {
642 my ($self, $accesspoint, $uplink) = @_;
644 my $modified_accesspoint = $self->api_call(
646 "/access_points/$accesspoint",
648 'uplink' => $uplink, # name of attached access point
652 $self->{'__saisei_error'} = "Rate Plan not modified"
653 unless ($modified_accesspoint || $self->{'__saisei_error'}); # should never happen
659 =head2 api_modify_existing_accesspoint
661 Modify a existing accesspoint.
665 sub api_modify_existing_accesspoint {
666 my ($self, $accesspoint, $uplink, $upratelimit, $downratelimit) = @_;
668 my $modified_accesspoint = $self->api_call(
670 "/access_points/$accesspoint",
672 'downstream_rate_limit' => $downratelimit,
673 'upstream_rate_limit' => $upratelimit,
674 # 'uplink' => $uplink, # name of attached access point
678 $self->{'__saisei_error'} = "Access point not modified"
679 unless ($modified_accesspoint || $self->{'__saisei_error'}); # should never happen
685 =head2 api_add_host_to_user
687 ties host to user, rateplan and default access point.
691 sub api_add_host_to_user {
692 my ($self,$user, $rateplan, $ip, $accesspoint) = @_;
694 my $new_host = $self->api_call(
699 'rate_plan' => $rateplan,
700 'access_point' => $accesspoint,
704 $self->{'__saisei_error'} = "Host not created"
705 unless ($new_host || $self->{'__saisei_error'}); # should never happen
711 =head2 api_delete_host_to_user
713 unties host from user and rateplan.
714 this will set the host entry at Saisei to the default rate plan with the user and access point set to <none>.
718 sub api_delete_host_to_user {
719 my ($self,$user, $rateplan, $ip) = @_;
721 my $default_rate_plan = $self->api_call("GET", '?token=1&select=default_rate_plan');
722 return if $self->api_error;
723 $self->{'__saisei_error'} = "Did not receive a default rate plan"
724 unless $default_rate_plan;
726 my $default_rateplan_name = $default_rate_plan->{collection}->[0]->{default_rate_plan}->{link}->{name};
728 my $delete_host = $self->api_call(
733 'access_point' => '<none>',
734 'rate_plan' => $default_rateplan_name,
738 $self->{'__saisei_error'} = "Host not created"
739 unless ($delete_host || $self->{'__saisei_error'}); # should never happen
746 my ($self, $opt) = @_;
748 my $existing_tower_ap;
749 my $tower_name = $opt->{tower_name};
751 #check if tower has been set up as an access point.
752 $existing_tower_ap = $self->api_get_accesspoint($tower_name) unless $self->{'__saisei_error'};
754 # modify the existing accesspoint if changing tower .
755 $self->api_modify_existing_accesspoint (
757 '', # tower does not have a uplink on sectors.
758 $opt->{tower_uprate_limit},
759 $opt->{tower_downrate_limit},
760 ) if $existing_tower_ap && $opt->{modify_existing};
762 #if tower does not exist as an access point create it.
763 $self->api_create_accesspoint(
765 $opt->{tower_uprate_limit},
766 $opt->{tower_downrate_limit}
767 ) unless $existing_tower_ap;
769 my $accesspoint = $self->api_get_accesspoint($tower_name);
775 my ($self, $opt) = @_;
777 my $existing_sector_ap;
778 my $sector_name = $opt->{sector_name};
780 #check if sector has been set up as an access point.
781 $existing_sector_ap = $self->api_get_accesspoint($sector_name);
783 # modify the existing accesspoint if changing sector .
784 $self->api_modify_existing_accesspoint (
787 $opt->{sector_uprate_limit},
788 $opt->{sector_downrate_limit},
789 ) if $existing_sector_ap && $opt->{modify_existing};
791 #if sector does not exist as an access point create it.
792 $self->api_create_accesspoint(
794 $opt->{sector_uprate_limit},
795 $opt->{sector_downrate_limit},
796 ) unless $existing_sector_ap;
798 # Attach newly created sector to it's tower.
799 $self->api_modify_accesspoint($sector_name, $opt->{tower_name}) unless ($self->{'__saisei_error'} || $existing_sector_ap);
801 # set access point to existing one or newly created one.
802 my $accesspoint = $existing_sector_ap ? $existing_sector_ap : $self->api_get_accesspoint($sector_name);
807 sub export_provisioned_services {
811 my $part_export = FS::Record::qsearchs('part_export', { 'exportnum' => $param->{export_provisioned_services_exportnum}, } )
812 or die "unknown exportnum $param->{export_provisioned_services_exportnum}";
815 my @svcparts = FS::Record::qsearch({
816 'table' => 'export_svc',
817 'addl_from' => 'LEFT JOIN part_svc USING ( svcpart ) ',
818 'hashref' => { 'exportnum' => $param->{export_provisioned_services_exportnum}, },
820 my $part_count = scalar @svcparts;
822 my $parts = join "', '", map { $_->{Hash}->{svcpart} } @svcparts;
824 my @svcs = FS::Record::qsearch({
825 'table' => 'cust_svc',
826 'addl_from' => 'LEFT JOIN svc_broadband USING ( svcnum ) ',
827 'extra_sql' => " WHERE svcpart in ('".$parts."')",
830 my $svc_count = scalar @svcs;
833 for (my $c=1; $c <=100; $c=$c+1) { $status{int($svc_count * ($c/100))} = $c; }
836 foreach my $svc (@svcs) {
837 if ($status{$process_count}) { my $s = $status{$process_count}; $job->update_statustext($s); }
838 ## check if service exists as host if not export it.
839 _export_insert($part_export,$svc) unless api_get_host($part_export, $svc->{Hash}->{ip_addr});