Freeside:4:Documentation:Developer:Overview

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

Code Base Structure

The most essential directories for you to know about:

FS/FS 

perl modules in the FS namespace.

httemplate 

mason cgi scripts and other files for the main web interface

FS/bin 

standard installed scripts that keep Freeside running

bin 

additional helpful scripts, not automatically installed or integral to functioning

fs_selfservice 

a separate web interface to allow individual customers to access their accounts

ng_selfservice 

the "next generation" of the selfservice interface, built in php

rt 

code for the integrated ticket tracking system, mostly third-party but contains some customizations

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

Records

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

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

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

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

Employees

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

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

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

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

Agents

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

Customers

An FS::cust_main object represents a customer.