Get jBilling

Custom Business Logic

Introduction

Starting with version 3.1,  jBilling provides you with it’s own simple and accessible method for handling custom business logic through the use of easy to manage plug-in extensions. Earlier versions required the use of separate BRMS systems with their own GUI, in particular JBoss/Drools. This required a good deal more technical expertise and while still available to use, it is no longer the default for jBilling. If you wish to read our old BRMS guide which includes examples and information about Drools please click here.

It is important to note that this guide is mostly applicable to the Community Edition. The Enterprise Edition of jBilling already comes with built-in support for complex pricing, plans, and bundles. In the Enterprise Edition, complex pricing is done with pricing models, which are extensible components that encapsulate pricing logic. Plans, and bundles, group and price products in a way that greatly simplifies product management.
This is not to say that plug-ins with custom logic are not used in the Enterprise Edition; they are, but mostly for areas other than pricing and bundling.

There are numerous benefits for jBilling’s decision to run custom logic from plug-ins.

  • With the business logic contained in the plug-ins, you do not need to change the core code. This means upgrading your logic is a snap and, conversely, you can just as easily upgrade your application without any merges: your custom logic is safely separated in plug-ins.
  • jBilling stands for ‘Java Billing’. We love Java. Writing custom logic in Java just makes sense.

Your billing system should always reflect your business rules.  In many cases, this will lead to ever-increasing complexity for the billing system. For example, it is very common that a product needs more than just a simple flat price. Many factors might need to be considered to determine that price, such as a volume discount, a limited-time promotion, or pricing based on the location of the customer. The possible options are endless.

Another area of a billing system that requires great flexibility is the relationship among products. If you could clearly establish 'commands' to how products relate to each other, then you could implement business rules such as: “if you buy 10 books, you get a free calendar,” or “bundle A includes a book, a calendar, and a poster.”

Those are just two simple examples of what could be a source of great complexity in a billing system. How can your billing system provide you with the necessary flexibility you require to have all your business rules successfully implemented? Using plug-ins allow you to apply operational decisions based on company policy. It also gives you the ability to maintain or modify these rules without needing to change the core code of the application, providing you with increased control over your billing system for compliance and better business management.

This guide is an overview of how to implement these plug ins to easily manage your business logic with jBilling. For more detailed documentation, read the jBilling Extension Guide. If you have not done so, please read the Getting Started/How to Get Started guide that will walk you through the basics of customer and product creation, and how to create your first invoice. This will provide you with an order for B.Smith, once that is in place we can begin.

Meta Fields

Before you begin to implement and make changes to the jBilling plug-in system. It is helpful to know a little bit about meta fields. You will need to implement a meta field before you work with the example plug-in.

Meta fields were introduced first in jBilling 3.1.0 Community Edition. A meta field is simply an extra field you add to a particular form within your billing system. jBilling gives you valuable flexibility by providing you with the ability to create fields in one of five billing areas called “Entity Types”.

  • Customer
  • Product
  • Order
  • Invoice
  • Payment

Creating a meta field is easy. For the plug-in example that follows you will need to create the following meta field.

  1. Click on the configuration tab and then in the sidebar on the left click on the meta field option. This should bring up the five entity types we listed above to choose from.

  2. Choose the entity type, “Product”. At this point there will be no meta fields entered so click on the “+ Add New” button on the right to take you to the meta field form.
  3. Notice the first field “Number” is listed as “New”. This will be the meta field id # and it will not be assigned until after the meta field is created. You will need this id # for the plug-in example. Please make a note of it.
  4. Fill out the following fields; Name = “Discount”, Data type = “Decimal”, and Display Order = 1. Leave Default Value blank.

  5. Ensure the check boxes Mandatory and Disabled are not selected and click Save Changes.

You should be back at meta field configuration page. If you like, you can go back to the product creation page to see that your newly created field “Discount” is now part of the product creation form. You will be using the information in this field in our next example.

The Plug-In System

To make your billing system as easy to use as possible jBilling has implemented a system of plug-ins based on Strategy and Chain of Responsibility designs. This allows you to create the steps needed, (using the plug-ins provided or plug-ins you create yourself), that your business rules require and excluding those that do not apply. For example, you might normally add all products ordered to your invoice but then have a series of taxes such as federal, state, local and maybe a VAT, (Value Added Tax), at the end. You would simply select and configure the plug-ins needed to create the tax rules and jBilling will take care of the rest. Let’s walk through a particular example to show you how simple business rules can be established, managed, and maintained.

The example we will use is a basic product discount rule. You will create and maintain a category of products you wish to sell at a discount. You should have already created a customer called B.Smith along with a product and category. You will now add a new category for discount products, modify it, and apply your discount rule by implementing a supplied plug-in.

  1. Create a new category of products called “Discount products”. Within that category create a product called “Discount Banners”. You will see your new Discount Meta Field; For now continue to keep the meta field “Discount” blank. Keep track of the category id # as you will be needing it soon.

  2. Click on the configuration tab at the top of the screen and then click on plug-ins on the left side bar. This brings up a full list of all installed plug-ins. Changing any of the pre-installed plug-ins without a full understanding of what they do may result in unwanted results so please be careful.

  3. Take a moment to click on at least one of these plug-in categories. You will see some pre-installed plug-ins displayed to the right. Click on any of these displayed plug-ins to bring up a detailed description of what that plug-in does.
  4. In the list of plug-ins categories you will see a category called “Product Pricing”. Click on it to highlight this category. There is no default plug-in implemented yet but we will install one now by clicking the “+ Add New Button” that will be on the right. This should take you to the plug-in page.

  5. You will see a drop down list with several similar sounding plug-ins. Select the one ending with “.DiscountPricingTask”.
  6. Once selected you will see a list of windows to fill in. These are the parameters needed to provide jBilling with the right information to implement your new rule. Different Plug-Ins will require different fields.
  7. The first box is labeled “Order” and this allows you to determine the order in which the rules will be applied. Please enter "1" here.
  8. The next parameter is the Discount Category ID box. Please enter the category id number you have for the “Discount products” category. This will apply the discount to that category of products.
  9. You can now define the discount percentage at the product level using a meta field by entering the meta field id and enter 10 in the “Default Discount Percentage” box. Whole numbers here represent the percentage amount so 10 = 10%. Your fields should look like this.

  10. Now, return to use that category and you will see the prices in the product category have not changed, but when applied to an order, the price has been reduced by 10 percent.

Also, you may now go and add new products or edit pre-existing ones and, in the discount meta-field, determine individual discount prices for those particular products. Try this out by entering 15 in the “Discount” meta field, and you will see it overrides the default value of the plug-in.

Even simpler you can skip the meta field entirely. Just use the plug-in directly as a default value for your entire discount line of products. This takes away your ability to modify individual products, but it does help you see just how flexible and scaleable jBilling’s plug-in system can be. Including your own plug-ins you build in Java can help your billing system grow even further providing you with ultimate customization.

As you can see, there is a lot you can do with this simple plug-in that is provided mostly just as an example. The best part really is that you have the source of the plug-in. You can change it, enhance it, extend it, or create a new one entirely, all in Java. This is open source enterprise billing software at its best.

jBilling provides you with the tools you need to implement all your business rules quickly and easily, without needing to change core code. You simply chain together the list of plug-ins to generate the invoices you need.