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

From Freeside
Jump to: navigation, search
(→‎Misc)
(→‎Resellers)
 
(6 intermediate revisions by 2 users not shown)
Line 113: Line 113:
  
 
Fixed wireless 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) ===
 
=== Cable (svc_cable) ===
Line 193: Line 196:
  
 
* Some notes on [[Freeside:3:Documentation:Administration:Upselling | Upselling]]
 
* Some notes on [[Freeside:3:Documentation:Administration:Upselling | Upselling]]
 +
 +
= Customers =
 +
 +
== Address normalization ==
 +
 +
* Census Bureau - free, no account needed. To use, go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "U.S. Census Bureau".
 +
 +
* Postal Service - free, account required.  To use, go http://www.usps.com/webtools/ register and agree not to use the API for batch purposes.  Then, go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "U.S. Postal Serivce", and set "usps_webtools-userid" and "usps_webtools-password" to your credentials.
 +
 +
* Melissa WebSmart - paid commercial service.  http://www.melissadata.com/  To use, after purchasing an account from MelissaData,go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "Melissa WebSmart", and set "melissa-userid" to your credentials.  Optionally, "melissa-enable_geocoding" may be turned on to use Melissa for geolocation and census coding as well, instead of the default free services.
  
 
= Resellers =
 
= Resellers =
 +
 +
=== Wholesaler configuration ===
 +
[[Freeside:3:Documentation:Administration:Wholesaler|Using agents for setting up Wholesalers]]
  
 
= Employees =
 
= Employees =
Line 207: Line 223:
 
* Check the "Disable employee" box to disable this employee.
 
* 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.
 
* 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 ==  
 
== Employee groups and access control ==  
Line 350: Line 374:
 
* Setting up [[Freeside:3:Documentation:Administration:Texas Tax | Texas Tax]]
 
* 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].
 
* 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 ==
 
== Commissions ==
Line 371: Line 482:
 
* [[Freeside:3:Documentation:Torrus_Installation | Installation]]
 
* [[Freeside:3:Documentation:Torrus_Installation | Installation]]
 
* [[Freeside:3:Documentation:Torrus_Administration | Administration]]
 
* [[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 ==
 
== Old / uncommon ==

Latest revision as of 14:48, 10 November 2022

Contents

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.

Some exports use SSH, SCP or SFTP to communicate with external machines. See the documentation on 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

  • 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
  • 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
  • opensrs.pm: OpenSRS integration
  • sqlmail.pm: Real-time export to SQL-backed mail server

svc_forward

  • artera_turbo.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.
  • 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_phone

  • globalpops_voip.pm:
  • grandstream.pm: Grandstream phone and ATA provisioning. This blog article is a start at documentation.
  • indosoft.pm:
  • internal_diddb.pm:
  • netsapiens.pm:
  • phone_shellcommands.pm:
  • phone_sqlradius.pm:
  • thirdlane.pm:
  • vitelity.pm: Vitelity provisioning

svc_external

  • artera_turbo.pm:

svc_dsl

Services

Generic

Accounts (svc_acct)

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

Hardware (svc_hardware)

Equipment supplied to customers

External (svc_external)

Externally-tracked service

Access

DSL (svc_dsl)

Broadband (svc_broadband)

Fixed wireless broadband

Cable (svc_cable)

DISH Network (svc_dish)

Telephony

Customer phone number / DID (svc_phone)

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

Package Category

Package categories define groups of package classes.

Category name
defines an invoice section if that feature is enabled.
Weight
determines the order in which invoice_sections appear.
Collapse identical items into one
causes identical packages to appear folded into a single line item with a quantity when checked rather than the default once line item per package.

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

Customers

Address normalization

  • Census Bureau - free, no account needed. To use, go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "U.S. Census Bureau".
  • Postal Service - free, account required. To use, go http://www.usps.com/webtools/ register and agree not to use the API for batch purposes. Then, go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "U.S. Postal Serivce", and set "usps_webtools-userid" and "usps_webtools-password" to your credentials.
  • Melissa WebSmart - paid commercial service. http://www.melissadata.com/ To use, after purchasing an account from MelissaData,go to Configuration -> Settings, in the "UI" section, and set "address_standardize_method" to "Melissa WebSmart", and set "melissa-userid" to your credentials. Optionally, "melissa-enable_geocoding" may be turned on to use Melissa for geolocation and census coding as well, instead of the default free services.

Resellers

Wholesaler configuration

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 XXX future todo some sort of ill-defined thing with configuring a custom field to designate install / recall / service call / removal

Packages

not yet; package(+location)-specific appointments are a future TODO

  • Setup a package category for packages that can schedule appointments
  • In the package category, select a queue for appointments or pick "Agent-specific queue"

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: 
      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)
  • 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 Ghostscript (gs)
  • Install teTeX or TeX Live
  • Ensure that the pslatex, dvips, and pdflatex 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: epsffit -c 0 0 90 36 yourlogo.eps >logo.eps
    • ("no %%BoundingBox:" error? Fix with eps2eps)
  • Upload the resized logo as the logo.eps configuration option.
  • 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.

Invoice Layout and Content

Basic Invoice Styles

Several variables make significant changes to the appearance of invoices.

invoice_sections
enables the division of invoices into sections defined by package categories
package categories must be setup for this to work properly
invoice_sections_method
Section the invoices based on location, instead of package category.

With sectionsWithout sections

invoice_usesummary
Indicates that html and latex invoices should be in summary style and make use of invoice_latexsummary or invoice_htmlsummary.
summary_subtotals_method
Defines what information to use when displaying summaries on invoices. Locations and package categories currently supported.

With summaryWithout summary

usage_class_as_a_section
enables the construction of a section per usage_class on invoices

Usage class as a section

svc_phone_sections
enables the creation of a section for each svc_phone

svc_phone sections

Invoice Templates

  • {{#ifeq: latex | latex | LaTeX | HTML }} invoices use Text::Template with {{#ifeq: latex | latex | [@-- and --@] | <%= and %> }} delimiters.
  • {{#ifeq: latex | latex | Edit the invoice_latexcoupon, | The following can be set to override the default behaviour of using the invoice_latex* data transformed to HTML: }} invoice_latexreturnaddress, invoice_latexfooter, invoice_latexnotes, and invoice_latexsmallfooter configuration options. {{#ifeq: latex | latex | If you are adventurous, | You may }} edit invoice_latex as well.

Common VOIP plan options for invoice appearance

Certain configuration options on telephony plan packages can have significant impact on the appearances of invoices by changing the data calculated and stored at the time of invoice generation.


CDR invoice display format [output_format]
controls the data stored for the usage detail on the invoice. Current choices are
 default                   - date, time, destination, regionname, duration, price
 default with source       - source, date, time, destination, regionname, duration, price
 default with account code - date, time, account code, destination, regionname, duration, price
 simple                    - date, time, user, destination, duration, price
 simple with source        - date, time, source, destination, duration, price
Section in which to place usage charges (whether separated or not) [usage_section]
names an invoice section which is to contain the usage portion of the invoiced package. If the section is to be included in a summary page then you will need to ensure the spelling exactly matches a package category
Include usage summary with recurring charges when usage is in separate section [summarize_usage]
creates an additional (2nd) line on the invoice showing the total usage associated with the package. Typically appears below a 'setup' and 'recurring' line (if they exist).
Always put usage details in separate section [usage_mandate]
causes freeside to generate an extra section for the usage details even when freeside is not using invoice sections. Make sure to also set the section (usage_section) you want the CDR's to go into.

Other Variables Changing Invoice Layout at Billing Time

separate_usage
controls the splitting of the setup, recurring, and usage components of packages into separate line items at generation time. It is one of two mechanisms which cause one or more separate 'Usage' lines to appear for each package. The other is the usage_mandate on a telephony price plan.

Variables Neither Perfectly Rendering nor Perfectly Generational

date_format
describes the appearance of dates

Usage is not universal and in some instances date format may be frozen when data is stored in the database.

money_char
defines the symbol to be used for currency in many locations

Usage is not universal and may in some instances be stored permanently in the database.

invoice_default_terms
declares the default payment terms for invoices

When this setting is changed, invoices which were not defaulted will retain their old value.

Boolean Rendering Variables

invoice_show_prior_due_date
Show previous invoice due dates when showing prior balances. Default is to show invoice date.
invoice_include_aging
Show an aging line after the prior balance section. Only valid when invoice_sections is enabled.
invoice_smallernotes
Display the notes section in a smaller font on invoices.
invoice_smallerfooter
Display footers in a smaller font on invoices.
invoice-ship_address
Include the shipping address on invoices.
invoice-all_pkg_addresses
Show all package addresses on invoices, even the default.
disable_line_item_date_ranges
Prevent freeside from automatically generating date ranges on invoice line items.
disable_previous_balance
Disable inclusion of previous balance, payment, and credit lines on invoices.
previous_balance-summary_only
Only show a single line summarizing the total previous balance rather than one line per invoice.
balance_due_below_line
Place the balance due message below a line. Only meaningful when when invoice_sections is false.
invoice-unitprice
enables a quantity (qty) field for quick charges, but otherwise only changes the rendering with the addition of qty and unit price columns on invoices

Freeside:Configuration:previous balance-section

Other Rendering Variables

invoice_latextopmargin
Optional LaTeX invoice topmargin setting. Include units.
invoice_latexheadsep
Optional LaTeX invoice headsep setting. Include units.
invoice_latexaddresssep
Optional LaTeX invoice separation between invoice data and the 'to' address (usually invoice_latexreturnaddress). Include units.
invoice_latextextheight
Optional LaTeX invoice textheight setting. Include units.
invoice_latexextracouponspace
Optional LaTeX invoice textheight space to reserve for a tear off coupon. Include units.
invoice_latexcouponfootsep
Optional LaTeX invoice separation between tear off coupon and footer. Include units.
invoice_latexcouponamountenclosedsep
Optional LaTeX invoice separation between total due and amount enclosed line. Include units.
invoice_latexcoupontoaddresssep
Optional LaTeX invoice separation between invoice data and the 'to' address (usually invoice_latexreturnaddress). Include units.
invoice_latexverticalreturnaddress
Place the return address under the company logo rather than beside it.
invoice_latexcouponaddcompanytoaddress
Add the company name to the 'To' address on the remittance coupon because the return address does not contain it.
previous_balance-exclude_from_total
Do not include previous balance in the 'Total' line. Only meaningful when invoice_sections is false. Optionally provide text to override the 'Total New Charges' description.
company_name
Your company name.
company_address
Your company address.
finance_pkgclass
The default package class for late fee charges, used if the fee event does not specify a package class itself. Also used to determine which invoice_section is the finance section of the invoice.
cust_bill-max_same_services
Maximum number of the same service to list individually on invoices before condensing to a single line listing the number of services. Defaults to 5.
cust_bill-consolidate_services
Consolidate service display into fewer lines on invoices rather than one per service.

Miscellaneous Variables Impacting Customer Perception of Invoices

These variables do not change the invoice per se, but do change what is emailed to a customer as an invoice.

invoice_email_pdf
Send PDF invoice as an attachment to emailed invoices. By default, includes the plain text invoice as the email body, unless invoice_email_pdf_note is set.
invoice_email_pdf_note
If defined, this text will replace the default plain text invoice as the body of emailed PDF invoices.
voip-cust_email_csv_cdr
Enable the per-customer option for including CDR information as a CSV attachment on emailed invoices.

HTML invoice templates

  • Convert your logo to PNG format and upload it as the logo.png configuration option.
  • {{#ifeq: html | latex | LaTeX | HTML }} invoices use Text::Template with {{#ifeq: html | latex | [@-- and --@] | <%= and %> }} delimiters.
  • {{#ifeq: html | latex | Edit the invoice_htmlcoupon, | The following can be set to override the default behaviour of using the invoice_latex* data transformed to HTML: }} invoice_htmlreturnaddress, invoice_htmlfooter, invoice_htmlnotes, and invoice_htmlsmallfooter configuration options. {{#ifeq: html | latex | If you are adventurous, | You may }} edit invoice_html as well.

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 customer number sequence

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

Manually setting next invoice number sequence

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

Taxes

District based taxes

Payment Receipts

The payment_receipt_email template is used for manually applied payments.

Credit cards and Electronic checks

Misc

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

Invoicing and Payments

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: 

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

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: 

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

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: 

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

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: 

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

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

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

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

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

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: 

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

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

VoIP

RADIUS

Torrus Network monitoring

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

  1. Navigate the main menu to Configuration -> Miscellaneous -> System log emails
  2. Click the Add log email condition link
  3. Enter the E-Mail address to receive notices
  4. Specify the Log Context and Minimum Log Level to generate notices
  5. Choose if notices must match the specific chosen context
  6. 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

This page is part of the Freeside Context Sensitive Help. Please review the Editing Guidelines before making modifications to this page.
Retrieved from "https://secure.freeside.biz/mediawiki/index.php?title=Freeside:3:Documentation:Administration&oldid=9834"