Latest revision as of 13:25, 26 July 2009

Exports (provisioning)

Exports allow you to provision services to remote machines, databases and APIs. Some exports, such as sqlradius and sqlradius_withdomain, enable a feed for retrieving rating/usage data.

Exports can be added and edited under

Configuration -> Provisioning, services and packages -> View/edit exports

Most exports place jobs in the job queue for new, modified or deleted services. Jobs are run by freeside-queued. This daemon needs to be running before exports are acted upon.

Click on Add a new export to create a new export. Select exports from the dropdown to show more information on each export, including available options, setup and usage.

Exports are activated by associating them with one or more service definitions.

Following is a list of which exports can be associated with each type of service.

svc_acct

acct_plesk.pm: Real-time export to Plesk managed mail service
acct_sql.pm: Real-time export of accounts to SQL databases .
artera_turbo.pm:
bsdshell.pm:
communigate_pro.pm: Real-time export to a CommuniGate Pro mail server
communigate_pro_singledomain.pm:
cpanel.pm: Real-time export to Cpanel control panel.
cp.pm: Real-time export to Critical Path Account Provisioning Protocol
cyrus.pm: Real-time export to Cyrus IMAP server
everyone_net.pm: Real-time export to Everyone.net outsourced mail service
infostreet.pm: Real-time export to InfoStreet streetSmartAPI
ldap.pm: Real-time export to LDAP
passwdfile.pm:
radiator.pm: Real-time export to RADIATOR
shellcommands.pm:
shellcommands_withdomain.pm: Real-time export via remote SSH (vpopmail, ISPMan)
sqlmail.pm: Real-time export to SQL-backed mail server
sqlradius.pm: Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS)
sqlradius_withdomain.pm: Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS) with realms
sysvshell.pm:
textradius.pm:
vpopmail.pm: Real-time export to vpopmail text files

svc_domain

bind.pm: Batch export to BIND named
bind_slave.pm: Batch export to slave BIND named
domain_shellcommands.pm: Run remote commands via SSH, for domains (qmail, ISPMan).
domain_sql.pm: Real time export of domains to SQL databases .
http.pm: Send an HTTP or HTTPS GET or POST request
opensrs.pm: OpenSRS integration
sqlmail.pm: Real-time export to SQL-backed mail server

svc_forward

artera_turbo.pm:
forward_shellcommands.pm: Run remote commands via SSH, for forwards
postfix.pm: Postfix text files
sqlmail.pm: Real-time export to SQL-backed mail server

svc_www

apache.pm: Export an Apache httpd.conf file snippet.
www_plesk.pm: Real-time export to Plesk managed hosting service
www_shellcommands.pm: Run remote commands via SSH, for virtual web sites (directory maintenance, FrontPage, ISPMan)

svc_broadband

nas_wrapper.pm: A meta-export that triggers other svc_broadband exports.
prizm.pm: Real-time export to Northbound Interface
router.pm: Send a command to a router.
snmp.pm: Sends SNMP SETs to an SNMP agent.
trango.pm: Sends SNMP SETs to a Trango AP.

svc_external

artera_turbo.pm:

Packages

Price Plans

Common price plans

flat
subscription
prorate
sqlradacct_hour
voip_cdr
prepaid

Wholesale price plans

bulk

Other price plans

flat_delayed
flat_introrate
prorate_delayed

base_delayed
base_rate

sql_external
sql_generic

Price plans of questionable functionality

flat_comission_cust
flat_comission_pkg
flat_comission

voip_sqlradacct

sesmon_hour
sesmon_minute

Misc

Some notes on Upselling

Resellers

Employees

Go to Configuration -> Employees -> Employees to view the existing employees and add new ones. It is highly recommended to add a separate account for each person rather than using role accounts.

To add a new employee, click on "Add an employee"
Or to edit an existing group, click on the employee number or name in the list of employees.
Enter or edit the username, password and name. If editing an existing employee and no password change is desired, the password fields can be left blank.
Check the "Disable employee" box to disable this employee.
In the "Employee groups" section, mark or unmark checkboxes to indicate the access groups for this employee.

Employee groups and access control

To setup employee access control or agent/reseller virtualization, you need to setup employee groups. Go to Configuration -> Employees -> Employee groups to view the existing groups and add new ones. The system starts with a "Superuser" group which has access to all functionality for the first agent.

To add a new group, click on "Add an employee group"
Or to edit an existing group, click on the group number or name in the list of groups.
Enter or edit the group name.
In the "Group limited to these agent(s)" section, mark checkboxes next to the agents this employee group should be able to see. Employees in this group will only see customers of the selected agents in the system and reports.
In the "Group access rights" section, mark or unmark checkboxes to indicate the access rights this employee group should have. Rights marked with an "*" are global rights which provide access to global data which is shared among all agents. Their use is not recommended for groups which are limited to a subset of agents.
After adding a new group, don't forget to go back and add or edit employees to place them into the new group.

Billing

Invoice events

Use invoice events to implement your business rules for re-sending invoices and late notices, retrying cards, suspending, etc.

Configuration -> Billing -> View/Edit invoice events

The freeside-daily script should be run daily to bill customers and run invoice collection events.
- Typically, this is accomplished with an entry in the freeside user's crontab such as:
```
0 0 * * * /usr/local/bin/freeside-daily
```
- If running freeside-daily manually, ensure the TZ variable is set to your timezone with a command such as:
```
TZ="US/Pacific" freeside-daily fs_daily
```
If any monthly events are enabled, the freeside-monthly script should be run monthly.
Invoice events can also be used to implement agent-virtualized invoices. (add more info)

Invoices

Templates

Typeset (LaTeX) invoice templates

Prerequisites

Almost all distributions include the necessary prerequisites listed here, manual installation is practically never necessary.
Install Ghostscript (gs)
Install teTeX or TeX Live
Ensure that the pslatex, dvips, and pdflatex command line utilities were installed

Content setup

Edit the invoice_latexreturnaddress, invoice_latexfooter, invoice_latexnotes, and invoice_latexsmallfooter configuration options. If you are adventurous, edit invoice_latex as well.

Logo setup

The EPS logo is for PDF and printed invoices.

For best results, save a vector format logo in EPS (Encapsulated PostScript) format.
- Your graphic artist can create vector image from a bitmap (tracing etc).
- Converting a bitmap such as a JPG can work (the bigger the better), but it may render in lower quality, blurry or with the "jaggies" (especially when actually printed, not just viewed as a PDF)
Resize the logo to 90pt X 36pt: epsffit -c 0 0 90 36 yourlogo.eps >logo.eps
Copy the resized logo to /usr/local/etc/freeside/conf.your_datasrc/logo.eps
Problems? Try bin/strip-eps <oldlogo.eps >trynewlogo.eps

The PNG logo is for emailed and online invoices.

Freeside ships with a logo of 92 x 62. Any logo close to this size should work with the default HTML template.

HTML invoice templates

Place your logo in PNG format at /usr/local/etc/freeside/conf.your_datasrc/logo.png
Edit the invoice_html configuration option or the /usr/local/etc/freeside/conf.your_datasrc/invoice_html file. HTML invoices use Text::Template with <%= and %> delimiters.
The following configuration options can be set to override the default behaviour of using the invoice_latex* data transformed to HTML: invoice_htmlreturnaddress, and invoice_htmlfooter, invoice_htmlnotes.

Plaintext invoice templates

See the Text::Template documentation for details on the substitution language.
You must call the invoice_lines() function at least once - pass it a number of lines, and it returns a list of array references, each of two elements: a service description column, and a price column. Alternatively, call invoice_lines() with no arguments, and pagination will be disabled - all invoice line items will print on one page, with no padding (recommended for email invoices).
Descriptions of variables are available in invoice_html

Misc

Manually setting next invoice number sequence

With PostgreSQL, to number invoices starting at 5000:
```
SELECT SETVAL(cust_bill_invnum_seq, 4999);
```
With MySQL:

Payment Receipts

The payment_receipt_email template is used for manually applied payments.

Credit cards and Electronic checks

Real-time credit card and electronic check processing
Batch credit card and electronic check processing
Credit card expiration alerts: Customize the alerter_template configuration option and run freeside-expiration-alerter daily.
Credit card decline alerts: Customize the declinetemplate configuration option and set the emaildecline configuration option.

Misc

Setting up Encrypted Credit Cards
Setting up Texas Tax
Setting up VoIP
Need to print to Windows printers? Follow steps 1-4 of Share Your Windows Printer.
Setting up Slony replication and failover
Using a non-standard PostgreSQL Schema

This page is part of the Freeside Context Sensitive Help. Please review the Editing Guidelines before making modifications to this page.

@@ Line 1: / Line 1: @@
-== Provisioning ==
+= Exports (provisioning) =
-== Services ==
+'''Exports''' allow you to provision services to remote machines, databases and APIs.  Some exports, such as ''sqlradius'' and ''sqlradius_withdomain'',  enable a feed for retrieving rating/usage data.
-== Packages ==
+Exports can be added and edited under
+: Configuration -> Provisioning, services and packages -> View/edit exports
-===Upselling===
+Most exports place jobs in the job queue for new, modified or deleted services.  Jobs are run by [[Freeside:1.7:Documentation:Developer/bin/freeside-queued|freeside-queued]].  This daemon needs to be running before exports are acted upon.
-'''Scenario:'''
+Click on ''Add a new export'' to create a new export.  Select exports from the dropdown to show more information on each export, including available options, setup and usage.
-;:You have a customer with a 500mb email account, and they would like to upgrade to the 1000mb email account
+Exports are activated by associating them with one or more '''service definitions'''.
-'''Solution:'''
+Following is a list of which exports can be associated with each type of service.
-;:Freeside does not yet support add-on packages that launch external commands, so the best solution presently is to upgrade a user from the 500mb service to the 1000mb service by calling an appropriate "modify" command for the export associated with the package.
+==svc_acct==
+* [[Freeside:1.7:Documentation:Administration:acct_plesk.pm|acct_plesk.pm]]:  Real-time export to Plesk managed mail service
+* acct_sql.pm:  Real-time export of accounts to SQL databases .
+* artera_turbo.pm:
+* bsdshell.pm:
+* communigate_pro.pm:  Real-time export to a CommuniGate Pro mail server
+* communigate_pro_singledomain.pm:
+* cpanel.pm:  Real-time export to Cpanel control panel.
+* cp.pm:  Real-time export to Critical Path Account Provisioning Protocol
+* cyrus.pm:  Real-time export to Cyrus IMAP server
+* everyone_net.pm:  Real-time export to Everyone.net outsourced mail service
+* infostreet.pm:  Real-time export to InfoStreet streetSmartAPI
+* ldap.pm:  Real-time export to LDAP
+* passwdfile.pm:
+* radiator.pm:  Real-time export to RADIATOR
+* shellcommands.pm:
+* shellcommands_withdomain.pm:  Real-time export via remote SSH (vpopmail, ISPMan)
+* sqlmail.pm:  Real-time export to SQL-backed mail server
+* sqlradius.pm:  Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS)
+* sqlradius_withdomain.pm:  Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS) with realms
+* sysvshell.pm:
+* textradius.pm:
+* vpopmail.pm:  Real-time export to vpopmail text files
-'''Example:'''
+==svc_domain==
+* bind.pm:  Batch export to BIND named
+* bind_slave.pm: Batch export to slave BIND named
+* domain_shellcommands.pm:  Run remote commands via SSH, for domains (qmail, ISPMan).
+* domain_sql.pm:  Real time export of domains to SQL databases .
+* http.pm:  Send an HTTP or HTTPS GET or POST request
+* [[Freeside:1.7:Documentation:Administration:opensrs.pm|opensrs.pm]]: OpenSRS integration
+* sqlmail.pm:  Real-time export to SQL-backed mail server
-# Config -> Provisioning, services and packages -> View/Edit Exports
+==svc_forward==
-# Edit the shell command for your 500mb service, and your 1000mb service
+* artera_turbo.pm:
-# Call appropriate shell scripts using the 'modify' field to change disk quotas
+* forward_shellcommands.pm:  Run remote commands via SSH, for forwards
-# Select a customer
+* postfix.pm:  Postfix text files
-# Under packages, click "Change Package"
+* sqlmail.pm:  Real-time export to SQL-backed mail server
-# Upgrade the user to the 1000mb service by selecting the 1000mb package, and your "modify" script will now be called. The reverse would be done if you were moving someone from 1000mb to 500mb
-== Resellers ==
+==svc_www==
+* apache.pm:  Export an Apache httpd.conf file snippet.
+* [[Freeside:1.7:Documentation:Administration:www_plesk.pm|www_plesk.pm]]:  Real-time export to Plesk managed hosting service
+* www_shellcommands.pm:  Run remote commands via SSH, for virtual web sites (directory maintenance, FrontPage, ISPMan)
+==svc_broadband==
+* nas_wrapper.pm:  A meta-export that triggers other svc_broadband exports.
+* prizm.pm:  Real-time export to Northbound Interface
+* router.pm:  Send a command to a router.
+* snmp.pm:  Sends SNMP SETs to an SNMP agent.
+* trango.pm:  Sends SNMP SETs to a Trango AP.
+==svc_external==
+* artera_turbo.pm:
+= Packages =
+== Price Plans ==
+=== Common price plans ===
+* flat
+* subscription
+* prorate
+* sqlradacct_hour
+* voip_cdr
+* prepaid
+=== Wholesale price plans ===
+* bulk
+=== Other price plans ===
+* flat_delayed
+* flat_introrate
+* prorate_delayed
+* base_delayed
+* base_rate
+* sql_external
+* sql_generic
+=== Price plans of questionable functionality ===
+* flat_comission_cust
+* flat_comission_pkg
+* flat_comission
+* voip_sqlradacct
+* sesmon_hour
+* sesmon_minute
+== Misc ==
+* Some notes on [[Freeside:1.7:Documentation:Administration:Upselling | Upselling]]
+= Resellers =
+= Employees =
 == Employees ==
-== Billing ==
+Go to Configuration -> Employees -> Employees to view the existing employees and add new ones.  It is highly recommended to add a separate account for each person rather than using role accounts.
-===Real-time Processing===
-====Configuration====
+* To add a new employee, click on "Add an employee"
-#Install a real-time processing module, such as Business::OnlinePayment::TCLink, or Business::OnlinePayment::Exact<pre><nowiki>
+* Or to edit an existing group, click on the employee number or name in the list of employees.
- root# cpan Business::OnlinePayment::TCLink
+* Enter or edit the username, password and name.  If editing an existing employee and no password change is desired, the password fields can be left blank.
-</nowiki></pre>
+* Check the "Disable employee" box to disable this employee.
-#Remove the Batch Card processing event, and add a Real-Time Card processing event
+* In the "Employee groups" section, mark or unmark checkboxes to indicate the access groups for this employee.
-#* Configuration -> Billing -> View/Edit Invoice Events
-#* Click on "Batch card"
-#** Check off "Disabled"
-#** Click "Apply changes"
-#* Click on "Add a new invoice event"
-#** Name it something like "Realtime card"
-#** Choose the radio button "Run card with a Business::OnlinePayment realtime gateway"
-#** Click on "Add invoice event"
-#Enable your payment gateway
-#* Configuration -> Settings
-#* Click "Edit Configuration"
-#* Click the "Billing" tab
-#** For the 'business-onlinepayment' field, enter the Business::OnlinePayment module you are using, followed by your account ID, password, and (optionally), type of action<pre><nowiki>
- TCLink
- someuser
-  password
- Normal Authorization
-</nowiki></pre>
-#*** Some payment gateways such as LinkPoint don't use a username/password, and require additional parameters. These can be passed in as key<newline>value pairs<pre><nowiki>
- LinkPoint
-               <-- intentionally left blank
-               <-- intentionally left blank
- Normal Authorization
- storename     <-- key
-        <-- value
- keyfile       <-- key
-.pem    <-- value
- lbin          <-- key
- /usr/bin.lbin <-- value
- tmp
- /tmp/secure
-</nowiki></pre>
-#** Click "Apply Changes"
-References
+== Employee groups and access control ==
-# http://search.cpan.org/src/WITTEN/Business-OnlinePayment-TCLink-1.03/README.freeside
-# http://www.sisd.com/freeside/list-archive/msg03193.html
-# http://wavetail.420.am:81/freeside/docs/billing.html
-====Testing Real-Time Processing====
+To setup employee access control or agent/reseller virtualization, you need to setup employee groups.  Go to Configuration -> Employees -> Employee groups to view the existing groups and add new ones.  The system starts with a "Superuser" group which has access to all functionality for the first agent.
-''One Time Transactions''
-* Choose a customer account
-* Click on 'Process credit card payment'
-* Enter a payment ammount, and credit card details
-* Click 'Process payment'
-* The transaction should happen immediately
-* Click on 'View this customer'
-* At the bottom of the screen, "Payment History" should include this transaction
-''Recurring Transactions''
+* To add a new group, click on "Add an employee group"
-* Choose a customer account
+* Or to edit an existing group, click on the group number or name in the list of groups.
-* Click on 'Bill now', or run the freeside-daily cronjob from the command line as the freeside user
+* Enter or edit the group name.
-* At the bottom of the screen, "Payment History" should include this transaction
+* In the "Group limited to these agent(s)" section, mark checkboxes next to the agents this employee group should be able to see.  Employees in this group will only see customers of the selected agents in the system and reports.
+* In the "Group access rights" section, mark or unmark checkboxes to indicate the access rights this employee group should have.  Rights marked with an "*" are global rights which provide access to global data which is shared among all agents. Their use is not recommended for groups which are limited to a subset of agents.
+* After adding a new group, don't forget to go back and add or edit employees to place them into the new group.
-== Misc ==
+= Billing =
+== Invoice events ==
+* Use invoice events to implement your business rules for re-sending invoices and late notices, retrying cards, suspending, etc.
+<code>Configuration -> Billing -> View/Edit invoice events</code>
+* The freeside-daily script should be run daily to bill customers and run invoice collection events.
+** Typically, this is accomplished with an entry in the freeside user's crontab such as: <pre>0 0 * * * /usr/local/bin/freeside-daily</pre>
+** If running freeside-daily manually, ensure the <code>TZ</code> variable is set to your timezone with a command such as: <pre>TZ="US/Pacific" freeside-daily fs_daily</pre>
+* If any monthly events are enabled, the freeside-monthly script should be run monthly.
+* Invoice events can also be used to implement agent-virtualized invoices. (add more info)
+== Invoices ==
+=== Templates ===
+==== Typeset (LaTeX) invoice templates ====
+===== Prerequisites =====
+* Almost all distributions include the necessary prerequisites listed here, manual installation is practically never necessary.
+* Install [http://www.ghostscript.com/ Ghostscript] (gs)
+* Install [http://www.tug.org/tetex/ teTeX] or [http://www.tug.org/texlive/ TeX Live]
+* Ensure that the <code>pslatex</code>, <code>dvips</code>, and <code>pdflatex</code> command line utilities were installed
+===== Content setup =====
+* Edit the invoice_latexreturnaddress, invoice_latexfooter, invoice_latexnotes, and invoice_latexsmallfooter configuration options. If you are adventurous, edit invoice_latex as well.
+===== Logo setup =====
+The <em title="Encapsulated Postscript">EPS</em> logo is for PDF and printed invoices.
+* For best results, save a '''vector format''' logo in EPS (Encapsulated PostScript) format.
+** Your graphic artist can create vector image from a bitmap (tracing etc).
+** Converting a bitmap such as a JPG can work (the bigger the better), but it may render in lower quality, blurry or with the "jaggies" (especially when actually printed, not just viewed as a PDF)
+* Resize the logo to 90pt X 36pt: <code>epsffit -c 0 0 90 36 yourlogo.eps >logo.eps</code>
+* Copy the resized logo to <code>/usr/local/etc/freeside/conf.''your_datasrc/logo.eps''</code>
+* Problems?  Try <code>bin/strip-eps <oldlogo.eps >trynewlogo.eps</code>
+The <em title="Portable Network Graphic">PNG</em> logo is for emailed and online invoices.
+Freeside ships with a logo of 92 x 62.  Any logo close to this size should work with the default HTML template.
+==== HTML invoice templates ====
+* Place your logo in PNG format at <code>/usr/local/etc/freeside/conf.''your_datasrc''/logo.png</code>
+* Edit the invoice_html configuration option or the <code>/usr/local/etc/freeside/conf.''your_datasrc''/invoice_html</code> file.  HTML invoices use Text::Template with <%= and %> delimiters.
+* The following configuration options can be set to override the default behaviour of using the invoice_latex* data transformed to HTML: invoice_htmlreturnaddress, and invoice_htmlfooter, invoice_htmlnotes.
+==== Plaintext invoice templates ====
+* See the Text::Template documentation for details on the substitution language.
+* You must call the invoice_lines() function at least once - pass it a number of lines, and it returns a list of array references, each of two elements: a service description column, and a price column. Alternatively, call invoice_lines() with no arguments, and pagination will be disabled - all invoice line items will print on one page, with no padding (recommended for email invoices).
+* Descriptions of variables are available in [[Freeside:1.7:Documentation:Template:invoice_html|invoice_html]]
+=== Misc ===
+==== Manually setting next invoice number sequence ====
+* With PostgreSQL, to number invoices starting at 5000: <pre>SELECT SETVAL(cust_bill_invnum_seq, 4999);</pre>
+* With MySQL:
+== Payment Receipts ==
+The [[Freeside:1.7:Documentation:Template:payment_receipt_email|payment_receipt_email]] template is used for manually applied payments.
+== Credit cards and Electronic checks ==
+* [[Freeside:1.7:Documentation:Administration:Real-time_Processing | Real-time credit card and electronic check processing]]
+* [[Freeside:1.7:Documentation:Administration:Batch_Processing | Batch credit card and electronic check processing]]
+* Credit card expiration alerts: Customize the ''alerter_template'' configuration option and run <code>freeside-expiration-alerter</code> daily.
+* Credit card decline alerts: Customize the ''declinetemplate'' configuration option and set the ''emaildecline'' configuration option.
+= Misc =
 * Setting up [[Freeside:1.7:Documentation:Administration:Encrypted Credit Cards | Encrypted Credit Cards]]
 * Setting up [[Freeside:1.7:Documentation:Administration:Texas Tax | Texas Tax]]
 * Setting up [[Freeside:1.7:Documentation:Administration:VoIP | VoIP]]
+* Need to print to Windows printers?  Follow steps 1-4 of  [http://iharder.sourceforge.net/current/macosx/winmacprinter/ Share Your Windows Printer].
+* Setting up [[Freeside:1.7:Documentation:Administration:Slony | Slony replication and failover]]
+* Using a non-standard [[Freeside:1.7:Documentation:Administration:PostgreSQL_Schema | PostgreSQL Schema]]
+{{ContextSensitiveHelp}}

Difference between revisions of "Freeside:1.7:Documentation:Administration"

Latest revision as of 13:25, 26 July 2009

Contents

Exports (provisioning)

svc_acct

svc_domain

svc_forward

svc_www

svc_broadband

svc_external

Packages

Price Plans

Common price plans

Wholesale price plans

Other price plans

Price plans of questionable functionality

Misc

Resellers

Employees

Employees

Employee groups and access control

Billing

Invoice events

Invoices

Templates

Typeset (LaTeX) invoice templates

Prerequisites

Content setup

Logo setup

HTML invoice templates

Plaintext invoice templates

Misc

Manually setting next invoice number sequence

Payment Receipts

Credit cards and Electronic checks

Misc

Navigation menu

Search