Download jBilling Telecom Guide PDF

TitlejBilling Telecom Guide
File Size4.3 MB
Total Pages96
Table of Contents
                            Chapter 1
Mediation & Rating
	About jBilling 'telco'
		Who should read this?
	The need for mediation
	Rating events
	Mediation and Rating with jBilling
		Updating orders
Chapter 2
The Mediation Process
			Batch size
			Buffer size
			Rules optimization
	The list of mediation processes
Chapter 3
The Mediation Configuration
Chapter 4
	The readers plug-ins
		The file reader plug-ins
		The JDBC reader plug-ins
	Creating you own reader plug-in
		Reader plug-in responsibilities
		Code re-use
Chapter 5
The record format
	XML format description
		The record key
			Purging the keys table
Chapter 6
Processing with rules
		Mediation rules
		Item management rules
		Pricing rules
		The MediationResult object
		Step 1: Start
			Input State
			Output state
			Things to do
		Step 2: After User
			Input State
			Output state
			Things to do
		Step 3: Current Order
			Input State
			Output state
			Things to do
		Step 4: Resolve Product (Item)
			Input State
			Output state
			Things to do
		Step 5: Pricing
			Input State
			Output state
			Things to do
		Step 6: Item Management
			Input State
			Output state
			Things to do
		Step 7: Account update
			Input State
			Output state
			Things to do
	Transforming the data
		Record splitting
		Record grouping
		Padding and other field modifications
	Extending the mediation module
Chapter 7
	Rating events
		The pricing result
		Executing pricing rules
		Item relationship management plug-in
	Pricing with rules
		Dealing with large number of pricing rules
Chapter 8
Mediation errors
	The mediation results
		Done and billable
		Done and not billable
		Error detected
		Error declared
	Reprocessing records with errors
		Saving the records with errors
		Fixing the errors
		Reprocessing the records
Chapter 9
Real-time Mediation
	The difference of real time processing
		Processing an event in real time
		Validating an event before it happens
Chapter 10
Example scenario
	Our example plan
	Initial configuration
		Mediation configuration
		Items and customers
	Expressing the plan with rules
		Mediation rules
			Defining the user
			Defining the event date
			Long distance calls
			Weekend calls
			Standard calls
		Item management rules
			Free weekends for subscribers only
			Minutes included in the plan
		Pricing long distance calls
	Processing some events
Chapter 11
	Overview of the provisioning process in jBilling
		The advantage of JMS
		An Example
	The internal provisioning module
		The provisioning status of orders
		Provisioning events and the provisioning plug-in
		Provisioning rules
		The provisioning queues
	The external provisioning module
		Configuration of the Message Mapping component
		The external provisioning plug-in
			Error handling
Document Text Contents
Page 48

little of your work (if at all any), this step will be the one where you provide the actual
logic that the system needs to follow.

Input State
• currentOrder: The order that will receive the one time charges coming from this


Output state
• lines: The list needs to get new order lines. Each new order line will have a

product (item) and a quantity. This the core of what the mediation process is
meant to do: map an event to a product, which is represented as an order line in

• step: Rather than using a transition rules, the step is typically set in the 'then'
section of the rule to step 5.

• New pricing request: This is not a variable to set in the result object. This is a
new pricing request that you might need to do by inserting an object in the
memory context.

• description: an explanation of the charges coming from this event (optional).

Things to do
Add a new order line

The result object has a list of order lines that capture products that the customer is
buying because of this event . This means that you need to create an instance of the
object OrderLineDTO() populated with the information of the purchase. The following is
an example (or helper) function:

function OrderLineDTO newLine(Integer itemId, BigDecimal quantity) {
OrderLineDTO line = new OrderLineDTO();
return line;

An event typically maps to one product, but it does not have to. That is why the 'lines'
variable of the record class is a List.

Let's use the above function in an example rule that uses the 'duration' field from the
CDR to product (item) id 2900:

rule 'resolve call item and request price'
$result : MediationResult(step == MediationResult.STEP_4_RESOLVE_ITEM)
$quantity : PricingField( name == "duration",

resultId == $

Page 49

new BigDecimal($quantity.getStrValue())));

update( $result );

PricingResult request = priceRequest(2800, $result); // because it will be converted to
insert( request );

The important part of this rules is that the quantity is coming directly from the value of
the 'duration' field of the CDR. The rules assumes that every CDR that made it to this
step maps to the same product (2900). It would be very easy to add more conditions
based on other fields for conditionally map to other products.

In this example, product 2900 maps to a generic phone call. This item will be later
evaluated and swapped to another item depending on the custom begin a subscriber (or
not) of a specific plan (more on this later).

Regardless, this rule makes a explicit pricing request for the product 2800. The logic is: if
the customer is a subscriber, it will be free so the price is irrelevant. But if she is not a
subscriber, then the product will be the 2800 and the pricing needs to be done based on
a rate card.

Requesting a price is as simple as adding an instance of PricingRequest. More on this
in the rating section.

Set the description

It will make it much easier for the customer if an event that translates to a charge is
explained. The typical way is by having a section of the invoice with a list of events with
the description, date and price.

jBilling does keep track of every event processed, and it can add a description to them.
This is later used for the invoice presentation just described.

This is an example:

rule 'resolve call destination'
$result : MediationResult(step == MediationResult.STEP_4_RESOLVE_ITEM, description
== null )
$phoneCalled : PricingField( name == "dst", resultId == $
# set mediation event description to the call destination
modify( $result ) {
setDescription("Phone call to " +


Transition rule

Page 95

described in the previous section. All the parameters (enclosed in '|') have been parsed
so you get the real values.

How are the command parameters passed to the plug-in? The plug-in receives a single
string that follows the format defined in the above configuration. Thus, it is the plug-in
responsibility to extract the parameters from this string.

The plug-in parameters (do not confuse with the command parameters. The plug-in
parameters are used for every call and do not change in between calls) are typically
used to store data needed to reach the external system (port numbers, IP addresses)
and establish a session (user name, password...).

We can now finally code the plug-in for our sample cell phone operator. Here, we simply
ignore the details of the connection to the external system, as actual implementations
vary greatly (telnet sessions, web services, RESTful HTTP calls, etc.). We will just flesh
out the code that provides the connection and assume a generic externalCall object
with two methods (newSubscription() and cancelSubscription(), each
accepting a single number argument and returning an int indicating the outcome of the
operation: 1 if successful and 0 if unsuccessful).

class SimpleProvisioningTask extends PluggableTask
implements IExternalProvisioning {

private static final String PROCESSOR = "sample_cell_service";

public String getId() {

public Map<String,Object> sendRequest(String id,
String command) throws TaskException {

// Obtain and validate the "number" parameter
// Here we use a helper method that fetches the value
// of number from the command ex:
// cancelSubscription:number,123456789;
String number = getCommandParameter(“number”, command);
if (number == null || number.equals("")) {
throw new TaskException("invalid number");

// The command string contains the command names indicated
// in the mapping configuration:
// - addSubscription
// - cancelSubscription
int result = 0;
if (command.startsWith("addSubscription")) {
result = externalCall.newSubscription(number);
} else if (command.startsWith ("cancelSubscription")) {
result = externalCall.cancelSubscription(number);
} else {
throw new TaskException("Invalid command " + command);
Map<String,Object> resultMap = new HashMap<String,Object>();
resultMap.put("result", Integer.valueOf(result));
return resultMap;

Page 96


Note that a single provisioning event could involve more than one call to the provisioned
system, or even parallel calls to separate external systems. Each command is
encapsulated in a separate Request in the mapping configuration.

If the request has been configured with a postResult property with a "true" value, the
response provided by the external system will be propagated by means of the JMS
inbound queue. The response JMS message will contain all input parameters that were
present in the input JMS message (prefixed by "in_") and all output parameters
generated by the external system (prefixed by "out_").

Let's see the output message mapping in action. Assuming an input message containing
the following fields:

Name Value

id fffa1ea0-a44a-11dd-aa93-0002a5d5c51b

command activate_service

number 6041231234

The generated output message will contain the following fields:

Name Value

in_id fffa1ea0-a44a-11dd-aa93-0002a5d5c51b

in_command activate_service

in_number 6041231234

out_result success

Error handling
In case of errors during execution of the external provisioning plug-in, caused by lack of
availability of the connection to the external system or other conditions, the external
provisioning module nevertheless provides an error response. This response has the
'out_result' property populated with an "unavailable" value, and an "exception"
property containing the exception message that details the type of error condition raised
during execution of the plug-in. An error message for the previous example would look
like the following:

Name Value

in_id fffa1ea0-a44a-11dd-aa93-0002a5d5c51b

in_command activate_service

in_number 6041231234

out_result unavailable

exception NullPointerException

Similer Documents