Telecom Guide: The Open Source Enterprise Billing System

w
w
w
.
j
B
i
l
l
i
n
g
.
c
o
m
The Open Source Enterprise Billing System
Telecom Guide
Copyright
This document is Copyright 2004-2010 Enterprise jBilling Softwre !td" #ll $ights
$eser%ed" &o prt of this document my 'e reproduced( trnsmitted in ny form or 'y
ny mens -electronic( mechnicl( photocopying( printing or otherwise- without the prior
written permission of Enterprise jBilling Softwre !td"
jBilling is registered trdemr) of Enterprise jBilling Softwre !td" #ll other 'rnds nd
product nmes re trdemr)s of their respecti%e owners"
Author
Emilino Conde nd others
Revision number and software version
This re%ision is 2"0( 'sed on jBilling 2"1"0
Table of Contents
CHAPTER 1
E!"AT"#$ % RAT"$&'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' (
About jBilling 'telco'.......................................................................................................................................9
Who should read this?.................................................................................................................................. 9
Requirements..............................................................................................................................................10
The need for mediation................................................................................................................................ 10
Rating events................................................................................................................................................. 11
Mediation and Rating with jBilling.............................................................................................................11
Updating orders.......................................................................................................................................... 14
CHAPTER )
THE E!"AT"#$ PR#CE**''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 1+
verview........................................................................................................................................................ 1!
"e#lo$ment ...................................................................................................................................................1!
Performance .............................................................................................................................................. 20
Batch sie............................................................................................................................................... 20
Buffer sie.............................................................................................................................................. 21
Rules optimiation................................................................................................................................. 21
%cheduling..................................................................................................................................................... &'
The list of mediation #rocesses.................................................................................................................... &'
CHAPTER ,
THE E!"AT"#$ C#$-"&.RAT"#$''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''')/
CHAPTER 0
REA!ER*''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''')(
!he readers plug"ins................................................................................................................................... 29
!he file reader plug"ins.......................................................................................................................... 29
!he #$B% reader plug"ins..................................................................................................................... &0
%reating 'ou o(n reader plug"in................................................................................................................&1
Reader plug"in responsi)ilities.............................................................................................................. &&
%ode re"use............................................................................................................................................ &*
CHAPTER 1
THE REC#R! -#RAT'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ,/
(M) format descri#tion.............................................................................................................................. *+
!he record +e'............................................................................................................................................&,
Purging the +e's ta)le............................................................................................................................ &-
,-am#le......................................................................................................................................................... *!
CHAPTER /
PR#CE**"$& 2"TH R.3E*'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 0)
verview........................................................................................................................................................ '*
.ediation rules...........................................................................................................................................4&
/tem management rules.............................................................................................................................. 4&
Pricing rules................................................................................................................................................44
%te#s............................................................................................................................................................... ''
!he .ediationResult o)0ect....................................................................................................................... 44
1tep 12 1tart................................................................................................................................................ 4*
/nput 1tate.............................................................................................................................................. 4*
3utput state............................................................................................................................................ 4*
!hings to do........................................................................................................................................... 44
1tep 22 5fter User....................................................................................................................................... 4,
/nput 1tate.............................................................................................................................................. 4,
3utput state............................................................................................................................................ 4-
!hings to do........................................................................................................................................... 4-
1tep &2 %urrent 3rder................................................................................................................................. 4-
/nput 1tate.............................................................................................................................................. 49
3utput state............................................................................................................................................ 49
!hings to do........................................................................................................................................... 49
1tep 42 Resol6e Product 7/tem8.................................................................................................................. 49
/nput 1tate.............................................................................................................................................. *0
3utput state............................................................................................................................................ *0
!hings to do........................................................................................................................................... *0
1tep *2 Pricing............................................................................................................................................ *2
/nput 1tate.............................................................................................................................................. *2
3utput state............................................................................................................................................ *2
!hings to do........................................................................................................................................... *2
1tep 42 /tem .anagement.......................................................................................................................... *&
/nput 1tate.............................................................................................................................................. *&
3utput state............................................................................................................................................ *&
!hings to do........................................................................................................................................... *4
1tep ,2 5ccount update...............................................................................................................................**
/nput 1tate.............................................................................................................................................. **
3utput state............................................................................................................................................ **
!hings to do........................................................................................................................................... **
Transforming the data.................................................................................................................................../
Record splitting.......................................................................................................................................... *4
Record grouping......................................................................................................................................... *4
Padding and other field modifications....................................................................................................... *,
,-tending the mediation module..................................................................................................................+
CHAPTER +
RAT"$&'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''1(
Rating events................................................................................................................................................. .9
!he pricing result....................................................................................................................................... *9
9:ecuting pricing rules...............................................................................................................................40
/tem relationship management plug"in.......................................................................................................40
0ricing with rules.......................................................................................................................................... /0
$ealing (ith large num)er of pricing rules................................................................................................42
CHAPTER (
E!"AT"#$ ERR#R*''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''/,
The mediation results................................................................................................................................... /'
$one and )illa)le....................................................................................................................................... 44
$one and not )illa)le................................................................................................................................. 44
9rror detected............................................................................................................................................. 44
9rror declared............................................................................................................................................. 4*
Re#rocessing records with errors................................................................................................................//
1a6ing the records (ith errors....................................................................................................................44
;i:ing the errors......................................................................................................................................... 4,
Reprocessing the records............................................................................................................................4,
CHAPTER 4
REA35T"E E!"AT"#$''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' /(
The difference of real time #rocessing........................................................................................................ /9
Processing an e6ent in real time................................................................................................................. 49
<alidating an e6ent )efore it happens........................................................................................................ ,0
CHAPTER 16
E7AP3E *CE$AR"#'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''+)
ur e-am#le #lan......................................................................................................................................... +*
1nitial configuration......................................................................................................................................+*
Plug"ins.......................................................................................................................................................,&
.ediation configuration............................................................................................................................. ,4
/tems and customers................................................................................................................................... ,4
,-#ressing the #lan with rules.....................................................................................................................+.
.ediation rules...........................................................................................................................................,4
$efining the user....................................................................................................................................,,
$efining the e6ent date.......................................................................................................................... ,,
=ong distance calls.................................................................................................................................,-
Wee+end calls........................................................................................................................................ ,-
1tandard calls......................................................................................................................................... ,9
/tem management rules.............................................................................................................................. -0
;ree (ee+ends for su)scri)ers onl'....................................................................................................... -0
.inutes included in the plan..................................................................................................................-0
Pricing long distance calls.......................................................................................................................... -1
0rocessing some events................................................................................................................................. !&
CHAPTER 11
PR#8"*"#$"$&''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''(0
1ntroduction...................................................................................................................................................!.
verview of the #rovisioning #rocess in jBilling....................................................................................... !.
!he ad6antage of #.1................................................................................................................................ -4
5n 9:ample................................................................................................................................................ -,
The internal #rovisioning module............................................................................................................... !+
!he pro6isioning status of orders............................................................................................................... -,
Pro6isioning e6ents and the pro6isioning plug"in...................................................................................... --
Pro6isioning rules.......................................................................................................................................-9
!he pro6isioning queues............................................................................................................................ 91
The e-ternal #rovisioning module...............................................................................................................91
%onfiguration of the .essage .apping component.................................................................................. 92
!he e:ternal pro6isioning plug"in.............................................................................................................. 9*
9rror handling........................................................................................................................................ 9,
Chapter 1
Mediation & Rating
About jBilling 'telco'
*elcome to jBilling telco+ ,ny 'elie%e tht open source will ply nd incresingly
importnt role in the future of enterprise softwre" Billing will not 'e n e-ception( not
e%en for %ery comple- nd demnding industries li)e telecommunictions" jBilling is the
result of the collecti%e effort of dedicted professionls( %olunteers nd compnies tht
need n enterprise 'illing solution"
# 'illing system is t the hert of mny orgni.tions" /t is mission criticl system" /ts
importnce is such tht mny compnies opt to de%elop their own simply to 'e 'le to
retin full control of the 'illing solution" #n open source 'illing solution is %ery ttrcti%e
in this scenrio0 'y h%ing the source code( compny cn h%e full control of their
'illing solution" /t cn de%elop plug-ins to meet its own 'usiness needs( its de%elopers
cn c1uire the )now-how of e%ery spect of the 'illing system" The compny cn
chie%e full control of their 'illing system without writing one from scrtch"
2ntil the relese of jBilling 1"1"0( jBilling did not h%e enough fle-i'ility to tc)le
comple- 'usiness rules relted to 'undling( item reltionships( t-es nd pricing"
#dditionlly( for telecom 'illing whole module ws missing0 medition"
The recent integrtion with Business $ules ,ngement System 3B$,S4( rules
engine nd the de%elopment of the medition module put jBilling in the legue of 'illing
systems needed for the telecommunictions industry"
Two yers fter tht initil 5telco5 relese 31"1"04( new relese of jBilling pushed the
telco cp'ilities much further" jBilling 2"1"0 incresed performnce rdiclly( to the
point of se%erl hundred of records second" /t lso included rel-time medition
fetures nd comprehensi%e mngement of C6$s error cses( long with other
impro%ements"
/n only few yers( jBilling hs e%ol%ed %ery rpidly to the point tht is now competing
with proprietry 'illing systems with licensing cost in the hundreds of thousnds or e%en
millions of dollrs"
/n this document we will focus on the medition component nd descri'e scenrios tht
re typicl for telecom 'illing" jBilling will continue its fst e%olution( dding more
fetures nd 'ecoming more ro'ust" 7or tht( we need your help" 8rticipte in the
jBilling community 'y posting on the forums( reporting 'ugs( su'mitting plug-ins or
code"
Who should read this?
The udience of this document is those jBilling users tht need to set-up medition
process" This usully trnsltes to telecom compnies( 'ut this is not e-clusi%ely for
them" There re other industries tht lso h%e this type of re1uirement nd do not
pro%ide phone ser%ices"
The medition module cn process e%ents of ny type( not just trditionl phone clls0
instnt messging( downlods( dt( 9:/8( /8T9( etc" /f there re e%ents generted 'y
n e-ternl system tht should 'e fed into the 'illing system( jBilling5s medition module
cn t)e cre of them"
Requirements
To fully understnd this document( you need to h%e some pre%ious )nowledge of
jBilling" The concept of customer( n order( pyment( nd in%oice( etc""" needs to 'e
cler" These re e-plined in the jBilling User Guide document"
The medition module m)es e-tensi%e use of jBilling5s plug-in rchitecture nd the
integrtion with the Business $ules ,ngement System" These re co%ered in the
jBilling extension guide document( it is recommended you red nd h%e tht document
hndy when going through this document"
;ou cn downlod the ltest %ersions of these two documents for free t the
documenttion section of the jBilling we' site"
This document t times e-plins how to e-tend or customi.e the 'eh%ior of the
medition module" To t)e d%ntge of this( you will need to understnd the 'sics of
softwre engineering nd the <% Enterprise Edition pltform"
The need for mediation
# phone cll is n e%ent tht t)es plce outside the 'illing system" 7rom 'illing
perspecti%e( phone cll is ctully purchse of ser%ice 'y customer" This e%ent is
)nown to the telephony system nd registered s record in some storge de%ice"
# phone cll is just n e-mple( there re mny other types of e%ents tht hppen
outside the 'illing system nd yet should 'e sooner or lter included in n in%oice for the
customer to py" 6ownloding content( for e-mple( or sending n instnt messge from
cell phone( recei%ing n emil( etc""" #ny e%ent where customer is in%ol%ed m)ing
usge of ser%ices need to 'e communicted to the 'illing system( otherwise no'ody is
pying for those ser%ices+
Becuse of the nture of these e%ents( the informtion tht the system records could 'e
in %ery different formts" Ech telephone switch %endor hs its own formt( nd tht is
only for phone clls 3%oice4" #ll the other ser%ices tht in%ol%e dt( messges( etc cn
'e deli%ered 'y their own systems tht follow %ery different nd proprietry formts" :n
top of ll tht( new types of ser%ices re 'eing lunched ll the time"
There re two min pproches to m)e the 'illing system wre of these e%ents" There
is the 'tch method( where the medition process periodiclly goes o%er these records
nd su'mit the rele%nt informtion of ech e%ent to the 'illing system" The other
method is to do it ll in rel-time0 s soon s n e%ent hppens( the e%en is sent to
jBilling for immedite processing( which includes rting nd updting the customer5s
ccount"
/n ny cse( the medition component hs to 'e %ery fle-i'le to llow the processing of
new types of e%ent records with only chnges to configurtion files"
7le-i'ility is )ey( 'ut there is nother importnt chllenge0 performnce" The e%ents tht
the medition process needs to go through hppen %ery often" Ech phone cll is n
e%ent+ # compny offering phone ser%ices could esily h%e millions of these e%ents
e%ery dy( nd they ll h%e to 'e mnged 'y the medition process"
jBilling ddresses ll of the 'o%e0 'tch medition( rel-time medition or
com'intion of 'oth" /t is %ery fle-i'le nd fst /t is not n isolted module tht
communictes with the 'illing engine= insted( it is 'uilt-in to the core of jBilling to
impro%e 'oth the fle-i'ility nd performnce of the o%erll 'illing solution"
Rating events
The system tht first )nows 'out n e%ent nd records the e%ent does not h%e ny
)nowledge on how to chrge for the e%ent" # telephony switch will )now which phone
num'er the phone cll originted( the num'er tht ws clled( when tht hppened( how
long the cll ws(etc""
#ll this is %ery useful( 'ut stops short of the )ey 1uestion0 how mu9h did the phone 9all
9ost: This then is relted to other 1uestions li)e0 who is the customer> is the customer
su'scri'ed to some )ind of pln or 'undle tht m)e the phone cll free>
The sme pplies to ny other type of e%ent" # we' ser%er will 'e 'le to tell the /8
ddress tht downloded music file( 'ut it is unwre of the price the customer should
py for this file"
The process of ssigning price to n e%ent is wht we cll rting"
jBilling hs %ery d%nced 'uilt-in rting cp'ilities 'sed on
rules mnged 'y Business $ules ,ngement System" #ll the
dt contined in the e%ent is %il'le for rting" 7or e-mple( the
price of phone cll will gretly depend on the dy( time( length(
origin( destintion( etc" These re dt fields contined in the e%ent tht re mde
%il'le 'y the medition process to the rting engine of jBilling"
Mediation and Rating with jBilling
!et5s now go o%er high le%el description of how medition nd rting wor) with jBilling"
,ost of the remining of this document will 'e detiled descriptions of the modules
nd processes mentioned in this o%er%iew" ;ou cn use this initil o%er%iew s rod-
mp to ll the pieces tht come together to pro%ide medition nd rting in jBilling"
There re two different wys to get n e%ent processed 3medited4" :ne is to h%e in
file or 6B for 'tch processing( nd nother one is to do it in rel-time 'y clling n #8/
method when n e%ent hppens"
!et5s strt with digrm of 'tch scenrio0
Rating is the
process of giving
a price to an
event.
1" The e-ternl system pro%ides ser%ice to customer" This is typiclly
telephone switch for phone clls( 'ut it could 'e ny other system( li)e we'
ser%er ser%ing content to internet users"
1" The e-ternl system s%es n e%ent record with the detils of the ser%ice
pro%ided to the customer" The storge is usully te-t file( 'ut it could lso 'e
reltionl dt'se 3$6B,S4 or other types of storge" 7or the telephone switch
e-mple( n e%ent hppens e%ery time phone cll is ttempted" The e%ent
records re then typiclly clled 5Cll 6etiled $ecords5 3C6$4" The e%ent will
h%e ll the dt lter needed to rte nd 'ill the customer"
2" The internl jBilling scheduler strts the medition process" This hppens
periodiclly( typiclly dily" The medition process will find the configured plug-ins
tht h%e the logic on how to red the e%ents nd wht to do with them" This
Illustration 1: Overview of jBilling's ediation flow!"atch#
component is just n 5orchestrtor5( it does not )now how to do the ctul
processing" 7or tht( it fully relies on plug-ins"
?" The medition process will red the configurtion records" Ech configurtion
record points to reder plug-in" The process then clls ech of these reder
plug-ins"
4" # reder plug-in )nows how to red e%ents0 their loction( the formt( how to
di%ide record in meningful dt fields" Still( the scope is limited to reding" The
reder does not )now the mening of these dt fields"
@" The dt of group of records is now returned s <% o'jects to the medition
process"
A" The medition process clls the processor plug-in with the dt of n e%ent
record"
B" The processor plug-in cn decide wht to do with the record" The stndrd
implementtion is rules-'sed plug-in" This mens tht you will 'e using B$,S
to process the e%ent" This step gi%es mening to the dt" Cere is where field
in record is trnsformed into units( or dte( or wy to identify who( in the
'illing system( should 'e pying for this e%ent"
D" The process returns to the medition process red-to-use 'illing dt 'out the
e%ents0 wht item ws sold( when the e%ent too) plce( nd the customer
in%ol%ed in the e%ent"
E" The medition process cn now m)e simple cll to the jBilling core to crete
or updte purchse order" This lst step gets the 'illing system updted with
the cti%ity the customer did when intercting with the e-ternl system in the first
step"
!et5s now re%iew this sme digrm( 'ut in rel-time scenrio0
/n rel-time scenrio( the records re not stored" /nsted( they re sent s they hppen
to the 'illing system" The 'o%e illustrtion shows 'siclly the sme flow s the 'tch
digrm( 'ut in this rel-time cse the reders re gone"
The reders h%e only one concern( nd it is to red records from there the e-ternl
system s%ed them" /f tht is not needed( then we don5t need reders" The e-ternl
system will 'e clling jBilling e%ery time new e%ent hppens 3or is 'out to hppen( s
we5ll see lter4"
This rel-time cll is done using the stndrd jBilling #8/ 3usully using S:#8 s
protocol4" There re specific methods in the #8/ to llow the processing of e%ents 'y the
medition process" /t is worth noting tht the medition process itself( the module( is
unwre of how the records re deli%ered to it" /t does not )now if the records re
coming from file tht ws red 'y reder( or they cme through the #8/ in rel-time"
This is importnt( 'ecuse it mens tht the configurtion of the medition process
remins unchnged regrdless of the deli%ery mechnism or source of the C6$s" This
will then llow for setups where 'oth 'tch nd rel-time processing re in plce"
pdating orders
The pre%iew section ends with step 10( when the medition process updtes or cretes
n order to reflect the e%ent into the customer5s ccount" # fir 1uestion t this point is
wht order is 'eing updted> when does the medition process crete n order( n
when does it just updte n e-isting one> wht )ind of order will it crete>
Illustration $: Real%tie ediation data flow
The e%ents 'eing processed 'y the medition process re
purchses of ser%ices from your customers" #s such( to trnslte
this to the jBilling world( they h%e to 'e put into purchse
orders"
The medition process( 'eing fully utomted process 'y
nture( needs to decide how the e%ents will 'e plced into orders" &he ediation
process will onl' create or update one time orders" The reson for this is simple0 the
e%ents 'egin processed re nturlly one-time purchses"
/t would not 'e prcticl to crete one order for e%ery e%ent0 customer cn end up with
hundreds or more orders e%ery month" /t is 'etter to updte n e-isting one-time
purchse order( nd just h%e one purchase order per "illing c'cle"
This 'rings us to the concept of 5min su'scription50 recurring order tht sets the length
of customer 'illing cycle s fr s the medition process is concerned" The min order
is recurring0 it genertes n in%oice periodiclly" The only difference 'etween 5min
su'scription5 nd ny other recurring order is flg the m)es the order 5min
su'scription50
# customer cn only h%e one recurring order set s 5min su'scription5" /n this recurring
order you will usully dd periodic recurring chrges( li)e the 5pln5 fee" This is not
re1uirement( you could h%e min su'scription with totl mount of .ero" The
medition process will loo) into the min su'scription order to decide if new order
needs to 'e creted for the e%ent 'eing processed( or n e-isting order cn 'e updted"
This is 'siclly logic 'sed on dtes0 the dte of the e%ent( nd the dtes of the min
order"
There will 'e only one one-time order with chrges coming from e%ents per period" This
is( if the min order is monthly order( then there will 'e only one one-time order with
e%ents creted 'y the medition process per month"
#n order creted 'y the medition process will h%e some
clrifiction te-t in the 5notes5 field of the order" /t will simply
sy tht the order ws creted 'y the medition process"
Beside this( there isn5t nything different 'etween this order
n one tht you crete( nd nothing pre%ents you from editing the orders creted 'y the
medition process0 it is just not good prctice" #lthough it should not 'other the
medition process( it is just less confusing if you crete your own orders nd le%e the
ones creted 'y the medition process untouched"
!et5s see n e-mple0 customer hs recurring order( monthly( set s min
su'scription" This order strted on <nury 1@ nd hs generted two in%oices( one for
the period 1F1@ to 2F14 nd nother one for the period 2F1@ to ?F14"
&he ediation
process converts
external events into
purchase orders
Illustration (: &he 'ain su"scription' flag
&he ediation
process never
updates the ain
su"scription order
*hen the medition process runs there re three e%ents for this customer0
1" ?F1B for 10G
2" ?F24 for @G
?" 4F1@ for 1G
7or e%ent 1( the medition process cretes new one-time purchse order with n order
line of 10G" The ctul item( 1untity nd price for the order line re prt of the medition
rules nd will 'e co%ered in detil in lter chpters"
7or e%ent 2( the medition process finds tht there is lredy one-time purchse order
tht co%ers the period ?F1@ H 4F14" /t then just updtes this order 3the one creted when
the pre%ious e%ent ws processed4" 6epending on other fctors( this cn 'e just n
updte on the 1untity of n e-isting order line( or new order line"
7or e%ent ?( the medition process cn not find one time order for the period tht strts
on 4F1@( so it cretes new one"
The wy the medition process identifies one-time order for specific period of time is
'y chec)ing the 5cti%e since5 field" The first order creted for e%ents 1 nd 2 will h%e n
cti%e since of ?F1@( while the second one will 'e 4F1@" The medition process )nows
tht this orders co%er only one month 'ecuse tht is the recurring period of the min
su'scription order"
/n typicl configurtion( when the 'illing process runs to produce n in%oice for the
period strting on ?F1@( it will find two pplic'le orders0 the min su'scription order nd
the one-time order with the e%ents from the medition process" /t then genertes single
in%oice for the customer with ll the compiled chrges= the customer does not wnt to
)now nything 'out medition processes nd orders( just simple in%oice with the right
chrges will do"
The 'illing process in this cse will ignore the other one-time order 'ecuse its cti%e
since is too fr in the future( tht order will 'e pic)ed up the following month" Cowe%er(
the first one-time order will not 'e pic)ed up the ne-t month 'ecuse( 'eing one-time
order( its sttus is set to 5finished5 fter 'eing pplied to n in%oice"
Chapter 2
The Mediation Process
Overview
The medition process is the component tht orchestrtes nd coordintes ll the steps
needed to complete the medition" By itself( it doesn5t )now much on wht to process
nd wht to do with the e%ents" 7or tht( it chec)s in the jBilling plug-in configurtion to
find out the <% clsses tht cn t)e cre of those ts)s"
The medition process is implemented s stteless session 'en( the clss nme is
MediationSessionBean" The internl jBilling scheduler will cll this clss to tell it tht it
is time for the medition process to t)e plce" The clss is cting s 5fcde5 to the
e-ternl world to llow n esy entry point where to trigger the medition process"
Deployment
The medition module is em'edded with jBilling" ;ou don5t need to do ny specil
instlltion specific to the medition module" /nstlling ser%er with jBilling is ll you
need to h%e the medition module instlled"
This does not men tht there ren5t ny deployment options" ;ou cn run your
medition process in the sme physicl ser%er s the jBilling ser%er( or you cn run it on
its own in different mchine" This second option is usully recommended 'ut for the
lest demnding scenrios( the medition process re1uires good del of processing
power"
#s mentioned 'efore( jBilling ser%er cn do e%erything or just some 'illing functions"
To cti%te or decti%te role( we need to edit the configurtion file
5jbilling.properties5( locted in the directory jbilling/conf"
The following is n e-mple where ll the roles re cti%e( this ser%er will perform ll the
'illing functions0
# if the daily batch includes running the billing process
process.run_billing=true
# if the daily batch includes running the ageing process
process.run_ageing=true
# if the daily batch includes running the partner process
process.run_partner=true
# if the daily batch includes running the order expiration
notification process
process.run_order_expire=true
# if the daily batch includes running the invoice reminder
notificationprocess
process.run_invoice_reminder=true
# if the daily batch includes running the overdue penalties process
process.run_penalty=true
# if the daily batch includes running the list statistic collection
process
process.run_list=true
# if the daily batch includes running the credit card expiration
notification process
process.run_cc_expire=true
# if the daily batch includes running the mediation process
process.run_mediation=true
&ow( if we wnt to deploy medition-only ser%er( we only need turn ll the 'o%e
properties to 5flse5( e-cept the 5process.run_mediation property tht should remin
5true5"
*e could e%en h%e multiple ser%ers doing medition" #t the time( this re1uires
distri'uting the e%ent files to ech jBilling ser%er doing medition0
/n the 'o%e illustrtion( we h%e the e-ternl system trnsferring the e%ent files to two
different medition ser%ers" Those ser%ers re fully dedicted to process medition
e%ents" They h%e deployed loclly ll tht is needed to process those e%ents( so they
cn interct directly with the dt'se ser%er where ll the 'illing informtion is stored"
To complete the e-mple( there is lso present nother jBilling ser%er tht is doing
e%erything 'ut medition0 ser%ing re1uest to we' clients( ser%ing we' ser%ices( running
the 'illing process( etc"
The 'o%e scenrio is certinly possi'le( 'ut it isn5t li)ely one" E%en in %ery demnding
scenrios( single ser%er dedicted to processing e%ents is enough to deli%er the
throughput re1uired" Since %ersion 2"1( jBilling5s high-performnce for C6$ processing
hs mde multi-ser%ers medition deployments unnecessry"
Illustration ): * deplo'ent with two ediation servers
erformance
# common concern when thin)ing 'out medition is performnce" #fter ll( the mount
of e%ents to process in dily 'sis cn 'e huge( e%en for medium si.ed compnies" /n
typicl 'illing system( the medition process is done in three %ery defined phses0
medition( rting nd ccount updtes"
The first one is mostly 5dt processing5 process0 filter out
records tht re not needed( com'ined others( nd in generl
le%e the records in formt tht is esy to rte" Then it comes
the rting tht ssigned the prices to ech record" 7inlly( the 'illing system is clled to
updte the customer5s ccounts with the new chrges"
Some systems m)e clims on performnce relted to processing records( when they
only do one of these three steps0 they only rte( or the only medite" /n jBilling( ll these
steps re still there( 'ut they re done in one single process" ;ou cn e-pect
performnce of hundreds of records per second with ll three phses included in the
processing"
E%en 'etter is the fct tht ll this is done without hrd-coding your medition nd rting
rules logic in <% or C lnguge( nor with hedche-producing I,! file configurtions"
/nsted( jBilling uses rules-'sed processing method( em'edding the <Boss rules
3drools4 rules engine to represent the 'usiness rules needed for medition s e-ctly
tht0 'usiness rules to 'e processed 'y rules engine"
Batch si!e
The )ey to jBilling;s remr)'le speed while using rules-engine is the wy it
processes the e%ents0 it does not t)e one e%ent nd sends it to the rules engine for
medition( then rting( then updte the customer ccount" /t does ll those three thing in
one cll to the rules engine"
7urthermore( it t)es group of e%ents nd send them for processing to the rules
engine" The medition module will s) the reder plug-in for group of records to
process( nd it will pss this group to the medition plug-in 3typiclly the rules 'sed
one4"
The %lue of how mny records to process t time is then prt of the reder5s
prmeters" The stndrd reder plug-ins tht come pc)ged with jBilling t)e the
prmeter batch_size to define this %lue" The defult is 100"
The higher this num'er( the more memory you will need for the medition process nd
the more the rules engine will h%e to do to orchestrte the mny e%ents tht re t ny
gi%en time in the memory conte-t" :n the other hnd( the smller this num'er the more
times the rules engine is clled( which represents some o%erhed"
Thus( the idel num'er is not s simple s 5the higher the 'etter5" # 'tch si.e of 100
3the defult4 is usully good" /n mny cses the 'est performnce cme from %lues
'etween 10 nd ?0"
There re mny fctors tht will influence the idel 'tch si.e0 the formt of your records
3how mny fields( dt types( etc4 nd the type nd num'er of rules re the most
importnt" The esiest wy to find you idel 'tch si.e is to simply e-periment with few
different %lues" 6o this only fter you h%e completed ll your rules nd your
configurtion is fully tested( otherwise you might 'e t)ing redings on mo%ing trget"
jBilling can full'
process hundreds of
records per second.
!st 'ut not lest( do )eep in mind tht 'y defult( the Tomct instlltion tht comes
with the stndrd jBilling hs configured m-imum usge of $#, of 2@A ,B" This is
%ery little memory for the medition process" 6epending on your 'tch si.e( you will
h%e to increse this" T)e loo) to the catalina.sh or catalina.bat files" There you cn
find the <9, prmeters tht include the m-imum memory"
Bu""er si!e
7or file-'sed reders( there is lso the si.e of the 'uffer used when reding dt from
the C6$ file" These reders t)e the prmeter buffer_size" The defult is D1E2 nd the
%lue is in chrcters" *hen the reder hs to ccess the file with records in the hrd
dri%e( it will spend some time just re1uesting ccess to tht file to the operting system"
This o%erhed is specilly high if( to red the num'er of records tht the 'tch si.e
needs( the reder hs to go do mny /: interctions with the hrd dri%e" The idel 'uffer
si.e then depends on the 'tch si.e nd the si.e of ech record"
This prmeter is used 'y jBilling only s prmeter to the <% o'ject
Buffered$eder"
Rules optimi!ation
The min d%ice 'out rules optimi.tion is to %oid doing it" ,)e sure tht you h%e
lredy tried the pre%ious performnce optimi.tions 'efore strting optimi.ing rules" /n
most cses( e%en the worst written rules 3from performnce perspecti%e4 perform
pretty well"
C%ing sid tht( there re some typicl cses tht cn speed up the process
significntly0
*void 'regex' and favor '++' as operators
# common implementtion of rte crds in%ol%es decision t'le with one line per rte
nd 5prefi-5 to mtch the phone num'er clled nd the ssign price" This is %ery esy
to implement nd usully hs n ccept'le performnce" Cere is n e-mple from
rel cse0
name == "dst", strValue matches "^$param.*", resultId == $resultId
;et( the rules engine does not li)e the 5mtches5 opertor %ery much" *ith it( it cn5t
optimi.e how the rules 5net5 is formed in memory nd it hs to do 'rute force
comprison"
Since these rte crds usully h%e thousnds of rows 3which trnslte to thousnds of
rules4( you cn see significnt increse in performnce for the price of more
complicted decision t'le"
The tric) is to replce the rule with the 5mtches5 opertor for mny rules with the 5JJ5
opertor( ech of these new rules wor)ing on one digit of the prefi- tht you need to
mtch" The result is more decision t'le with mny more columns( 'ut they cn 'e
well rrnged so they re not too hrd to del with"
The rules engine will now 'e 'le to do node shring nd node inde-ing of these
thousnds of rules"
,rite rules using the sae order
The order of conditions within rule nd e%en the order of constrints within single
condition ffects the order of within the net of rules tht the rules engine cretes" This in
turn will llow the rules engine to shre nodes" The more nodes rules shre with other
rules( the 'etter"
!et5s see simple e-mple" T)e loo) to the following two rules0
rule 'user setter from username'
when
$compan ! "ompan#$%& '
$result ! (ediation)esult&step == (ediation)esult.*$+,_-_*$.)$, userId == null'
$field ! ,ricin/0ield& name == "userfield", strValue matches "^1a234.*" resultId ==
$result.id'
then
modif& $result ' 5
set6serId& /et6serId0rom6sername&$field./et*trValue&', $compan./etId&'' '7
8
end
rule 'user setter from id'
when
$result ! (ediation)esult&userId == null, step == (ediation)esult.*$+,_-_*$.)$'
$field ! ,ricin/0ield& name == "userfield", strValue matches "^192:4.*" resultId ==
$result.id'
then
modif& $result ' 5
set6serId& /et6serId&$field./et*trValue&', $compan./etId&'' '7
8
end
:ne of the cn 'e re-orgni.ed to mtch the sme 5se1uence5 of rules s the other rule"
/f we t)e the second rule nd rewrite it li)e this0
when
$result.id'
then
modif& $result ' 5
8
end
Then the rules engine will 'e 'le to shre mny of the conditions tht 'oth rules need"
This mens smller nd fster 5net5 of rules in the memory conte-t"
,rite rules ordering "' the ost restrictive condition first
<ust li)e with stndrd procedurl lnguges( if you strt chin of 5ifs5 with the one tht
is most li)ely to fil( then you will 'e s%ing processing time 'y %oiding doing
unnecessry tests of conditions"
!et5s t)e the pre%ious rule" The condition of e-istence of the o'ject 5"ompan#$%5 if
poorly plced" This will ctully ne%er fil" /t is 'etter to push this condition to the 'ottom
of the rule0
when
$result.id'
$company : CompanyDTO( )
then
modif& $result ' 5
8
end
The rest loo)s fine" /t is good prctice to strt medition rule with condition 'out
its step" This is 1uite restricti%e nd it is esy to remem'er( which leds to ll the rules to
strt the sme wy for utomtic node-shring"
!cheduling
:K( we h%e now ser%er tht is going to 'e doing medition" *e only hd to instll
jBilling nd m)e sure tht the 5process.run_mediation property is set to 5true5"
&ow( when is it tht the medition process will t)e plce> #nd how often will it run>
7or this( we lso use properties in the 5jbilling.properties5 configurtion file" The
two properties in%ol%ed re the sme used to run the 'illing process0
# !hese t"o properties set the fre#uency of the jbilling batch
process
# !he fist property indicates at "hat time of the day the trigger
has to
# happen for the very first time. $fter this first run you "ill
need % minutes
# &specified by process.fre#uency' to run the trigger again.
# !he first property is optional. (f it is not present) then the
next trigger "ill happen at
# startup * minutes indicated in process.fre#uency.
# time+ ,,,,MM--.//mm &a full date follo"ed by // is the hours in
01hs format and mm the minutes'.
process.time=
# fre#uency+ the number of minutes bet"een runs
process.fre#uency=203
/n fct( these properties dictte when the 5'tch5 process( in generl( will run" *ht will
'e included in tht 'tch process is then up to the 'oolen properties tht strt with
5process"5 referred in the pre%ious section"
/n the pre%ious e-mple( the 'tch process 3tht will 'e including medition4 will run
e%ery 12 hours( strting 12 hours from the moment the ser%er goes up"
The list of mediation processes
*hen medition process strts( you cn %erify tht this hppened 'y t)ing loo) to
the medition process list" Clic) on 58rocess5( then on 5,edition5 to ccess the list
screen0
*hen the process is on-going 3it hs strted( 'ut hs not finished yet4( the 5End5 nd
5:rders updted5 columns will 'e 'ln)" !et5s re%iew ech column5s mening0
/60 This is simple uni1ue identifier of this medition process"
Configurtion /60 Cere you cn see which medition configurtion the process used for
the processing" This is useful 'ecuse you cn h%e multiple configurtion present t
the sme time" The su'ject of medition configurtions is co%ered in the ne-t section"
Strt0 The time the medition process strted"
End0 The time the medition process ended"
:rders updted0 Cow mny orders this process creted or updted" /t is common tht
this num'er is e1ul to the num'er of records present in the files processed( 'ut it
doesn5t h%e to 'e" There re mny circumstnces where records do not trnslte into
n order updted"
Illustration -: &he list of ediation processes
Chapter 3
The Mediation
Configuration
:nce the medition process is setup( the ne-t step is to dd 5medition configurtions5" #
5medition configurtion5 tells the medition process where the e%ent records re nd
how to red them 'y pointing to plug-in tht )nows how to perform those ts)s"
;ou need to h%e t lest one medition configurtion for the medition process to do
something( if there ren5t ny configurtions present when the medition process is
triggered( then nothing will hppen"
To mnge the medition configurtions clic) on 5System5 nd then on 5Configurtion50
To crete new configurtion clic) on the lin) 5#dd new configurtion5" The /6 nd
cretion dte will 'e gi%en 'y the system" ;ou cn enter nme to lter identify this
configurtion"
;ou will need one configurtion per 5type5 of e%ent" 7or e-mple( if you need to process
%oice clls nd S,S messges( then you will need two configurtions" ;ou cn nme
the first one 59oice5 nd the second one 5S,S5" This ssumes tht those two e%ent types
re stored in their own files( with their own formts"
The order num'er tells the medition component which configurtion to use first( which
one is ne-t( etc" The plug-in /6 points to reder plug-in" This plug-in is the component
tht will do the ctul record reding( nd it is co%ered in the ne-t section"
Chapter 4
Readers
The readers plug#ins
# medition configurtion needs the /6 of reder plug-in" This is the wy the medition
process ctully )nows wht clss is going to 'e doing the record reding" Becuse
there is one-to-one reltionship 'etween medition configurtion nd reder plug-
in( you will only need se%erl configurtions when you h%e the need to use mny
different reders" This hppens when you h%e files with different formts or %rious
sources li)e files nd dt'ses ll of them with e%ents to process"
;ou cn dd reder plug-in just li)e ny other plug-in from the 58lug-ins5 screen" Clic)
on 5System5 then 58lug-ins50
Currently( jBilling comes with four possi'le reder plug-ins( one for files with fields
seprted 'y chrcter( nother one for files with fi-ed record length( generic
<6BC dt'se reder( nd ,ySL! dt'se reder0
Separator4ile5eader0 This plug-in cn red te-t files where the fields re
seprted 'y string( usully chrcters li)e comm"
4ixed4ile5eader0 This plug-in cn red te-t files where the fields occupy e-ct
positions in the record( nd the record itself is lwys the sme length" Ech field
is not seprted 'y ny chrcter"
6-B75eader0 This plug-in cn red records from dt'se using <6BC" /t
supports two schemes for mr)ing which records h%e 'een red" This first wy
is 'y remem'ering the lst id red 'y the lst process( then only reding records
with ids greter thn this %lue" The second wy is 'y using timestmp column
to mr) the red records"
MyS895eader0 This plug-in is n e-tension of the <6BC$eder plug-in nd
pro%ides some defult %lues nd simpler plug-in prmeters for reding from
,ySL! dt'ses"
The "ile reader plug#ins
The file reder plug-ins hold the informtion of where the record files re locted nd
wht formt it is tht they follow"
The following prmeters re in common to 'oth reders0
format_file0 This is re1uired prmeter" /t is the nme of the formt file" *e will
discuss the content nd function of the formt file in the ne-t section"
format_directory0 The directory where the formt file is locted" This is n optionl
prmeter( if not present( the %lue of the property 5'seMdir5 is used with n ppended
5medition5 directory" The defult directory is then 5jbilling/resources/mediation5"
directory0 The directory where the e%ent files re locted" This is n optionl
prmeter with the sme defult s the pre%ious one"
suffix0 This is the lst prt of the file nme to 'e included for processing 3lso )nown
s 5file e-tension54" /n the pre%ious illustrtion we see the 5cs%5 suffi-" This mens tht
only files ending on 5cs%5 will 'e t)en for processing" ;ou cn use 5#!!5 s %lue to
indicte tht there should not 'e ny filtering( ll files locted in the directory should 'e
processed" This is n optionl prmeter( it defults to 5#!!5"
rename0 This is 'oolen prmeter( possi'le %lues re 5true5 or 5flse5" /f 5true5( the
medition process will renme file fter it hs 'een fully processed( ppending the tg
5"done5 to its originl nme" This wor)s well /n com'intion with the 5suffi-5 prmeter to
%oid processing the sme file twice" This is n optionl prmeter( it defults to 5flse5"
date4ormat0 This is the formt tht the reder e-pects to find dte %lues in the file"
*hen field is dte( the reder will prse it so it cn 'e lter hndled s dte 3rther
tht string of chrcters4" ;ou will 'e 'le to tell the reder which fields re dtes in
the formt file" The dte formt hs to comply with the ptterns set 'y the stndrd <%
clss 5Simple6te7ormt5( these re descri'ed here" This is n optionl field( it defults
to 5yyyyMMdd.//mmss5"
The Separator4ile5eader plug-in hs n dditionl prmeter0
separator0 The chrcter or chrcters the seprte ech field" This is n optionl
prmeter( it defults to comm 35(54"
batch_si:e0 The num'er of records to red t time( for group processing" This gretly
ffects the performnce of the process( see the 8erformnce section for more
informtion"
remove8uote0 /f the reder should remo%e surrounding 1uotes from ech field" This
would llow the content of fields to h%e the seprtor chrcter s content"
auto(-0 /f true( the reder will ssign %lue to the )ey field for e%ery record"
buffer_si:e0 The num'er or chrcters tht the reder will use to fill its 'uffer e%ery
time it ccess file" This is performnce prmeter( see the 8erformnce section for
more detils"
The $%B& reader plug#ins
To use the <6BC reder plug-ins( m)e sure the <6BC dri%er for your dt'se is
copied to the jbilling/lib directory"
Re9ord mar<ing method
By defult( the 5lst id red5 mr)ing method is used( which s%es the lst id processed
'y the lst process run in the preference M;-($!(<=_6-B7_5;$-;5_9$S!_(- &;<'" /t will
only red records with ids greter thn this %lue"
/f the timestamp_column_name plug-in prmeter is set 3or the defult
jbilling_timestamp column is found in the t'le4( the timestmp mr)ing method is
used( which only reds records tht h%en5t 'een timestmped nd timestmps them
fter they re red" The d%ntge of this method is tht it llows composite primry
)eys( 'ut possi'le disd%ntge is tht it must updte the t'le"
Plug5in parameters
The following prmeters re in common to 'oth reders0
batch_si:e0 The num'er of records to red t time( for group processing" This gretly
ffects the performnce of the process( see the 8erformnce section for more
informtion"
database_name0 The nme of the dt'se" 6efult is jbilling_cdr"
table_name0 The nme of the t'le to red the records from" 6efult is cdr"
>ey_column_name0 #llows single )ey column to 'e specified" 6efult is to
utomticlly use the primry )ey from the t'le5s metdt" Should this fil( it defults
to id"
username0 The usernme for connecting to the dt'se" 6efult is S$"
pass"ord0 The pssword for connecting to the dt'se" 6efult is n empty string"
order_by0 #llows columns to 'e specified for the <5-;5_B, cluse in the SL! tht
selects the records for processing" This is importnt for the 5lst id red5 mr)ing method(
which ssumes the lst id is the highest id" 6efult is to order 'y primry )ey scending"
timestamp_column_name0 &me of the column used for timestmping columns" #lso
indictes to the reder tht the timestmp record mr)ing method should 'e used"
6efult is to chec) for jbilling_timestamp column( nd if found( the timestmp
record mr)ing method is used( otherwise the 5lst id5 method is used"
"here_append0 #llows ppending SL! to the ?/;5; cluse of the SL! tht selects the
records for processing" ,inly used for testing purposes"
6-B75eader specific prmeters0
driver0 The <6BC dri%er string" 6efults to the CSL!6B dri%er string"
url0 The <6BC 2$! string" 8ro%iding %lue for this prmeter cuses database_name
prmeter to h%e no effect" 6efults to n CSL!6B 2$! for test dt'se found in
the jbilling/resources/mediation directory"
MyS895eader specific prmeters0
host0 The ,ySL! ser%er hostnme or /8 ddress" 6efult is @02.3.3.@
port0 The ,ySL! ser%er port" 6efult is AA3B
&reating you own reader plug#in
$eders re 'usiness rules plug-ins" This is design decision ment to fcilitte
creting new reders without h%ing to modify jBilling" ;ou cn e-tend some of the
e-isting reder plug-ins or crete your own to
stisfy re1uirements tht go 'eyond wht the
defult reders do"
E-mples of situtions where you would need you
own reder re0 your files re not plin te-t( they
do need some dditionl processing 'efore the records re red'le0 decryption or
jBilling's "usiness rules plug%in
architecture is covered in detail in
the '.xtension Guide' docuent
decompression for e-mple" #nother possi'le scenrio is when your records re not in
file( 'ut in some other rchi%e li)e reltionl dt'se"
&ote tht none of the pre%ious e-mples mention the formt of the file" /f wht you need
is reder for te-t file for prticulr formt of the records 3num'er of fields( loction
of the fields( etc4 then you do not need to de%elop your own reder plug-in" ;ou just need
to pro%ide the record formt to the e-isting reders" This is e-plined in the ne-t chpter"
/f you do h%e to de%elop you own reder plug-in( doing it is pretty simple( 'ut li)e ny
plug-in de%elopment( it does re1uire <% progrmming" The plug-in ctegory is 1@( for
the interfce 5Mediation5eader5"
Reader plug#in responsi'ilities
!i)e ny 'usiness rule plug-in( reder hs to implement <% interfce pro%ided 'y
jBilling nd e-tend the clss 5Cluggable!as>5" 7or this ctegory( there re two methods
tht your plug-in needs to implement0 record reding nd %lidtion"
$ecord reding comes from the fct tht the interfce (Mediation5eader ctully
e-tends the stndrd <% interfce (terable" Thus( you need to pro%ide n
implementtion of the method 5itertor5 which returns n o'ject (terator" There isn5t
much to 'e sid 'out this o'ject tht is not lredy well documented in the stndrd
<% documenttion" This o'ject represents n itertor( li)e cursor tht reder records
from source"
The itertor will iterte through o'jects type 5ecord" This is jBilling clss( it holds one
record with ll the fields"
Cere is the core of wht reder plug-in hs to do0 red record from the e%ents source
nd crete 5ecord o'ject with the informtion e-trcted from such source" Ech field
hs to 'e encpsulted in Cricing4ield o'ject( which is lso %ery simple o'ject"
*hen you red field from record( dd it to the record 'y clling 5ecord.add4ield&'"
/n fct( it will do this in groups" /t will red group of records nd return it s 9ist" This
is not re1uirement( you cn lwys red only one record( put it in n $rray9ist( nd
return tht" #s good prctice( it is 'est if your plug-in respects the %lue of the
prmeter 5batchSi:e5" #ny clss tht e-tends $bstract5eader hs ccess to this
prmeter" /t signls to the plug-in the e-pected num'er of records it should red in one
itertion( its purpose is mostly performnce optimi.tion"
#nother function your plug-in is responsi'le is %lidtion" The scope of the %lidtion is
typiclly just the prmeters of the plug-in0 re ll the re1uired prmeters present> :f
course( you cn %lidte nything you wnt here" /f there re one or more errors( simply
dd the error messges to the %ector you re getting s prmeter for this method nd
return flse"
&ode re#use
The e-isting plug-in reders might not do ll you need reder to do( 'ut they might do
some useful things lredy" Before strting your own reder from scrtch 3directly
implementing Mediation5eader4( it is good ide to m)e sure you won5t 'e writing
code tht is lredy there"
/f you won5t 'e reding file or from dt'se 0 /f your records re in some other type
of storge tht is not plin te-t files( you might wnt to still use the formt ser%ice
pro%ided 'y the clss $bstract5eader" This mens tht you cn e-tend this clss nd
dd the ctul reding cp'ilities to to it" ;ou will 'e 'le to cll 5get7ormt5 nd get
formt o'ject creted from the formt I,! file" This will m)e your reder plug-in much
more fle-i'le tht if you hrd-code the formt into the reder"
/f you will 'e reding file0 The clss $bstract4ile5eader reds records from plin-
te-t file( le%ing the prsing of record 3di%iding the record on mny different fields4
unimplemented" /f ll you need is different wy to 're) record into mny fields( you
cn e-tend this clss nd simply implement the method split4ields"
T)e loo) to the plug-in Separator4ile5eader" /t is %ery simple( 'ecuse ll the wor)
is done 'y $bstract4ile5eader" Bre)ing the record into mny fields is %ery esy in
this implementtion"
/f you will 'e reding from dt'se 0 6-B75eader pro%ides num'er of e-tension
points" 7or e-mple( o%erriding the get8ueryString&' method llows custom SL!
1uery to 'e used for selecting records to process" :%erriding the record5ead&' ndFor
recordCrocessed&' methods could llow different record mr)ing methods to 'e
implemented"
Chapter 5
The record format
"M# format description
The reder plug-ins pro%ided with the stndrd jBilling distri'ution cn red files in ny
formt" This is possi'le 'ecuse the description of the formt is in n I,! file( rther
thn 'eing hrd-coded into the plug-in" /nsted of h%ing one plug-in per switch( we cn
h%e one plug-in for ll the switches tht write e%ents in file with the fields seprted
'y chrcter" The ctul formt of the records will 'e pssed to the plug-in s
prmeter( the sme pplies to the chrcters tht cts s field seprtor"
The formt file strts nd end with NformtO tg" /nside this 'loc)( you cn only h%e
NfieldO sections( where ech field is descri'ed" The %lid tgs tht you cn use within
5field5 'loc) re0
nme0 The nme of the field" This should 'e uni1ue 3two fields should not h%e the sme
nme4( nd will 'e the wy to identify the field lter wht using medition nd pricing
rules"
type0 The dt type of this field" 9lid types re 5string5( 5integer5( 5flot5 nd 5dte5" 7or
dte formts( the pttern specified s plug-in prmeter will 'e used to con%ert the
initil string to 6te o'ject" See the 5dte7ormt5 prmeter descri'ed in the 5$eders5
chpter"
strt8osition0 This is only %lid for fi-ed-length formts" /t is the strting position of
field( strting with 515"
length0 This is only %lid for fi-ed-length formts" /t is the num'er of chrcters this field
t)es strting from 5strt8osition5"
durtion7ormt0 *hen field represents unit of time 3seconds( minutes or hours4(
you might wnt to hndle this %lue in seconds" jBilling cn con%ert the field to seconds
if you specify the formt0 use C for hours( , for minutes nd S for seconds" E-mple0
01?0@E( with formt CC,,SS will 'e 1 hour ?0 minutes nd @E seconds" The %lue of
the field will 'e @4@E seconds" 2se integer s type for this field"
isKey0 /f this tg is present 3without content4( it mens tht this field is prt of the record5s
)ey" The record )ey is composed of ll the fields tht h%e 'een 5flgged5 with this tg"
jBilling will chec) 'efore processing record if the )ey hs 'een lredy processed"
This will pre%ent processing the sme record more thn once" /t will lso group ll the
records tht re in se1uence nd shre the sme )ey( treting them s single record"
The record (ey
The )ey of record is one or more of its fields" This )ey hs to 'e uni1ue0 two records
cn not h%e the sme )ey" ;ou h%e to define which field3s4 m)e the )ey using the
5isKey5 tg of the formt file"
jBilling uses this )ey for se%erl ts)s" The first is to group records" Prouping records
cn result in mny lines in the e%ents file to 'e treted s one single record" /f two or
more consecuti%e lines in the files shre the sme )ey( they will 'e grouped into one
record" !et5s ssume file hs the first field s )ey( the rest of the fields re dt0
3333@)AA)D3)033E303D.@3@3@3
33330)AA)@DD3)033E3032.@3@3@3
33330)AA)@133)033E30@D.@3@3@3
3333A)AA)0333)033E300D.@3@3@3
/n the 'o%e e-mple( there re three records nd four lines" The second record is mde
out of two lines 'ecuse of the grouping" &ote tht for grouping to hppen( the lines with
the sme )ey h%e to 'e together( one fter the other"
The other importnt function of the record )ey is to chec) for duplictes" jBilling will
store in t'le the )eys of ll the records lredy processed" #fter reding record 'ut
'efore processing it( jBilling will chec) ginst the t'le of )eys to see if the current
record5s )ey is present" /f so( it will s)ip the record 'ecuse it is considered duplicte"
!et5s see gin the lst e-mple with just simple chnge in the line5s order0
3333@)AA)D3)033E303D.@3@3@3
33330)AA)@DD3)033E3032.@3@3@3
3333A)AA)0333)033E300D.@3@3@3
33330)AA)@133)033E30@D.@3@3@3
&ow the results will 'e 1uite different0 there re lso three records( 'ut they re ll mde
from one line only" The fourth line will 'e ignored( considered duplicte" /t hs the
sme )ey s the second line( nd it is not plced right fter it" The fct tht there is
nother line seprting the two with the sme id m)es ll the difference"
)urging the (eys ta'le
#s mentioned 'efore( there is the dt'se t'le M;-($!(<=_5;7<5- in the jBilling
schem tht holds e%ery )ey processed0
M;-($!(<=_5;7<5-
(-_F;, G$57/$5 @33
S!$5!_-$!;!(M; !(M;S!$MC
;=-_-$!;!(M; !(M;S!$MC
M;-($!(<=_C5<7;SS_(- (=!;H;5
M;-($!(<=_5;7<5- <C!9<7F
This t'le cn grow too 'ig( holding dt tht is too old to 'e useful" /t is good prctice
to est'lish policy on when to delete records from this t'le" /t is up to you to setup the
script nd the method to run it periodiclly" The SL! sttement to delete the records will
loo) li)e0
-;9;!; 45<M M;-($!(<=_5;7<5- ?/;5; S!$5!_-$!;!(M; I today J A3 daysK
The 'o%e pseudo-SL! script would delete ll the records tht re older thn ?0 dys"
Cow old is too old is for you to decide"
$%ample
The following is simple e-mple( in%ol%ing records with only four fields" These records
re usge records for 'ndwidth( we h%e in ech e%ent the totl gig'yte consumption"
!et5s strt with formt tht is comm seprted0
IformatL
IfieldL
InameLrecord_idI/nameL
ItypeLstringI/typeL
IisFey/L
I/fieldL
IfieldL
InameLuser_idI/nameL
ItypeLintegerI/typeL
I/fieldL
IfieldL
InameLtotal_gbI/nameL
I/fieldL
IfieldL
InameLuse_dateI/nameL
ItypeLdateI/typeL
I/fieldL
I/formatL
!et5s ssume tht this file nme is my7ormt"-ml nd its loction is the defult0
jbilling/resources/mediation. This file will 'e descri'ing the formt of n e%ent file
tht hs the fields seprted 'y 5(5" The reder plug-in configurtion will loo) li)e this0
# file with dt tht follows the e-mple formt will loo) li)e this0
3333@)AA)D3)033E303D.@3@3@3
33330)AA)@DD3)033E3032.@3@3@3
3333A)AA)@133)033E30@D.@3@3@3
33331)AA)0333)033E300D.@3@3@3
The 'o%e records show the usge of totl of @000 PB from user ??" The nme of this
file would h%e to end with 5cs%5 to 'e pic)ed up 'y the reder( since this is the suffi- we
dded s prmeter erlier"
!et5s now do the sme e-ercise( 'ut considering tht the record files h%e fi-ed-length
fields" The I,! formt file would loo) li)e this0
IformatL
IfieldL
InameLrecord_idI/nameL
ItypeLstringI/typeL
IstartCositionL@I/startCositionL
IlengthLDI/lengthL
IisFey/L
I/fieldL
IfieldL
InameLuser_idI/nameL
IstartCositionLBI/startCositionL
IlengthL0I/lengthL
I/fieldL
IfieldL
InameLtotal_gbI/nameL
IstartCositionLEI/startCositionL
IlengthL1I/lengthL
I/fieldL
IfieldL
InameLuse_dateI/nameL
ItypeLdateI/typeL
IstartCositionL@0I/startCositionL
IlengthL@DI/lengthL
I/fieldL
I/formatL
*e hd to specify for ech field where does the field strts nd how mny chrcters it
t)es" The plug-in configurtion uses the fi-ed-length clss0
The sme records we sw 'efore will loo) different in the te-t files" The dt is the
sme( only the formt chnges0
3333@AA33D3033E303D.@3@3@3
33330AA@DD3033E3032.@3@3@3
3333AAA@133033E30@D.@3@3@3
33331AA0333033E300D.@3@3@3
;ou re right if you thin) tht the suffi- of the file should 'e other thn 5cs%5" 7or clrity(
this is correct( CS9 indictes comm seprted %lues" The plug-in does not )now this(
so the e-mple will wor) nywy"
Illustration 11: Using a fixed%length plug%in
Chapter 6
Processing with rules
Overview
#t one point in the medition processing 3see step D in the initil o%er%iew digrm4( the
record is redy to 'e processed" The reder pro%ided the records from the e%ent
storge( now something needs to 'e done with these records( we need to gi%e mening
to ll the dt coming s fields in ech record"
The ,edition 8rocess plug-in 'sed on the interfce (MediationCrocess" The defult
implementtion of this plug-in is rules-'sed" This mens tht the ctul logic of wht
the plug-in does is e-ternli.ed to 'usiness rules mnged 'y the 6rools rules engine"
To understnd this section you will h%e to h%e good understnding of rules
processing"
The medition plug-in m)es use of three different
types of rules0
1" ,edition rules0 m)e the 'sic interprettion
of the rw dt coming from the reder
2" /tem mngement rules0 6els with pln(
'undles nd rules li)e0 QThe first 100 units re free( the ne-t re notR
?" 8ricing rules0 #ssigns price to those items tht cn need different price 'sed
on some dt present in the C6$" The 'est e-mple is long distnce clls"
*ediation rules
The plug-in t)es s input the record o'ject 3type 5ecord( see the clss digrm in the
pre%ious chpter4" 7rom this input( its is responsi'le for0
$eturning one or more order lines with the items nd 1untities of wht the
customer is 'uying" This is trnsltion( from e%ent record to ctul items nd
1untities"
6etermine the jBilling user" The e%ent represents n ction done 'y user" /n
other words( which customer orders need to 'e updted>
6etermine the currenc'" Since the e%ent is purchse( jBilling needs to )now
wht is the currency of the purchse"
6etermine the date of the e%ent"
#s you cn see( the responsi'ilities of this component re the %ery core of the medition
process" /t t)es record without ny mening 3just con%eniently con%erted to <%
o'jects 'y the reders4 nd from the record dt it hs to convert the record into
purchse tht the 'illing system understnds" The plug-in will not updte ny orders on
ny of the customer5s informtion( 'ut it will m)e %il'le ll the necessry dt for the
medition process to do this"
+tem management rules
These rules re typiclly in different pc)ge" This is( you h%e group them together in
the B$,S or in seprte file" Then you cn use this pc)ge from the item
mngement plug-in 35ules(temManager04 nd from the medition plug-in" This
techni1ue is useful when you need the sme rules ffecting 'oth the medition process
nd other res of the system without h%ing the rule repeted in mny pc)ges"
&o learn ore a"out rules and
rule%"ased plug%ins/ ta0e a loo0
to the .xtension Guide
docuent.
/tem mngement rules ffect how the items relte to ech other" They cn 'e used to
group items( replce n item with nother one nd other ctions tht re needed to
configure plns nd 'undles"
)ricing rules
!i)e the pre%ious type( this rules re usully in seprte pc)ge of rules" Then you
cn cll them from the pricing plug-in 5ulesCricing!as>0 s well s from the medition
plug-in"
*ith these rules( you will chnge the price of n item" This is %ery importnt when the
defult price is not %lid for the record 'eing processed"
!teps
7or record to 'e fully processed( mny steps h%e to t)e plce" Strting with
ssigning user to the e%ent( to the updte of the user5s ccount" Some steps in%ol%e
mny ctions0
1" *tart0 The process strts 'y determining the user nd dte" #dditionl rules tht
chec) for errors in the record 'elong to this step s well"
2" After user0 The user is )nown now" The currency for this e%ent is set"
?" Current order0 The current order for the user nd the dte of the e%ent is
fetched"
4" "tem resolution0 The e%ent is now mpped to jBilling item 3product4" #
description of the e%ent is lso gi%en to lter list the e%ent in the in%oice detils
section"
@" Pri9ing0 /f the e%ent cn not use the defult item price( then rules tht chnge
this price re triggered in this step"
A" "tem management0 8ln n 'undles rules"
B" A99ount .pdate0 The lst step t)es cre of updting the customer5s ccount
with the chrges resulting from the e%ent"
/t is rre tht you will need to cti%ely write rules for ech step" /n most cses you will
only use the rules tht jBilling pro%ides nd dd some only for few steps" Still( it is good
to 'e fmilir with ll the steps"
The *ediationResult o'ject
The wy jBilling )eeps trc) of the results for ech record is through the
Mediation5esult o'ject" There will 'e one instnce of this o'ject for ech record tht
needs to 'e processed in the memory conte-t0
# Mediation5esult o'ject )nows then the current step this record is in( nd ny
informtion tht hs 'een collected so fr" 7or e-mple( if record is in step 2( then we
cn ssume tht the user(d is set"
,ost of the rules interct he%ily with this o'ject" ;ou don5t need to )now ll its fields( 'ut
it is 'est if you re fmilir with most of them"
Step ,- Start
This is the first step" The result record is mostly empty nd the gol is to set the user nd
dte"
+nput State
The result record is populted only with the dt tht is )nown to the system from the
%ery 'eginning" E%ery other field is empty0 they will 'e set 'y the rules"
recordFey0 The uni1ue identifier of the record" This ws set 'y the reder plu-in"
configuration=ame0 The nme of the configurtion medition" This will 'e
helpful when you h%e mny different configurtions0 S,S( %oice( dt( etc""
persist0 'oolen flg to indicte if this record is 5rel5 record tht needs to 'e
persisted or not" This would 'e flse in scenrios where you re clling the #8/
method 5validateCurchase5 which use the medition module to resol%e record
'ut they should not lter the customer5s ccount" This trnsltes to 5cn the
customer 'uy this5( rther thn 5this customer 'ought this5" The first cse should
h%e persist J flse( the second one true"
Output state
user(d0 set with the /6 of the user tht the e%ent 'elongs to
event-ate0 set with the dte nd time tht this e%ent too) plce"
Things to do
Setting the user /60
;ou cn find the user /6 with ny of the core clsses of jBilling" This function find the
user /6 from user nme0
function Inte/er /et6serId0rom6sername&*trin/ username, Inte/er entitId' 5
6ser=> user = new 6ser=>&username, entitId'7
return user./et+ntit&' ?= null @ 6ser./et+ntit&'./et6serId&' ! null7
8
The clsses you wnt to t)e loo) t re 2serB! nd 2ser6#S34"
Cere there is n e-mple rule tht uses the 'o%e drools function to set the user id
'sed on the C6$ field 5user7ield50
rule 'user setter'
no2loop Abecause the user mi/ht be wron/ and the set /ets a null
when
$field ! ,ricin/0ield& name == "userfield", resultId == $result.id'
$compan ! "ompan#$%& ' A needed to determine a user b its user name
then
modif& $result ' 5
set6serId& /et6serId0rom6sername&$field./et*trValue&', $compan./etId&'' '7
8
end
Setting the 6te0
;ou need to find out the dte of this e%ent" This is typiclly esy( here it is n e-mple
'sed on the 5strt5 C6$ field0
rule 'date setter'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_-_*$.)$, eBent#ate == null'
$field ! ,ricin/0ield& name == "start", resultId == $result.id'
then
modif& $result ' 5
set+Bent#ate& $field./et#ateValue&' '7
8
end
&ote how we get dt type dte out of the field just 'y clling the right getter"
$emo%e ny undesired record0
/f there re conditions tht would m)e record not process'le 3n error( for e-mple4(
it is 'est to del with them erly in the process" Step 1 is the 'est plce"
The following e-mple will finish the processing of clls tht re not nswered0
rule 'cancel not answered call'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_-_*$.)$, done == false '
$field ! ,ricin/0ield& name == "disposition", resultId == $result.id, Balue ?= ".C*D+)+#" '
then
$result.set#one&true'7
retract&$result'7
end
The most importnt prt is tht the record is set s 5done5( nd then remo%ed 3retrcted4
from the memory conte-t"
Trnsition rule
:nce the user nd the dte re resol%ed( we cn mo%e on to the ne-t step" /t is good to
'e wre of this type or rules( 'ut most pro''ly you won5t need to modify them0
rule 'from start to after user'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_-_*$.)$, userId ?= null,
eBent#ate ?= null, currencId == null'
A onl one record for a /iBen user at a time
not& eEists& (ediation)esult& $result.userId == userId, step F
(ediation)esult.*$+,_-_*$.)$' ' '
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_G_.0$+)_6*+)'7
8
end
&ote tht there is specific logic to %oid h%ing two records for the sme customer 'eing
processed t the sme time" This is usully needed to %oid misclcultions in the 5diffs5
section 3the clcultion of how much the customer ccount ws modified 'y the current
record4"
Step .- /"ter ser
&ow tht we )now to whom this record 'elongs nd when it ws done( we cn get to do
ny other step tht re1uires them" By defult( this is only to set the currency"
+nput State
user(d0 set with the /6 of the user tht the e%ent 'elongs to
event-ate0 set with the dte nd time tht this e%ent too) plce"
Output state
currency(d0 the currency tht this e%ent will 'illed on"
Things to do
Setting the currency
;ou pro''ly wnt to use for this e%ent the currency tht the customer uses" This is
simple function tht does tht0
function int /et#efault"urrenc&Inte/er userId' 5
return new 6ser=>&userId'./et"urrencId&'7
8
Cere5s n e-mple rule setting the currency with the 'o%e function0
rule 'currenc setter'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_G_.0$+)_6*+),
currencId == null'
then
modif& $result ' 5
set"urrencId& /et#efault"urrenc&$result./et6serId&'' '7
8
end
;ou could 'e setting the currency using ny other criteri( li)e the loction where the
e%ent hppened for e-mple" The 'o%e is only simple e-mple( 'ut %ery typicl
implementtion"
Trnsition rule
/f ll you re doing in this step is to set the currency( this is how the trnsition rules loo)s
li)e0
rule "from after user to current order"
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_G_.0$+)_6*+),
currencId ?= null, current%rder == null'
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_H_"6))+C$_%)#+)'7
8
end
Step 0- &urrent Order
7etching the current order is typiclly step you cn ignore" ;ou cn consider it n
5internl5 step"
The medition process now needs to )now which one time order to use when dding the
chrges tht will 'e coming from this e%ent" T)e loo) to the section Q2pdting ordersR
for more informtion on this"
+nput State
currency(d0 the currency tht this e%ent will 'illed on"
Output state
current<rder0 The order tht will recei%e the one time chrges coming from this
e%ent"
Things to do
Setting the current order
7inding nd setting the current order is %ery simple0
rule '/et current order'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_H_"6))+C$_%)#+),
current%rder == null'
then
modif& $result ' 5
set"urrent%rder& %rder=>./et%r"reate"urrent%rder&$result./et6serId&',
$result./et+Bent#ate&', $result./et"urrencId&', $result./et,ersist&'' '7
8
end
;ou will rrely h%e to modify the 'o%e rules( 'ut s usul( it is good to 'e wre of it"
Trnsition rule
Cere the rule tht t)es cre of trnsitioning from step ? to step 40
rule "from current order to resolBe item"
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_H_"6))+C$_%)#+),
current%rder ?= null, done == false '
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_;_)+*%>V+_I$+('7
8
end
Step 1- Resol2e )roduct 3+tem4
$esol%ing the product is the %ery core of the medition process" Cere it is where you
ap a 12R to a "illa"le service" *hile the other steps in the medition process needed
little of your wor) 3if t ll ny4( this step will 'e the one where you pro%ide the ctul
logic tht the system needs to follow"
+nput State
current<rder0 The order tht will recei%e the one time chrges coming from this
e%ent"
Output state
lines0 The list needs to get new order lines" Ech new order line will h%e
product 3item4 nd 1untity" This the core of wht the medition process is
ment to do0 mp n e%ent to product( which is represented s n order line in
jBilling"
step0 $ther thn using trnsition rules( the step is typiclly set in the 5then5
section of the rule to step @"
&ew pricing re1uest0 This is not %ri'le to set in the result o'ject" This is
new pricing re1uest tht you might need to do 'y inserting n o'ject in the
memory conte-t"
description0 n e-plntion of the chrges coming from this e%ent 3optionl4"
Things to do
#dd new order line
The result o'ject hs list of order lines tht cpture products tht the customer is
'uying 'ecuse of this e%ent " This mens tht you need to crete n instnce of the
o'ject <rder9ine-!<34 populted with the informtion of the purchse" The following is
n e-mple 3or helper4 function0
function %rder>ine#$% new>ine&Inte/er itemId, =i/#ecimal Iuantit' 5
%rder>ine#$% line = new %rder>ine#$%&'7
line.setItemId&itemId'7
line.setJuantit&Iuantit'7
line.set#efaults&'7
return line7
8
#n e%ent typiclly mps to one product( 'ut it does not h%e to" Tht is why the 5lines5
%ri'le of the record clss is !ist"
!et5s use the 'o%e function in n e-mple rule tht uses the 5durtion5 field from the
C6$ to product 3item4 id 2E000
rule 'resolBe call item and reIuest price'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_;_)+*%>V+_I$+('
$Iuantit ! ,ricin/0ield& name == "duration",
resultId == $result.id'
then
$result./et>ines&'.add&new>ine&G:99,
new =i/#ecimal&$Iuantit./et*trValue&''''7
$result.set*tep&(ediation)esult.*$+,_K_,)I"ICL'7
update& $result '7

,ricin/)esult reIuest = price)eIuest&GM99, $result'7 NN because it will be conBerted to
this...
insert& reIuest '7
end
The importnt prt of this rules is tht the 1untity is coming directly from the %lue of
the 5durtion5 field of the C6$" The rules ssumes tht e%ery C6$ tht mde it to this
step mps to the sme product 32E004" /t would 'e %ery esy to dd more conditions
'sed on other fields for conditionlly mp to other products"
/n this e-mple( product 2E00 mps to generic phone cll" This item will 'e lter
e%luted nd swpped to nother item depending on the custom 'egin su'scri'er 3or
not4 of specific pln 3more on this lter4"
$egrdless( this rule m)es e-plicit pricing re1uest for the product 2D00" The logic is0 if
the customer is su'scri'er( it will 'e free so the price is irrele%nt" But if she is not
su'scri'er( then the product will 'e the 2D00 nd the pricing needs to 'e done 'sed on
rte crd"
$e1uesting price is s simple s dding n instnce of Cricing5e#uest. ,ore on this
in the rting section"
Set the description
/t will m)e it much esier for the customer if n e%ent tht trnsltes to chrge is
e-plined" The typicl wy is 'y h%ing section of the in%oice with list of e%ents with
the description( dte nd price"
jBilling does )eep trc) of e%ery e%ent processed( nd it cn dd description to them"
This is lter used for the in%oice presenttion just descri'ed"
This is n e-mple0
rule 'resolBe call destination'
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_;_)+*%>V+_I$+(, description
== null '
$phone"alled ! ,ricin/0ield& name == "dst", resultId == $result.id'
then
A set mediation eBent description to the call destination
modif& $result ' 5
set#escription&",hone call to " O
$phone"alled./et*trValue&''7
8
end
Trnsition rule
/n this step( the trnsition rule does need some thought" :ne fctor is tht not ll C6$s
will 'e needing pricing step( in some cses the defult price of product pplies"
#nother fctor is tht you might wnt pricing rules to 'e used not only from the medition
process( 'ut from other res of the system 3li)e clls to the #8/ when creting n
order4"
This mens tht the pricing rules will not use the Mediation5esult o'ject t ll" They
will run when the Cricing5e#uest is detected nd lrgely determine the order using the
slience 3 drools ttri'ute4"
!st 'ut not lest( if there is only one rule doing mpping to product id 3li)e the
e-mple 'o%e4 then it is simple nd esy to just set the ne-t step right there" But this is
not n option if there re mny rules doing mpping"
!et5s see simple trnsition e-mple0
rule "from resolBe item to pricin/"
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_;_)+*%>V+_I$+(,
description ?= null '
,ricin/)esult& price == null, pricin/0ields)esultId == $result.id '
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_K_,)I"ICL'7
8
end
Step 5- )ricing
This is n optionl step( only needed if the defult price for the product 3item4 needs to
'e chnged depending on the dt coming from the C6$"
This step is specil( 'ecuse pricing is done in other prts of jBilling( not just when the
medition hppens" #nd since the o'ject Mediation5esult is only for medition( the
pricing step is usully not dependent on this o'ject"
8ricing is done using the Cricing5esult o'ject" This is descri'ed in the 5$ting5 section
of this guide"
;ou will need to re1uest price 'y dding n instnce of Cricing5esult to the
memory conte-t 3done in the pre%ious step4( nd then t)e the price from the o'ject to
chnge the price of the order line tht you dded in the pre%ious step"
+nput State
&ot pplic'le0 Mediation5esult is not in%ol%ed"
Output state
&ot pplic'le0 Mediation5esult is not in%ol%ed"
Things to do
#ssign the new price
The pricing rules should 'e running with higher slience 3priority4 thn the rule tht
ssigns the price for it to wor) well" This is n e-mple0
rule 'price assi/nment'
when
$result ! (ediation)esult&step P (ediation)esult.*$+,_Q_I$+(_(.C.L+(+C$'
$price ! ,ricin/)esult& pricin/0ields)esultId == $result.id, price ?= null '
$line ! %rder>ine#$%& itemId == $price.itemId' from $result.lines
then
$line.set,rice& $price./et,rice&' '7
update& $result '7
end
Trnsition rule
The trnsition is %ery simple( nd it mostly relies in the slience of the rule0
rule "from pricin/ to item"
salience 2-9 A has to run after the pricin/ rules had a chance of A settin/
the price
when
$result ! (ediation)esult&step == (ediation)esult.*$+,_K_,)I"ICL'
,ricin/)esult&pricin/0ields)esultId == $result.id ' A probabl not needed
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_Q_I$+(_(.C.L+(+C$'7
8
end
Step 6- +tem *anagement
This step is similr to the pre%ious one in tht the rules tht do item mngement
typiclly 'elong to different rules pc)ge 'ecuse they re lso needed for ctions
li)e creting n order from the #8/"
Cowe%er( the result o'ject does get modified in this step" *hen step A strts( you finlly
h%e product defined( 1untity of wht ws 'ought( nd price" So it is time to
chnge the current order ccordingly"
#fter this( you will let the stndrd item mngement rules tht t)e cre of 'undles nd
plns to do their thing 3see the e-tension guide for more on item mngement rules4"
+nput State
lines0 with the order lines correctly set0 item id( 1untity( price"
Output state
old9ines0 This should h%e the order lines of the current order s they were
'efore ny chnges coming from the e%ent 'eing processed"
current<rder0 The current order should 'e chnged( dding line or dding
1untity to n e-iting line with the chrges coming from this C6$"
Things to do
#dd line to the current order
This is function tht helps dding line to the current order" /t itself relies on helper
methods from jBilling o'jects0
A updates the current order
function Boid add>ine&(ediation)esult result' 5
result.set%ld>ines&%rder>ine=>.cop&result./et"urrent%rder&'./et>ines&'''7

if &?result./et>ines&'.is+mpt&''
%rder>ine=>.add>ine&result./et"urrent%rder&',
result./et>ines&'./et&9', false'7
8
#nd rule tht uses the function0
rule 'line creation'
when
$result ! (ediation)esult&step ==
(ediation)esult.*$+,_Q_I$+(_(.C.L+(+C$, old>ines == null '
then
add>ine&$result'7 A will add the first line to the current order and set old>ines
update&$result'7
A to allow item mana/ement rules
insert&$result./et"urrent%rder&''7
end
The interesting prt of this rule is tht it inserts the current order into the memory
conte-t" This is to llow item mngement rules to do their wor)" They will 'e e-pecting
instnce of <rder-!< to e%lute items( su'scriptions( etc" They will lter this instnce(
swpping items( dding others( etc"
Trnsition rule
The trnsition rule needs to h%e low slience( to m)e sure tht it runs fter ll the
item mngement rules 3which re typiclly prt of pc)ge outside the medition
rules4 h%e rn lredy"
rule "from item to diffs"
salience 2-9 A let all the item mana/ement rules fire first
when
$result ! (ediation)esult&step ==
(ediation)esult.*$+,_Q_I$+(_(.C.L+(+C$, old>ines ?= null'
then
modif& $result ' 5
set*tep&(ediation)esult.*$+,_<_#I00'7
8
end
Step 7- /ccount update
The lst step is to updte the customer5s ccount" #t this point is lso done
comprison 'etween how the order loo)ed li)e 'efore the e%ent nd fter 3 5diff54( nd
this informtion is s%ed s prt of the history of the order"
This is step tht you won5t typiclly h%e to m)e ny chnges to the stndrd jBilling
rules" /s one of the so clled 5internl rules5"
+nput State
current<rder0 complete with ll the new chrges"
Output state
done0 is now set to 5true5"
diff9ines0 with the result of the comprison 'etween the old current order nd
the new one"
Things to do
This lst rule hs lot of responsi'ilities0
S%e the current order to the dt 'se
Set the diff lines 'y using helper method from <rder9ineB9"
The record is done( so this field is set to true nd the record is remo%ed from the
memory conte-t long with the current order 3for performnce nd clrity4"
!et5s see n e-mple0
rule 'resolBe diff lines'
when
$result ! (ediation)esult& step == (ediation)esult.*$+,_<_#I00'
$compan ! "ompan#$%&'
then
if &$result./et,ersist&'' 5
new %rder#.*&'.saBe&$result./et"urrent%rder&''7
8
$result.set#iff>ines&%rder>ine=>.diff%rder>ines&
$result./et%ld>ines&', $result./et"urrent%rder&'./et>ines&'''7
$result.set#one&true'7
retract&$result'7
retract&$result./et"urrent%rder&''7 Adoable because we can count with one record bein/
process for a /iBe user at a time
if &$result./et,ersist&'' 5
new %rder=>&'.checR%rder>ineJuantities&
$result./et%ld>ines&',
$result./et"urrent%rder&'./et>ines&',
$compan./etId&', $result./et"urrent%rder&'./etId&''7
8
end
Transforming the data
/n mny cses( the dt coming from the C6$ will not 'e in consistent formt or in
formt tht let us write rules esily" /t cn 'e tht 'efore the rules tht contin the ctul
'usiness logic of the medition process run( some dt trnsformtion needs to 'e
done"
Record splitting
/t is not hrd to find sitution where n e%ent ctully mens more thn one chrge
3unfortuntely for customers4" /n generl( you cn del with this 'y simply dding mny
lines 3see step 44" This is esy nd t)es d%ntge of the 'uilt-in support for mpping
one C6$ to multiple products"
There is nother method tht cn 'e more elegnt from technicl perspecti%e" ;ou cn
insert new instnce of Mediation5esult into the memory conte-t( long with the
Mediation5ecord nd the Cricing4ields" This is n d%nce techni1ue tht is out of
scope for this guide( 'ut few pointers ct get you in the right direction"
The medition rules do not )now where the o'jects tht re in the memory conte-t cme
from" #t ny time( you cn dd new dt to the memory conte-t nd the rules engine will
process it" This is wht we do for item mngement( we insert the current order in the
memory conte-t so rules tht rect to n instnce or <rder-!< get cti%ted" 7or pricing
there is lso use of this dynmic insertion into the memory conte-t"
/n short( these re the steps you need to follow to crete new C6$ for the meditions
rules to process0
1" Crete new 5ecord
2" Crete new Mediation5esult " ;ou need the 5recordFey5 of this result o'ject
to h%e the )ey of the record creted in step 1"
?" Crete new Cricing4ield instnces 3pro''ly mny4" The 5result(d5 of ech of
these instnces need to 'e set with the id of the result o'ject form step 2"
4" #dd the pricing fields nd the result to the memory conte-t"
Record grouping
There is the other wy too0 mny e%ents coming from the e-ternl system ctully men
only one thing from 'illing perspecti%e" /f n record does not men nything t ll( you
would just remo%e it s shown in the step 1 section" The pro'lem is when two or more
records hold some dt tht pplies to just one 'ill'le e%ent"
The medition module hs the cp'ility of h%ing mny records in memory t the sme
time" The num'er of them depends on the reder" The stndrd reders will red the
num'er of records gi%en specific prmeter" /n most cses( this mens tht you will
need to use custom plug-in tht e-tends one of the current reders nd o%errides the
'tch si.e logic"
The gol is to 'e sure tht the memory conte-t will h%e at the sae tie the records
tht need to 'e merged" :nce this is done( the merging rule is not different thn the
rules re%iewed in the 5Steps5 section0 you will chec) for conditions tht hppen in more
thn one record nd perform n ction"
)adding and other "ield modi"ications
The dt tht is coming from the e%ent record might need some twe)s to fcilitte
writing rules" 7or e-mple( the phone num'er tht is 'eing clled might come with
country code if the phone is long distnce" The pro'lem is tht if the phone cll is locl
one( the telephony system doesn5t store the e%ent with ny country code"
7or writing pricing rules( it will 'e %ery con%enient if you cn rely on fi-ed-length
destintion phone num'er tht hs ll the codes0 country( re( etc"
# simple rule cn t)e cre of this0
"hen
Mfield + Cricing4ield&name==NdstN) eval&strGalue.length&'==@3''
then
Mfield.setStrGalue& N3@@@N * Mfield.getStrGalue&' 'K
This rules trnsltes s0 if the 5dst5 field 3which holds the destintion num'er4 is 10 digits
long( then dd Q0111R string in front of it"
The 'est plce for this type of rule is step 2" This is( fter the 'sics re co%ered nd
my'e the record filtered out ltogether( 'ut 'efore ny ctul product logic is done
'sed on the C6$ fields"
This is just simple e-mple( you cn chec) nd mnipulte ny field t will" *hen
writing rules( you h%e ccess to ll the <% string mnipultion methods from the
String clss 3we used 5length5 in the e-mple4"
$%tending the mediation module
;ou might need to dd some custom functionlity to the defult medition process" This
is mostly true when the helper methods offered 'y the jBilling clsses re not enough
for your re1uirements"
;ou do not need dd <% code if wht you need to do cn 'e done with rules( or e%en
with 6rools functions" 7or e-mple( if you need to con%ert seconds to minutes nd round
the result up to the ne-t minute 3 typicl procedure for wireless phone clls4( you cn
dd function to 6rools tht does this for you nd just cll the function from your rules"
:n the other hnd( there re other scenrios tht re1uire plug-in e-tensions" # common
one is when defining the user re1uires dditionl logic" Ech e-ternl system might
identify the user in %ery different wy0 sometimes it is /,S/( sometimes is ,S/S6& or
e%en just n /8 ddress" To mp this identifiers to jBilling user /6( you might need to
m)e cll to n e-ternl ser%ice( or 1uery dt'se"
The )ey to dding new <% code to the medition module is to )eep in mind tht there
re no restrictions or limittions on how to do this" There isn5t specific clss to e-tend
or pc)ge where to put your clsses"
#s you could see from the e-mple rules( it is %ery esy to cll ny <% clss from
rule" #ll you need to do then is pc)ge your clsses in wy tht they will 'e prt of the
<9, clss pth( then dd the import to the rule5s source nd use the clss s you would
do from norml <% code"
Chapter 7
Rating
Rating events
So fr( in the pre%ious chpters nd e-mples( rting hs 'een mostly ignored" The
digrm with the medition process o%er%iew on pge 12 does not h%e n e-plicit
5rting5 step" *ht if you need to process e%ents tht need e-plicit ssignment of
price>
The pricing result
/n jBilling( rting is done with rules" The rules re cti%ted 'y the presence of n
instnce of Cricing5esult( nd they typiclly le%e the result in this o'ject s well"
!et5s strt 'y t)ing loo) to this clss0
Cere it is n e-mple0
rule Nlong distance plan $ priceN
"hen
# 9ong distance call
Mresult + Cricing5esult& item(d == 0E33) price == null '
Subscription5esult& item(d == 0233) user(d == Mresult.user(d)
subscribed == true ' # 9ong -istance Clan $
then
modify& Mresult ' O
# 9ong -istance 7all base price &special prices may still
# be set via the rating card'
setCrice&N3.03N'K
P
9<H.debug&NCricing set because of plan 0233N'K
end
The rule chec)s tht there is pricing result o'ject for s specific item tht remins
unresol%ed0 the price is null" /n this e-mple( the condition lso dds tht the user is
su'scri'ed to specific pln s well"
The 5then5 section is %ery esy0 set the price of the result"
E8ecuting pricing rules
6epending where the pricing is needed( the pricing rules will 'e e-ecuted following
different pth"
8ricing within the medition process
*hen the medition process runs( to get the pricing rules to run you need to mnully
insert new instnce of Cricing5esult in the memory conte-t" This is e-plined in the
Steps section"
8ricing outside the medition process
By using the plug-in 5ulesCricing!as>0 you cn h%e pricing from other res of
jBilling tht re not the medition process 'ut need price" 7or e-mple( the list of items
will show up with price( nd this price cn 'e ffected 'y rules if the rules plug-in is
prt of your configurtion"
This plug-in is %ery simple" /t cretes n instnce of Cricing5esult( initili.ed with the
)nown informtion0 user id( item id( etc" Then it clls the rules nd returns whte%er price
is in the price field of the result o'ject"
/f you need the sme pricing rules to 'e cti%e in 'oth the medition process s well s
the rest of jBilling( then use this plug-in" The rules should 'e pc)ged in n
independent pc)ge tht is used 'y 'oth the medition plug-in nd the pricing plug-in"
+tem relationship management plug#in
This plug-in cn dd( remo%e nd swp items when n order line is dded to n order"
*ith this plug-in you cn implement tiered pricing( for e-mple" This is when the price of
n item chnges depending how mny units re 'ought in gi%en period of time0 the
first 100 units re included in you monthly pln( the ne-t 100 re price @0 cents( then
ne-t 100( 40 cents nd so on"
;ou cn do this without the pricing plug-in 'ecuse the inforation that affects the price
is not directl' in the event. /n this cse( the sole fctor tht ffects the price of the e%ent
is how mny units the customer hs 'ought so fr( in this 'illing cycle" Tht is not
present in ny of the e%ent fields" #ctully( tht is something tht the 'illing system
)nows"
/n this cse( you cn implement the rting for your medition process with the help of
only the item reltionship mngement plug-in"
ricing with rules
The medition process( when updting the order in step 10( m)es the cll to the
jBilling core pssing long ll the fields from the record tht originted the order
modifictions" This then llows the pricing rules to h%e ccess to the record fields nd
ct ccordingly to set the price of the item tht is 'eing dded to the customer5s order"
*hen the price of n e%ent depends on mny fields from the e%ent( then you need to
use the pricing plug-in" The typicl e-mple is phone cll0 the e%en record will h%e
fields tht ffect the finl price of the cll0 re code from where the phone originted(
re code clled( time of the dy( dy of the wee)( etc"
/n tht cse( the item reltionship mngement plug-in will 'e of little help to set the
price0 here switching or dding n item of the order doesn5t do wht we need" *e )now
the item in%ol%ed0 phone cll( now we need to gi%e it price"
#s mentioned erlier( the pricing rules h%e in its wor)ing memory ll the Cricing4ield
o'jects( just li)e ny rules of the medition process" *e cn then write rules tht 1uery
on those o'jects0
rule B31 . D@0
"hen
Msrc + Cricing4ield& name == NsrcN) strGalue matches NQB31.RN'
Mdst + Cricing4ield& name == NdstN) strGalue matches NQD@0.RN)
result(d == Msrc.result(d'
Mresult + Cricing5esult& item(d == 0E33) price == null)
pricing4ields5esult(d == Msrc.result(d '
then
modify& Mresult ' O
setCrice&N2N'K
P
end
This rule is typicl pricing rule for medition( let5s go through it in detil0
There re three conditions in the rule0 The re code of the originting phone num'er
hs to 'e 5A045( the re code of destintion num'er hs to 'e 5@125 nd the item
in%ol%ed s to 'e the /6 52D005" /f ll three conditions re met( the the price will 'e set to
se%en"
!et5s slice the conditions in ll its prts0
Msrc + PricingField& name == NsrcN) strGalue matches NQB31.RN'
There re two conditions tht the field hs to meet" /n the drools lnguge( tht is done
'y simply using e-pressions seprted 'y comms inside the nme of the cll" $ecord
fields re represented in the wor)ing memory 'y Crice4ield o'jects"
Msrc + Cricing4ield& name == "src") strGalue matches NQB31.RN'
/n our formt file( the field with the source phone num'er( the num'er where the cll is
'eing mde( hs the nme 5src5 nd is of type string" This e-mple is ctully t)en from
the steris) C6$ formt definition"
Msrc + Cricing4ield& name == NsrcN) strValue matches "^60.!"'
7rom this phone num'er( we re only interested in the re code" Tht is the first ? digits
of the field" Since this field is string( we cn use the method 5getStr9lue5 'y treting
tht s property of the o'ject 3following the j% 'ens definition( drools will dd the
5get5 to the method( tht why we only need to type 5str9lue5 in the rule4"
This method will return String o'ject" The opertor to do the comprison will do
regulr e-pression" This is how we chec) tht the first three digits h%e specific %lue"
The rest of this rule is stright forwrd0 the second condition is similr to the first one( it
just chec)s tht the destintion num'er strts with 5@125" The third condition is
re1uirement to ny pricing rule0 we need to limit the rule to prticulr item( otherwise
we would 'e setting the price of ll the items"
Both the second nd the third condition h%e nd 5lignment5 condition" This is the prt of
the condition tht m)es sure tht ll the pricing fields in the rule 'elong to the sme
C6$" This is needed( 'ecuse there could 'e mny records 'eing e%luted in memory
t the sme time"
%ealing with large num'er o" pricing rules
The pricing e-mple we just sw get the jo' done0 it set the price for clls 'etween the
A04 re code nd the @12 re code" Still this ws done with rule tht is 10 or so lines
of rules code" #nd we might potentilly need one rule per re code com'intion" *e
cn end up with hundreds or thousnds of rules tht re lmost the sme e-cept for
the re code num'ers nd the price"
There is solution for this sitution0 6ecision T'les" This is feture of 6rools( it
llows you to use n spredsheet done with :pen :ffice or E-cel 3or plin te-t C9S
file4 nd enter the dt for ech rule s row" /n 6rools decision t'les re wy to
generte rules dri%en from the dt entered into spredsheet"
They re tool to generte the 5technicl5 te-t rule tht we sw erlier in this chpter
utomticlly from the dt of spredsheet" ;ou will define templte with the rule te-t
in common to ll the rules( then you only need to enter the source re code( trget re
code nd price for ech rule" Ech of these %lues go in their own spredsheet cell"
There is no point in documenting here how to use decision t'les( they re not prt of
jBilling( 'ut prt of 6rools" There is chpter dedicted to them in the 6rools
documenttion"
The following e-mple will help you get strted fster0
8ricing
Se1uentil T$2E
/mport
9ri'les org"pche"log4j"!ogger !:P
%3>$/!/3> %3>$/!/3> 5%!/3>
Call Type =item "d> !igits Pri9e &roup
2D00 @EE41A@ 0"2D0 1
2D00 @21@@E1 0"1D0 1
2D00 @21@@D@ 0"1D0 1
$uleSet
com"spienter"j'illing"ser%er"item"8ricing7ield(
com"spienter"j'illing"ser%er"item"ts)s"8ricing$esult(
org"pche"log4j"!ogger
Rule!a)le Rates
5%!/<5!/3>"
?R3UP
Gresult 0 8ricing$esult 8ricing7ield
item/d JJ Gprm( price JJ null(
Gresult/d 0 pricing7ields$esult/d
nme JJ SdstS( str9lue mtches STGprm"US( result/d
JJ Gresult/d
modify3Gresult4 V set8rice3SGprmS4= W
!:P"de'ug3SSetting price of item 1 to S X
Gresult"get8rice344=
Chapter 8
Mediation errors
The mediation results
*hen the medition process is done( the results of wht hppened with ech of the
C6$s tht were processed re %il'le" There re mny outcomes0 the record
produced some chrges to customer( or my'e it did not( or my'e some errors
pre%ented ll the steps from hppening"
7or those records tht present errors( jBilling will s%e them so you cn setup n
utomted wy to get the reprocessed"
But first( it is importnt to understnd the results tht jBilling identifies" The following
sections list ech of the possi'le results
%one and 'illa'le
This is the 5typicl5 result0 record ws successfully processed 3ll the steps4 nd it
trnslted into chrge to customer" 7or this to hppen( the 5done5 field of the
medition result o'ject needs to 'e set with 5true5 nd the 5lines5 field should h%e some
lines in it"
%one and not 'illa'le
The record ws successfully processed 3done is set to true4( 'ut there re no lines
present" The typicl e-mple is when record represents n e%ent tht the customer will
not py for" !i)e phone cll tht ws not nswered0
rule cancel not ans"ered call
"hen
Mresult + Mediation5esult&step == Mediation5esult.S!;C_@_S!$5!)
done == false '
Mfield + Cricing4ield& name == NdispositionN) result(d ==
Mresult.id) value S= N$=S?;5;-N '
then
Mresult.set-one&true'K
retract&Mresult'K
end
;ou should lwys mr) records s done( e%en when they re not 'ill'le"
Error detected
/f result is left with done e1ul to flse nd the medition process is done( then jBilling
will consider this n error" ;ou should lwys h%e rules tht contemplte e%ery outcome
of record nd set the 5done5 field s true"
The medition process will try to identify the reson why this record filed( ssigning
code 3or mny4 to it" This code then will 'e s%ed long with the whole record for lter
reprocessing 3see the ne-t section4"
The following t'le shows the situtions tht jBilling will chec)( nd the codes for ech of
them0
ediationRe9ord field Error Code
lines &o items re mpped to this
record
<B-&:M!/&E
diff!ines The delt 'etween the
e-isting order nd the new
chrges ws not resol%ed
<B-&:M6/77
current:rder The user5s current order
ws not fetched
<B-&:M:$6E$
user/d The user ws not ssigned
for this record"
<B-&:M2SE$
currency/d The currency of this record
ws not resol%ed"
<B-&:MC2$$E&C;
e%ent6te The dte of this record ws
not resol%ed"
<B-&:M6#TE
7or e-mple( if record is coming for customer tht hs not 'een creted in jBilling(
then the rules tht try to ssign the user to the record will fil nd the 5user/d5 will 'e left
'ln)" #ll the rest of the steps will not t)e plce 'ecuse the rule tht trnsitions from
step 1 to 2 will ne%er t)e plce0 the user hs not 'e resol%ed"
;ou will find the record in the recycle 'in( with pro''ly ll the error codes in it e-cept the
dte" *hen you see this( you )now tht the rel culprit is the user( 'ecuse it is the field
ssocited with the erlier step"
Error declared
/t is good prctice to try to co%er ll the possi'le situtions tht record cn h%e with
rules" /f there is n error tht you cn detect( then you cn let jBilling )now using the field
5errors5 from the Mediation5esult. This is list of strings( so you cn dd ny
num'er of errors( they will 'e preser%ed when the errors re s%ed for reprocessing"
Cere is n e-mple tht ctches negti%e durtions0
rule chec> call duration
"hen
done == false '
Mfield + Cricing4ield& name == NdurationN) result(d ==
Mresult.id) value I 3 '
then
Mresult.set-one&true'K
Mresult.add;rror&N;55.-T5$!(<=N'K
retract&Mresult'K
end
There isn5t ny limit to the formt or num'er of errors tht you cn dd" They just need to
m)e sense to you" #s you sw in the pre%ious section( the errors tht jBilling resol%es
use codes tht strt with 5<B5( so your errors should strt with something else"
Reprocessing records with errors
jBilling will consider ll the records tht fll into the error ctegories 3detected or
declred4 s not processed" This is importnt( 'ecuse otherwise the filter tht jBilling
does to %oid processing the sme record twice would pre%ent record with n error to
'e processed lter"
The norml wor)-flow would 'e0 the medition process runs( some records h%e errors(
you re%iew these records nd correct wht cused the pro'lems( then run the medition
process gin only for the records tht hd errors"
Sa2ing the records with errors
There is plug-in ctegory tht is in chrge of s%ing records with errors" The id of this
ctegory is 21" There re two implementtions of medition error hndlers0
S%eTo7ile,editionErrorCndler0
This plug-in will s%e to file e%ery record with n error" The formt is plin te-t with
ech field seprted 'y comms 3cs%4" These re the prmeters tht modify its
'eh%ior0
directory0 the directory where the files will 'e s%ed" /t defults to the %lue of
the property 5'seMdir5 from the j'illing"properties file with the dded
5meditionFerrors5" E-mple0 if 5'seMdir5 is QFhomeFj'illingFR then the error files will
'in in QFhomeFj'illingFmeditionFerrorsR"
fieMnme0 The nme of the file nme to use" /t defults to Qmedition-errorsR" The
system will lwys dd Qcs%R e-tension to the files s%ed"
rotteMfileMdily0 if 5true5( then the file nme will h%e the dte dded to its nme
in the fomt QMyyyy,,ddR" E-mple Qmedition-errorsM20100?01"cs%R"
S%eTo<6BC,editionErrorCndler0
This plug-in will s%e record in dt'se for e%ery record with n error" /t will use the
nme of ech pricing field s the column nme tht the t'le getting the errors hs to
h%e"
These re the prmeters tht modify its 'eh%ior0
url0 This is mndtory prmeter" /t is the url for <6BC connection to dt'se(
i"e" jd'c0postgres1l0FFloclhost0@4?2Fj'illingMtest
dri%er0 The <6BC dri%er clss for connecting to 6B( defults to
5org"postgres1l"6ri%er5
usernme0 The user nme for the dt'se( defults to 5S#5
pssword0 The pssword for the dt'se( defults to 'ln) string 3SS4
t'leMnme0 The nme of t'le nme for s%ing the error records( defults to
5meditionMerrors5
errorsMcolumn0 The column nme for s%ing error codes( defults to
5errorMmessge5
retryMcolumn0 Column nme for s%ing flg of reprocessing( defults to
5shouldMretry5"
9i8ing the errors
&ow tht you h%e the records tht produced errors( nd tht you )now why 3or t lest(
strting point thn)s to the error codes4( you will need to fi- the pro'lem"
The pro'lems cn 'e grouped in two ctegories0 rules nd dt" The first one hppens
when some of your rules re wrong( incomplete or just missing" 7or e-mple rte crd
with pricing rules might 'e missing some destintions( which cuses the price to 'e .ero
nd n error detection rule to fire"
6t rules re those tht in%ol%e some missing or wrong dt" /f customer is missing
'ecuse she ws gi%en phone line 'efore she hs record in the 'illing system( then
the 'illing system will complin"
;ou will need to somehow seprte the records tht you wnt to reprocess" /f you re
using dt'se( then this cn 'e s simple s setting 'oolen column to true"
Reprocessing the records
*hen it m)es sense to reprocess the records 'ecuse the errors h%e 'een fi-ed( you
cn just simply run the medition process gin"
/f you re using files( you cn simply copy the file s%ed 'y the error hndler plug-in" /f
your originl file ws cs% file( then you could get wy without h%e n e-tr medition
configurtion for the reprocessing of medition records"
/n prctice( it is 'est to just h%e one medition configurtion( with its formt nd other
dt( to del with the reprocessing" This is clled the recycle 'in" /t is more prcticl
'ecuse you cn get to 1uite utomted configurtion" !et5s see n e-mple0
1" The medition process runs( for ll its configurtions" The norml one find some
errors( which re s%ed in dt'se" The recycle 'in does not find nything(
'ecuse the column tht flgs n error record to 'e reprocessed defults to
flse"
2" #n opertor re%iews the records in the recycle 'in( nd proceeds to fi- some of
them" She sets the retry column to 5true5"
?" The medition process runs gin" #s in the first step( it will process norml
records nd some of them might go to the recycling t'le" *hen the recycling
configurtion runs( this time it will find some process'le records tht re ctully
fi-ed records from the first run"
# new configurtion to hndle the fi-ed errors is prcticl 'ecuse it helps you del with
the logistics of these records0 where they re( when to process them( etc" This does not
men tht you need new medition rules to del with these records" The new
configurtion ffects only from where( or how the records get to 'e red( 'ut not how
they re processed"
The medition module is ignornt of how records re selected from processing( ll the
logic pplies to ny record regrdless of its origin"
Chapter 9
Realti!e Mediation
The difference of real time processing
The typicl medition scenrio in%ol%es lrge num'er of records generted 'y some
e-ternl system nd then processed in scheduled( periodicl run" This 'tch
processing hs mny limittions( the most importnt is tht there is some time 3usully
few hours or full dy4 in 'etween the e%ents hppening nd the 'illing system 5'eing
told5 of these e%ents"
Btch processing is still %ery common in the telecommunictions industry" /t hs 'een in
plce for long time nd people re comfort'le with it" Still( it is product of the
technicl limittions of computer systems tht tody re decdes old"
/f you need to %lidte n e%ent "efore letting in hppen( or you need to )eep 'lnce
updted up to the second( then 'tch processing will not do it" The clssic 'usiness
cse for this is pre-pid ser%ices where customer hs 'lnce nd cn only use
ser%ice s long s the 'lnce remins positi%e" E%ery ttempt to use the ser%ice hs to
chec) if there is enough 'lnce"
jBilling cn process e%ents 'oth in 'tch nd rel-time" $el-time processing does not
in%ol%e reder plug-ins to go to files or dt'ses for the records" /nsted( the #8/ is
used to send the e%ents s they hppen"
)rocessing an e2ent in real time
To send n e%ent in rel time( your system needs to 'e 'le to m)e S:#8 cll to
jBilling" There re specific #8/ methods used for deling with rel-time medition" These
re documented in the integrtion guide" This is list of the most rele%nt ones0
rte:rder *ill e%lute n order with pricing rules
nd item mngement rules without
creting the order" ;our ppliction cn
show the order to the customer to
ppro%ed it( nd the crete it"
rte:rders Sme s the pre%ious one( 'ut it does
mny orders in single cll"
getCurrent:rder $eturns the order tht the medition
process is using to collect usge for
'illing period"
updateCurrent#rder Runs the mediation pro9ess for a single
event? passed as an argument
%lidte8urchse $uns the medition process for single
e%ent( 'ut it does not updte the customer
ccount" /nsted( it chec)s if the customer
hs enough 'lnce to purchse the
chrges tht the e%ent represents"
%lidte,ulti8urchse Sme s pre%ious( 'ut t)ing se%erl
e%ents s input"
The most importnt method is update7urrent<rder" # cll to this method would
mount to the medition process running for one single e%ent" The method will t)e n
rry of pricing fields( this is the e1ui%lent of medition reder reding one e%ent nd
returning tht to the medition process"
This method cn insted t)e n rry of order lines" /f this is the cse( then the
medition process does not run" See the integrtion guide for more detils"
Cere there is n e-mple of n #8/ cll tht would medite in rel-time one e%ent0
,ricin/0ield pf = new ,ricin/0ield&"call2tpe", SlocalT'7
,ricin/0ield duration = new ,ricin/0ield&"duration", K'7 NN K min
,ricin/0ield dst = new ,ricin/0ield&"dst", "-GH;KQ<M"'7
%rderDs order = api.update"urrent%rder&userId, null,
new ,ricin/0ield14 5 pf, duration, dst 8, new #ate&',
""all to " O dst./et*trValue&''7
This code strts 'y creting three pricing fields" This is the dt tht the medition
process will use to resol%e the item( 1untity nd potentilly price"
This dt is pssed to jBilling clling update7urrent<rder" The jBilling user hs to 'e
)nown to the cller lredy" The description of the e%ent is lso pssed"
&ote the differences with 'tch processing" /n 'tch processing( the user is resol%ed
with rules in in step 1 nd the description is lso done in rule"
This e-mple ssumes tht there re rules the will m)e sense out of the fields 5cll-
type5( 5durtion5 nd 5dst5" These rules don5t need to 'e specific to rel-time medition"
The sme set of rules could 'e doing 'tch nd rel-time medition"
#fter this cll( the one-time order 'elonging to the user ffected will h%e n e-tr line( or
n incresed 1untity" This updted order is returned to the clling code"
:alidating an e2ent 'e"ore it happens
So fr( the scenrios for medition h%e 'een tht n e%ent hs t)en plce" This is( it is
in the pst" *ht if you wnt to chec) if n e%ent should 'e llowed to hppen>
This is the typicl 5pre-pid5 scenrio0 customer 'uys phone nd 5lods it5 with some
initil mount of money" This customer is llowed to use the phone s long s the
'lnce on the ccount is greter thn .ero" Before usge 3'efore cll is plced( n
sms messge sent( etc4( the telephony system should cll the 'illing system to %lidte
tht this ser%ice is %il'le to the user"
# %ery similr cse is the one where the user is not pre-pying( 'ut there is credit limit"
Cere the customer is gi%en credit limit when the customer is first singed-up" The
customer cn use the ser%ices up to tht limit" *hen the limit is reched( the ser%ices
re withheld"
jBilling will )eep trc) of these 'lnces 3pre-pid or credit limit4 nd help with the
%lidtion through the 5validateCurchase5 #8/ method" 8lese refer to the 2ser5s guide
3'lnce type section4 nd integrtion guide for more informtion"
The following is the high le%el se1uence of e%ents0
# cll to validateCurchase will 3usully4 result in the medition process clled" This is
to resol%e the fields tht come s rw dt to n ctul product with price" The totl of
this chrge will then 'e compred ginst the customer5s 'lnce 3su'trcted if it is pre-
pid( or dded if it is on credit4"
The result of this comprison is the pssed to the cller" The results include not just
5true5 or 5flse5 'ut 1untity of how much of tht product the customer could currently
'uy" This is helpful to enforce limits on ser%ices0 if customer hs 'lnce to m)e
cll of @0 seconds( then the cll should 'e terminted fter tht time"
#fter this cll is done( the 'lnce 3nd current order4 of the customer is unffected" ;ou
need to cll update7urrent<rder for the 'lnce to 'e modified"
This is n e-mple cll to validateCurchase0
,ricin/0ield14 pfG = 5
new ,ricin/0ield&"src", "Q9;"',
new ,ricin/0ield&"dst", "K-G"',
new ,ricin/0ield&"duration", -',
new ,ricin/0ield&"userfield", m6ser./et6serCame&'',
new ,ricin/0ield&"start", new #ate&'' 87
result = api.Balidate,urchase&mId, null, pfG'7
The code strts setting few pricing fields" Then clling the %lidtion method" The
second prmeter 3the item4 is left null0 we e-pect the product to 'e resol%ed using the
medition rules"
Chapter 1"
#$a!ple scenario
Our e%ample plan
#fter going through e%ery step nd component of the medition process( it is time to put
e%erything together to m)e phone pln wor) with jBilling" The ide is not so much to
get into comple- scenrios( 'ut to see ll the pieces wor)ing together"
:urs is phone pln offered 'y compny tht uses #steris) s telephone switch"
The mr)eting deprtment decided to cll this pln QSuper @00R( it includes the following0
@00 nytime minutes
7ree clls for the wee)ends
?0 cents per minute( when clling on wee)dys nd going 'o%e the included
@00 minutes"
!ong distnce clls re llowed 'ut priced seprtely" The price per minute is
dependent on where the cll origintes nd where nd the trget phone num'er"
The monthly fee is 100 dollrs"
*e will strt from freshly instlled jBilling" This mens tht we will not co%er
instlltion nd deployment" /nsted( we will focus on the items( configurtion nd rules
tht m)e this pln come to life"
&nitial configuration
*e will 'e using the e-mple compny &rend for this e-ercise" By defult( this compny
is lredy creted in jBilling s the compny num'er 1" $emem'er( you cn login using
the user nme 5dmin5 with pssword 512?1we5"
Trend5s configurtion is not redy for the )ind of 'usiness rules we need to implement in
our pln( we will h%e to dd some plug-ins to llow rule-'sed processing"
)lug#ins
/tems mngement0 The plug-in configured for &rend for item mngement is the
5ules(temManager0" This rules-'sed plug-in is wht we need( so there re no chnges
to do here"
8ricing0 Cere &rend hs lso the right plug-in 5ulesCricing!as>0" This will llow us to
set-up rting rules in our medition process"
,edition 8rocess0 The 5ulesMediation!as> is lredy present in the configurtion(
'ut you need to chnge the prmeters it uses" This plug-in needs to ccess to not just
the medition rules( 'ut lso the item mngement nd pricing rules" /n the 'undle tht
you downloded( the item mngement pc)ge lso includes the pricing rules( so you
need the medition process plug-in to h%e two prmeters0
,edition rules0 nmeJurl( %lueJhttp0FFloclhost0D0D0Fdrools-
gu%norForg"drools"gu%nor"Pu%norFpc)geF,editionF!#TEST
/tem mngement nd pricing rules0 nmeJurl(
%lueJhttp0FFloclhost0D0D0Fdrools-
gu%norForg"drools"gu%nor"Pu%norFpc)geFtrendMitemMmngementF!#TEST
$eders0 *e re going to need one reder plug-in" &rend hs none( so we need to dd
one tht is cp'le of reding the e%ent files creted 'y #steris)" The type of file is
seprted 'y comms( so we will use the Separator4ile5eader" *e need to specify
the formt file( jBilling comes out-of-the-'o- with the steris) file formt in the file
asteris>.xml" 8retty much e%ery defult %lue for the plug-in is fine for this e-mple(
we5ll just specify to renme the files once they re processed nd the suffi- of the files to
process( since we )now they ll end with 5"cs%50
/t is good ide t this point to t)e loo) to the formt file" :pen
jbilling/resources/mediation/asteris>.xml with te-t editor" /t is firly esy to
crete one of these formt files out of the switch5s documenttion" *hen writing the
pln5s 'usiness rules( we will 'e often referring to prticulr record field 'y nme" ;ou
will need to 'e fmilir with the formt file nd the C6$ documenttion from steris) to
understnd the rules we5ll 'e writing in lter sections"
*ediation con"iguration
Since we now h%e reder plug-in redy to run( we cn now crete new medition
configurtion" Clic) on 5System5 then 5,edition5 nd then on the lin) 5#dd new
configurtion5"
7or nme( we will use 5#steris)5( nd for the plug-in /6 we enter 1B0( since tht is the /6
of our reder plug-in 3see the pre%ious illustrtion40
+tems and customers
The e-mple compny &rend does not h%e ny of the telecom items we need for this
e-ercise" They re0
*ee)end phone cll minute( priced t 0 dollrs"
8hone cll minute included in the pln( priced t 0 dollrs"
Illustration 1$: &he reader plug%in with its paraeters
Illustration 1(: &he exaple ediation configuration
8hone cll minute not included in pln 3'o%e @00 minutes4( priced t 0"?0
Stndrd phone cll minute( priced t 0"?0 dollrs
!ong distnce minute( the price is no relly importnt( it will 'e set with rules"
The 5Super @005 pln( priced t 100 dollrs"
Cere re the items( the /6 num'ers of ech of them re importnt( we will need them
when writing rules0
7or customers( we will just use those tht re lredy loded for &rend" There re three(
with num'ers 2( 12 nd 22"
$%pressing the plan with rules
:ur phone ser%ice pln is pretty simple( nd yet when we thin) how to implement it we
disco%er tht it in%ol%ed mny 'usiness rules" These 'usiness rules we cn e-press %ery
well using the 'usiness rules mngement system 3B$,S4"
To clrify wht we wnt to chie%e( we put together flow digrm with the min logic
points tht m)e our pln0
;ou cn see tht the 5type5 of rule is color coded0 we will need some of the rules to 'e for
the medition plug-in( most for the item mngement plug-in nd e%en some pricing
rules to hndle long distnce rting"
This )ind of digrm helps to understnd the e-tent of the re1uirements( 'ut it hs
drw'c)" # rule system does not follow typicl logic flow li)e the one in the digrm(
where there is only one conditions or conse1uence done t ny gi%e time( nd
e%erything hppens in strict se1uence"
$ules wor) 'est when it does not mtter which rule is e-ecuted first or which one lst"
/mgine tht they ll get e-ecuted at the sae tie" Then( it is esier to mintin nd
dd new rules"
*ediation rules
The medition plug-in is where e%erything strts" *e re going to 'e setting few rules
to e-trct dt from the e%ent records nd 5trnslte5 their content to jBilling" These
rules will 'e useful s n e-mple( 'ut there re some omissions0 for e-mple( ll the
line cretion rules should pro''ly chec) tht the phone cll ws ctully nswered" The
ide is tht if you h%e good understnding of these e-mples( you will 'e 'le to 'uild
on them to setup rel production rules on your own"
Illustration 1): &he logic for the exaple plan
%e"ining the user
/n this e-mple will ssume tht the user nme comes directly in the record s the field
5userfield50
IfieldL
InameLuserfieldI/nameL
ItypeLstringI/typeL
I/fieldL
Thus( the medition rule to define the user loo)s li)e this 3see the Step 1 section for
more informtion on setting the user( nd the content on the help function used here40
"hen
user(d == null'
Mfield + Cricing4ield& name == NuserfieldN) result(d ==
Mresult.id'
Mcompany + 7ompany-!<& ' # needed to determine a user by its
user name
then
modify& Mresult ' O
setTser(d& getTser(d4romTsername&Mfield.getStrGalue&')
Mcompany.get(d&'' 'K
P
%e"ining the e2ent date
Ech record s the strt dte nd time( this is the time stmp the phone cll strted0
IfieldL
InameLstartI/nameL
ItypeLdateI/typeL
I/fieldL
The medition rule tht t)es this field nd sets the dte is0
"hen
event-ate == null'
Mfield + Cricing4ield& name == NstartN) result(d == Mresult.id'
then
modify& Mresult ' O
set;vent-ate& Mfield.get-ateGalue&' 'K
P
;ong distance calls
#t the medition process( we only need to identify if the record 'elongs to long
distnce cll or not" /f it is( it should dd the order line using item 24" Tht is ll( we don5t
need to worry 'out the price of the cll t this point( 'ut we do need to re1uest the price
so the pricing rules do their jo'"
salience @3
"hen
Mresult + Mediation5esult&step ==
Mediation5esult.S!;C_1_5;S<9G;_(!;M'
Mfield + Cricing4ield& name == NdurationN) result(d ==
Mresult.id'
Cricing4ield& src$rea7ode + strGalue) name == NsrcN)
result(d == Mresult.id'
Cricing4ield& dst$rea7ode + strGalue) name == NdstN)
eval& Ssrc$rea7ode.substring&3)A'.e#uals&
dst$rea7ode.substring&3)A'' '
then
Mresult.get9ines&'.add&ne"9ine&01) ne"
Big-ecimal&Mfield.getStrGalue&''''K
Mresult.setStep&Mediation5esult.S!;C_D_C5(7(=H'K
update& Mresult 'K
Cricing5esult re#uest = price5e#uest&01) Mresult'K // because
it "ill be converted to this...
insert& re#uest 'K
The code in this rule t)es the %lues of the 5src5 nd 5dst5 fields nd compres the first
three digits" /f the re not e1ul 3notice the 5+5 chrcter to negte4( then the line with item
24 is dded( with the 1untity coming from the %lue of the 5durtion5 field"
*e re e-plicitly gi%ing this rule high priority 3slience e1uls to 104( so it runs the first
mong the line cretion rules" Then( we re setting the step to @ 3pricing4" #ll this is
needed( otherwise the other order cretion lines might lso crete n order line0 for
e-mple( if there is long distnce cll on wee)end"
This long distnce rule is exclusive of ll other line cretion rules0 if the cll is long
distnce( then use the long distnce item nd do not execute an' other product
resolution rules. This is esily chie%ed 'y the direct setting of the step of the result
o'ject to @"
Wee(end calls
/f the cll hppens on wee)end 3nd it is not long distnce4( we need to use item 210
salience D
"hen
Cricing4ield& name == NstartN)
eval& calendarGalue.get&7alendar.-$,_<4_?;;F' ==
7alendar.S$!T5-$, ' UU
eval& calendarGalue.get&7alendar.-$,_<4_?;;F' ==
7alendar.ST=-$, ')
Mfield + Cricing4ield& name == NdurationN)
then
Mresult.get9ines&'.add&ne"9ine&0@) ne"
Big-ecimal&Mfield.getStrGalue&''''K
insert& ne" Subscription5esult&Mresult.getTser(d&') 0D' 'K
update& Mresult 'K
*e do not h%e to worry 'out this cll 'eing long distnce0 tht ws t)en cre of 'y
the pre%ious rule when it set the step to @"
/n this rule( we need to chec) if the cll hppened on wee)end" 7or tht( the
con%enience method 5getClendr9lue5 of the clss Cricing4ield comes %ery hndy"
Chec)ing for the dy of the wee) is simple cll to the <% stndrd clss 7alendar"
<ust li)e in the pre%ious rules( we ssign priority to this rule" /t is lower thn the long
distnce rule 3we wnt ll long distnces clls to 'e treted s such regrdless of
nything else4( 'ut still higher thn norml rule" By doing this( nd e-plicitly setting the
step of the result to @( we %oid h%ing to write comple- rule for norml clls"
&ote tht there isn5t pricing re1uest in this cse0 wee)end clls h%e much esier
pricing( they don5t need rte crd"
*it minute( isn5t this gi%ing ever'one free wee)end clls> Tht is not wht we wnt(
free wee)end clls re only for those tht h%e su'scri'ed to our 5Super @005 pln"
Since we )now tht the sttus of su'scription is needed( we re inserting now in the
memory conte-t n o'ject tht will crry this informtion" Then( item mngement rules
cn ct on this nd swp items s needed"
Therefore( we re going to t)e cre of not gi%ing this free cll in the ne-t pc)ge of
rules tht do item mngement" See the digrm in the lst illustrtion"
Standard calls
/f cll is not done on wee)end nd it is not long distnce( it is just plin norml
phone cll tht should use item 2?0
"hen
M#uantity + Cricing4ield& name == NdurationN)
then
Mresult.get9ines&'.add&ne"9ine&0A)
ne" Big-ecimal&M#uantity.getStrGalue&''''K
update& Mresult 'K
*e don5t need to chec) in this rule tht the cll is on wee)dys or tht is locl cll" /f
the 5durtion5 field is still in the wor)ing memory( it mens tht the cll is stndrd"
The rule is %ery simple then( just use item 2?" This( of course( is not t)ing cre of
m)ing the cll free for customers tht re su'scri'ed to our pln nd within the @00 free
minutes" Tht will 'e done with item mngement rules"
+tem management rules
2nli)e medition rules( item mngement rules re commonly hndled 'y 'usiness
users" These rules re 'strct to the e%ents themsel%es( you cn thin) of them in
'usiness terms"
Becuse of this( we will crete these rules using the B$,S grphic interfce( s
opposed s typing the rule code creting 5technicl5 rules" *e will t)e d%ntge of
jBilling5s domin specific lnguge for item mngement rules"
9ree wee(ends "or su'scri'ers only
;ou might recll tht the medition plug-in would use the free wee)end phone cll item
for e%eryone" &ow it is time to limit this to only those tht h%e su'scri'ed to our pln0
Thn)s to the use of the 6S!( the rule is self-e-plntory" :nly those su'scri'ed to our
pln cn h%e free wee)end clls= the rest get the stndrd item with price of ?0 cents"
*inutes included in the plan
:ur su'scri'ers re entitled to @00 minutes of free clls" 7or tht( we will first 'lindly
con%ert ny item 2? 3stndrd cll4 to item 22 3free cll4 if the customer is su'scri'er"
Then( with nother rule( we will m)e sure tht the mount of those free minutes does
not e-ceed @00" /f so( it will trnsfer the e-cess minutes to item ?1 3e-cess minute4(
which is priced t ?0 cents0
/t would 'e possi'le to %oid h%ing item ?1 ltogether nd dd the e-cess of minutes to
item 2?( which is the stndrd phone cll minute" This would m)e the first rule more
complicted( 'ecuse we would not 'e 'le to trnsfer all items 2? to item 22 3the rules
would contrdict ech other4" The first rule would need to chec) if item 22 is present nd
if it so( only trnsfer when the 1untity is not grter thn @00"
The decision ws to )eep tht rule simpler 'y dding nother item 3?14"
)ricing long distance calls
/t is time to gi%e price to those long distnce clls" *e switch to different pc)ge
now( the pricing pc)ge of rules" /n this e-mple( we will only set price for cll
'etween two specific re codes0
"hen
Msrc + Cricing4ield& name == NsrcN) strGalue matches NQB31.RN'
Mdst + Cricing4ield& name == NdstN) strGalue matches NQD@0.RN)
result(d == Msrc.result(d'
Mresult + Cricing5esult& item(d == 01) price == null)
pricing4ields5esult(d == Msrc.result(d '
then
modify& Mresult ' O
setCrice&N3.D3N'K
P
Cere we simply chec) if the item in 1uestion is 24( since this is our long distnce minute
item" /f so( then we chec) if the cll is from A04 to @12" /f so( the price is @0 cents"
*e will pro''ly h%e lrge num'er of these )ind of rules( 'sed on more then just
two fields" This will li)ely led to decision t'le where you cn mintin these rules in
spredsheet"
rocessing some events
*e need to put ll the rules to wor) 'y running the medition process nd get few
e%ents processed"
7or tht( we need first to crete the min su'scription orders for two customers" To do
tht( we h%e to dd the preference tht llows compny to use min orders0
(=S;5! (=!< C5;4;5;=7; &(-) !,C;_(-) !$B9;_(-) 4<5;(H=_(-) (=!_G$9T; '
G$9T;S & @2) 1@) D) @) @'
*ith tht( we re dding preference 41 to &rend 3compny 14"
&ow( crete n order for customer 5jsmith5 with the pln item 32@4" ,)e sure the 5min
su'scription5 flg is set0
The records for #steris) C6$s re too long to copy here in ny meningful wy" !et5s
see the most importnt fields0
3@)B31@0A@0A1)B31@0A@0A1)...)0332@@3@.@@13@@)0332@@3@.@@13@B)0332@@3@.
@@1D@@)A33)0VD)$=S?;5;-)A)jsmith
30)B31@0A@0A1)D@0@0A@0A1)...)0332@@3@.@@13@@)0332@@3@.@@13@B)0332@@3@.
@@1D@@)D3)0VD)$=S?;5;-)A)jsmith
3A)B31@0A@0A1)B31@0A@0A1)...)0332@@3A.@@13@@)0332@@3A.@@13@B)0332@@3A.
@@1D@@)2D)0VD)$=S?;5;-)A)jsmith
31)B31@0A@0A1)B31@0A@0A1)...)0332@@3A.@@13@@)0332@@3A.@@13@B)0332@@3A.
@@1D@@)2D)0VD)$=S?;5;-)A)t"ilson
*e h%e long distnce cll in the second record( two wee)end clls in the lst two
records= the first record should get into the included minutes nd of course jsmith is
su'scri'ed to the pln( 'ut twilson is not( so tht lst record should not 'e free phone
cll"
;ou cn not run the medition process mnully( you would need to schedule it s
e-plined in erlier chpters" #fter the medition process t)es plce( we will h%e one
new order for jsmith" This is one-time order with the chrges coming from the 'o%e
records0
Chapter 11
Pro%isioning
&ntroduction
8ro%isioning cn 'e defined( from jBilling5s point of %iew( s the process of supplying
e%ents to other systems( such s ser%ice gtewy or telephony netwro) system( in
order to h%e those e%ents ser%iced 3or Spro%isionedS4 s re1uired"
7or e-mple( consider the ser%ice cti%tion process0 customer c1uires ser%ice(
which implies the cretion of n order in jBilling" The system tht pro%ides the ser%ice is
howe%er seprted from jBilling itself( nd therefore cti%tion nd decti%tion of the
ser%ice itself is crried out seprtely"
This is not the 'est scenrio( s usully you5ll need more responsi%eness from the
ser%ice infrstructure when certin 'illing e%ents occur0 if the customer opens n
ccount nd pys it( cti%te the ser%ice( or do the e-ct opposite when n in%oice is not
pid timely" This is where pro%isioning comes into the picture"
The pro%isioning module pro%ides jBilling with the 'ility to communicte with such
systems( in wy tht is 'oth scl'le nd fle-i'le enough to stisfy most integrtion
scenrios"
Overview of the provisioning process in jBilling
/llustrtion 1@ shows how pro%isioning is integrted into jBilling nd demrctes its min
components"
The pro%isioning process is initited from 'tch ts) tht cn 'e scheduled from within
jBilling" This ts) identifies ll orders tht re1uire pro%isioning nd determines if specific
Illustration 1-: 3igh level design of the provisioning odule
e%ents 3such s newly creted su'scription4 h%e occurred" /f so( it fires the
pproprite e%ent( which is cptured 'y the pro%isioning plug-in ts) processor"
The plug-in processor recei%es these e%ents nd psses its dt to the 'usiness rules
component" Business rules t)e cre of determining the type of e%ent tht is 'eing
processed nd wht commnds nd prmeters must 'e pssed to the e-ternl system"
The use of 'usiness rules pro%ides gret fle-i'ility in integrtion( s ll commnds nd
prmeters tht must 'e pssed to the e-ternl system cn 'e 'strcted in the
'usiness rules nd cn therefore 'e esily modified or dpted to ny system"
:nce the e-chnge pttern hs 'een populted 'y the rules engine( the plug-in
proceeds to prepre messge contining ll commnds nd prmeters just
generted( nd su'mits this messge to n out'ound <,S 1ueue"
#t the recei%ing end of this 1ueue lies the e-ternl pro%isioning component" This
component t)es cre of recei%ing the messge nd determining how the commnds
indicted in the messge must 'e pssed to the e-ternl system" /t then su'mits the
commnds to the e-ternl system nd processes its responses"
#ll responses from the e-ternl system re wrpped in <,S messge nd su'mitted
'c) to the internl pro%isioning component 'y mens of n in'ound messge 1ueue"
The response messge is prsed 'y the internl component nd the pro%isioning sttus
of the order is updted"
The ad2antage o" $*S
The use of <,S pro%ides gret fle-i'ility nd scl'ility to the process0 you cn deploy
the e-ternl pro%isioning module in seprte ser%er( nd cn esily control the mount
of processing threds tht will ser%ice the 1ueue nd respond to incoming messges"
#lso( you cn t)e d%ntge of the persistence nd fult-tolernce cp'ilities pro%ided
'y ll <,S infrstructures"
#s cn 'e noted on 7igure 1@ 'o%e( the <,S 1ueues effecti%ely decouple the internl
nd e-ternl pro%isioning modules" This not only pro%ides infrstructurl d%ntge 3in
terms of scl'ility4( 'ut lso pro%ides sophisticted functionlity0 the <,S infrstructure
llows multiple messge producers for ech 1ueue nd 3when STopicS 1ueues re used(
s is the cse here4 multiple consumers"
This not only implies tht you cn su'stitute either the internl or e-ternl modules with
customi.ed messge producers or consumers tht generte or ser%ice pro%isioning
re1uests in completely different mnner( 'ut lso tht you5re 'le to integrte other
modules in the pro%isioning process without detching the 'uilt-in components"
Therefore you cn h%e customi.ed pro%isioning e%ent genertors tht post messges
to the out'ound 1ueue nd dri%e the e-ternl pro%isioning module s if those messges
were coming from the internl module( llowing you to h%e single point of interction
with the e-ternl system"
/n the sme mnner( you cn pro%ide customi.ed <,S-dri%en components tht recei%e
notifictions from the out'ound or in'ound 1ueue to pro%ide dditionl functionlity 3for
e-mple( custom component listening to the in'ound 1ueue to generte e-mil
confirmtions whene%er successful pro%isioning opertion t)es plce4"
The only re1uirement n e-ternl <,S-wre component needs to )now to instntly
prticipte in the pro%isioning process is to 'e 'le to SunderstndS the lnguge in
which pro%isioning messges re trnsmitted"
/n E8ample
Throughout this chpter( we will refer to hypotheticl telecommunictions infrstructure
tht pro%ides cell phone ser%ices to pying customers to e-emplify the use of the
pro%isioning modules to feed n e-ternl system" *e ssume tht jBilling is 'eing used
to pro%ide 'illing ser%ices to this infrstructure( nd )eep trc) of pyments( su'scription
cncelltions nd chrging for the ser%ices pro%ided"
7or the s)e of simplicity( we ssume there is only one ser%ice type 3which mps to
single item type in ll orders4( which is flt rte pln" jBilling will hndle the monthly
recurring pyments tht users will py to recei%e the ser%ice"
The e-ternl system we5re trying to tl) to hndles cti%tion nd decti%tion of the cell
phone ser%ice" /t hs no notion of the pyments nd in%oicing hndled 'y jBilling( nd
only needs to )now when to cti%te new su'scri'er 3'ecuse it hs strted to py the
monthly fee4 or when to decti%te former su'scription 3'ecuse the user hs stopped
pying the monthly fee4"
Therefore( we need to notify the e-ternl system 'out su'scription cti%tion nd
decti%tion e%ents tht occur within jBilling during 'illing opertions"
*hile we progress through this chpter( we will return to this e-mple nd pro%ide code
nd implementtion detils 'out how the pro%isioning process helps orchestrte the
interctions 'etween jBilling nd the telecommunictions infrstructure in this e-mple"
The internal provisioning module
The internl pro%isioning module t)es cre of identifying the e%ents tht re1uire
pro%isioning( pplying 'usiness rules to these e%ents nd rely the commnds produced
'y the rules to the e-ternl pro%isioning module"
/n order to cti%te the pro%isioning process( the jbilling.properties file needs to 'e
modified to contin the following line0
process.run_provisioning=true
Setting this property to true( dily 'tch process tht runs within jBilling will generte
pro%isioning e%ents s they re detected"
The pro2isioning status o" orders
:rders 3nd order lines4 now h%e sttus field tht indictes their pro%isioning sttus"
#ll orders entered will trc) the sttus of the pro%isioning process" This sttus ser%es to
identify which orders still need to 'e pro%isioned nd which h%e lredy 'een su'ject to
this process"
These re the ccept'le sttus codes0
C5<G(S(<=(=H_S!$!TS_$7!(G;
C5<G(S(<=(=H_S!$!TS_(=$7!(G;
C5<G(S(<=(=H_S!$!TS_C;=-(=H_$7!(G;
C5<G(S(<=(=H_S!$!TS_C;=-(=H_(=$7!(G;
C5<G(S(<=(=H_S!$!TS_4$(9;-
C5<G(S(<=(=H_S!$!TS_T=$G$(9$B9;
These %lues cn 'e used from within the pro%isioning rules to determine the sttus of
the pro%isioning process nd id in deciding wht specific opertions should 'e
forwrded to pro%ision the e%ent"
)ro2isioning e2ents and the pro2isioning plug#in
jBilling5s plugg'le rchitecture introduces the notion of e%ents( which is the wy in
which the system notifies the occurrence of gi%en set of conditions to chin of
o'ser%ers for the purpose of h%ing the e%ent ser%iced" The description of e%ents nd
the wy in which they re implemented nd produced within jBilling is 'eyond the
purpose of this chpter nd is descri'ed in detil in Chpter B of the jBilling5s E-tension
Puide"
8ro%isioning conditions re hndled s jBilling e%ents" # dily 'tch process scns the
dt'se serching for order tht re1uire pro%isioning" :nce it finds one( it determines
whether specific e%ent hs t)en plce for tht order nd( if necessry( rises n e%ent
tht will 'e fed to the chin of plug-ins configured in jBilling" This is the strting point of
the pro%isioning process"
The type of e%ent tht is fired determines which specific type of pro%isioning ction tht
will t)e plce0
Subscription$ctive;vent0 fired when su'scription 'ecomes cti%e 3usully it
is used to trigger the cti%tion of the relted ser%ice4" This e%ent refers to the
entire order( rther thn specific order lines"
Subscription(nactive;vent0 fired when su'scription chnges stte nd
'ecomes incti%e 3usully this e%ent is used to trigger decti%tion of the relted
ser%ice4" This e%ent refers to the entire order"
=e"8uantity;vent0 fired when the 1untity of n order line is chnged 3usully it
is used to trigger chnge of ser%ice type or le%el4" This e%ent refers to single
order line"
/t is importnt to note tht the e%ent ser%es s signl of the occurrence of gi%en
condition( nd m)es no ssumptions whtsoe%er regrding the hndling of the
condition" This is delegted to the plug-in chin"
The e%ent is pushed through the plug-in chin in serch of plug-in tht will ser%ice the
e%ent" This is e-ctly the sme wy in which jBilling ser%ices other e%ents tht occur in
the system( such s pyment filures or un%il'ility of pyment gtewys 3gin( refer
to the E-tension Puide for further informtion regrding e%ents( plug-ins nd their
implementtion detils4"
By defult( pro%isioning e%ents re ser%iced 'y 'usiness rules written in the 6rools
lnguge( s descri'ed in the ne-t section" jBilling pro%ides defult implementtion
tht ser%ices pro%isioning e%ents( clled Crovisioning7ommands5ules!as>" ;ou cn of
course write dedicted plug-in to ser%ice pro%isioning e%ents( this is just the defult
implementtion nd will 'e descri'ed 'elow"
/n order to properly ser%e pro%isioning re1uests with 'usiness rules( you will need to
cti%te this plug-in 'y configuring it in the plug-in list under the System .L Clugins
menu of jBilling5s 2ser /nterfce" $efer to the jBilling 2ser5s Puide nd E-tension
Puide for instructions on how to cti%te plug-ins in the system"
The purpose of this plug-in is tht of e%luting the order 3or order line4 for which the
e%ent is t)ing plce ginst the set of pro%isioning rules you pro%ide" These rules will
descri'e wht specific interctions should t)e plce with the e-ternl system in order to
properly ser%ice the e%ent"
/n the cse of our smple telecommunictions infrstructure( we5re only interested in the
Subscription$ctive;vent nd Subscription(nactive;vent e%ents( which
notify us 'out su'scription cti%tions nd decti%tions( which re the cses in which
we need to interct with the e-ternl system to pro%ide or suspend the cell phone
ser%ice" /n this cse( we ignore the =e"8uantity;vent condition( whose min
purpose is tht of sensing chnges in rte plns or ser%ice types" Since our smple cell
phone opertors only pro%ides single flt rte pln( we cn sfely ignore chnges in
rte plns or ser%ice types"
)ro2isioning rules
Business rules e-pressed in the 6rools lnguge re %ery fle-i'le mnner of cpturing
'usiness-relted decisions nd h%e 'een widely dopted within jBilling" The
pro%isioning process is not n e-ception( s the defult internl pro%isioning module
delegtes ll decisions on how to process specific pro%isioning e%ent to 'usiness
rules"
Business rules re introduced elsewhere nd will not 'e descri'ed here( plese refer to
the SChpter A 8rocessing with rulesS section of this document( Chpter D of jBilling5s
E-tension Puide or the 6rools 2ser Puide for further informtion regrding the synt-
nd usge of 'usiness rules"
!et5s therefore concentrte on simple pro%isioning rule0
rule provisioning_activate
"hen
Morder9ine + <rder9ine-!<&item(d == 0) provisioningStatus(d ==
7onstants.C5<G(S(<=(=H_S!$!TS_(=$7!(G;'
7ommandManager&event!ype == NactivatedN'
then
command.add7ommand&Nactivate_userN) Morder9ine.get(d&''K
command.addCarameter&NmsisdnN) N@0A1DN'K
command.addCarameter&NimsiN) N@@@@@N'K
end
The rule 'o%e mtches ll e%ents of type Scti%tedS 3the event!ype property hs two
possi'le %lues( SactivatedS or SdeactivatedS4( for order lines with item /6 2 h%ing
pro%isioning sttus of C5<G(S(<=(=H_S!$!TS_(=$7!(G; 3which mens they were
incti%e prior to the pro%isioning opertion 'eing ser%iced4"
/f these conditions pply( the rule dds list of commnds nd prmeters to the
ScommandS o'ject 3which is glo'l import of type com.sapienter.jbilling.server.
provisioning.tas>.Crovisioning7ommands5ules!as>.7ommandManager4( 'y clling
the pproprite add7ommand&' nd addCarameter&' methods"
These commnds nd prmeters re the ones tht will 'e pssed to the e-ternl
system %i the <,S messge nd their 1untity( type nd %lue is he%ily dependent on
the type of ser%ice you5re trying to in%ol%e in the pro%isioning process"
;ou cn pss se%erl commnds nd prmeters( in the sme mnner0
rule W
"hen
W
then
command.add7ommand&Ndo_somethingN) Morder9ine.get(d&''K
command.addCarameter&Nparm@N) N@0A1DN'K
command.add7ommand&Ndo_something_elseN) Morder9ine.get(d&''K
command.addCarameter&Nparm0N) ND1A0@N'K
end
Ech commnd is identified 'y commnd nme 3the first rgument to the
add7ommand&' cll( Scti%teMuserS in this cse4( which will 'e importnt lter( when the
messge commnds will 'e trnslted into e-ternl clls"
The order line /6 num'er is pssed in the commnd definition nd ser%es in identifying
the order line for which the e%ent ws rised when the pro%isioning response is
processed"
:f course( you cn supply dditionl rules tht cpture other conditions" ;ou cn pply
whte%er conditions you wish on the order line 3item type( 1untity( mount( etc"4 or use
order line dt s prmeter dt in the commnd clls"
The 6rools wor)ing memory for pro%isioning 'usiness rules contins two types of
o'jects tht cn 'e used to e-press rule conditions or ctions in 'usiness rules0
command0 glo'l 7ommandManager o'ject" /t contins two methods for dding
commnds nd commnd prmeters to the pro%isioning messge0
add7ommand&String command=ame) 9ong order9ine(d'0 is used
to dd commnd to the pro%isioning messge" The commnd will lter
trnslte to n interction in the e-ternl pro%isioning module"
addCarameter&String name) String value'0 nme-%lue pir
tht descri'es prmeter to 'e pssed to the e-ternl pro%isioning
module 3usully used to communicte dt to the pro%isioned system4"
7ommandManager0 you cn use this o'ject in rule conditions s well" This o'ject
e-poses the following properties0
event!ype0 Cs two possi'le %lues0 SactivatedS or SdeactivatedS(
indicting whether the e%ent hppened during su'scription cti%tion or
decti%tion( respecti%ely 3in cse of =e"8uantity;vents( it is
SactivatedS when the pre%ious 1untity for the order line ws 0(
SdeactivatedS when the new 1untity for the order line hs 'een set to
0( nd hs no meningful %lue when 'oth prior nd new 1untities re
different from 04"
<rder-!<0 the o'ject tht descri'es order prmeters" ;ou cn use it to
mtch most order dt( such s sttus( recurrences( periods( user( etc"
<rder9ine-!<0 used in conditions to mtch the order line tht triggered the
e%ent 3in cse of =e"8uantity;vent4 or ny line in the order 3in cse of
Subscription$ctive;vent or Subscription(nactive;vent4"
:rder!ine6T: contins most dt regrding the order line( such s item(
1untity( mount( price( etc"
$eturning to our smple cell phone opertor( we would need to cpture our 'usiness
conditions 3which re ser%ice cti%tion nd decti%tion4 in two 'usiness rules0
rule Service$ctivation
"hen
7ommandManager & event!ype == NactivatedN '
Mline + <rder9ine-!< & provisioningStatus(d ==
7onstants.C5<G(S(<=(=H_S!$!TS_(=$7!(G; '
then
command.add7ommand&Nactivate_serviceN) Mline.get(d&''K
command.addCarameter&NnumberN) Mline.get-escription&''K
end
rule Service-eactivation
"hen
7ommandManager & event!ype == NdeactivatedN '
Mline + <rder9ine-!< & provisioningStatus(d ==
7onstants.C5<G(S(<=(=H_S!$!TS_$7!(G; '
then
command.add7ommand&Ndeactivate_serviceN) Mline.get(d&''K
command.addCarameter&NnumberN) Mline.get-escription&''K
end
The SService$ctivationS rule t)es cre of mpping ser%ice cti%tion e%ents" *e5re
interested in SactivatedS event!ypes for order lines whose pro%isioning sttus is
(=$7!(G; 3this ser%es to filter out e%ents for su'scriptions tht h%e lredy 'een
cti%ted in the pst4" *e pss single commnd to the e-ternl pro%isioning module
3Sactivate_serviceS4 with single prmeter 3the SnumberS prmeter( contining
the cell phone num'er( which for the s)e of simplicity of the e-mple hs 'een
retrie%ed from the description property of the order line4"
The SService-eactivationS rule t)es cre of the opposite sitution0 mpping
ser%ice decti%tions signled for su'scriptions tht re still in the $7!(G; stte" This
trnsltes to the single commnd Sdeactivate_serviceS( with the single prmeter
SnumberS contining the cell phone num'er"
/n this cse( we don5t enforce specific item /6 in the conditions of these rules s we5re
ssuming tht our simplified cell phone opertor hs only one item which mps to the
only rte it pro%ides" This is ll we need to cpture the two simple conditions tht re
rele%nt to our contri%ed cell phone opertor" # SnormlS ser%ice would pro''ly need
se%erl rules filtering out chnges in rtes or plns( rechrges of prepid trffic( filures
in the pro%isioning clls( etc"
:nce ll pro%isioning rules h%e 'een e%luted nd the 7ommandManager o'ject hs
'een populted with the commnds nd prmeters to 'e pssed to the e-ternl
pro%isioning module( the plug-in proceeds to generte messge tht will 'e posted to
the out'ound <,S 1ueue"
The pro2isioning queues
#ll <,S messges trnsit in 1ueues defined t system le%el" By defult( jBilling uses
#pche #cti%e,L s <,S pro%ider" The 1ueues defined 'y defult on the stndrd
instlltion re #ueue.jbilling.provisioning7ommands s the out'ound 1ueue nd
topic.jbilling.provisioning7ommands5eply s the in'ound 1ueue"
:f course( you cn choose different <,S pro%ider or chnge the nme of the 1ueues if
needed" Lueue prmeters in jBilling re 'strcted inside Spring configurtion file
nmed jbilling.jms.xml( locted under the jbilling/conf directory"
8lese refer to the Spring documenttion to determine how to configure different <,S
pro%ider or chnge the 1ueue nmes 3lthough the ltter is seldom necessry4"
The e%ternal provisioning module
The e-ternl pro%isioning module ser%ices the out'ound <,S 1ueue nd t)es cre of
con%erting the <,S messge generted 'y the pro%isioning plug-in 3or some other
client4 into series of commnds tht will 'e forwrded to the e-ternl system"
Commnds descri'e the interctions with the pro%isioned system tht must t)e plce in
order to ser%ice pro%isioning e%ent" Commnds cn h%e series of prmeters( set
of nme-%lue pirs indicting the nme of the prmeter nd its %lue"
The first cti%ity crried out 'y the e-ternl pro%isioning module is tht of decoding the
input messge nd creting commnd mp tht descri'es the commnds recei%ed"
This commnd mp trnsltes into simple 9istIString)StringL o'ject tht
contins the list of nme-%lue pirs of ll prmeters pssed to the e-ternl module"
The ,essge ,pper must 'e configured to est'lish the commnds nd prmeters
tht our e-ternl pro%isioning module ccepts nd %lidte incoming messges nd
responses" Configurtion of the ,essge ,pping component is the su'ject of the ne-t
section"
The e-ternl pro%isioning module pushes this commnd mp through stc) of e-ternl
pro%isioning plug-ins 3which follow the stndrd jBilling plug-in con%entions4" These
plug-ins t)e cre of processing the pro%isioning re1uest nd performing the ctul
interction with the e-ternl systems" This is where most of the coding effort goes when
implementing pro%isioning ser%ice" *e will descri'e the cretion of e-ternl
pro%isioning plug-ins lter in this chpter( for the moment we5re just interested in )nowing
tht the messge mpper will recei%e the messge generted 'y the rules in the internl
module nd rely the commnd mp to our plug-in"
&on"iguration o" the *essage *apping component
#s pre%iously noted( the ,essge ,pping component of the e-ternl pro%isioning
module needs to )now wht commnds nd prmeters cn 'e pssed to the
pro%isioning plug-ins" This ser%es to %lidte incoming messges 3remem'er tht the
e-ternl pro%isioning module could recei%e messges from other sources( nd therefore
messges could 'e gr'led or incorrectly formed4"
The file tht contining configurtion dt for the messge mpper is locted under
jbilling/conf nd is nmed jbilling.provisioning.xml" This file is Spring 'en
definition file nd descri'es the mpping of <,S messge into commnds"
The commnd trnsltion logic is di%ided into commnds" Ech commnd descri'es
set of interctions nd defines set of prmeters tht will 'e pssed to the pro%isioned
system" /t lso defines set of processors( which re the entities tht descri'e the
interction with the e-ternl system"
8lese refer to the Spring documenttion if you need further informtion regrding 'en
fctories nd their use" !et5s concentrte on descri'ing the functionlity of the
configurtion prmeters nd their use" The following demonstrtes the configurtion for
the Scti%teMser%iceS nd Sdecti%teMser%iceS commnds introduced in the rules
creted for our smple cell phone opertor"
IbeansL
Ibean id=NprovisioningN
class=Ncom.sapienter.jbilling.server.provisioning.config.CrovisioningNL
Iproperty name=NcommandsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.7ommandNL
Iproperty name=NidN value=Nactivate_serviceN /L
Iproperty name=NfieldsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.4ieldNL
Iproperty name=NnameN value=NnumberN /L
I/beanL
I/listL
I/propertyL
Iproperty name=NprocessorsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.CrocessorNL
Iproperty name=NidN value=Nsample_cell_serviceN /L
Iproperty name=Nre#uestsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.5e#uestNL
Iproperty name=NorderN value=N@N /L
Iproperty name=NsubmitN
value=Nne"Subscription+number)UnumberUKN /L
Iproperty name=Npost5esultN value=NtrueN /L
I/beanL
I/listL
I/propertyL
I/beanL
I/listL
I/propertyL
I/beanL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.7ommandNL
Iproperty name=NidN value=Ndeactivate_serviceN /L
Iproperty name=NfieldsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.4ieldNL
Iproperty name=NnameN value=NnumberN /L
I/beanL
I/listL
I/propertyL
Iproperty name=NprocessorsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.CrocessorNL
Iproperty name=NidN value=Nsample_cell_serviceN /L
Iproperty name=Nre#uestsNL
IlistL
Ibean
class=Ncom.sapienter.jbilling.server.provisioning.config.5e#uestNL
Iproperty name=NorderN value=N@N /L
Iproperty name=NsubmitN
value=NcancelSubscription+number)UnumberUKN /L
Iproperty name=Npost5esultN value=NtrueN /L
I/beanL
I/listL
I/propertyL
I/beanL
I/listL
I/propertyL
I/beanL
I/listL
I/propertyL
I/beanL
I/beansL
Both commnds 'o%e define single processor nmed Ssample_cell_serviceS in
their SprocessorsS property" The nme of the processor is used to identify the e-ternl
pro%isioning plug-in tht will t)e cre of ser%icing the interction"
The Ssample_cell_serviceS processor defines two re1uests to the e-ternl system"
$e1uests h%e n SorderS ttri'ute tht indictes the order in which they should 'e
e-ecuted"
$e1uest property SsubmitS indictes the interctions tht will 'e posted to the e-ternl
system 3its SvalueS ttri'ute contins the commnd tht will 'e pssed to the plug-in(
such s Sne"Subscription+number)UnumberUKS 3note the prmeter plceholders
such s SUnumberUS tht indicte the loction of the commnd in which prmeter %lues
will 'e e-pnded when <,S messge is trnslted4" This specific e-mple mps to
commnd nmed Sne"SubscriptionS with prmeter nmed SnumberS"
$e1uest properties h%e two more properties tht cn 'e configured0 Spost$esultS is
'oolen property tht controls whether the commnd response is posted 'c) to the
in'ound <,S 1ueue( nd Scontinue:nTypeS indictes the %lue of the response result
tht represents %lid trnsction nd llows the plug-in to proceed with the ne-t
re1uest commnd( if present" /f no Scontinue:nTypeS property is specified( e-ecution will
stop t this re1uest"
The following t'le descri'es ll ttri'utes of the configurtion file in greter detil0
Tag Re@uired ultipli9ity !es9ription
proBisionin/
;es 1 $oot tg"
command
;es 1 $e1uires n id ttri'ute( to identify this
commnd" The %lue of the id ttri'ute will
mp to the 5commnd5 prmeter recei%ed in
the <,S messge"
field
&o 0""U Ech field contins the nme of prmeter
pssed in the <,S messge" The
5defult9lue5 ttri'ute is optionl( if present(
its %lue is used only if the field is not present
in the <,S messge( or its %lue is null or
empty"
processor
;es 1""U The id ttri'ute is re1uired nd will llow the
,6B to find the right plug-in" E%ery plug-in
hs to h%e the 5id5 prmeter present"
reIuest
;es 1""U The order ttri'ute is re1uired nd llows the
re1uests to 'e sorted for e-ecution"
submit
;es 1 The string tht will 'e sent to the plug-in(
defining plceholders for the input
prmeters s needed"
response
&o 0""1 :nly groups the response relted tgs
post_result
&o 0""1 /f present( then the ,6B hs to post the
results on the in'ound 1ueue"
continue_on_tp
e
&o 0""1 /f not present( then do not continue to the
ne-t re1uest" /f present( then continue only
on the type specified" E%ery cll to plug-in
hs to return the field 5result5" /f the %lue of
tht field mtches the %lue of this tg(
continue to the ne-t re1uest"
The e8ternal pro2isioning plug#in
The specific plug-in tht hndles the commnd e-ecution t)es cre of creting the
connection with the e-ternl system s necessry 3opening telnet session or whte%er
other opertions re necessry to est'lish communictions with the e-ternl system4"
There re two e-ternl pro%isioning plug-ins shipped with jBilling0 C#/ nd ,,SC(
co%ering two use cses for the plug-in 3one using telnet session with the e-ternl
system( the other relies on we' ser%ice clls to interct with the ,,SC ser%ice4" ,ost
pro''ly( you5ll need to implement your own plug-in to hndle communictions with the
e-ternl system( 'ut these two could ser%e to illustrte the wy in which the plug-in
ser%ice the commnd mp pssed 'y the messge mpper"
E-ternl pro%isioning plug-ins h%e plug-in ctegory of their own 3ctegory 1D( see the
E-tension Puide for further informtion on plug-in ctegories nd their role in plug-in
configurtion4" They follow the sme principle to which ll jBilling plug-ins must dhere0
e-tend the 'strct clss Cluggable!as>" /n ddition( they need to implement the
(;xternalCrovisioning interfce( which mndtes implementtion of two methods0
MapIString) <bjectL send5e#uest&String id) String command' thro"s
!as>;xception
nd
String get(d&'
The %lue returned 'y the plug-in5s get(d&' method must mtch the processor5s id
property indicted in the messge mpping configurtion" This is how the messge
mpper identifies which processors to in%o)e for ech specific commnd( nd llows you
to seprte commnds in different plug-ins 3for e-mple( if you need to feed two different
e-ternl systems for the sme pro%isioning e%ent4"
The send5e#uest&' method is the one tht ctully performs the interction with the
e-ternl system" *hen clled( its id prmeter contins the P2/6 of the <,S messge
to uni1uely identify the originting <,S messge( wheres the command prmeter
contins the resulting string tht ws constructed 'sed on the I,! configurtion
descri'ed in the pre%ious section" #ll the prmeters 3enclosed in 5Y54 h%e 'een prsed
so you get the rel %lues"
Cow re the commnd prmeters pssed to the plug-in> The plug-in recei%es single
string tht follows the formt defined in the 'o%e configurtion" Thus( it is the plug-in
responsi'ility to e-trct the prmeters from this string"
The plug-in prmeters 3do not confuse with the commnd prmeters" The plug-in
prmeters re used for e%ery cll nd do not chnge in 'etween clls4 re typiclly
used to store dt needed to rech the e-ternl system 3port num'ers( /8 ddresses4
nd est'lish session 3user nme( pssword"""4"
*e cn now finlly code the plug-in for our smple cell phone opertor" Cere( we simply
ignore the detils of the connection to the e-ternl system( s ctul implementtions
%ry gretly 3telnet sessions( we' ser%ices( $ESTful CTT8 clls( etc"4" *e will just flesh
out the code tht pro%ides the connection nd ssume generic external7all o'ject
with two methods 3ne"Subscription&' nd cancelSubscription&'( ech
ccepting single num'er rgument nd returning n int indicting the outcome of the
opertion0 1 if successful nd 0 if unsuccessful4"
class SimpleCrovisioning!as> extends Cluggable!as>
implements (;xternalCrovisioning O
private static final String C5<7;SS<5 = Nsample_cell_serviceNK
public String get(d&' O
return C5<7;SS<5K
P
public MapIString)<bjectL send5e#uest&String id)
String command' thro"s !as>;xception O
// <btain and validate the NnumberN parameter
// /ere "e use a helper method that fetches the value
// of number from the command ex+
// cancelSubscription+number)@0A1DB2EVK
String number = get7ommandCarameter&XnumberY) command'K
if &number == null UU number.e#uals&NN'' O
thro" ne" !as>;xception&Ninvalid numberN'K
P

// !he command string contains the command names indicated
// in the mapping configuration+
// . addSubscription
// . cancelSubscription
int result = 3K
if &command.starts?ith&NaddSubscriptionN'' O
result = external7all.ne"Subscription&number'K
P else if &command.starts?ith &NcancelSubscriptionN'' O
result = external7all.cancelSubscription&number'K
P else O
thro" ne" !as>;xception&N(nvalid command N * command'K
P
MapIString)<bjectL resultMap = ne" /ashMapIString)<bjectL&'K
resultMap.put&NresultN) (nteger.value<f&result''K
return resultMapK
P
P
&ote tht single pro%isioning e%ent could in%ol%e more thn one cll to the pro%isioned
system( or e%en prllel clls to seprte e-ternl systems" Ech commnd is
encpsulted in seprte $e1uest in the mpping configurtion"
/f the re1uest hs 'een configured with post5esult property with StrueS %lue( the
response pro%ided 'y the e-ternl system will 'e propgted 'y mens of the <,S
in'ound 1ueue" The response <,S messge will contin ll input prmeters tht were
present in the input <,S messge 3prefi-ed 'y Sin_S4 nd ll output prmeters
generted 'y the e-ternl system 3prefi-ed 'y Sout_S4"
!et5s see the output messge mpping in ction" #ssuming n input messge contining
the following fields0
$ame 8alue
id fff1e0-44-11dd-E?-0002@d@c@1'
commnd cti%teMser%ice
num'er A0412?12?4
The generted output messge will contin the following fields0
$ame 8alue
inMid fff1e0-44-11dd-E?-0002@d@c@1'
inMcommnd cti%teMser%ice
inMnum'er A0412?12?4
outMresult success
Error handling
/n cse of errors during e-ecution of the e-ternl pro%isioning plug-in( cused 'y lc) of
%il'ility of the connection to the e-ternl system or other conditions( the e-ternl
pro%isioning module ne%ertheless pro%ides n error response" This response hs the
5out_result5 property populted with n SunavailableS %lue( nd n SexceptionS
property contining the e-ception messge tht detils the type of error condition rised
during e-ecution of the plug-in" #n error messge for the pre%ious e-mple would loo)
li)e the following0
$ame 8alue
inMid fff1e0-44-11dd-E?-0002@d@c@1'
inMcommnd cti%teMser%ice
inMnum'er A0412?12?4
outMresult un%il'le
e-ception &ull8ointerE-ception

Telecom Guide: The Open Source Enterprise Billing System

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Telecom Guide: The Open Source Enterprise Billing System

Uploaded by

Copyright:

Available Formats

w

You might also like