Freeside:3:Documentation:Developer

Introduction

Please consider sharing your modifications with the community and helping integrate them into the standard code!

Subscribe to the freeside-devel mailing list. Send your changes as git pull requests or unified diffs (diff -u). If possible, send changes against current git master and also any branch they should be applied to (i.e. FREESIDE_2_3_BRANCH). However, if all you have is diffs against a release, well, probably best to send what you have rather than waiting.

Also note that the license requires that you provide source code if you provide hosted access to a modified Freeside instance.

Signup and self-service

You can of course customize the signup and self-service templates as well as plug into the self-service API from Perl, PHP or any other language via XML-RPC. See the SelfService API.

There are notes for the existing signup.cgi, signup.html or success.html as well.

Backoffice

New customer page

You can link to the new customer page (https://billing.example.com/freeside/edit/cust_main.cgi) with parameters set to lock or pre-select the agent and/or first package. (Note: version 1.9.5+ or 2.1.2+)

• lock_agentnum: Locks the agent selection to this agent, even if the current user would otherwise be able to select other agents. For example:

 https://billing.example.com/freeside/edit/cust_main.cgi?lock_agentnum=2

• lock_pkgpart: Locks the package select to this pkgpart. Can be set to a single pkgpart or a comma-separated list of pkgparts. For example:

 https://billing.example.com/freeside/edit/cust_main.cgi?lock_pkgpart=6
 https://billing.example.com/freeside/edit/cust_main.cgi?lock_pkgpart=6,2

An example with both lock_agentnum and lock_pkgpart:

 https://billing.example.com/freeside/edit/cust_main.cgi?lock_agentnum=2;lock_pkgpart=6,2

Backend plugins

The backend code is structured to make it easy to add "plugins" of various types. You can easily add new price plans, new exports, event plugins (conditions and actions) and new kinds of service tables.

Price plans

Price plans

Exports

Exports

CDR formats

Files

• New CDR formats (CSV, fixed length or anything-SV) files can be imported by adding a FS/FS/cdr/formatname.pm file. An example may be found in eg/cdr_template.pm

Databases and APIs

• Write a script to import CDRs from remote databases or APIs. See the existing ones in the bin/ directory for examples. For a remote database, cdr-ivr.import is a good example.

(Invoice) Events

Invoice events have been refactored in 1.9.x and are now just events. The new events have "Condition" and "Action" plugins.

Services

Service tables are fully "plug-in" able:

• Create the table (see "Schema changes" below)

• use base qw( FS::svc_Common );

• Define the table_info subroutine.
• (Recommended) Define the label subroutine.
• Create a new ACL for the service in AccessRight.pm (Services: New service name)
• Optionally, grant the ACL on upgrade in access_right.pm

Additional developer information

Schema changes

Schema changes - Quick documentation on how to make schema changes

Agent virtualization

Agent-virtualized config - Quick notes on how to agent-virtualize new parts of the configuration tables

Tax data vendor support

Tax data vendor support - Notes on how to support a new vendor of tax data

Git usage notes

Committing to both master and FREESIDE_3_BRANCH

Mark's method

• make some changes on master, or merge them in from a topic branch, then commit them
• git checkout FREESIDE_3_BRANCH (or "git checkout 3.x", etc. if you've locally named it something else)
• git show master -U5 |patch -p1 #-U5 for more context, to avoid committing things in the wrong place ala #16114
• and then do the same "git commit" command as before
• (the one catch is that you have to "git add" any new files after patching)
• any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
• git push origin master FREESIDE_3_BRANCH # push both branches
• then you do a "git checkout master" to go back

Mike's method

• make some changes on master, or merge them in from a topic branch, then commit them
• git format-patch -1 -U5 [sha1 of commit] >filename.patch #-U5 for more context, to avoid committing things in the wrong place ala #16114
• git checkout 2.3 (or "git checkout FREESIDE_3_BRANCH", etc. according to how you've named it)
• patch -p1 <filename.patch
• and then do the same commit
• (the one catch is that you have to "git add" any new files after patching)
• any conflicts will show up when doing the patch--if it's something complicated I like to patch --dry-run first
• then you do a "git checkout master" to go back

Ivan's (deprecated) method

• Requires separate freeside/ and freeside3/ trees
• 3add filename filename
• 3commit 'commit message' filename filename

Ivan's (new?) method

• git checkout FREESIDE_3_BRANCH
• git cherry-pick commit_id commit_id ...
• git push
• (git checkout master #to switch back)

API documentation

3.x API documentation