Freeside - User contributions [en]

Freeside:4:Documentation:Developer:Overview

2017-01-25T21:59:17Z

Jonathan:

This document provides an introductory overview of the major modules and scripts in the Freeside system. It is targeted towards the version 4 branch. It is not comprehensive, but is rather designed to help new developers get started. Code snippets are illustrative, and developers should consult the embedded pod documentation for any given module or method before using it.

==Code Base Structure==

The most essential directories for you to know about:

; FS/FS : perl modules in the '''FS''' namespace.
; httemplate : mason cgi scripts and other files for the main web interface
; FS/bin : standard installed scripts that keep Freeside running
; bin : additional helpful scripts, not automatically installed or integral to functioning
; fs_selfservice : a separate web interface to allow individual customers to access their accounts
; ng_selfservice : the "next generation" of the selfservice interface, built in php
; rt : code for the integrated ticket tracking system, mostly third-party but contains some customizations

Typically, a project will involve updating process in FS/FS and view in httemplate.

==Records==

Most objects described below use '''FS::Record''' as a base. This provides common methods
for storing and retrieving records from the database. By convention, modules that create
Record-based objects have all-lowercase names, with mixed-case used for mixins and objects
that are not stored in the database.

Record objects are not automatically updated in the database when manipulated; for this, the
standard methods '''insert''', '''replace''' and '''delete''' are provided (though they are often overridden by individual modules to perform additional module-specific actions.)

The standard method '''check''' is run by insert and replace to validate data before storing it it the database. This is almost always overridden by individual modules according to its specific validation needs. FS::Record provides a variety of common methods for validating individual fields in check (e.g. '''ut_float''' to validate a floating-point number, '''ut_floatn''' if that field is allowed to be null, etc.)

To retrieve data from the database, functions '''qsearch''' (for multiple records) and '''qsearchs''' (when you expect only a single record) are provided. These must be imported explicitly from FS::Record into your script. They return appropriately blessed objects in the FS namespace.

==Employees==

People with access to the main web interface are known as Employees ('''FS::access_user'''). Each employee can belong to one or more Employee Groups ('''FS::access_group'''), which define their access rights to the system and the customers they are allowed to view. Because of the module names, employees are also often just called users.

Access rights are defined in '''FS::AccessRight''' and consist of plain english strings describing the right (e.g. 'Edit customer', 'Change customer package', etc.) Appropriate access rights should always be checked in the web interface before any data processing occurs.

Within the web interface, the '''FS::access_user''' object for current authenticated employee can be accessed in the variable ''$FS::CurrentUser::CurrentUser''. Access rights can be checked for this object using the ''access_right'' method, e.g.

die "access denied"
unless $FS::CurrentUser::CurrentUser->access_right('Edit customer');

Ensuring that agents only access their own customers is referred to in the code as "agent virtualization", and for the most part it must be done individually in any qsearch call, with the aid of the FS::access_user method '''agentnums_sql''':

my @cust_main = qsearch(
table => 'cust_main',
extra_sql => 'WHERE ' . $FS::CurrentUser::CurrentUser->agentnums_sql,
);

The SQL code returned by agentnums_sql will check the appropriate employee access rights and the agents associated with the employee group, returning only those records the employee has access to. Additional parameters may need to be passed to agentnums_sql, depending on the circumstaces.

==Agents==

Agents ('''FS::agent''') are resellers in the system. Each agent has many customers, but each customer has one and only one agent. Even if a system is not being used by multiple agents, an initial "Internal" agent is created upon system installation, such that customers will always have an agent.

Configuration for agents occurs under the '''Companies''' subheading in the Configuration drop-down menu of the main web interface, though that terminology is not used much beyond that.

==Customers==

An '''FS::cust_main''' object represents a customer. For the most part, this will be regular telecom customers. Most actions that can be taken, from ordering a package to generating a bill, occur through FS::cust_main methods. A great number of tables link back to cust_main, and they will be discussed in their own sections below.

There is also a master "System Accounts" customer created upon installation, and individual agents can also have a master customer assigned to them. These are used for things like tracking system wide services such as domains.

==Packages==

==Services==

==Conf==

==Prospects==

==Payments==

Freeside:4:Documentation:Developer:Overview

2017-01-25T21:37:59Z

Jonathan: Jonathan moved page Freeside:4:Documentation:Developer to Freeside:4:Documentation:Developer:Overview: previous was too generic

This document provides an introductory overview of the major modules and scripts in the Freeside system. It is not comprehensive, but is rather designed to help new developers get started. It is targeted towards the version 4 branch.

==Code Base Structure==

The most essential directories for you to know about:

; FS/FS : perl modules in the '''FS''' namespace.
; httemplate : mason cgi scripts and other files for the main web interface
; FS/bin : standard installed scripts that keep Freeside running
; bin : additional helpful scripts, not automatically installed or integral to functioning
; fs_selfservice : a separate web interface to allow individual customers to access their accounts
; ng_selfservice : the "next generation" of the selfservice interface, built in php
; rt : code for the integrated ticket tracking system, mostly third-party but contains some customizations

Typically, a project will involve updating process in ''FS/FS'' and view in ''httemplate''.

==Records==

Most objects described below use '''FS::Record''' as a base. This provides common methods
for storing and retrieving records from the database. By convention, modules that create
Record-based objects have all-lowercase names, with mixed-case used for mixins and objects
that are not stored in the database.

Record objects are not automatically updated in the database when manipulated; for this, the
standard methods ''insert'', ''replace'' and ''delete'' are provided (though they are often overridden by individual modules to perform additional module-specific actions.)

The standard method ''check'' is run by ''insert'' and ''replace'' to validate data before storing it it the database. This is almost always overridden by individual modules according to its specific validation needs. '''FS::Record''' provides a variety of common methods for validating individual fields in ''check'' (e.g. ''ut_float'' to validate a floating-point number, ''ut_floatn'' if that field is allowed to be null, etc.)

To retrieve data from the database, functions ''qsearch'' (for multiple records) and ''qsearchs'' (when you expect only a single record) are provided. These must be imported explicitly from '''FS::Record''' into your script. They return appropriately blessed objects in the '''FS''' namespace.

==Employees==

People with access to the main web interface are known as Employees ('''FS::access_user'''). Each employee can belong to one or more Employee Groups ('''FS::access_group'''), which define their access rights to the system and the customers they are allowed to view. Because of the module names, employees are also often just called users.

Access rights are defined in '''FS::AccessRight''' and consist of plain english strings describing the right (e.g. 'Edit customer', 'Change customer package', etc.) Appropriate access rights should always be checked in the web interface before any data processing occurs.

Within the web interface, the '''FS::access_user''' object for current authenticated employee can be accessed in the variable ''$FS::CurrentUser::CurrentUser''. Access rights can be checked for this object using the ''access_right'' method, e.g.

die "access denied"
unless $FS::CurrentUser::CurrentUser->access_right('Edit customer');

==Agents==

Agents ('''FS::agent''') are resellers in the system. Each agent has many customers, but each customer has one and only one agent.

==Customers==

An FS::cust_main object represents a customer.

==Packages==

==Services==

==Conf==

==Prospects==

Freeside:4:Documentation:Developer

2017-01-25T21:37:59Z

Jonathan: Jonathan moved page Freeside:4:Documentation:Developer to Freeside:4:Documentation:Developer:Overview: previous was too generic

#REDIRECT [[Freeside:4:Documentation:Developer:Overview]]

Freeside:4:Documentation:Developer:Overview

2017-01-25T21:12:07Z

Jonathan:

Freeside:4:Documentation:Developer:Overview

2017-01-25T21:11:12Z

Jonathan: Still under construction

=Freeside Developer Code Overview=

This document provides an introductory overview of the major modules and scripts in the Freeside system. It is not comprehensive, but is rather designed to help new developers get started. It is targeted towards the version 4 branch.

==Code Base Structure==

The most essential directories for you to know about:

; FS/FS : perl modules in the '''FS''' namespace.
; httemplate : mason cgi scripts and other files for the main web interface
; FS/bin : standard installed scripts that keep Freeside running
; bin : additional helpful scripts, not automatically installed or integral to functioning
; fs_selfservice : a separate web interface to allow individual customers to access their accounts
; ng_selfservice : the "next generation" of the selfservice interface, built in php
; rt : code for the integrated ticket tracking system, mostly third-party but contains some customizations

Typically, a project will involve updating process in ''FS/FS'' and view in ''httemplate''.

==Records==

Most objects described below use '''FS::Record''' as a base. This provides common methods
for storing and retrieving records from the database. By convention, modules that create
Record-based objects have all-lowercase names, with mixed-case used for mixins and objects
that are not stored in the database.

Record objects are not automatically updated in the database when manipulated; for this, the
standard methods ''insert'', ''replace'' and ''delete'' are provided (though they are often overridden by individual modules to perform additional module-specific actions.)

The standard method ''check'' is run by ''insert'' and ''replace'' to validate data before storing it it the database. This is almost always overridden by individual modules according to its specific validation needs. '''FS::Record''' provides a variety of common methods for validating individual fields in ''check'' (e.g. ''ut_float'' to validate a floating-point number, ''ut_floatn'' if that field is allowed to be null, etc.)

To retrieve data from the database, functions ''qsearch'' (for multiple records) and ''qsearchs'' (when you expect only a single record) are provided. These must be imported explicitly from '''FS::Record''' into your script. They return appropriately blessed objects in the '''FS''' namespace.

==Employees==

People with access to the main web interface are known as Employees ('''FS::access_user'''). Each employee can belong to one or more Employee Groups ('''FS::access_group'''), which define their access rights to the system and the customers they are allowed to view. Because of the module names, employees are also often just called users.

Access rights are defined in '''FS::AccessRight''' and consist of plain english strings describing the right (e.g. 'Edit customer', 'Change customer package', etc.) Appropriate access rights should always be checked in the web interface before any data processing occurs.

Within the web interface, the '''FS::access_user''' object for current authenticated employee can be accessed in the variable ''$FS::CurrentUser::CurrentUser''. Access rights can be checked for this object using the ''access_right'' method, e.g.

die "access denied"
unless $FS::CurrentUser::CurrentUser->access_right('Edit customer');

==Agents==

Agents ('''FS::agent''') are resellers in the system. Each agent has many customers, but each customer has one and only one agent.

==Customers==

An FS::cust_main object represents a customer.

==Packages==

==Services==

==Conf==

==Prospects==

Freeside:3:Documentation:Installation

2016-09-12T23:24:26Z

Jonathan: /* Additional modules */

== Introduction ==

These are from-scratch installation instructions for the raw source code. They are suitable for intermediate-to-advanced sysadmins. Folks looking for easy installation are advised to try the VMware appliance or Debian packages instead.

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended.
** [http://www.mysql.com MySQL] and [http://www.mariadb.org/ MariaDB] are supported. Freeside v3.4 or later and DBIx::DBSchema 0.35 or later are required.

''Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running a different database than the backend.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/DateManip Date::Manip]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/GD-Barcode GD::Barcode]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/Net-SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP-Lite SOAP::Lite]
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/XML-LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML-Simple XML::Simple]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/Log-Dispatch Log::Dispatch]
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/Date-Simple Date::Simple]
* [http://search.cpan.org/dist/DateTime-Format-ICal DateTime::Format::ICal]
* [http://search.cpan.org/dist/DateTime-Set DateTime::Set]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Geo-Coder-Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/Geo-GoogleEarth-Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/HTML-TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IO-Scalar IO::Scalar]
* [http://search.cpan.org/dist/IO-String IO::String]
* [http://search.cpan.org/dist/IPC-Run-SafeHandles IPC::Run::SafeHandles]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
* [http://search.cpan.org/dist/XML-LibXML-LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Net-HTTPS-Any Net::HTTPS::Any]

==== Optional modules ====

* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''
* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(only if faxing invoices)''
* [http://search.cpan.org/dist/POE POE] ''(only if using alternate standalone XML-RPC server)''
* [http://search.cpan.org/dist/Sys::SigAction Sys::SigAction] ''(only if port combining with network monitoring)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them (in the appropriate section).

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
$ freeside-adduser -g 1 fs_api
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* It is recommended to [[Freeside:3:Documentation:RT_Installation|install the integrated RT ticketing system]], even if you will not be using it. Alternatively, if you are interested in working on fixes to run without integrated ticketing, delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:4:Documentation:Developer/FS/SelfService

2016-07-30T00:23:29Z

Jonathan:

==NAME==
FS::SelfService - Freeside self-service API

==SYNOPSIS==
<code>
# password and shell account changes
use FS::SelfService qw(passwd chfn chsh);

# "my account" functionality
use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );

#new-style login with an email address and password
# can also be used for svc_acct login, set $emailaddress to username@domain
my $rv = login ( { 'email' => $emailaddress,
'password' => $password,
},
);
if ( $rv->{'error'} ) {
#handle login error...
} else {
#successful login
$session_id = $rv->{'session_id'};
}

#classic svc_acct-based login with separate username and password
my $rv = login( { 'username' => $username,
'domain' => $domain,
'password' => $password,
}
);
if ( $rv->{'error'} ) {
#handle login error...
} else {
#successful login
$session_id = $rv->{'session_id'};
}

#svc_phone login with phone number and PIN
my $rv = login( { 'username' => $phone_number,
'domain' => 'svc_phone',
'password' => $pin,
}
);
if ( $rv->{'error'} ) {
#handle login error...
} else {
#successful login
$session_id = $rv->{'session_id'};
}

my $customer_info = customer_info( { 'session_id' => $session_id } );

#payment_info and process_payment are available in 1.5+ only
my $payment_info = payment_info( { 'session_id' => $session_id } );

#!!! process_payment example

#!!! list_pkgs example

#ordering a package with an svc_acct service
my $rv = order_pkg( { 'session_id' => $session_id,
'pkgpart' => $pkgpart,
'svcpart' => $svcpart,
'username' => $username,
'domsvc' => $domsvc, #svcnum of svc_domain
'_password' => $password,
}
);

#!!! ordering a package with an svc_domain service example

#!!! ordering a package with an svc_phone service example

#!!! ordering a package with an svc_external service example

#!!! ordering a package with an svc_pbx service

#ordering a package with no service
my $rv = order_pkg( { 'session_id' => $session_id,
'pkgpart' => $pkgpart,
'svcpart' => 'none',
}
);

#quoting a package, then ordering after confirmation

my $rv = quotation_new({ 'session_id' => $session_id });
my $qnum = $rv->{quotationnum};
# add packages to the quotation
$rv = quotation_add_pkg({ 'session_id' => $session_id,
'quotationnum' => $qnum,
'pkgpart' => $pkgpart,
'quantity' => $quantity, # defaults to 1
});
# repeat until all packages are added
# view the pricing information
$rv = quotation_info({ 'session_id' => $session_id,
'quotationnum' => $qnum,
});
print "Total setup charges: ".$rv->{total_setup}."\n".
"Total recurring charges: ".$rv->{total_recur}."\n";
# quotation_info also provides a detailed breakdown of charges, in
# $rv->{sections}.

# ask customer for confirmation, then:
$rv = quotation_order({ 'session_id' => $session_id,
'quotationnum' => $qnum,
});

#!!! cancel_pkg example

# signup functionality
use FS::SelfService qw( signup_info new_customer new_customer_minimal );

my $signup_info = signup_info;

$rv = new_customer( {
'first' => $first,
'last' => $last,
'company' => $company,
'address1' => $address1,
'address2' => $address2,
'city' => $city,
'state' => $state,
'zip' => $zip,
'country' => $country,
'daytime' => $daytime,
'night' => $night,
'fax' => $fax,
'payby' => $payby,
'payinfo' => $payinfo,
'paycvv' => $paycvv,
'paystart_month' => $paystart_month
'paystart_year' => $paystart_year,
'payissue' => $payissue,
'payip' => $payip
'paydate' => $paydate,
'payname' => $payname,
'invoicing_list' => $invoicing_list,
'referral_custnum' => $referral_custnum,
'agentnum' => $agentnum,
'pkgpart' => $pkgpart,

'username' => $username,
'_password' => $password,
'popnum' => $popnum,
#OR
'countrycode' => 1,
'phonenum' => $phonenum,
'pin' => $pin,
}
);

my $error = $rv->{'error'};
if ( $error eq '_decline' ) {
print_decline();
} elsif ( $error ) {
reprint_signup();
} else {
print_success();
}
</code>
==DESCRIPTION==
Use this API to implement your own client "self-service" module.

If you just want to customize the look of the existing "self-service" module, see XXXX instead.

==PASSWORD, GECOS, SHELL CHANGING FUNCTIONS==
; passwd
:Changes the password for an existing user in svc_acct. Takes a hash reference with the following keys:
:; username
::Username of the account (required)
:; domain
::Domain of the account (required)
:; old_password
::Old password (required)
:; new_password
::New password (required)
:; new_gecos
::New gecos
:; new_shell
::New Shell
; chfn; chsh
=="MY ACCOUNT" FUNCTIONS==
; login HASHREF
:Creates a user session. Takes a hash reference as parameter with the following keys:
:; email
::Email address (username@domain), instead of username and domain. Required for contact-based self-service login, can also be used for svc_acct-based login.
:; username
::Username
:; domain
::Domain
:; password
::Password

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors.
:; session_id
::Session identifier for successful logins
; customer_info HASHREF
:Returns general customer information.

:Takes a hash reference as parameter with a single key: '''session_id'''

:Returns a hash reference with the following keys:
:; name
::Customer name
:; balance
::Balance owed
:; open
::Array reference of hash references of open inoices. Each hash reference has the following keys: invnum, date, owed
:; small_custview
::An HTML fragment containing shipping and billing addresses.
:; The following fields are also returned
::first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo payname month year invoicing_list postal_invoicing
; edit_info HASHREF
:Takes a hash reference as parameter with any of the following keys:

:first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo paycvv payname month year invoicing_list postal_invoicing

:If a field exists, the customer record is updated with the new value of that field. If a field does not exist, that field is not changed on the customer record.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors
; invoice HASHREF
:Returns an invoice. Takes a hash reference as parameter with two keys: session_id and invnum

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors
:; invnum
::Invoice number
:; invoice_text
::Invoice text
; list_invoices HASHREF
:Returns a list of all customer invoices. Takes a hash reference with a single key, session_id.

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors
:; invoices
::Reference to array of hash references with the following keys:
::; invnum
:::Invoice ID
::; _date
:::Invoice date, in UNIX epoch time
; list_payby HASHREF
:Returns a list of all stored customer payment information (credit cards and electronic check accounts). Takes a hash reference with a single key, session_id.

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors
:; payby
::Reference to array of hash references with the following keys:
::; custpaybynum::; weight
:::Numeric weighting. Stored payment information with a lower weight is attempted first.
::; payby
:::CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
::; paymask
:::Masked credit card number (or, masked account and routing numbers)
::; paydate
:::Credit card expiration date
::; payname
:::Exact name on card (or bank name, for electronic checks)
::; paystate
:::For electronic checks, bank state
::; paytype
:::For electronic checks, account type (Personal/Business, Checking/Savings)
; insert_payby HASHREF
:Adds new stored payment information for this customer. Takes a hash reference with the following keys:
:; session_id:; weight
::Numeric weighting. Stored payment information with a lower weight is attempted first.
:; payby
::CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
:; payinfo
::Credit card number (or electronic check "account@routing")
:; paycvv
::CVV2 number / security code
:; paydate
::Credit card expiration date
:; payname
::Exact name on card (or bank name, for electronic checks)
:; paystate
::For electronic checks, bank state
:; paytype
::For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
:; payip
::Optional IP address from which payment was submitted

:If there is an error, returns a hash reference with a single key, '''error''', otherwise returns a hash reference with a single key, '''custpaybynum'''.

; update_payby HASHREF
:Updates stored payment information for this customer. Takes a hash reference with the following keys:
:; custpaybynum
::ID of stored payment information to update
:; session_id:; weight
::Numeric weighting. Stored payment information with a lower weight is attempted first.
:; payby
::CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD (on-demand credit card) or DCHK (on-demand electronic check).
:; payinfo
::Credit card number (or electronic check "account@routing")
:; paycvv
::CVV2 number / security code
:; paydate
::Credit card expiration date
:; payname
::Exact name on card (or bank name, for electronic checks)
:; paystate
::For electronic checks, bank state
:; paytype
::For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
:; payip
::Optional IP address from which payment was submitted

:All keys except '''sessionid''' and '''custpaybynum''' are optional; if omitted, the previous values in the record will be preserved.
:If there is an error, returns a hash reference with a single key, '''error''', otherwise returns a hash reference with a single key, '''custpaybynum'''.

; delete_payby HASHREF
:Removes stored payment information. Takes a hash reference with two keys, '''session_id''' and '''custpaybynum'''. Returns a hash reference with a single key, '''error''', which is an error message or empty for successful removal.
; cancel HASHREF
:Cancels this customer.

:Takes a hash reference as parameter with a single key: '''session_id'''

:Returns a hash reference with a single key, '''error''', which is empty on success or an error message on errors.
; payment_info HASHREF
:Returns information that may be useful in displaying a payment page.

:Takes a hash reference as parameter with a single key: '''session_id'''.

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors
:; balance
::Balance owed
:; payname
::Exact name on credit card (CARD/DCRD)
:; address1
::Address line one
:; address2
::Address line two
:; city
::City
:; state
::State
:; zip
::Zip or postal code
:; payby
::Customer's current default payment type.
:; card_type
::For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
:; payinfo
::For CARD/DCRD payment types, the card number
:; month
::For CARD/DCRD payment types, expiration month
:; year
::For CARD/DCRD payment types, expiration year
:; cust_main_county
::County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see [[Freeside:4:Documentation:Developer/FS/cust main county|FS::cust_main_county]]). Note these are not FS::cust_main_county objects, but hash references of columns and values.
:; states
::Array reference of all states in the current default country.
:; card_types
::Hash reference of card types; keys are card types, values are the exact strings passed to the process_payment function
; process_payment HASHREF
:Processes a payment and possible change of address or payment type. Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; amount
::Amount
:; save
::If true, address and card information entered will be saved for subsequent transactions.
:; auto
::If true, future credit card payments will be done automatically (sets payby to CARD). If false, future credit card payments will be done on-demand (sets payby to DCRD). This option only has meaning if '''save''' is set true.
:; payname
::Name on card
:; address1
::Address line one
:; address2
::Address line two
:; city
::City
:; state
::State
:; zip
::Zip or postal code
:; country
::Two-letter country code
:; payinfo
::Card number
:; month
::Card expiration month
:; year
::Card expiration year

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; process_payment_order_pkg
:Combines the '''process_payment''' and '''order_pkg''' functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; process_payment_change_pkg
:Combines the '''process_payment''' and '''change_pkg''' functions in one step. If the payment processes sucessfully, the package is ordered. Takes a hash reference as parameter with the keys of both methods.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; process_payment_order_renew
:Combines the '''process_payment''' and '''order_renew''' functions in one step. If the payment processes sucessfully, the renewal is processed. Takes a hash reference as parameter with the keys of both methods.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; list_pkgs
:Returns package information for this customer. For more detail on services, see [[#list_svcs|"list_svcs"]].

:Takes a hash reference as parameter with a single key: '''session_id'''

:Returns a hash reference containing customer package information. The hash reference contains the following keys:
:; custnum
::Customer number
:; error
::Empty on success, or an error message on errors.
:; cust_pkg HASHREF
::Array reference of hash references, each of which has the fields of a cust_pkg record (see [[Freeside:4:Documentation:Developer/FS/cust pkg|FS::cust_pkg]]) as well as the fields below. Note these are not the internal FS:: objects, but hash references of columns and values.
::; part_pkg fields
:::All fields of part_pkg for this specific cust_pkg (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)
::; part_svc
:::An array of hash references indicating information on unprovisioned services available for provisioning for this specific cust_pkg. Each has the following keys:
:::; part_svc fields
::::All fields of part_svc (be careful with this information - it may reveal more about your available packages than you would like users to know in aggregate)
::; cust_svc
:::An array of hash references indicating information on the customer services already provisioned for this specific cust_pkg. Each has the following keys:
:::; label
::::Array reference with three elements: The first element is the name of this service. The second element is a meaningful user-specific identifier for the service (i.e. username, domain or mail alias). The last element is the table name of this service.
::; svcnum
:::Primary key for this service
::; svcpart
:::Service definition (see [[Freeside:4:Documentation:Developer/FS/part svc|FS::part_svc]])
::; pkgnum
:::Customer package (see [[Freeside:4:Documentation:Developer/FS/cust pkg|FS::cust_pkg]])
::; overlimit
:::Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).
; list_svcs
:Returns service information for this customer.

:Takes a hash reference as parameter with a single key: '''session_id'''

:Returns a hash reference containing customer package information. The hash reference contains the following keys:
:; custnum
::Customer number
:; svcs
::An array of hash references indicating information on all of this customer's services. Each has the following keys:
::; svcnum
:::Primary key for this service
::; label
:::Name of this service
::; value
:::Meaningful user-specific identifier for the service (i.e. username, domain, or mail alias).

::Account (svc_acct) services also have the following keys:
::; username
:::Username
::; email
:::username@domain
::; seconds
:::Seconds remaining
::; upbytes
:::Upload bytes remaining
::; downbytes
:::Download bytes remaining
::; totalbytes
:::Total bytes remaining
::; recharge_amount
:::Cost of a recharge
::; recharge_seconds
:::Number of seconds gained by recharge
::; recharge_upbytes
:::Number of upload bytes gained by recharge
::; recharge_downbytes
:::Number of download bytes gained by recharge
::; recharge_totalbytes
:::Number of total bytes gained by recharge
; order_pkg
:Orders a package for this customer.

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgpart
::Package to order (see [[Freeside:4:Documentation:Developer/FS/part pkg|FS::part_pkg]]).
:; quantity
::Quantity for this package order (default 1).
:; locationnum
::Optional locationnum for this package order, for existing locations.

::Or, for new locations, pass the following fields: address1*, address2, city*, county, state*, zip*, country. (* = required in this case)
:; address1:; address 2:; city:; :; svcpart
::Service to order (see [[Freeside:4:Documentation:Developer/FS/part svc|FS::part_svc]]).

::Normally optional; required only to provision a non-svc_acct service, or if the package definition does not contain one svc_acct service definition with quantity 1 (it may contain others with quantity >1). A svcpart of "none" can also be specified to indicate that no initial service should be provisioned.

:Fields used when provisioning an svc_acct service:
:; username
::Username
:; _password
::Password
:; sec_phrase
::Optional security phrase
:; popnum
::Optional Access number number

:Fields used when provisioning an svc_domain service:
:; domain
::Domain

:Fields used when provisioning an svc_phone service:
:; phonenum
::Phone number
:; pin
::Voicemail PIN
:; sip_password
::SIP password

:Fields used when provisioning an svc_external service:
:; id
::External numeric ID.
:; title
::External text title.

:Fields used when provisioning an svc_pbx service:
:; id
::Numeric ID.
:; name
::Text name.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions.
; change_pkg
:Changes a package for this customer.

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgnum
::Existing customer package.
:; pkgpart
::New package to order (see [[Freeside:4:Documentation:Developer/FS/part pkg|FS::part_pkg]]).
:; quantity
::Quantity for this package order (default 1).

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors.
:; pkgnum
::On success, the new pkgnum
; renew_info
:Provides useful info for early renewals.

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier

:Returns a hash reference. On errors, it contains a single key, '''error''', with the error message. Otherwise, contains a single key, '''dates''', pointing to an array refernce of hash references. Each hash reference contains the following keys:
:; bill_date
::(Future) Bill date. Indicates a future date for which billing could be run. Specified as a integer UNIX timestamp. Pass this value to the '''order_renew''' function.
:; bill_date_pretty
::(Future) Bill date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
:; amount
::Base amount which will be charged if renewed early as of this date.
:; renew_date
::Renewal date; i.e. even-futher future date at which the customer will be paid through if the early renewal is completed with the given '''bill-date'''. Specified as a integer UNIX timestamp.
:; renew_date_pretty
::Renewal date as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
:; pkgnum
::Package that will be renewed.
:; expire_date
::Expiration date of the package that will be renewed.
:; expire_date_pretty
::Expiration date of the package that will be renewed, as a human-readable string. (Convenience for display; subject to change, so best not to parse for the date.)
; order_renew
:Renews this customer early; i.e. runs billing for this customer in advance.

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; date
::Integer date as returned by the '''renew_info''' function, indicating the advance date for which to run billing.

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; cancel_pkg
:Cancels a package for this customer.

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgpart
::pkgpart of package to cancel

:Returns a hash reference with a single key, '''error''', empty on success, or an error message on errors.
; provision_acct
:Provisions an account (svc_acct).

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgnum
::pkgnum of package into which this service is provisioned
:; svcpart
::svcpart or service definition to provision
:; username:; domsvc:; _password; provision_phone
:Provisions a phone number (svc_phone).

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgnum
::pkgnum of package into which this service is provisioned
:; svcpart
::svcpart or service definition to provision
:; countrycode:; phonenum:; address1:; address2:; city:; county:; state:; zip:; country
::E911 Address (optional)
; provision_pbx
:Provisions a customer PBX (svc_pbx).

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgnum
::pkgnum of package into which this service is provisioned
:; svcpart
::svcpart or service definition to provision
:; id:; title:; max_extensions:; max_simultaneous:; ip_addr; provision_external
:Provisions an external service (svc_external).

:Takes a hash reference as parameter with the following keys:
:; session_id
::Session identifier
:; pkgnum
::pkgnum of package into which this service is provisioned
:; svcpart
::svcpart or service definition to provision
:; id:; title
==="MY ACCOUNT" CONTACT FUNCTIONS===
; contact_passwd
:Changes the password for the currently-logged in contact.

:Takes a hash reference as parameter with the following keys:
:; session_id:; new_password
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
; list_contacts
:Takes a hash reference as parameter with a single key, '''session_id'''.

:Returns a hash reference with two parameters: '''error''', which contains an error message, or empty on success, and '''contacts''', a list of contacts.

:'''contacts''' is an array reference of hash references (i.e. an array of structs, in XML-RPC). Each hash reference (struct) has the following keys:
; contactnum; class
:Contact class name (contact type).
; first
:First name
; last
:Last name
; title
:Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
; emailaddress
:Comma-separated list of email addresses
; comment; selfservice_access
:Y when enabled

; edit_contact
:Updates information for the currently-logged in contact, or (optionally) the specified contact.

:Takes a hash reference as parameter with the following keys:
:; session_id:; contactnum
::If already logged in as a contact, this is optional.
:; first:; last:; emailaddress
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
; new_contact
:Creates a new contact.

:Takes a hash reference as parameter with the following keys:
:; session_id:; first:; last:; emailaddress:; classnum
::Optional contact classnum (TODO: or name)
:; comment:; selfservice_access
::Y to enable self-service access
:; _password
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.
; delete_contact
:Deletes a contact. (Note: Cannot at this time delete the currently-logged in contact.)

:Takes a hash reference as parameter with the following keys:
:; session_id:; contactnum
:Returns a hash reference with a single parameter, '''error''', which contains an error message, or empty on success.

==="MY ACCOUNT" QUOTATION FUNCTIONS===
All of these functions require the user to be logged in, and the 'session_id' key to be included in the argument hashref.`

; list_quotations HASHREF
:Returns a hashref listing this customer's active self-service quotations. Contents are:
:; quotations
::an arrayref containing an element for each quotation.
:; quotationnum
::the primary key
:; _date
::the date it was started
:; num_pkgs
::the number of packages
:; total_setup
::the sum of setup fees
:; total_recur
::the sum of recurring charges
; quotation_new HASHREF
:Creates an empty quotation and returns a hashref containing 'quotationnum', the primary key of the new quotation.
; quotation_delete HASHREF
:Disables (does not really delete) a quotation. Takes the following arguments:
:; session_id:; quotationnum - the quotation to delete
:Returns 'error' => a string, which will be empty on success.
; quotation_info HASHREF
:Returns total and detailed pricing information on a quotation.

:Takes the following arguments:
:; session_id:; quotationnum - the quotation to return
:Returns a hashref containing:

:- total_setup, the total of setup fees (and their taxes) - total_recur, the total of all recurring charges (and their taxes) - sections, an arrayref containing an element for each quotation section. - description, a line of text describing the group of charges - subtotal, the total of charges in this group (if appropriate) - detail_items, an arrayref of line items - pkgnum, the reference number of the package - description, the package name (or tax name) - quantity - amount, the amount charged If the detail item represents a subtotal, it will instead contain: - total_item: description of the subtotal - total_amount: the subtotal amount
; quotation_print HASHREF
:Renders the quotation as HTML or PDF. Takes the following arguments:
:; session_id:; quotationnum - the quotation to return:; format - 'html' or 'pdf'
:Returns a hashref containing 'document', the contents of the file.
; quotation_add_pkg HASHREF
:Adds a package to a quotation. Takes the following arguments:
:; session_id:; pkgpart - the package to add:; quotationnum - the quotation to add it to:; quantity - the package quantity (defaults to 1):; address1, address2, city, state, zip, country - address fields to set the service location
:Returns 'error' => a string, which will be empty on success.
; quotation_remove_pkg HASHREF
:Removes a package from a quotation. Takes the following arguments:
:; session_id:; pkgnum - the primary key (quotationpkgnum) of the package to remove:; quotationnum - the quotation to remove it from
:Returns 'error' => a string, which will be empty on success.

; quotation_order HASHREF
:Converts the packages in a quotation into real packages. Takes the following arguments:

:Takes the following arguments:
:; session_id:; quotationnum - the quotation to order
==SIGNUP FUNCTIONS==
; signup_info HASHREF
:Takes a hash reference as parameter with the following keys:
:; session_id - Optional agent/reseller interface session
:Returns a hash reference containing information that may be useful in displaying a signup page. The hash reference contains the following keys:
:; cust_main_county
::County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see [[Freeside:4:Documentation:Developer/FS/cust main county|FS::cust_main_county]]). Note these are not FS::cust_main_county objects, but hash references of columns and values.
:; part_pkg
::Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see [[Freeside:4:Documentation:Developer/FS/part pkg|FS::part_pkg]]). Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and [[Freeside:4:Documentation:Developer/FS/part pkg#payby|"payby" in FS/part pkg|FS::part_pkg#payby|"payby" in FS::part_pkg]]). Note these are not FS::part_pkg objects, but hash references of columns and values. Requires the 'signup_server-default_agentnum' configuration value to be set, or an agentnum specified explicitly via reseller interface session_id in the options.
:; agent
::Array reference of hash references, each of which has the fields of an agent record (see [[Freeside:4:Documentation:Developer/FS/agent|FS::agent]]). Note these are not FS::agent objects, but hash references of columns and values.
:; agentnum2part_pkg
::Hash reference; keys are agentnums, values are array references of available packages for that agent, in the same format as the part_pkg arrayref above.
:; svc_acct_pop
::Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see [[Freeside:4:Documentation:Developer/FS/svc acct pop|FS::svc_acct_pop]]). Note these are not FS::svc_acct_pop objects, but hash references of columns and values.
:; security_phrase
::True if the "security_phrase" feature is enabled
:; payby
::Array reference of acceptable payment types for signup
::; CARD
:::credit card - automatic
::; DCRD
:::credit card - on-demand - version 1.5+ only
::; CHEK
:::electronic check - automatic
::; DCHK
:::electronic check - on-demand - version 1.5+ only
::; LECB
:::Phone bill billing
::; BILL
:::billing, not recommended for signups
::; COMP
:::free, definitely not recommended for signups
::; PREPAY
:::special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
:; cvv_enabled
::True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
:; msgcat
::Hash reference of message catalog values, to support error message customization. Currently available keys are: passwords_dont_match, invalid_card, unknown_card_type, and not_a (as in "Not a Discover card"). Values are configured in the web interface under "View/Edit message catalog".
:; statedefault
::Default state
:; countrydefault
::Default country
; new_customer_minimal HASHREF
:Creates a new customer.

:Current differences from new_customer: An address is not required. promo_code and reg_code are not supported. If invoicing_list and _password is passed, a contact will be created with self-service access (no pkgpart or username is necessary). No initial billing is run (this may change in a future version).

:Takes a hash reference as parameter with the following keys:
:; first
::first name (required)
:; last
::last name (required)
:; ss
::(not typically collected; mostly used for ACH transactions)
:; company
::Company name
:; address1
::Address line one
:; address2
::Address line two
:; city
::City
:; county
::County
:; state
::State
:; zip
::Zip or postal code
:; daytime
::Daytime phone number
:; night
::Evening phone number
:; fax
::Fax number
:; payby
::CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see [[#signup_info|"signup_info"]] (required)
:; payinfo
::Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
:; paycvv
::Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
:; paydate
::Expiration date for CARD/DCRD
:; payname
::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
:; invoicing_list
::comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
:; referral_custnum
::referring customer number
:; agentnum
::Agent number
:; pkgpart
::pkgpart of initial package
:; username
::Username
:; _password
::Password
:; sec_phrase
::Security phrase
:; popnum
::Access number (index, not the literal number)
:; countrycode
::Country code (to be provisioned as a service)
:; phonenum
::Phone number (to be provisioned as a service)
:; pin
::Voicemail PIN

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Configuration | View/Edit message catalog)
; new_customer HASHREF
:Creates a new customer. Takes a hash reference as parameter with the following keys:
:; first
::first name (required)
:; last
::last name (required)
:; ss
::(not typically collected; mostly used for ACH transactions)
:; company
::Company name
:; address1 (required)
::Address line one
:; address2
::Address line two
:; city (required)
::City
:; county
::County
:; state (required)
::State
:; zip (required)
::Zip or postal code
:; daytime
::Daytime phone number
:; night
::Evening phone number
:; fax
::Fax number
:; payby
::CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see [[#signup_info|"signup_info"]] (required)
:; payinfo
::Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
:; paycvv
::Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
:; paydate
::Expiration date for CARD/DCRD
:; payname
::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
:; invoicing_list
::comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
:; referral_custnum
::referring customer number
:; agentnum
::Agent number
:; pkgpart
::pkgpart of initial package
:; username
::Username
:; _password
::Password
:; sec_phrase
::Security phrase
:; popnum
::Access number (index, not the literal number)
:; countrycode
::Country code (to be provisioned as a service)
:; phonenum
::Phone number (to be provisioned as a service)
:; pin
::Voicemail PIN

:Returns a hash reference with the following keys:
:; error
::Empty on success, or an error message on errors. The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Configuration | View/Edit message catalog)
; regionselector HASHREF | LIST
:Takes as input a hashref or list of key/value pairs with the following keys:
:; selected_county
::Currently selected county
:; selected_state
::Currently selected state
:; selected_country
::Currently selected country
:; prefix
::Specify a unique prefix string if you intend to use the HTML output multiple time son one page.
:; onchange
::Specify a javascript subroutine to call on changes
:; default_state
::Default state
:; default_country
::Default country
:; locales
::An arrayref of hash references specifying regions. Normally you can just pass the value of the ''cust_main_county'' field returned by '''signup_info'''.

:Returns a list consisting of three HTML fragments for county selection, state selection and country selection, respectively.
; location_form HASHREF | LIST
:Takes as input a hashref or list of key/value pairs with the following keys:
:; session_id
::Current customer session_id
:; no_asterisks
::Omit red asterisks from required fields.
:; address1_label
::Label for first address line.

:Returns an HTML fragment for a location form (address, city, state, zip, country)
; expselect PREFIX [ DATE ]
:Takes as input a unique prefix string and the current expiration date, in yyyy-mm-dd or m-d-yyyy format

:Returns an HTML fragments for expiration date selection.
; popselector HASHREF | LIST
:Takes as input a hashref or list of key/value pairs with the following keys:
:; popnum
::Access number number
:; pops
::An arrayref of hash references specifying access numbers. Normally you can just pass the value of the ''svc_acct_pop'' field returned by '''signup_info'''.

:Returns an HTML fragment for access number selection.
; domainselector HASHREF | LIST
:Takes as input a hashref or list of key/value pairs with the following keys:
:; pkgnum
::Package number
:; domsvc
::Service number of the selected item.

:Returns an HTML fragment for domain selection.
; didselector HASHREF | LIST
:Takes as input a hashref or list of key/value pairs with the following keys:
:; field
::Field name for the returned HTML fragment.
:; svcpart
::Service definition (see [[Freeside:4:Documentation:Developer/FS/part svc|FS::part_svc]])

:Returns an HTML fragment for DID selection.

==RESELLER FUNCTIONS==
Note: Resellers can also use the '''signup_info''' and '''new_customer''' functions with their active session, and the '''customer_info''' and '''order_pkg''' functions with their active session and an additional ''custnum'' parameter.

For the most part, development of the reseller web interface has been superceded by agent-virtualized access to the backend.

; agent_login
:Agent login
; agent_info
:Agent info
; agent_list_customers
:List agent's customers.

==BUGS==
==SEE ALSO==
[[Freeside:4:Documentation:Developer/bin/freeside-selfservice-clientd|freeside-selfservice-clientd]], [[Freeside:4:Documentation:Developer/bin/freeside-selfservice-server|freeside-selfservice-server]]

==POD ERRORS==
Hey! '''The above document had some coding errors, which are explained below:'''

; Around line 1503:
:Unknown directive: =over4
; Around line 1535:
:'=item' outside of any '=over'
; Around line 1612:
:You forgot a '=back' before '=head2'
; Around line 1757:
:'=item' outside of any '=over'

Freeside:4:Documentation

2015-12-24T03:58:59Z

Jonathan: /* New feature documentation */

= Note =

Documentation specific to git master / 4.x. For now, refer to this as an add-on to the 3.x documentation.

= Installation and upgrades =

The minimum Perl version is now 5.10.

== Backend Installation ==

* New installation
* Integrated RT installation
* OS-specific installation guides (source)
** [[Freeside:4:Documentation:InstallingOnDebian7]]

== Upgrading ==

* [[Freeside:4:Documentation:Upgrading|Upgrading from 3.3 or later to 4.x]]

= Administrator =

* [[Freeside:4:Documentation:Administrator:Multi-currency|Multi-currency]]
* [[Freeside:4:Documentation:Administrator:Fees|Automated fees]] (under development)
* [[Freeside:4:Documentation:Cacti|Cacti Integration]]
* [[Freeside:4:Documentation:MagicMail|MagicMail Integration]]

= Developer =

* [[Freeside:4:Documentation:Developer:Authentication_Plugins|Authentication Plugins]]
* [[Freeside:4:Documentation:TaxEngine|Tax Engines]]

= Changelog =

* [[Freeside:4.0:Changelog|4.0 Changelog]]

= New feature documentation =

* [[Freeside:4:Documentation:Appointments]]
* Emails triggered by system log events can be set up at Configuration -> Miscellaneous -> System log emails

Freeside:4:Documentation:Cacti

2015-11-24T08:06:03Z

Jonathan: /* Connecting Cacti To Freeside */

== Connecting Cacti To Freeside ==

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Make sure
the Host Template has Associated Graph Templates and Data Queries for
any graphs you wish to automatically generate. Create a Graph Tree for
new devices to be automatically added to, and note the tree's id number.
Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* Hostname or IP - of your Cacti server

* User Name - with permission to run scripts in the cli directory

* Script Path - full path to that directory (eg /usr/share/cacti/cli/)

* Host Template ID - for adding new devices

* Graph Tree ID - to which the host will be added

* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer

* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)

* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.

* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.

* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)

* Path to cacti include dir (relative to script_path) - optional, defaults to ../site/include/ if unspecified, might need to be changed to ../include/ if you installed cacti from source

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these fields. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that. Graphs will be
generated for each graph template you specified, as well as any you explicitly
configured.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

==Troubleshooting==

After a device is provisioned, the graphs won't show up until the next time the
cacti server runs its poller and exports the graphs; by default, this is every
five minutes. If you try to view the graphs in this window, it will say they don't
exist.

When upgrading a freeside server that uses this export, make sure to check that
the most recent freeside_cacti.php file is copied into the script directory
on the cacti server.

==Known Issues==

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Currently does not support graph-title in graph generation (specify title in template instead)

Currently does not support graphs that require custom input-fields

Currently does not support specifying reindex-method for graphs from Data Queries

Freeside:4:Documentation:Cacti

2015-07-03T22:10:21Z

Jonathan:

== Connecting Cacti To Freeside ==

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Make sure
the Host Template has Associated Graph Templates and Data Queries for
any graphs you wish to automatically generate. Create a Graph Tree for
new devices to be automatically added to, and note the tree's id number.
Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* Hostname or IP - of your Cacti server

* User Name - with permission to run scripts in the cli directory

* Script Path - full path to that directory (eg /usr/share/cacti/cli/)

* Host Template ID - for adding new devices

* Graph Tree ID - to which the host will be added

* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer

* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)

* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.

* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.

* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these fields. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that. Graphs will be
generated for each graph template you specified, as well as any you explicitly
configured.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

==Troubleshooting==

After a device is provisioned, the graphs won't show up until the next time the
cacti server runs its poller and exports the graphs; by default, this is every
five minutes. If you try to view the graphs in this window, it will say they don't
exist.

When upgrading a freeside server that uses this export, make sure to check that
the most recent freeside_cacti.php file is copied into the script directory
on the cacti server.

==Known Issues==

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Currently does not support graph-title in graph generation (specify title in template instead)

Currently does not support graphs that require custom input-fields

Currently does not support specifying reindex-method for graphs from Data Queries

Freeside:3:Documentation:NG Self-Service

2015-05-06T02:26:11Z

Jonathan: /* Notes */

NG Self-service is the next generation version of our customer self-service portal. The application is written in PHP and utilizes CSS to allow modification and manipulation to the look and feel easier than before.

==Installation==
* Copy the ng_selfservice directory into the appropriate directory on your web/self-service portal server.
* Edit freeside.class.php to point to your Freeside server:
<pre>var $URL = 'http://yourfreesideserver:8080/';</pre>
* Enable selfservice-xmlrpc in Configuration -> Settings.
* Restart the Freeside services

==Configuration==
* Configuration -> Settings: ng_selfservice-menu allows additional custom scripts and removal of default pages to enhance the capabilities of the self-service portal. You can also rename the links in the menus to fix your specific needs.
<pre>
main.php Home

services.php Services
services.php My Services
services_new.php Order a new service

personal.php Profile
personal.php Personal Information
password.php Change Password

payment.php Payments
payment_cc.php Credit Card Payment
payment_ach.php Electronic Check Payment
payment_paypal.php PayPal Payment
payment_webpay.php Webpay Payments

usage.php Usage
usage_data.php Data usage
usage_cdr.php Call usage

tickets.php Help Desk
tickets.php Open Tickets
tickets_resolved.php Resolved Tickets
ticket_create.php Create a new ticket

docs.php FAQs

logout.php Logout
</pre>

==Notes==
* Communication is not encrypted. Communication should be routed via a VPN or other secure tunnel/mechanism.
* You might also have to install debian package php5-xmlrpc

Freeside:4:Documentation:Cacti

2015-04-30T22:01:00Z

Jonathan: /* Connecting Cacti To Freeside */

== Connecting Cacti To Freeside ==

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Make sure
the Host Template has Associated Graph Templates and Data Queries for
any graphs you wish to automatically generate. Create a Graph Tree for
new devices to be automatically added to, and note the tree's id number.
Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* Hostname or IP - of your Cacti server

* User Name - with permission to run scripts in the cli directory

* Script Path - full path to that directory (eg /usr/share/cacti/cli/)

* Host Template ID - for adding new devices

* Graph Tree ID - to which the host will be added

* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer

* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)

* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.

* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.

* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these fields. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that. Graphs will be
generated for each graph template you specified, as well as any you explicitly
configured.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

==Known Issues==

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Currently does not support graph-title in graph generation (specify title in template instead)

Currently does not support graphs that require custom input-fields

Currently does not support specifying reindex-method for graphs from Data Queries

Freeside:4:Documentation:Cacti

2015-04-30T21:59:48Z

Jonathan: /* Known Issues */

== Connecting Cacti To Freeside ==

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Make sure
the Host Template has Associated Graph Templates and Data Queries for
any graphs you wish to automatically generate. Create a Graph Tree for
new devices to be automatically added to, and note the tree's id number.
Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* Hostname or IP - of your Cacti server

* User Name - with permission to run scripts in the cli directory

* Script Path - full path to that directory (eg /usr/share/cacti/cli/)

* Host Template ID - for adding new devices

* Graph Tree ID - to which the host will be added

* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer

* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)

* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.

* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.

* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these values. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that. Graphs will be
generated for each graph template you specified, as well as any you explicitly
configured.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

==Known Issues==

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Currently does not support graph-title in graph generation (specify title in template instead)

Currently does not support graphs that require custom input-fields

Currently does not support specifying reindex-method for graphs from Data Queries

Freeside:4:Documentation:Cacti

2015-04-30T20:57:52Z

Jonathan: /* Connecting Cacti To Freeside */

== Connecting Cacti To Freeside ==

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Make sure
the Host Template has Associated Graph Templates and Data Queries for
any graphs you wish to automatically generate. Create a Graph Tree for
new devices to be automatically added to, and note the tree's id number.
Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* Hostname or IP - of your Cacti server

* User Name - with permission to run scripts in the cli directory

* Script Path - full path to that directory (eg /usr/share/cacti/cli/)

* Host Template ID - for adding new devices

* Graph Tree ID - to which the host will be added

* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer

* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)

* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.

* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.

* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these values. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that. Graphs will be
generated for each graph template you specified, as well as any you explicitly
configured.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

==Known Issues==

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Freeside:4:Documentation:Cacti

2015-04-30T20:30:38Z

Jonathan: /* Known Issues */

Freeside:4:Documentation:MagicMail

2015-04-21T03:00:54Z

Jonathan: Initial doc for magicmail integration

== Connecting MagicMail to Freeside ==

Through the MagicMail admin interface, configure an API Client with client type FREESIDE, and make note of the Client ID and Password. Configure a system domain for each domain name you will use (freeside does not currently integrate with "hosted" domains in magicmail) and make sure these domains are accessible by the API Client.

In Freeside, go to Configuration->Services->Provisioning exports to add a new export. From the Add Export page, select magicmail for Export then enter...

* Hostname or IP Address - of your MagicMail server

* API Client ID

* API Client Password

* Account Prefix - will be appended with customer numbers to create customer account ids

* Package - the package that will be assigned to the account's master user by this export (should be EMAIL for one svc_acct per customer)

* Port - optional, port for API calls to MagicMail server, default 443

* Auto purge user/account on unprovision - if checked, automatically purges deleted accounts/user upon unprovisioning services, immediately freeing up usernames for re-use but making it impossible to retrieve deleted mailboxes

* Enable debug warnings - if checked, prints debug info to the error log for every API request and response

After adding the export, go to Configuration->Services->Service definitions. The export you just created will be available for selection when adding or editing svc_acct service definitions; check the box to activate it for a given service.

This export runs in real time during provisioning, meaning a service will not be successfully provisioned until the MagicMail export completes.

Every customer with any services provisioned on this export will have an account created for them in MagicMail when the first service is provisioned. The account name will be the ''Account Prefix'' plus the customer's number. Each svc_acct provisioned for a customer will be one user/mailbox/emailaddress on the account. There is no way to export more than one emailaddress per user/mailbox.

== Multiple Packages Per Customer ==

Though you should only have one magicmail export per service definition, you can use different export definitions on different services to offer a variety of different packages to your customers. So long as the ''Account Prefix'' is the same on all magicmail export definitions, they will all use the same MagicMail account for each customer.

The master user on the account will be the first service provisioned on the account, and it will be assigned the appropriate packages for all services on that account (additional users will be given the ADDITIONAL NOCOST MAILBOX package, and nothing else.) If the master user is unprovisioned before other provisioned services, master user status and assigned packages will be transferred to the oldest remaining provisioned service. Master user packages are synchronized with the freeside customer's currently provisioned services whenever a magicmail export using that ''Account Prefix'' provisions or unprovisions a service.

== Known Issues ==

Currently only works with password encoding types ''Plain text'', ''Unix password (DES encrypted)'', ''Unix password (MD5 digest)'' and ''LDAP (plain text)''. In freeside, go to Configuration->Settings and check the value of default-password-encoding.

Freeside:4:Documentation

2015-04-21T02:13:00Z

Jonathan: /* Administrator */

= Note =

Documentation specific to git master / 4.x. For now, refer to this as an add-on to the 3.x documentation.

= Installation and upgrades =

== Backend Installation ==

* New installation
* Integrated RT installation
* OS-specific installation guides (source)
** [[Freeside:4:Documentation:InstallingOnDebian7]]

== Upgrading ==

* [[Freeside:4:Documentation:Upgrading|Upgrading from 3.3 or later to 4.x]]

= Administrator =

* [[Freeside:4:Documentation:Administrator:Multi-currency|Multi-currency]]
* [[Freeside:4:Documentation:Administrator:Fees|Automated fees]] (under development)
* [[Freeside:4:Documentation:Cacti|Cacti Integration]]
* [[Freeside:4:Documentation:MagicMail|MagicMail Integration]]

= Developer =

* [[Freeside:4:Documentation:Developer:Authentication_Plugins|Authentication Plugins]]

= Changelog =

* [[Freeside:4.0:Changelog|4.0 Changelog]]

Freeside:4:Documentation:Cacti

2015-04-08T21:51:19Z

Jonathan: /* Connecting Cacti To Freeside */

Freeside:4:Documentation:Cacti

2015-04-08T21:40:22Z

Jonathan: /* Connecting Cacti To Freeside */

Freeside:4:Documentation

2015-04-08T21:35:54Z

Jonathan: adding link to cacti integration

= Note =

Documentation specific to git master / 4.x. For now, refer to this as an add-on to the 3.x documentation.

= Installation and upgrades =

== Backend Installation ==

* New installation
* Integrated RT installation
* OS-specific installation guides (source)
** [[Freeside:4:Documentation:InstallingOnDebian7]]

== Upgrading ==

* [[Freeside:4:Documentation:Upgrading|Upgrading from 3.3 or later to 4.x]]

= Administrator =

* [[Freeside:4:Documentation:Administrator:Multi-currency|Multi-currency]]
* [[Freeside:4:Documentation:Administrator:Fees|Automated fees]] (under development)
* [[Freeside:4:Documentation:Cacti|Cacti Integration]]

= Developer =

* [[Freeside:4:Documentation:Developer:Authentication_Plugins|Authentication Plugins]]

= Changelog =

* [[Freeside:4.0:Changelog|4.0 Changelog]]

Freeside:4:Documentation:Cacti

2015-04-07T02:01:17Z

Jonathan: /* Connecting Cacti To Freeside */

Freeside:4:Documentation:Cacti

2015-04-07T02:00:35Z

Jonathan: /* Connecting Cacti To Freeside */

Freeside:4:Documentation:Cacti

2015-04-07T01:59:55Z

Jonathan: Created page with "= Connecting Cacti To Freeside = Copy the freeside_cacti.php script from the bin directory of your Freeside installation to the cli directory of your Cacti installation. Giv..."

= Connecting Cacti To Freeside =

Copy the freeside_cacti.php script from the bin directory of your Freeside
installation to the cli directory of your Cacti installation. Give this file
the same permissions as the other files in that directory, and create
(or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by
devices exported by Freeside, and note the template's id number. Optionally,
create a Graph Tree for these devices to be automatically added to, and note
the tree's id number. Configure a Graph Export (under Settings) and note
the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to
add a new export. From the Add Export page, select cacti for Export then enter...

* the Hostname or IP address of your Cacti server

* the User Name with permission to run scripts in the cli directory

* the full Script Path to that directory (eg /usr/share/cacti/cli/)

* the Host Template ID for adding new devices

* the Graph Tree ID for adding new devices (optional)

* the Description for new devices; you can use the tokens
$ip_addr and $description to include the equivalent fields
from the broadband service definition, or $contact to use
the customer's contact name

* the Graph Export Directory, including connection information
if necessary (user@host:/path/to/graphs/)

* the minimum minutes between graph imports to Freeside (graphs will
otherwise be imported into Freeside as needed.) This should be at least
as long as the minumum time between graph exports configured in Cacti.
Defaults to 5 if unspecified.

* the maximum size per graph, in MB; individual graphs that exceed this size
will be quietly ignored by Freeside. Defaults to 5 if unspecified.

After adding the export, go to Configuration->Services->Service definitions.
The export you just created will be available for selection when adding or
editing broadband service definitions; check the box to activate it for
a given service. Note that you should only have one cacti export per
broadband service definition.

When properly configured broadband services are provisioned, they will now
be added to Cacti using the Host Template you specified. If you also specified
a Graph Tree, the created device will also be added to that.

Once added, a link to the graphs for this host will be available when viewing
the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside,
and they will be deleted and re-added if the ip address changes.

Currently, graphs themselves must still be added in Cacti by hand or some
other form of automation tailored to your specific graph inputs and data sources.

Freeside:3:Documentation:RT Installation

2015-01-21T18:31:23Z

Jonathan: Fleshed out Bootstrap RT's permissions, based on a 3.x install

== Introduction ==

These instructions document installation of the integrated internal RT ticketing system.

There is also support for running this integration against an external RT installation, but it is not (yet) documented.

Documentation contributions are welcome.

== Prerequisites ==

* [http://search.cpan.org/dist/Apache-Session Apache::Session]
* [http://search.cpan.org/dist/HTML-Tree HTML::TreeBuilder]
* [http://search.cpan.org/dist/HTML-Format HTML-Format] (CPAN: "install HTML::FormatText")
* [http://search.cpan.org/dist/Test-Inline Test::Inline]
* [http://search.cpan.org/dist/Class-ReturnValue Class::ReturnValue]
* [http://search.cpan.org/dist/DBIx-SearchBuilder DBIx::SearchBuilder]
* [http://search.cpan.org/dist/Log-Dispatch Log::Dispatch]
* [http://search.cpan.org/dist/Locale-Maketext-Lexicon Locale::Maketext::Lexicon]
* [http://search.cpan.org/dist/Locale-Maketext-Fuzzy Locale::Maketext::Fuzzy]
* [http://search.cpan.org/dist/Text-Wrapper Text::Wrapper]
* [http://search.cpan.org/dist/Time-modules Time-modules] (CPAN: "install Time::ParseDate")
* [http://search.cpan.org/dist/TermReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Autoformat Text::Autoformat]
* [http://search.cpan.org/dist/Text-Quoted Text::Quoted]
* [http://search.cpan.org/dist/Regexp-Common Regexp::Common]
* [http://search.cpan.org/dist/HTML-Scrubber HTML::Scrubber]
* [http://search.cpan.org/dist/Tree-Simple Tree::Simple]
* [http://search.cpan.org/dist/Crypt-SSLeay Crypt::SSLeay]
* [http://search.cpan.org/dist/GDGraph GD::Graph]
* [http://search.cpan.org/dist/UNIVERSAL-Require UNIVERSAL::require]
* [http://search.cpan.org/dist/XML-RSS XML::RSS]
* [http://search.cpan.org/dist/Calendar-Simple Calendar::Simple]
* [http://search.cpan.org/dist/GD-Graph GD::Graph]
* [http://search.cpan.org/dist/GD-Text GD::Text]
* [http://search.cpan.org/dist/CSS-Squish CSS::Squish]
* [http://search.cpan.org/dist/HTML-Element-Extended HTML::ElementTable]

Missing prerequisites? Please add them.

== Installation ==

* Create a new Unix group called 'rt'
<pre>
addgroup rt
</pre>
* Edit the top-level Makefile (within the freeside source directory - NOT rt directory), set RT_ENABLED to 1 and set the RT_DOMAIN, RT_TIMEZONE, and FREESIDE_URL variables.
<pre>
cd freeside-X.X/
nano Makefile
</pre>

* <pre><nowiki>$ make configure-rt</nowiki></pre>
* If your database is not on the local machine you will need to edit /opt/rt3/etc/RT_SiteConfig.pm and set the DatabaseHost value
* <pre><nowiki># make create-rt</nowiki></pre>
** ''Authentication errors?''
*** ''Edit <code>pg_hba.conf</code>, change "<code>ident sameuser</code>" auth to "<code>trust</code>" for the line starting with "<code>local all all</code>" (Debian 7.x has a METHOD column that is set to <code>peer</code>, this needs to be set to <code>trust</code>)''
*** ''Restart Pg''
*** ''Revert the change back and restart Pg after this installation step''
* <pre><nowiki>make install-rt</nowiki></pre>
* Configure Apache: make sure APACHE_CONF and FREESIDE_DOCUMENT_ROOT are set correctly in the Makefile, then run:
<pre>
make install-apache
</pre>

* Restart Apache (httpd) and log into the Freeside web interface using the username and password you created during the first part of the installation.

* Set the '''ticket_system''' configuration value to <code>RT_Internal</code>. (You may also wish to set '''ticket_system-default_queueid''' once you have RT configured.)

=== Bootstrap RT's permissions ===
*Click on "Ticketing Main" on the Freeside main menu to auto-create an RT login for your username
*From "Billing Main", go to Configuration > Employees > Employees, click on "Add an employee" and add a temporary SuperUser "root" user. Note: the user name must be "root" (without the quotes).
* Log into your Freeside installation as the "root" user you just created, by closing all of your browser windows, using a different browser, or by using <code><nowiki>https://root@yourmachone/freeside/</nowiki></code> syntax if your browser supports it.
* Click on "Ticketing Main" on the Freeside main menu. Go to Configuration > Ticketing > Ticketing Global, and then "User Rights". Enter your normal RT/Freeside login in the box labeled ADD USER, click on the "Rights for Administrators" tab, check the "Do anything and everything" box (SuperUser) and then click "Save Changes"
* As your regular user, go back to the freeside employee list, click on the "root" user and set it to disabled

== Futher Reading ==
* Follow the [http://wiki.bestpractical.com/ regular RT documentation] to configure RT, setup the mailgate, etc.

Freeside:3:Documentation:RT Installation

2015-01-21T18:20:37Z

Jonathan:

== Introduction ==

These instructions document installation of the integrated internal RT ticketing system.

There is also support for running this integration against an external RT installation, but it is not (yet) documented.

Documentation contributions are welcome.

== Prerequisites ==

* [http://search.cpan.org/dist/Apache-Session Apache::Session]
* [http://search.cpan.org/dist/HTML-Tree HTML::TreeBuilder]
* [http://search.cpan.org/dist/HTML-Format HTML-Format] (CPAN: "install HTML::FormatText")
* [http://search.cpan.org/dist/Test-Inline Test::Inline]
* [http://search.cpan.org/dist/Class-ReturnValue Class::ReturnValue]
* [http://search.cpan.org/dist/DBIx-SearchBuilder DBIx::SearchBuilder]
* [http://search.cpan.org/dist/Log-Dispatch Log::Dispatch]
* [http://search.cpan.org/dist/Locale-Maketext-Lexicon Locale::Maketext::Lexicon]
* [http://search.cpan.org/dist/Locale-Maketext-Fuzzy Locale::Maketext::Fuzzy]
* [http://search.cpan.org/dist/Text-Wrapper Text::Wrapper]
* [http://search.cpan.org/dist/Time-modules Time-modules] (CPAN: "install Time::ParseDate")
* [http://search.cpan.org/dist/TermReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Autoformat Text::Autoformat]
* [http://search.cpan.org/dist/Text-Quoted Text::Quoted]
* [http://search.cpan.org/dist/Regexp-Common Regexp::Common]
* [http://search.cpan.org/dist/HTML-Scrubber HTML::Scrubber]
* [http://search.cpan.org/dist/Tree-Simple Tree::Simple]
* [http://search.cpan.org/dist/Crypt-SSLeay Crypt::SSLeay]
* [http://search.cpan.org/dist/GDGraph GD::Graph]
* [http://search.cpan.org/dist/UNIVERSAL-Require UNIVERSAL::require]
* [http://search.cpan.org/dist/XML-RSS XML::RSS]
* [http://search.cpan.org/dist/Calendar-Simple Calendar::Simple]
* [http://search.cpan.org/dist/GD-Graph GD::Graph]
* [http://search.cpan.org/dist/GD-Text GD::Text]
* [http://search.cpan.org/dist/CSS-Squish CSS::Squish]
* [http://search.cpan.org/dist/HTML-Element-Extended HTML::ElementTable]

Missing prerequisites? Please add them.

== Installation ==

* Create a new Unix group called 'rt'
<pre>
addgroup rt
</pre>
* Edit the top-level Makefile (within the freeside source directory - NOT rt directory), set RT_ENABLED to 1 and set the RT_DOMAIN, RT_TIMEZONE, and FREESIDE_URL variables.
<pre>
cd freeside-X.X/
nano Makefile
</pre>

* <pre><nowiki>$ make configure-rt</nowiki></pre>
* If your database is not on the local machine you will need to edit /opt/rt3/etc/RT_SiteConfig.pm and set the DatabaseHost value
* <pre><nowiki># make create-rt</nowiki></pre>
** ''Authentication errors?''
*** ''Edit <code>pg_hba.conf</code>, change "<code>ident sameuser</code>" auth to "<code>trust</code>" for the line starting with "<code>local all all</code>" (Debian 7.x has a METHOD column that is set to <code>peer</code>, this needs to be set to <code>trust</code>)''
*** ''Restart Pg''
*** ''Revert the change back and restart Pg after this installation step''
* <pre><nowiki>make install-rt</nowiki></pre>
* Configure Apache: make sure APACHE_CONF and FREESIDE_DOCUMENT_ROOT are set correctly in the Makefile, then run:
<pre>
make install-apache
</pre>

* Restart Apache (httpd) and log into the Freeside web interface using the username and password you created during the first part of the installation.

* Set the '''ticket_system''' configuration value to <code>RT_Internal</code>. (You may also wish to set '''ticket_system-default_queueid''' once you have RT configured.)

=== Bootstrap RT's permissions ===
*Click on "Ticketing Main" on the Freeside main menu to auto-create an RT login for your username
*From "Billing Main", go to Configuration > Employees > Employees and add a temporary "root" user. Note: the user name must be "root" (without the quotes).
* Log into your Freeside installation as the "root" user you just created, by closing all of your browser windows, or by using <code><nowiki>https://root@yourmachone/freeside/</nowiki></code> syntax if your browser supports it.
* Click on "Ticketing Main" on the Freeside main menu. Go to Configuration > Ticketing > Ticketing Global, and then "User Rights". Grant the "SuperUser" right to your normal RT/Freeside login.
* Go back to the freeside employee list and disable the temporary "root" user.

== Futher Reading ==
* Follow the [http://wiki.bestpractical.com/ regular RT documentation] to configure RT, setup the mailgate, etc.