Freeside - User contributions [en]

Freeside:4:Documentation:Administration:Tax Districts

2019-06-12T08:32:24Z

Mitch: Add section on v4 upgrade

== Overview ==
Freeside supports billing taxes by district, instead of city/county/state.

Currently this is only supported in the state of Washington. Public data
sources provided by the Washington Dept. of Revenue are used to automatically
maintain tax rate tables, and classify customer locations into the correct
tax district.

== Setup ==

=== Enable Washington state sales tax districts ===

# Navigate to: Configuration > Settings
# Set option '''tax_district_method''' to '''Washington sales tax'''
# Set option '''tax_district_taxname''', the tax name to dsplay on the invoice, or keep the default as '''Tax'''
# Run '''freeside-daily''' or '''freeside-tax-district-update -l''' to populate tax tables, and classify customers into their districts

=== Download tax tables and classify customer tax districts ===

The WA tax tables will be automatically populated, and customers in WA will
be classified into their tax district he next time '''freeside-daily''' runs.

You don't have to wait for '''freeside-daily'''. The following command
will update the tax tables and classify WA customers into their tax district.

sudo -u freeside /usr/bin/freeside-tax-district-update -l freeside_username

=== Changing Tax Name ===

You can change the display name for this tax by setting the config option '''tax_district_taxname'''. After changing the configuration value, the tax tables must be updated with the new taxname. This will happen automatically on the 1st of each month. Use '''freeside-tax-district-update''' to force this update sooner.

== Administration ==

=== Tax table updates ===

'''freeside-daily''' will refresh the tax tables automatically on the first
of each month.

Tax tables can be forcibly updated at any time using the
'''freeside-tax-district-update''' utility.

If freeside is configured to use tax classes, with the '''enable_taxclasses'''
configuration value, a complete copy of the Washington tax table will be
created in every taxclass. If new tax classes are added later, the
'''freeside-tax-district-update''' utility can be used to force an immediate rebuild
of the tax table into the new tax class.

To view the tax table, navigate to Configuration > Billing > Locales and Tax Rates

=== Customer tax district classification ===

When an address record is created or edited, Freeside will ask the WA Dept.
of Revenue API which tax district to use for the address.

If an invalid address is entereed, the tax district cannot be determined.
The user will be advised to correct the address, or to manually choose a
tax district to use.

Invoices cannot be generated for a WA customer missing a tax district.
When a customer is missing a tax district:
* A notice appears on the customer page with instructions to fix
* Billing will not complete for this customer
* Freeside will retry, daily, to determine the customer tax district
* System log notices are generated about this problem. Subscribe to E-Mail alerts of these notices.

The '''freeside-tax-district-update''' tool can be used to force reclassification
of every WA state address in cust_location. This may be useful if the state
re-draws district lines, and all customers need to be reclassified.

=== Configure system log alerts ===

If a customer location record in the database lacks a tax district,
freeside-daily will attempt to correct this situation. If that fails,
Freeside will report an error to the system log.

Freeside will report another error every time '''freeside-daily''' runs, for
every WA cust_location record without a tax district.

It is recommended to set two e-mail system log alerts:
1. log-level: error, log-context: wa_sales
2. log-level: error, log-context: tax_rate_update

Using log-level: info, somebody can be notified of all tax tables updates,
and every successful tax district classification for a cust_location record.

See [[Freeside:3:Documentation:Administration#System_Log]] for help
configuration system log alerts.

== Upgrade from Version 3 to 4 ==

Beginning with Freeside version 4, duplicate rows for identical tax districts
in the cust_main_county table will block automatic tax table updates.

After upgrade, if an instance needs tax table repair,
'''freeside-wa-tax-table-repair --check''' will display information on
the problem tax rows. The duplicate rows can be merged with
'''freeside-wa-tax-table-repair --merge''' or
'''freeside-wa-tax-table-repair --merge-all'''

If a problem has developed with manually entered tax table rows for
Universal Service Fund, this can be fixed with
'''freeside-wa-tax-table-repaair --fix-usf'''

After running these tools, it's recommended to force a tax table update
with '''freeside-wa-tax-table-update -l'''

Freeside:3:Documentation:Administration:Real-time Processing:Bambora

2019-04-24T06:20:21Z

Mitch: Initial documentation for Bambora payment module

= Configuring Bambora Real-Time Processing =

See [[Freeside:3:Documentation:Administration:Real-time_Processing]] for general configuration

== Configure Bambora Merchant Settings ==

This module generates HTTP Authorization headers based on your
Bambora API Access Passcode. You must generate an API Access Passcode
within the Bambora merchant portal under the menu headings
Administration > Account Settings > Order Settings

If you intend to use tokenization, you must also copy the same
API Access Passcode to the configuration page found at
Configuration > Payment Profile Configuration

== Tokenization Implementation ==

Many-use tokenization is achieved via the Bambora Payment Profile feature

The token created by this module represents the Bambora customer_code identifier
for Payment Profile records

This module does not support advanced management of the Payment Profile,
such as storing multiple cards onto a single profile, or updating the
stored profile detail

Recommending configuration settings in your Bambora merchant portal:
( as of the time of this module's writing )

Main Manu > Configuration > Payment Profile Configuration

General Settings:
- Uncheck "Requre unique order numbers"
- Uncheck "Do not allow profile to be created with billing information
duplicated from an existing profile"

Security Settings:
- Select: API Access Passcode (requierd for this API)
- The API Access Passcode will be your "password" using this module

Credit Card Settings
- Uncheck "Do not allow profile to be created with card data duplicated
from an existing profile""

== Configure the Freeside Payment Gateway ==

* Within Freside, navigate to Main Menu > Configuration > Settings > Billing
* Configure the text box for Business::OnlinePayment module with your Merchant ID and API Passcode, and click Apply Changes

Bambora
123456789
F32C09C2996D4D9394802C7BA61F19E1

Freeside:3:Documentation:Administration:Real-time Processing

2019-04-24T06:10:57Z

Mitch: /* Introduction */ Add Bambora/Beanstream link

=Introduction=
Freeside uses Business::OnlinePayment to process payments in real-time. See the [http://perl.business/onlinepayment/ Business::OnlinePayment homepage] for supported processors.

Additional documentation available for:
* [[Freeside:1.9:Documentation:Administration:Real-time_Processing:IPPay|IPPay]]
* [[Freeside:3:Documentation:Administration:Real-time_Processing:Bambora|Bambora/Beanstream]]

=Configuring Real-Time Processing=

== Install gateway module ==

*Install a real-time processing module, such as Business::OnlinePayment::TCLink, or Business::OnlinePayment::Exact
Debian:
<pre><nowiki>
root# aptitude install libbusiness-onlinepayment-gatewayname-perl
</nowiki></pre>
Other OSes:
<pre><nowiki>
root# cpan Business::OnlinePayment::GatewayName
</nowiki></pre>

== Configure billing events ==

* Remove the Batch Card processing event(s), if any:
** Configuration -> Billing -> View/Edit Billing Events
** Click on "Batch card"
** Check off "Disabled"
** Click "Apply changes"

* Add an event for realtime processing:
** Configuration -> Billing -> View/Edit Billing Events
** Click on "Add a new invoice event"
** Choose Type "Invoice"
** Scroll down to the "Event action" dropdown at the bottom, and select "Run card with a Business::OnlinePayment realtime gateway"
** Click on "Add billing event definition" at the bottom of the form.

== Configure the payment gateway ==

* Configuration -> Settings
* Click the "Billing" tab
* Scroll down and click on the "business-onlinepayment" configuration option.
* In the text box, 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
123456 <-- value
keyfile <-- key
123456.pem <-- value
lbin <-- key
/usr/bin.lbin <-- value
tmp
/tmp/secure
</nowiki></pre>
* Click "Apply Changes"

=Testing Real-Time Processing=
==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==
* Choose a customer account
* Click on 'Bill now', or run the freeside-daily cronjob from the command line as the freeside user
* At the bottom of the screen, "Payment History" should include this transaction

= References =
* http://search.cpan.org/src/WITTEN/Business-OnlinePayment-TCLink-1.03/README.freeside
* http://www.sisd.com/freeside/list-archive/msg03193.html

Freeside:3:Documentation:Administration

2019-03-12T17:12:46Z

Mitch: /* Access */ svc_broadband links

= 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:3:Documentation:Developer/bin/freeside-queued|freeside-queued]]. This daemon needs to be running before exports are acted upon.

Some exports use SSH, SCP or SFTP to communicate with external machines. See the documentation on [[Freeside:3:Documentation:Administration:SSH_Keys|SSH keys]].

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==
* [[Freeside:3: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:
* [[Freeside:3:Documentation:Administration:communigate_pro.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
* [[Freeside:3:Documentation:Administration:ldap.pm|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
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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:3:Documentation:Administration:opensrs.pm|opensrs.pm]]: OpenSRS integration
* sqlmail.pm: Real-time export to SQL-backed mail server

==svc_forward==
* artera_turbo.pm:
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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.
* [[Freeside:3: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.
* [[Freeside:3:Documentation:Administration:prizm.pm|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_phone==
* globalpops_voip.pm:
* grandstream.pm: Grandstream phone and ATA provisioning. This [http://www.freeside.biz/blog/?p=11 blog article] is a start at documentation.
* indosoft.pm:
* internal_diddb.pm:
* netsapiens.pm:
* phone_shellcommands.pm:
* phone_sqlradius.pm:
* thirdlane.pm:
* [[Freeside:Documentation:Administration:vitelity.pm|vitelity.pm]]: Vitelity provisioning

==svc_external==
* artera_turbo.pm:

==svc_dsl==
* ikano.pm: see [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

= Services =

== Generic ==

=== Accounts (svc_acct) ===

Accounts - anything with a username (mailbox, shell, RADIUS, etc.)

* [[Freeside:3:Documentation:Administration:svc_acct:_password_encoding|Password encoding]]

=== Hardware (svc_hardware) ===

Equipment supplied to customers

=== External (svc_external) ===

Externally-tracked service

== Access ==

=== DSL (svc_dsl) ===

* [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

=== Broadband (svc_broadband) ===

Fixed wireless broadband

* [[Freeside:4:Documentation:Administration:svc_broadband.pm|svc_broadband.pm]]
* [[Freeside:4:Documentation:Administration:svc_broadband.pm#Automatically_Assign_IP_Addresses|Automatically Assign IP Addresses]]

=== Cable (svc_cable) ===

=== DISH Network (svc_dish) ===

== Telephony ==

=== Customer phone number / DID (svc_phone) ===

* [[Freeside:Documentation:Administration:Phone devices|Phone devices]]

=== Customer PBX (svc_pbx) ===

=== Phone circuit (svc_circuit) ===

== Hosting ==

=== Domains (svc_domain) ===

=== Certificate (svc_cert) ===

=== Forwards (svc_forward) ===

=== Mailing list (svc_mailinglist) ===

=== Site hosting (svc_www) ===

== Colocation ==

=== Customer router/switch port (svc_port) ===

= Packages =

{{Freeside:3:Documentation:Administration:pkg_category}}

== Price Plans ==

=== Common price plans ===

* flat
* subscription
* prorate
* sqlradacct_hour
* [[voip_cdr]]
* prepaid

=== Wholesale price plans ===

* bulk

* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:agent | agent]]
* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:cdr_termination |
cdr_termination ]]

=== 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:3:Documentation:Administration:Upselling | Upselling]]

= Resellers =

=== Wholesaler configuraiton ===
[[Freeside:3:Documentation:Administration:Wholesaler|Using agents for setting up Wholesalers]]

= Employees =

== 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.

Go to Configuration -> Ticketing -> Ticketing users
* Click on the Create link in the upper right hand corner
* Enter the same username as the Employee name above
* Enter any other information (Real name, Email address, etc. )
* Check both boxes in the access control box
* Click the Create button
(Be sure to add the ticketing user to the appropriate ticketing groups)

== 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.

= Installers / Appointments =

== Installers ==

* Designate some employees as installers (Configuration -> Employees -> Employees)
* Edit their schedules (Configuration -> Employees -> Installer availability)

== Ticketing ==

* Setup a queue for appointments (installations, removals, etc.), or use existing per agent queues
* Make sure the installer employees can own / see / edit tickets in this
queue (add them to a ticketing group with OwnTicket / SeeQueue on that queue or global, etc.)
* not yet <strike>XXX future todo some sort of ill-defined thing with configuring a custom field to designate install / recall / service call / removal</strike>

== Packages ==

not yet; package(+location)-specific appointments are a future TODO
<strike>
* Setup a package category for packages that can schedule appointments
* In the package category, select a queue for appointments or pick "Agent-specific queue"
</strike>

== Employee rights ==

* Upgrade should do this / should be available in a default install, but may not be implemented yet
* Give one or more employee groups "View appointments" and "Make appointment" (in Customer package rights)

= Billing =

== Billing events ==
Billing events are the primary mechanism to implement your business rules. Rules such as resend invoices, retry cards, suspend or cancel accounts for non-payment, etc. are all handled by billing events.

At a high level, follow the following steps to create billing events:
* Add a new Billing Event (Configuration > Billing > Billing events)
* Name the event
* Choose the type of event:
** Package - Packages and associated dates (Including Commissions)
** Invoice - Invoice status and dates
** Customer - Customer Balances and Information
** Batch Payment - Batch payment results
** Statement - Send statement
* Choose whether to apply to one or all agents
* Choose the frequency for the system to check and see if the event should run.
* Choose appropriate filters.
* Choose appropriate actions.

The form is dynamic so changing the type of event will change the available filters and actions.

== Daily and Monthly Scripts ==
* 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)
* Be sure to include the full path of freeside-daily in your cron job.

== Invoices ==

=== 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

==== 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: <code>epsffit -c 0 0 90 36 yourlogo.eps >logo.eps</code>
** ("no %%BoundingBox:" error? Fix with eps2eps)
* Upload the resized logo as the <code>logo.eps</code> configuration option.
* Problems? Try <code>bin/strip-eps <oldlogo.eps >trynewlogo.eps</code>

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.

{{Freeside:3:Documentation:Administration:invoice_layout}}

=== HTML invoice templates ===

* Convert your logo to PNG format and upload it as the <code>logo.png</code> configuration option.
{{Freeside:3:Documentation:Administration:invoice_templates|format=html}}

=== 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:3:Documentation:Template:invoice_html|invoice_html]]

=== Misc ===

==== Manually setting next customer number sequence ====

* With PostgreSQL, to number customers starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_main', 'custnum'), 4999);</pre>
* With MySQL, to number customers starting at 5000: <pre>ALTER TABLE cust_main AUTO_INCREMENT = 5000;</pre>

==== Manually setting next invoice number sequence ====

* With PostgreSQL, to number invoices starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_bill', 'invnum'), 4999);</pre>
* With MySQL, to number invoices starting at 5000: <pre>ALTER TABLE cust_bill AUTO_INCREMENT = 5000;</pre>

== Taxes ==

[[Freeside:3:Documentation:Administration:Tax_Districts | District based taxes]]

== Payment Receipts ==

The [[Freeside:3:Documentation:Template:payment_receipt_email|payment_receipt_email]] template is used for manually applied payments.

== Credit cards and Electronic checks ==
* [[Freeside:3:Documentation:Administration:Real-time_Processing | Real-time credit card and electronic check processing]]
* [[Freeside:3: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 =

These things should probably find a home properly filed in a section above.

== Invoicing and Payments ==

* Setting up [[Freeside:3:Documentation:Administration:Encrypted Credit Cards | Encrypted Credit Cards]] (default in new installs, highly recommended for older installs upgrading)
* Setting up [[Freeside:3:Documentation:Administration:Texas Tax | Texas Tax]]
* Need to print to Windows printers, and the PDF spool is not for you? Follow steps 1-4 of [http://iharder.sourceforge.net/current/macosx/winmacprinter/ Share Your Windows Printer].

== Refunds for automatic payments ==

A refund to an automatic payment can be made within the time limitation set by the payment gateway by using the refund link next to the payment:

<pre>05/19/2015 Payment by fs_queue (Credit card #411111xxxxxx1111) applied to Invoice #228 (05/19/15) (view receipt) (refund) (void) (unapply) - $24.60 $0.00</pre>

On the refund page the Amount defaults to the amount of the payment. If only a partial refund is to be made then change this to the proper amount:

<pre>
Refund
Date 05/19/2015
Amount $10.00 by Credit card
Reason Package amount incorrect
</pre>

For this example we will only refund a part of the payment as illustrated above. It is usually a good idea to add a Reason that provides additional information for the refund.

Once you have the refund fields filled out click the Post refund button

This will unapply the payment from the invoice leaving the balance of the payment available for application to an invoice:

<pre>
05/19/2015 Open Invoice #228 (Balance 25.21) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 unapplied
(view receipt) (apply) (refund) (void) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

Use the apply link to apply the remaining payment to the invoice. This will bring up the Apply Payment window where you can select the invoice to apply the payment to:

<pre>
Payment #77
Date: 05/19/2015
Amount: $25.21
Unapplied amount: $15.21

Apply to:
Invoice: #228 - 05/19/2015 - $25.21
Amount: $15.21
</pre>

After you click the Apply button you are left with the original invoice with a balance due from the refunded payment:

<pre>
05/19/2015 Open Invoice #228 (Balance 10.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

To balance the invoice you can use the Enter Credit link to issue a credit that can be applied to the invoice:

<pre>
Enter Credit

Date 05/19/2015 10:03:26 AM
Amount $10.00
Reason Package Error
Additional info Credit for package error
Auto-apply to invoices yes
</pre>

When entering the credit you can select a credit reason that was previously defined at Configuration -> Billing -> Credit Reasons or you can create a reason on the fly.
You can also add a small note in the "Additional info" field which will print on the customers invoice. Please keept this short as long text will get truncated on PDF invoices to prevent formatting issues.

Once the credit is applied the customers account will be balanced out:

<pre>
05/19/2015 Invoice #228 (Balance 0.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
05/19/2015 Credit by nkennedy (Package Error Credit for package error) applied to Invoice #228 (05/19/15) (delete) (unapply) (void) - $10.00 $0.00
</pre>

If you need to have taxes calculated as part of the refund you can start with issuing a credit using the Credit line items link. This will allow you to select the line item on the invoice and enter the amount to credit that entry.
Follow the rest of the instructions for re-applying the payment to the invoice and the left over balance is the amount you need to use after following the refund link on the payment.

== Commissions ==


* Setting up [[Freeside:3:Documentation:Administration:Commission|Commissions and Referrals]]

== VoIP ==

* Setting up [[Freeside:3:Documentation:Administration:VoIP | VoIP]]
* [[Simple Bulk DID Orders]]
* [[Bulk DID Orders]]
* [[Freeside:3:Documentation:Administration:VoIP:e911|e911 Providers]]

== RADIUS ==

* Setting up [[Freeside:3.0:Documentation:Administration:FreeRadius | FreeRadius]]

== Torrus Network monitoring ==

* [[Freeside:3:Documentation:Torrus_Installation | Installation]]
* [[Freeside:3:Documentation:Torrus_Administration | Administration]]

== System Log ==

The system log can be viewed by navigating the main menu to: Report -> Logs -> System logs

Freeside can be configured to generate E-Mail notices for system log entries.

=== To configure E-Mail Notices ===

# Navigate the main menu to Configuration -> Miscellaneous -> System log emails
# Click the ''Add log email condition'' link
# Enter the E-Mail address to receive notices
# Specify the Log Context and Minimum Log Level to generate notices
# Choose if notices must match the specific chosen context
# Click the ``Add log emailcondition`` button

'''Only match most specific context:''' Selecting this check box reduces the number of E-Mail events for some contexts. Log events are hierarchical. A specific log event may have multiple contexts. A single event may be both a ''daily'' event, and also a ''Cron::upload'' event, for example. With this checkbox selected, the example event would only trigger an E-Mail notification for the ''Cron::upload'' context, and not the ''daily'' context.

Change or remove the E-Mail notice by selecting a notice within the ''Log email condition'' configuration page

== Old / uncommon ==

* Setting up [[Freeside:3:Documentation:Administration:Time billing | Time billing]]
* Using a non-standard [[Freeside:3:Documentation:Administration:PostgreSQL_Schema | PostgreSQL Schema]]
* Setting up [[Freeside:3:Documentation:Administration:Slony | Slony replication and failover]] (old - PostgreSQL native replication is a more current solution)

{{ContextSensitiveHelp}}

Freeside:4:Documentation:Administration:svc broadband.pm

2019-03-12T17:10:20Z

Mitch: Automatically assign IP addresses

= Broadband Services svc_broadband.pm =

[[Freeside:4:Documentation:Developer/FS/svc_broadband]]

== Automatically Assign IP Addresses ==

This guide describes how Freeside can automatically assign IP
addresses while provisioning services for a customer.

=== Create a Service Definition ===

In the main menu, navigate to: Configuration > Services > Service Definitions

Add a new service definition of the type '''svc_broadband''', choosing the default configuration options

Configure any exports you want for this service. Exporting to a RADIUS
server, for example, will allow RADIUS to provision hardware with the
assigned IP address.

=== Create a Router Definition ===

In the main menu, navigate to: Configuration > Services > Wireless Broadband > Routers > Add a new router

Leave the '''Assign IP addresses manually''' box unchecked

Under '''service types''', check the box for your Service Definition

=== Allocate an Address Block to the Router ===

In the main menu, navigate to: Configuration > Services > Wireless Broadband > Address Blocks

Enter a gateway and a netmask. For example, Gateway 10.0.0.1 and Netmask of 24.
Click the Add button.

Your new network should appear in the list of Address Blocks.

Click the '''allocate''' link for the address block. Choose your router, and
click the Apply Changes button.

=== Create a Package with this Service ===

In the main menu, navigate to: Configuration > Packages > Package Definitions

Add a new Package definition. In the '''Services''' section, include your svc_broadband Service in this Package.

=== Order Package and Provision ===

Order the new package for a customer. View the customer's '''Packages'''
tab. Click the link to Provision Service displayed on the Package.

The provisioning page allows you to select from which router/block to provision from. The hardware will be assigned the first available IP address within the selected network block.

==== Choose from available IP addresses ====

By default, an IP address is provisioned for the service automatically. If the selected netblock is size /24 or smaller, you may choose to select from a list of available IP addresses within that block.

By clicking on the down arrow button attached to the IP address input box, a list of available IP addresses is revealed. You may choose from this list, or allow Freeside to choose the first available IP address automatically. For network blocks larger than /24, this list would be quite large and will not be displayed.

Freeside:3:Documentation:Administration:Tax Districts

2019-01-30T06:58:00Z

Mitch: Link to v4 documentation for feature

See also: [[Freeside:4:Documentation:Administration:Tax_Districts]]

==Overview ==
Freeside currently supports billing taxes by district, instead of city/county/state. Currently this is only supported in the state of Washington. The information is pulled from the Washington Department of Revenue for updating customer records with tax districts while also updating the tax rates in the internal tax editor located at Configuration -> Billing -> Locales and tax rates.

== Setup ==

Configure option: tax_district_method, in Configuration -> Settings. Currently the only option is Washington sales tax.

The command freeside-tax-district-update will need to be ran. User should be replaced with a valid user in Freeside.

<pre>freeside-tax-district-update user</pre>

The command will update the 'district' field for all customers and service locations using an online tax information lookup method. Looking up the tax district will create a cust_main_county record with the tax rate for that district. All jobs are queued so their may be some delay before all records are modified.

== Updating tax rates ==

The script wa_tax_rate_update can be used to update taxes in the cust_main_county table.

Example usage:

<pre>wa_tax_rate_update -t "State Sales Tax" -c "Sales"</pre>

-t defines the tax name 
-c defines the tax class

This will download the new rates and upgrade the tax tables. You will need to do this for each tax class
you have setup in your system.

Freeside:4:Documentation:Administration:Tax Districts

2019-01-30T06:56:45Z

Mitch: Created page with "== Overview == Freeside supports billing taxes by district, instead of city/county/state. Currently this is only supported in the state of Washington. Public data sources pr..."

== Overview ==
Freeside supports billing taxes by district, instead of city/county/state.

Currently this is only supported in the state of Washington. Public data
sources provided by the Washington Dept. of Revenue are used to automatically
maintain tax rate tables, and classify customer locations into the correct
tax district.

== Setup ==

=== Enable Washington state sales tax districts ===

# Navigate to: Configuration > Settings
# Set option '''tax_district_method''' to '''Washington sales tax'''
# Set option '''tax_district_taxname''', the tax name to dsplay on the invoice, or keep the default as '''Tax'''
# Run '''freeside-daily''' or '''wa_tax_rate_update -l''' to populate tax tables, and classify customers into their districts

=== Download tax tables and classify customer tax districts ===

The WA tax tables will be automatically populated, and customers in WA will
be classified into their tax district he next time '''freeside-daily''' runs.

You don't have to wait for '''freeside-daily'''. The following command
will update the tax tables and classify WA customers into their tax district.

<pre>wa_tax_rate_update -l freeside_username</pre>

=== Changing Tax Name ===

You can change the display name for this tax by setting the config
option '''tax_district_taxname'''. After changing the configuration
value, the tax tables must be updated with the new taxname. This
will happen automatically on the 1st of each month. Use
'''wa_tax_rate_update''' to force this update sooner.

== Administration ==

=== Tax table updates ===

'''freeside-daily''' will refresh the tax tables automatically on the first
of each month.

Tax tables can be forcibly updated at any time using the
'''wa_tax_rate_update''' utility.

If freeside is configured to use tax classes, with the '''enable_taxclasses'''
configuration value, a complete copy of the Washington tax table will be
created in every taxclass. If new tax classes are added later, the
'''wa_tax_rate_update''' utility can be used to force an immediate rebuild
of the tax table into the new tax class.

To view the tax table, navigate to Configuration > Billing > Locales and Tax Rates

=== Customer tax district classification ===

When an address record is created or edited, Freeside will ask the WA Dept.
of Revenue API which tax district to use for the address.

If an invalid address is entereed, the tax district cannot be determined.
The user will be advised to correct the address, or to manually choose a
tax district to use.

Invoices cannot be generated for a WA customer missing a tax district.
When a customer is missing a tax district:
* A notice appears on the customer page with instructions to fix
* Billing will not complete for this customer
* Freeside will retry, daily, to determine the customer tax district
* System log notices are generated about this problem. Subscribe to E-Mail alerts of these notices.

The '''freeside-tax-district-update''' tool can be used to force reclassification
of every WA state address in cust_location. This may be useful if the state
re-draws district lines, and all customers need to be reclassified.

=== Configure system log alerts ===

If a customer location record in the database lacks a tax district,
freeside-daily will attempt to correct this situation. If that fails,
Freeside will report an error to the system log.

Freeside will report another error every time '''freeside-daily''' runs, for
every WA cust_location record without a tax district.

It is recommended to set two e-mail system log alerts:
1. log-level: error, log-context: wa_sales
2. log-level: error, log-context: tax_rate_update

Using log-level: info, somebody can be notified of all tax tables updates,
and every successful tax district classification for a cust_location record.

See [[Freeside:3:Documentation:Administration#System_Log]] for help
configuration system log alerts.

Freeside:3:Documentation:Administration

2018-10-28T04:20:03Z

Mitch: /* To configure E-Mail Notices */ typo

= 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:3:Documentation:Developer/bin/freeside-queued|freeside-queued]]. This daemon needs to be running before exports are acted upon.

Some exports use SSH, SCP or SFTP to communicate with external machines. See the documentation on [[Freeside:3:Documentation:Administration:SSH_Keys|SSH keys]].

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==
* [[Freeside:3: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:
* [[Freeside:3:Documentation:Administration:communigate_pro.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
* [[Freeside:3:Documentation:Administration:ldap.pm|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
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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:3:Documentation:Administration:opensrs.pm|opensrs.pm]]: OpenSRS integration
* sqlmail.pm: Real-time export to SQL-backed mail server

==svc_forward==
* artera_turbo.pm:
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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.
* [[Freeside:3: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.
* [[Freeside:3:Documentation:Administration:prizm.pm|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_phone==
* globalpops_voip.pm:
* grandstream.pm: Grandstream phone and ATA provisioning. This [http://www.freeside.biz/blog/?p=11 blog article] is a start at documentation.
* indosoft.pm:
* internal_diddb.pm:
* netsapiens.pm:
* phone_shellcommands.pm:
* phone_sqlradius.pm:
* thirdlane.pm:
* [[Freeside:Documentation:Administration:vitelity.pm|vitelity.pm]]: Vitelity provisioning

==svc_external==
* artera_turbo.pm:

==svc_dsl==
* ikano.pm: see [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

= Services =

== Generic ==

=== Accounts (svc_acct) ===

Accounts - anything with a username (mailbox, shell, RADIUS, etc.)

* [[Freeside:3:Documentation:Administration:svc_acct:_password_encoding|Password encoding]]

=== Hardware (svc_hardware) ===

Equipment supplied to customers

=== External (svc_external) ===

Externally-tracked service

== Access ==

=== DSL (svc_dsl) ===

* [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

=== Broadband (svc_broadband) ===

Fixed wireless broadband

=== Cable (svc_cable) ===

=== DISH Network (svc_dish) ===

== Telephony ==

=== Customer phone number / DID (svc_phone) ===

* [[Freeside:Documentation:Administration:Phone devices|Phone devices]]

=== Customer PBX (svc_pbx) ===

=== Phone circuit (svc_circuit) ===

== Hosting ==

=== Domains (svc_domain) ===

=== Certificate (svc_cert) ===

=== Forwards (svc_forward) ===

=== Mailing list (svc_mailinglist) ===

=== Site hosting (svc_www) ===

== Colocation ==

=== Customer router/switch port (svc_port) ===

= Packages =

{{Freeside:3:Documentation:Administration:pkg_category}}

== Price Plans ==

=== Common price plans ===

* flat
* subscription
* prorate
* sqlradacct_hour
* [[voip_cdr]]
* prepaid

=== Wholesale price plans ===

* bulk

* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:agent | agent]]
* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:cdr_termination |
cdr_termination ]]

=== 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:3:Documentation:Administration:Upselling | Upselling]]

= Resellers =

=== Wholesaler configuraiton ===
[[Freeside:3:Documentation:Administration:Wholesaler|Using agents for setting up Wholesalers]]

= Employees =

== 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.

Go to Configuration -> Ticketing -> Ticketing users
* Click on the Create link in the upper right hand corner
* Enter the same username as the Employee name above
* Enter any other information (Real name, Email address, etc. )
* Check both boxes in the access control box
* Click the Create button
(Be sure to add the ticketing user to the appropriate ticketing groups)

== 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.

= Installers / Appointments =

== Installers ==

* Designate some employees as installers (Configuration -> Employees -> Employees)
* Edit their schedules (Configuration -> Employees -> Installer availability)

== Ticketing ==

* Setup a queue for appointments (installations, removals, etc.), or use existing per agent queues
* Make sure the installer employees can own / see / edit tickets in this
queue (add them to a ticketing group with OwnTicket / SeeQueue on that queue or global, etc.)
* not yet <strike>XXX future todo some sort of ill-defined thing with configuring a custom field to designate install / recall / service call / removal</strike>

== Packages ==

not yet; package(+location)-specific appointments are a future TODO
<strike>
* Setup a package category for packages that can schedule appointments
* In the package category, select a queue for appointments or pick "Agent-specific queue"
</strike>

== Employee rights ==

* Upgrade should do this / should be available in a default install, but may not be implemented yet
* Give one or more employee groups "View appointments" and "Make appointment" (in Customer package rights)

= Billing =

== Billing events ==
Billing events are the primary mechanism to implement your business rules. Rules such as resend invoices, retry cards, suspend or cancel accounts for non-payment, etc. are all handled by billing events.

At a high level, follow the following steps to create billing events:
* Add a new Billing Event (Configuration > Billing > Billing events)
* Name the event
* Choose the type of event:
** Package - Packages and associated dates (Including Commissions)
** Invoice - Invoice status and dates
** Customer - Customer Balances and Information
** Batch Payment - Batch payment results
** Statement - Send statement
* Choose whether to apply to one or all agents
* Choose the frequency for the system to check and see if the event should run.
* Choose appropriate filters.
* Choose appropriate actions.

The form is dynamic so changing the type of event will change the available filters and actions.

== Daily and Monthly Scripts ==
* 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)
* Be sure to include the full path of freeside-daily in your cron job.

== Invoices ==

=== 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

==== 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: <code>epsffit -c 0 0 90 36 yourlogo.eps >logo.eps</code>
** ("no %%BoundingBox:" error? Fix with eps2eps)
* Upload the resized logo as the <code>logo.eps</code> configuration option.
* Problems? Try <code>bin/strip-eps <oldlogo.eps >trynewlogo.eps</code>

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.

{{Freeside:3:Documentation:Administration:invoice_layout}}

=== HTML invoice templates ===

* Convert your logo to PNG format and upload it as the <code>logo.png</code> configuration option.
{{Freeside:3:Documentation:Administration:invoice_templates|format=html}}

=== 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:3:Documentation:Template:invoice_html|invoice_html]]

=== Misc ===

==== Manually setting next customer number sequence ====

* With PostgreSQL, to number customers starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_main', 'custnum'), 4999);</pre>
* With MySQL, to number customers starting at 5000: <pre>ALTER TABLE cust_main AUTO_INCREMENT = 5000;</pre>

==== Manually setting next invoice number sequence ====

* With PostgreSQL, to number invoices starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_bill', 'invnum'), 4999);</pre>
* With MySQL, to number invoices starting at 5000: <pre>ALTER TABLE cust_bill AUTO_INCREMENT = 5000;</pre>

== Taxes ==

[[Freeside:3:Documentation:Administration:Tax_Districts | District based taxes]]

== Payment Receipts ==

The [[Freeside:3:Documentation:Template:payment_receipt_email|payment_receipt_email]] template is used for manually applied payments.

== Credit cards and Electronic checks ==
* [[Freeside:3:Documentation:Administration:Real-time_Processing | Real-time credit card and electronic check processing]]
* [[Freeside:3: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 =

These things should probably find a home properly filed in a section above.

== Invoicing and Payments ==

* Setting up [[Freeside:3:Documentation:Administration:Encrypted Credit Cards | Encrypted Credit Cards]] (default in new installs, highly recommended for older installs upgrading)
* Setting up [[Freeside:3:Documentation:Administration:Texas Tax | Texas Tax]]
* Need to print to Windows printers, and the PDF spool is not for you? Follow steps 1-4 of [http://iharder.sourceforge.net/current/macosx/winmacprinter/ Share Your Windows Printer].

== Refunds for automatic payments ==

A refund to an automatic payment can be made within the time limitation set by the payment gateway by using the refund link next to the payment:

<pre>05/19/2015 Payment by fs_queue (Credit card #411111xxxxxx1111) applied to Invoice #228 (05/19/15) (view receipt) (refund) (void) (unapply) - $24.60 $0.00</pre>

On the refund page the Amount defaults to the amount of the payment. If only a partial refund is to be made then change this to the proper amount:

<pre>
Refund
Date 05/19/2015
Amount $10.00 by Credit card
Reason Package amount incorrect
</pre>

For this example we will only refund a part of the payment as illustrated above. It is usually a good idea to add a Reason that provides additional information for the refund.

Once you have the refund fields filled out click the Post refund button

This will unapply the payment from the invoice leaving the balance of the payment available for application to an invoice:

<pre>
05/19/2015 Open Invoice #228 (Balance 25.21) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 unapplied
(view receipt) (apply) (refund) (void) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

Use the apply link to apply the remaining payment to the invoice. This will bring up the Apply Payment window where you can select the invoice to apply the payment to:

<pre>
Payment #77
Date: 05/19/2015
Amount: $25.21
Unapplied amount: $15.21

Apply to:
Invoice: #228 - 05/19/2015 - $25.21
Amount: $15.21
</pre>

After you click the Apply button you are left with the original invoice with a balance due from the refunded payment:

<pre>
05/19/2015 Open Invoice #228 (Balance 10.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

To balance the invoice you can use the Enter Credit link to issue a credit that can be applied to the invoice:

<pre>
Enter Credit

Date 05/19/2015 10:03:26 AM
Amount $10.00
Reason Package Error
Additional info Credit for package error
Auto-apply to invoices yes
</pre>

When entering the credit you can select a credit reason that was previously defined at Configuration -> Billing -> Credit Reasons or you can create a reason on the fly.
You can also add a small note in the "Additional info" field which will print on the customers invoice. Please keept this short as long text will get truncated on PDF invoices to prevent formatting issues.

Once the credit is applied the customers account will be balanced out:

<pre>
05/19/2015 Invoice #228 (Balance 0.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
05/19/2015 Credit by nkennedy (Package Error Credit for package error) applied to Invoice #228 (05/19/15) (delete) (unapply) (void) - $10.00 $0.00
</pre>

If you need to have taxes calculated as part of the refund you can start with issuing a credit using the Credit line items link. This will allow you to select the line item on the invoice and enter the amount to credit that entry.
Follow the rest of the instructions for re-applying the payment to the invoice and the left over balance is the amount you need to use after following the refund link on the payment.

== Commissions ==


* Setting up [[Freeside:3:Documentation:Administration:Commission|Commissions and Referrals]]

== VoIP ==

* Setting up [[Freeside:3:Documentation:Administration:VoIP | VoIP]]
* [[Simple Bulk DID Orders]]
* [[Bulk DID Orders]]
* [[Freeside:3:Documentation:Administration:VoIP:e911|e911 Providers]]

== RADIUS ==

* Setting up [[Freeside:3.0:Documentation:Administration:FreeRadius | FreeRadius]]

== Torrus Network monitoring ==

* [[Freeside:3:Documentation:Torrus_Installation | Installation]]
* [[Freeside:3:Documentation:Torrus_Administration | Administration]]

== System Log ==

The system log can be viewed by navigating the main menu to: Report -> Logs -> System logs

Freeside can be configured to generate E-Mail notices for system log entries.

=== To configure E-Mail Notices ===

# Navigate the main menu to Configuration -> Miscellaneous -> System log emails
# Click the ''Add log email condition'' link
# Enter the E-Mail address to receive notices
# Specify the Log Context and Minimum Log Level to generate notices
# Choose if notices must match the specific chosen context
# Click the ``Add log emailcondition`` button

'''Only match most specific context:''' Selecting this check box reduces the number of E-Mail events for some contexts. Log events are hierarchical. A specific log event may have multiple contexts. A single event may be both a ''daily'' event, and also a ''Cron::upload'' event, for example. With this checkbox selected, the example event would only trigger an E-Mail notification for the ''Cron::upload'' context, and not the ''daily'' context.

Change or remove the E-Mail notice by selecting a notice within the ''Log email condition'' configuration page

== Old / uncommon ==

* Setting up [[Freeside:3:Documentation:Administration:Time billing | Time billing]]
* Using a non-standard [[Freeside:3:Documentation:Administration:PostgreSQL_Schema | PostgreSQL Schema]]
* Setting up [[Freeside:3:Documentation:Administration:Slony | Slony replication and failover]] (old - PostgreSQL native replication is a more current solution)

{{ContextSensitiveHelp}}

Freeside:3:Documentation:Administration

2018-10-28T04:16:41Z

Mitch: System Log, Log E-Mail Notices

= 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:3:Documentation:Developer/bin/freeside-queued|freeside-queued]]. This daemon needs to be running before exports are acted upon.

Some exports use SSH, SCP or SFTP to communicate with external machines. See the documentation on [[Freeside:3:Documentation:Administration:SSH_Keys|SSH keys]].

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==
* [[Freeside:3: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:
* [[Freeside:3:Documentation:Administration:communigate_pro.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
* [[Freeside:3:Documentation:Administration:ldap.pm|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
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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:3:Documentation:Administration:opensrs.pm|opensrs.pm]]: OpenSRS integration
* sqlmail.pm: Real-time export to SQL-backed mail server

==svc_forward==
* artera_turbo.pm:
* [[Freeside:3:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* 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.
* [[Freeside:3: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.
* [[Freeside:3:Documentation:Administration:prizm.pm|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_phone==
* globalpops_voip.pm:
* grandstream.pm: Grandstream phone and ATA provisioning. This [http://www.freeside.biz/blog/?p=11 blog article] is a start at documentation.
* indosoft.pm:
* internal_diddb.pm:
* netsapiens.pm:
* phone_shellcommands.pm:
* phone_sqlradius.pm:
* thirdlane.pm:
* [[Freeside:Documentation:Administration:vitelity.pm|vitelity.pm]]: Vitelity provisioning

==svc_external==
* artera_turbo.pm:

==svc_dsl==
* ikano.pm: see [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

= Services =

== Generic ==

=== Accounts (svc_acct) ===

Accounts - anything with a username (mailbox, shell, RADIUS, etc.)

* [[Freeside:3:Documentation:Administration:svc_acct:_password_encoding|Password encoding]]

=== Hardware (svc_hardware) ===

Equipment supplied to customers

=== External (svc_external) ===

Externally-tracked service

== Access ==

=== DSL (svc_dsl) ===

* [[Freeside:3:Documentation:Administration:svc_dsl:ikano|Ikano DSL provisioning and qualifications]]

=== Broadband (svc_broadband) ===

Fixed wireless broadband

=== Cable (svc_cable) ===

=== DISH Network (svc_dish) ===

== Telephony ==

=== Customer phone number / DID (svc_phone) ===

* [[Freeside:Documentation:Administration:Phone devices|Phone devices]]

=== Customer PBX (svc_pbx) ===

=== Phone circuit (svc_circuit) ===

== Hosting ==

=== Domains (svc_domain) ===

=== Certificate (svc_cert) ===

=== Forwards (svc_forward) ===

=== Mailing list (svc_mailinglist) ===

=== Site hosting (svc_www) ===

== Colocation ==

=== Customer router/switch port (svc_port) ===

= Packages =

{{Freeside:3:Documentation:Administration:pkg_category}}

== Price Plans ==

=== Common price plans ===

* flat
* subscription
* prorate
* sqlradacct_hour
* [[voip_cdr]]
* prepaid

=== Wholesale price plans ===

* bulk

* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:agent | agent]]
* [[Freeside:3:Documentation:Administration:Packages:Price_Plans:cdr_termination |
cdr_termination ]]

=== 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:3:Documentation:Administration:Upselling | Upselling]]

= Resellers =

=== Wholesaler configuraiton ===
[[Freeside:3:Documentation:Administration:Wholesaler|Using agents for setting up Wholesalers]]

= Employees =

== 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.

Go to Configuration -> Ticketing -> Ticketing users
* Click on the Create link in the upper right hand corner
* Enter the same username as the Employee name above
* Enter any other information (Real name, Email address, etc. )
* Check both boxes in the access control box
* Click the Create button
(Be sure to add the ticketing user to the appropriate ticketing groups)

== 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.

= Installers / Appointments =

== Installers ==

* Designate some employees as installers (Configuration -> Employees -> Employees)
* Edit their schedules (Configuration -> Employees -> Installer availability)

== Ticketing ==

* Setup a queue for appointments (installations, removals, etc.), or use existing per agent queues
* Make sure the installer employees can own / see / edit tickets in this
queue (add them to a ticketing group with OwnTicket / SeeQueue on that queue or global, etc.)
* not yet <strike>XXX future todo some sort of ill-defined thing with configuring a custom field to designate install / recall / service call / removal</strike>

== Packages ==

not yet; package(+location)-specific appointments are a future TODO
<strike>
* Setup a package category for packages that can schedule appointments
* In the package category, select a queue for appointments or pick "Agent-specific queue"
</strike>

== Employee rights ==

* Upgrade should do this / should be available in a default install, but may not be implemented yet
* Give one or more employee groups "View appointments" and "Make appointment" (in Customer package rights)

= Billing =

== Billing events ==
Billing events are the primary mechanism to implement your business rules. Rules such as resend invoices, retry cards, suspend or cancel accounts for non-payment, etc. are all handled by billing events.

At a high level, follow the following steps to create billing events:
* Add a new Billing Event (Configuration > Billing > Billing events)
* Name the event
* Choose the type of event:
** Package - Packages and associated dates (Including Commissions)
** Invoice - Invoice status and dates
** Customer - Customer Balances and Information
** Batch Payment - Batch payment results
** Statement - Send statement
* Choose whether to apply to one or all agents
* Choose the frequency for the system to check and see if the event should run.
* Choose appropriate filters.
* Choose appropriate actions.

The form is dynamic so changing the type of event will change the available filters and actions.

== Daily and Monthly Scripts ==
* 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)
* Be sure to include the full path of freeside-daily in your cron job.

== Invoices ==

=== 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

==== 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: <code>epsffit -c 0 0 90 36 yourlogo.eps >logo.eps</code>
** ("no %%BoundingBox:" error? Fix with eps2eps)
* Upload the resized logo as the <code>logo.eps</code> configuration option.
* Problems? Try <code>bin/strip-eps <oldlogo.eps >trynewlogo.eps</code>

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.

{{Freeside:3:Documentation:Administration:invoice_layout}}

=== HTML invoice templates ===

* Convert your logo to PNG format and upload it as the <code>logo.png</code> configuration option.
{{Freeside:3:Documentation:Administration:invoice_templates|format=html}}

=== 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:3:Documentation:Template:invoice_html|invoice_html]]

=== Misc ===

==== Manually setting next customer number sequence ====

* With PostgreSQL, to number customers starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_main', 'custnum'), 4999);</pre>
* With MySQL, to number customers starting at 5000: <pre>ALTER TABLE cust_main AUTO_INCREMENT = 5000;</pre>

==== Manually setting next invoice number sequence ====

* With PostgreSQL, to number invoices starting at 5000: <pre>SELECT SETVAL(pg_get_serial_sequence('cust_bill', 'invnum'), 4999);</pre>
* With MySQL, to number invoices starting at 5000: <pre>ALTER TABLE cust_bill AUTO_INCREMENT = 5000;</pre>

== Taxes ==

[[Freeside:3:Documentation:Administration:Tax_Districts | District based taxes]]

== Payment Receipts ==

The [[Freeside:3:Documentation:Template:payment_receipt_email|payment_receipt_email]] template is used for manually applied payments.

== Credit cards and Electronic checks ==
* [[Freeside:3:Documentation:Administration:Real-time_Processing | Real-time credit card and electronic check processing]]
* [[Freeside:3: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 =

These things should probably find a home properly filed in a section above.

== Invoicing and Payments ==

* Setting up [[Freeside:3:Documentation:Administration:Encrypted Credit Cards | Encrypted Credit Cards]] (default in new installs, highly recommended for older installs upgrading)
* Setting up [[Freeside:3:Documentation:Administration:Texas Tax | Texas Tax]]
* Need to print to Windows printers, and the PDF spool is not for you? Follow steps 1-4 of [http://iharder.sourceforge.net/current/macosx/winmacprinter/ Share Your Windows Printer].

== Refunds for automatic payments ==

A refund to an automatic payment can be made within the time limitation set by the payment gateway by using the refund link next to the payment:

<pre>05/19/2015 Payment by fs_queue (Credit card #411111xxxxxx1111) applied to Invoice #228 (05/19/15) (view receipt) (refund) (void) (unapply) - $24.60 $0.00</pre>

On the refund page the Amount defaults to the amount of the payment. If only a partial refund is to be made then change this to the proper amount:

<pre>
Refund
Date 05/19/2015
Amount $10.00 by Credit card
Reason Package amount incorrect
</pre>

For this example we will only refund a part of the payment as illustrated above. It is usually a good idea to add a Reason that provides additional information for the refund.

Once you have the refund fields filled out click the Post refund button

This will unapply the payment from the invoice leaving the balance of the payment available for application to an invoice:

<pre>
05/19/2015 Open Invoice #228 (Balance 25.21) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 unapplied
(view receipt) (apply) (refund) (void) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

Use the apply link to apply the remaining payment to the invoice. This will bring up the Apply Payment window where you can select the invoice to apply the payment to:

<pre>
Payment #77
Date: 05/19/2015
Amount: $25.21
Unapplied amount: $15.21

Apply to:
Invoice: #228 - 05/19/2015 - $25.21
Amount: $15.21
</pre>

After you click the Apply button you are left with the original invoice with a balance due from the refunded payment:

<pre>
05/19/2015 Open Invoice #228 (Balance 10.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
</pre>

To balance the invoice you can use the Enter Credit link to issue a credit that can be applied to the invoice:

<pre>
Enter Credit

Date 05/19/2015 10:03:26 AM
Amount $10.00
Reason Package Error
Additional info Credit for package error
Auto-apply to invoices yes
</pre>

When entering the credit you can select a credit reason that was previously defined at Configuration -> Billing -> Credit Reasons or you can create a reason on the fly.
You can also add a small note in the "Additional info" field which will print on the customers invoice. Please keept this short as long text will get truncated on PDF invoices to prevent formatting issues.

Once the credit is applied the customers account will be balanced out:

<pre>
05/19/2015 Invoice #228 (Balance 0.00) (void)
( View invoice events ) $25.21 $25.21
05/19/2015 Payment by nkennedy (Credit card #411111xxxxxx1111)
10.00 refunded on 05/19/2015
15.21 applied to Invoice #228 (05/19/15)
(view receipt) (refund) (void) (unapply) - $25.21 $0.00
05/19/2015 Refund by nkennedy (Credit card #411111xxxxxx1111) (view receipt) $10.00 $10.00
05/19/2015 Credit by nkennedy (Package Error Credit for package error) applied to Invoice #228 (05/19/15) (delete) (unapply) (void) - $10.00 $0.00
</pre>

If you need to have taxes calculated as part of the refund you can start with issuing a credit using the Credit line items link. This will allow you to select the line item on the invoice and enter the amount to credit that entry.
Follow the rest of the instructions for re-applying the payment to the invoice and the left over balance is the amount you need to use after following the refund link on the payment.

== Commissions ==


* Setting up [[Freeside:3:Documentation:Administration:Commission|Commissions and Referrals]]

== VoIP ==

* Setting up [[Freeside:3:Documentation:Administration:VoIP | VoIP]]
* [[Simple Bulk DID Orders]]
* [[Bulk DID Orders]]
* [[Freeside:3:Documentation:Administration:VoIP:e911|e911 Providers]]

== RADIUS ==

* Setting up [[Freeside:3.0:Documentation:Administration:FreeRadius | FreeRadius]]

== Torrus Network monitoring ==

* [[Freeside:3:Documentation:Torrus_Installation | Installation]]
* [[Freeside:3:Documentation:Torrus_Administration | Administration]]

== System Log ==

The system log can be viewed by navigating the main menu to: Report -> Logs -> System logs

Freeside can be configured to generate E-Mail notices for system log entries.

=== To configure E-Mail Notices ===

# Navigate the main menu to Configuration -> Miscellaneous -> System log emails
# Click the ''Add log email condition'' link
# Enter the E-Mail address to receive notices
# Specify the Log Context and Minimum Log Level to generate notices
# Choose if notices must match the specific chosen context
# Click the ``Add log emailcondition`` button

'''Only match most specific contex:''' Selecting this check box reduces the number of E-Mail events for some contexts. Log events are hierarchical. A specific log event may have multiple contexts. A single event may be both a ''daily'' event, and also a ''Cron::upload'' event, for example. With this checkbox selected, the example event would only trigger an E-Mail notification for the ''Cron::upload'' context, and not the ''daily'' context.

Change or remove the E-Mail notice by selecting a notice within the ''Log email condition'' configuration page

== Old / uncommon ==

* Setting up [[Freeside:3:Documentation:Administration:Time billing | Time billing]]
* Using a non-standard [[Freeside:3:Documentation:Administration:PostgreSQL_Schema | PostgreSQL Schema]]
* Setting up [[Freeside:3:Documentation:Administration:Slony | Slony replication and failover]] (old - PostgreSQL native replication is a more current solution)

{{ContextSensitiveHelp}}