Introduction
This is an unofficial administrators guide to Freeside, it is a work in progress and will be updated as time allows. I call it unofficial because this guide is in no way tied to Freeside Internet Services, Inc., though it is in reference to the software they create.
Though some of this guide comes from work I have done for customers a good portion of it is being written on my own time. If you find this guide helpful I would greatly appreciate it if you could show your support with a donation.
The goal of this guide is to provide a comprehensive document for configuring Freeside to suit your businesses needs. The scope of this guide is just on administrative tasks and a usage guide will be in the works very soon.
Table of Contents
Initial Configuration after Installation
After your installation is finished there are some important settings that you should review and change to suit your needs.
Log into Freeside and then over your mouse over the Configuration menu and click on Settings.
To edit a setting you will need to click on the name of the setting which opens a box to choose an option or enter text, in some cases, there are additional instructions as well.
Each section below corresponds to a section in the settings. This is just a general overview of what should be reviewed to get the system ready for live billing.
Important
invoice_from: Enter the default email address that will be used for sending invoices and notices.
smtpmachine: Enter the outgoing SMTP server that will be used for sending all invoices and notices (this does not have any effect on ticketing)
company_name: Enter your company name as it should show up on invoices, notices, and the UI
company_address: Enter your companies address as it should appear on invoices
company_phonenum: Enter the phone number that should be displayed on invoices and can be used as a variable in message templates
logo.png: Upload your company logo that will be used in the UI and HTML invoices. This logo should be small, around 92×62 pixels as noted in the setting instructions, as larger logos will skew the display of HTML invoices.
Billing
cust_main-select-prorate_day: This option can be very helpful if you have customers that need to change the date their invoices are generated on or if a customer orders new packages between billing cycles and you want everything to bill on the same day.
anniversary-rollback: Freeside will not allow packages to have a bill date of the 29th, 30th, or 31st of the month. By default, it will adjust the billing date forward to the 1st if a package is ordered on these days. If this setting is enabled it will instead roll the date back to the 28th so the billing will start in the month that the package was ordered.
next-bill-ignore-time: This setting should be enabled unless you are using one of the real-time billing package price plans, this is extremely rare and I don’t believe I have ever encountered a customer that uses them.
Without this setting enabled you could run into issues where a customer appears to be billing a day late because their package timestamp is after the time you are running the freeside-daily script.
Payments
cust_main-select-billday: This setting is very handy when you need to have customers that prefer to have their payment charged on a different day than when their invoice is created.
In order to make use of this setting, you will need to use the billing event condition “Customer’s monthly billing day is before or on current day or customer has no billing day”. This condition should be added to your payment and any late fee, notice, and suspension events.
payby: Set the available payment types. Be sure to select the blank one at the top or you will not be able to add customers that do not have a checking or credit card on file.
realtime-disable_payby: If you are using a payment batch for submitting ACH or Credit Card payments you will need to set those payment types in this setting so they will not be processed by the real-time billing system.
This is mostly used in Canada and other regions where electronic check processing is not available through Internet gateways.
Credit Cards
credit-card-surcharge-percentage: This allows you to add a surcharge when processing credit card payments using the real-time billing system.
Be sure to check with your payment processor to make sure this is set within their rules.
encryption: This is enabled by default and should be left so as it will encrypt the credit card data that gets stored in the database.
business-onlinepayment: This setting holds the information needed to process payments through an online payment gateway such as IPPay or Authorize.Net, a full list of supported gateways can be found at [http://perl.business/onlinepayment/ http://perl.business/onlinepayment/].
Before adding your gateway you will need to install the appropriate perl modules. A lot of these are available through the Freeside repository and can be found by searching in aptitude. If your module is not listed then download the source from the link above and compile it locally, do not install it using cpan as this could add unsupported Perl libraries to your Freeside server which could cause other issues.
When entering your information the first entry is the gateway name which should match the payment modules name, for example, ippay is IPPay and Authorize.Net is AuthroizeNet.
You can get the exact requirements for this setting by looking at the Perl module for your payment gateway and in the documentation, it should list what you need.
business-onlinepayment-test_transaction: If your gateway has a test server you can enable this setting to run test transactions while you are getting things configured. Be sure to disable this when you are ready to process live transactions.
card-types: If you want to limit the types of cards customers can use you can select them here.
card_masking_method: Be sure to set this to your needs as early as possible as changing this after you have been processing payments for some time will have very undesirable effects. Also be sure not to choose a masking method that removes the numbers used to identify the card type as this can prevent the card type from showing up in some reports.
Taxation
enable_taxclasses: Tax classes allow you to setup different groups of taxes for the same region and packages in those classes will be charged the appropriate taxes.
In most cases this is not needed unless you are offering VoIP and other services where some will require you to charge Federal/State USF/Voice taxes on your VoIP usage but not on other services.
require_taxclasses: If you have enabled tax classes you should enable this as well to make sure each package is assigned a tax class.
tax-ship_address: If you have customers that are billed in a different place than where their service is you should enable this setting and the taxes will be matched based on the shipping address instead of the default billing address.
tax-pkg_address: If you have customers that have packages in multiple locations and each has different taxation requirements then enable this setting and leave tax-ship_address disabled.
Packages
part_pkg-lineage: Do not enable this EVER! This had interesting intentions but I have never seen a situation where this did not cause major issues and create an extreme amount of bloat.
part_pkg-show_fcc_options: If you will need to file FCC form 477 you should enable this setting so you can set the appropriate options in your packages.
This also requires enabling access to the FCC options in your employee groups.
part_pkg-term_discounts: Do not enable this, it will not do what you think and as the text says it is not well optimized.
Printing
invoice_print_pdf: This is very useful and should be left enabled.
lpr: If you will be printing invoices directly from Freeside this should be set to the proper command. It is highly recommended that you set up your printer using CUPs as this will spool the print jobs and provide better error handling when there is a problem, like a printer running out of paper.
There are instructions floating about on how to use another printing processor called rlpr, do not use this as it has compatibility issues with just about every modern printer on the market.
logo.eps: Be sure to set this to your logo and that the logo is not larger than 1.9cm squared or it could cause invoice elements to be displaced.
Invoicing
discount-show-always: This allows packages that have been discounted for the entire amount of the package to still show up on invoices. By default, if a package does not have a value above $0.00 it will not generate a line item.
discount-show_available: When a discount is only applied for a specific duration this will show the remaining discount period.
disablepostalinvoicedefault: If you only email invoices then enabling this can be very helpful to ensure a customer is not accidentally set to postal invoice delivery.
invoice_usesummary: This will make the first page of the invoice a summary of charges, fees, payments, credits, etc. This can be very helpful for customers that have a very long bill.
invoice_default_terms: Set this to the terms that should be set by default when adding a new customer. You can always select a different value for specific customers when adding or editing their account.
invoice_sections: This allows you to section your invoice line items by Package Category or Location. This is very useful for making invoices more organized.
invoice-unitprice: This enables ordering quantities of packages instead of ordering individual packages to meet the quantity ordered. This should be enabled as most people use this feature.
Invoice Email
emailinvoiceonly: This will remove the postal invoice option when editing a customer account. This is helpful if you do not print and mail invoices.
emailinvoiceauto: If you enable the previous setting then you should enable this one too.
emailinvoiceautoalways: This probably does not do what you initially think it does and should most likely be left disabled.
What this does is when you provision an svc_acct service it will automatically add that address to the invoice email list for that customer. I am pretty sure this only works on version 3.x as version 4 uses the contacts for invoice delivery.
invoice_from_name: This sets a pretty display name for the from address instead of just showing the email address.
invoice_subject: Set this to the subject you would like used for the email sent containing a customers invoice
invoice_email_pdf: Attach a PDF copy of a customers invoice to the email.
invoice_email_pdf_msgnum: Set this to the message template you would like to use as the body of the invoice email instead of displaying the HTML version of the invoice. This can be very useful when using the previous setting as some email clients will display all invoice parts inline making it appear that more than one invoice was sent.
invoice_email_pdf_note: Use the previous setting instead of this one, it is much easier to make changes.
Invoice Balances
previous_balance-section: This is very handy for making a combined invoice/statement where it shows the previous unpaid invoices as well as current charges.
previous_balance-show_credit: If the previous balance is a credit it will not show on the invoices unless this setting is enabled.
Quotations
quotation_from: This allows you to use a different email address as the from field than what your invoices are sent out as. This can be very useful when you want responses to go to your sales team instead of billing.
quotation_subject: This sets the subject for quotations.
quotation_email_pdf: Enable this to send the quotation as a PDF attachment.
quotation_email_pdf_note: This text replaces the body of the email instead of using the HTML version of the quote.
quotation_disable_after_days: This will automatically disable quotations if they have not been converted to an order. This is very helpful to prevent stale quotations from hanging around.
Notification
log_sent_mail: Enable this right away. This makes troubleshooting email issues much easier and if it is not enabled there is no way to get the error back.
payment_receipt: This enables the payment receipt engine.
When a payment is made using the links on the Payment History tab then a receipt using the template defined below is sent to the customer.
When a payment is made using the automated billing events the customer is sent an invoice showing their charges and the payment with a $0.00 balance. The word Invoice is also replaced with Statement.
payment_receipt_statement_mode: This allows you to set a different invoice mode to be used for the payment receipt sent by the automated billing. This is very handy for changing details of the payment receipt without them affecting the overall invoicing system.
payment_receipt_msgnum: There is a default message template that you can use and modify to your liking, or you can create a new one and set it here to be used when sending payment receipts from manual payments.
smtp-username: Set this to the login that should be used if your outgoing mail server requires SMTP Authentication
smtp-password: Set this to the password that should be used if your outgoing mail server requires SMTP Authentication
smtp-encryption: Set this to the encyrption type your outgoing email server uses.
emaildecline: This sends an email to customers that have had their credit card or electronic check declined.
UI
payment_history-years: This is used to set the amount of history that is shown in the payment history tab. It accepts decimal values so you can set this to show as much or as little history as you like.
menu-prepend_links: This is used for adding links to the beginning of the Freeside UI tabs. I have used this for adding tabs with report results or linking to an external system.
cust_main-status_module: This changes the display of a customers status and should really be left at the default as there are a number of reports that were never updated to make them play nice with this setting.
cust_bill-enable_promised_date: This enables the promise to pay date features on invoices that can be used by specific conditions in the billing events. If you have billing events such as late notices/fees and automatic suspension events that use the invoice dates you should enable this so you can setup a date that your customer has promised to pay and avoid sending them notices or charging fees until after that date has passed.
logout-timeout: Please set this to a reasonable value to automatically log users out of the backend if they got up and forgot to lock their screen. This could be the difference between your company becoming the next data breach or not.
Addressses
google_maps_api_key: Definitely set this so the mapping functions in Freeside will work. The directions are linked in the setting description or you can follow this one Getting a Google Maps API Key
company_physical_address: Set this so the directions link will give you directions to the customer from your companies physical location.
address_standardize_method: Set this to U.S. Census Bureau initially and then get a USPS Webtools account as the USPS standardization is a bit more accurate. If you have a support contract with Freeside then they will set this to their service for you.
usps_webtools-userid:
usps_webtools-password: USPS Webtools is a free address standardization tool offered by the post office. Whether you are filing an FCC Form 477 report or not this can be very useful to ensure proper delivery of postal invoices and to make sure the mapping tools are accurate.
cust_main-auto_standardize_address: Do not set this, ever. If you do and there is an error in the standardization you will never know.
census_year: Set this to the proper year so the census tracts are set correctly when adding or changing a customer.
Customer number
cust_main-edit_agent_custid: This allows you to set a custom identifier for your customers apart from the internal customer number. This is helpful for maintaining existing customer numbers when moving from a legacy platform to Freeside.
cust_main-default_agent_custid: If you enabled the setting above you should probably enable this one too so the custom identifier is displayed in the UI, on invoices, and reports.
Customer Fields
editreferrals: Enable this as it will allow you to edit the advertising sources for existing customers. Otherwise, if you forget to add them when you create a new customer you will not be able to add or change them afterward.
cust_main-require_phone: This is handy to ensure new customers always have a phone number entered, otherwise if you need to call them you could be left in the dark.
cust_main-require_classnum: If you are using customer classes then you should enable this, otherwise you could have a lot of unclassified customers come up in your reports.
Reporting
maxsearchrecordsperpage: Set this to display more or fewer results per page by default on reports.
cust-fields: If you find you and others are selecting the same customer fields option often you can enable this setting so it will show those fields by default.
Localization
statedefault: Set this to your state so you don’t have to change it from CA each time you add a new customer.
Backup
dump-localdest: Path on your Freeside server to save the database dump to. This path must exist or freeside-daily will return an error.
dump-scpdest: scp destination for remotely copying the database dump. Key based authentication to the remote system must be established for the freeside user.
The Configuration Menu
Most of your Administrative tasks will take place in the Configuration menu. The sections below highlight each menu sub item and what you can do with them.
Settings
As you saw from the previous section there are a lot of settings in Freeside that allow you to make adjustments to just about everything.
The settings are fairly well documented in their descriptions so they will not be covered in a separate section, instead I will be sure to document any relevant settings for specific tasks.
Companies
Freeside is a multi-tenant capable system and this is done by specifying multiple Agents.
Agent Types
Agent types are used for making packages available to only one or specific agents. In this way you can make it so Agents can create their own packages and they will only be available to their customers, or you can make the packages that are available to the other companies and specify which companies they will be available for.
You should create your Agent Types before adding a new agent.
Creating a new Agent Type
- Go to Configuration -> Agents -> Agent Types and click on the Add a new agent type link.
- Enter an name in the Agent Type field, it is usually good to enter the name of the Company here
- Select any packages that should be available under this Agent type
- Click on the apply changes button
Disabling and Agent Type
If you no longer need an agent type you can disable it by clicking on the Agent Type name, tick the box labeled Disable and click on the apply changes button.
Agents
Agents are the companies that you will be sharing your Freeside server with.
Employee Group Configuration for Agents
Before you start adding Agents you should setup Employee groups to help control their access to your Freeside server.
A tried and true setup for Agent Employee groups is:
- Agent Employee Group: This group will be used among all agents so you do not want to select any Agents in the Group limited to these agent(s) area. Select any ACLs that the Agents Employees should have access to.
- Agent Manager Group:
- Agent Access Group:
Creating an Agent
You can create an Agent by going to Configuration -> Companies -> Agents and click on Add a new agent:
- Agent: Enter the companies name in this field
- Agent Type: Select the appropriate Agent type from the drop down box
- Master customer: Enter the customer number or name to search for the Agents customer. This will be used for billing and commissions.
- Ticketing queue: If you will be setting up the ticketing system for your Agents you can set their default queue here.
- Access Groups: Check the boxes
Agent Payment Gateways
Employee Management
Freeside has a very flexible Employee Management system to ensure you only give the permissions needed and nothing more.
Employee Access Control
Access to elements in Freeside are controlled by Employee groups that you can view and change by going to Configuration -> Employees -> Employee Groups and Access Controls.
The groups are stackable so you can make groups with different rights enabled and add Employees to the appropriate groups so they can access the features they need but not ones that they should not be in.
Example Group Structure
A good structure for the groups is as follows:
- Employee Group: This group should have any right that every employee, no matter what their job is, should have access to. This is going to be a fairly small list of rights but makes it so you don’t have to duplicate them across other groups.
(i.e. View customer, View customer history, View customer packages, etc.) - Billing Staff Group: Enable the financial rights that everyone in your billing department should have access to.
(i.e. New customer, Edit customer, Order customer package, One-time charge, Process Payment, etc.) - Support Staff Group: Enable rights that your Support staff should have access to.
(i.e. View customer services, Edit password, Change customer service, etc.) - Billing Admin Group: This group should have rights enable that are assigned to billing staff that are in a management role.
(i.e. Void invoices, Void payment, Credit line items, Post credit, etc.) - Support Admin Group: Enable rights for this group that your support administrators should have
(i.e. Unsuspend customer, Unsuspend customer package, Delay suspension events, etc.)
You should wind up with a list of groups that matches your companies infrastructure and allows for easy transitions when employees move up, or down, the leadership chain or even switch jobs entirely.
Once this is done you can add your employees and tick off the appropriate groups that they should belong to.
Managing Employees
Employee management is handled by going to Configuration -> Employees -> Employees. Here you can add, disable, and make changes to employee accounts.
When setting up employees you should make one account for each employee, do not use role accounts as this can cause confusion when looking at the logs to determine who was responsible for a mistake.
Special Employees
A number of special Employees are added to the system at installation that should never be modified or disabled:
- fs_queue: used to run queued jobs from the job scheduler
- fs_daily: used for running the freeside-daily script from cron and manually
- fs_selfservice: used for running the freeside-selfservice scripts
- fs_api: used for running the Freeside API
Adding an Employee
Click on the Add an employee link just above the employee list to open the Add employee screen and make the following inputs:
- Username: must be unique and it is highly recommended that a uniform approach be taken like first initial last name
- Password: It is best to use a random 13 character password initially and then have each user change it to their personal password after logging in for the first time.
- Last and First name: both fields need to be filled out
- Installer: Check this box if you are using the built-in installer scheduling and this employee is an installer (more on this in an upcoming section)
- Customer: This is used for employee commissions though using the salesperson system is a much better alternative as it is much more flexible
- Employee Groups: tick the box next to each group the employee should be a member of based on their role in your organization
Click on the Add employee button to finish adding the new employee
Editing an Employee
To edit an employee simply click on their username in the Employee list.
You can make any number of changes but do not change the username as this could have undesirable effects. When you are finished making changes click on the Apply changes button.
Disabling an Employee
As you will find with many things in Freeside you cannot delete them as this would have adverse effects on historical reporting and logs.<br>
In the case of employees, you can disable them by editing them, ticking the box labeled disabled, and clicking the Apply changes button.<br>
If you are replacing an employee do not attempt to reuse their account by changing the username as this will also change the username in the logs and reports
Customer/Contact Features
Customer Tags
Customer Classes
Customer Categories
Contact Types
Note Classes
Packages
Package Definitions
Anything you are selling through Freeside will be a Package in one form or another. You will access the Package Definitions screen by going to Configuration -> Packages -> Package Definitions.
Creating a Package Definition
Cloning a Package Definition
When you are creating many packages that have many of the same values you can save a lot of time by cloning a single package and only changing the necessary information.
- On the Package Definition screen select the package you want to duplicate from the drop-down box labeled “Select package”
- Click on the Clone existing package button
- Make the changes needed for the new Package Definition
- Click on the Add Package definition button at the bottom of the screen
Package Classes
Package Categories
Package Report Classes
Package Fees
Package fees are a new feature in Freeside starting with version 3.3 which allows you to define a fee that can be used by the Billing Events instead of using the Late Fee action. The benefit of using Package fees is they do not show up as one-time charges in the customer’s Package display thus reducing clutter.
Creating a Package Fee definition
- Go to Configuration -> Packages -> Fees and follow these steps:
- Fee definition fields:
- Click on the Add a new fee definition link
- Enter a name for the fee in the Description field, this is also what will be used as the invoice line item
- Enter a comment if needed in the Comment field
- Select an agent or leave at global if this should be available to all agents (the agent drop down box will not be visible if you only have one agent defined)
- Select the package class for the fee
- If you ever need to stop using a fee you can check the Disable this fee box and it will be removed from any selection boxes in the billing events and will not display with other active package fees
- Select whether the fee should show up as a setup fee or recurring charge. In most cases this should always be set to “a setup fee”
- Fee calculation fields:
- If this is a flat fee then enter an amount in the Flat fee amount field, otherwise leave this field blank
- If the fee should be calculated each time then select which method from the Based on drop down box and enter the appropriate percentages. The most popular amounts to base a fee on are the amount charged, this is the original full amount that was charged, and balance due which will only calculate the fee based on the amount still owed.
- Set the minimum amount of the fee in the Minimum fee field, leave blank for no minimum
- Set the maximum amount of the fee in the Maximum fee field, leave blank for no maximum
- If you use credit balances you can also limit the fee so it will not go over the customer’s credit balance by checking the box labeled “Limit to customer credit balance”
- Taxation fields:
- If the fee is taxable then check the box labeled “This fee is taxable”
- If you have Tax Classes setup then the Tax class name drop down box will be available for you to select the appropriate tax class.
- Once all the fields are filled out to your liking click on the Add fee definition button at the bottom of the page.
Now that you have your shiny new Package Fee I am sure you are itching to put it to good use
Using a Package Fee
- Go to Configuration -> Billing -> Billing Events. Either click on Add a new event or edit your existing event that you would like to replace the action on and follow these instructions:
- If creating a new event give it a meaningful name, select the type of event, and select the appropriate conditions for the event (a full description of setting up billing events will be in another section)
- In the Event Action section select Charge a fee based on this invoice from the Action drop down box
- Select the fee from the Fee definition drop down box
- If the fee should be held until the customers next regular billing then check the box labeled “Hold fee until the customer’s next bill”, otherwise the fee will be charged immediately.
- Click on the Add Billing event definition, or apply changes, button at the bottom of the page
When you are back at the Billing Event Definitions page you can use the query link to see what invoices the event will apply to and make any necessary adjustments to your conditions.