Buckets
Introduction
A bucket is a single monetary or non-monetary value, with an associated type. When stored in the OCS, a bucket’s core data consists of:
| Field | Description |
|---|---|
value |
The numeric value given to the bucket. May be negative or positive. The maximum value is2^63-1, and minimum value is -2^63 |
unit |
A logical monetary or non-monetary unit defining the type of value held in the bucket. This may be microcents, seconds, bytes, counter, or flag. |
expiry |
An optional expiry date/time may be defined for a bucket. Buckets with an expiry are automatically removed at the date/time as determined by (a) the system clock time and (b) the bucket timezone annotation (if any) |
Additional fields for auditing and session management exist, and bucket annotations may be used to grant buckets additional information for extended use in the OCS.
Some systems may group multiple buckets of the same type together, either hiding or obfuscating their granularity. In the N-Squared OCS each bucket is given a unique ID and each is managed independently.
Bucket Expiry
A bucket may be automatically expired (even with a non-zero or usable balance value) at
specific date and time by setting the bucket’s expiry to a fixed date and time.
Buckets on a wallet will always store an explicit date and time for expiry, if one
is set:
The bucket expiry is normally evaluated in the context of the OCS’s server timezone (which may
not be the same timezone as the one used to display the time in the OCS administration
screens), or if the wallet has a timezone annotation, in the context of the
wallet’s timezone.
Expiry Calculation
When defining an expiry for a bucket, the expiry can be given in terms of a calculation to be performed by the server:
When given as a calculation in this form, the bucket expiry is calculated immediately on save (the information to calculate the expiry is not stored for a later time by the OCS).
Bucket expiry details are covered in more detail in the bucket expiry section.
Auditing and History
As a “real time rating engine”, the N-Squared OCS maintains only the current balance of a wallet (and hence only the current balance of each individual bucket). However, extended auditing details in the bucket exist to provide both current and original creation details:
The following auditing fields are available for each bucket:
| Field | Description |
|---|---|
| Created | The timestamp for when the bucket was first created on the wallet, and the host/user who created the bucket. |
| Last Modified | The timestamp for when the bucket was last altered on the wallet, and the host/user who last altered it. |
| Initial Value | The value of the value field when the bucket was first created. This would be the value of the bucket as granted by a voucher if the bucket was created through a voucher redemption. |
| Derived From | This field is stored when the bucket was created by another OCS process, such as a voucher redemption or subscription being applied to the wallet. The information stored depends on the source of the bucket, and will include information such as the voucher serial number (if created by a voucher redemption). |
Annotations
Annotations are applied to buckets to grant buckets additional rule-sets which are then applied in the OCS where required. The following annotations may be applied:
Name
A bucket may be annotated with a name, which gives the bucket a unique (in the
wallet) name. Useful when a specific bucket has a special purpose, and only
one bucket should exist with that purpose.
Name annotations may be checked in rating to order buckets so that bucket usage is deterministic.
Group
A bucket may be annotated with the group annotation to group the bucket with
other buckets under a single named group. Group annotations are useful for
associating different buckets with different purposes - e.g. promotional
cash may be used for local phone calls only, so a group with the name promotional-cash
(for example) can be checked for during bucket selection prior to rating.
Once a group annotation is created, the group name is not editable. If a group must be changed, delete the group annotation and create a new one.
Group annotations may be checked in rating to order buckets so that bucket usage is deterministic.
Locations
A location annotation may be used during rating to restrict the use of certain buckets from being used in particular rating events.
For example, a promotional cash balance might be usable only for local (on-net) voice calls, and not for any other purpose. By defining a location annotation, a bucket will be excluded from rating sessions where the calling (or called) party is not in the allowed location list.
Parameters
| Name | Description |
|---|---|
whitelist |
The locations where the bucket has a whitelist association. The whitelist is optional. |
blacklist |
The locations where the bucket has a blacklist association. The blacklist is optional. |
purpose |
An string identifying the purpose & use of this location annotation. Set this to LocationRatingPolicy.source_location or LocationRatingPolicy.destination_location to have this annotation used by the Location Rating Policy |
An empty whitelist will mean the bucket can be used at any location (excepting for those listed in the whitelist). An empty blacklist will mean the bucket’s whitelist will determine the location(s) the bucket can be used from
Minimum Value
A minimum value annotation may be applied to a bucket to give a bucket a value other than 0 as the minimum value. All buckets without an explicit minimum value annotation are considered to have a minimum value of 0.
Minimum value annotations are useful for “limited credit” scenarios, where a wallet balance may decrease below 0 temporarily.
Static Value
A static value annotation may be applied to a bucket to fix the value of that bucket in place, regardless of rating applied to the balance. The value can be changed through the OCS administration screens, but rating will not alter the value.
During rating, the value of a static-value annotated bucket will be considered to have
the bucket’s value for each rating event the bucket is used in. That is, every
commit of funds during a session will consider the bucket to have the given
value. Every event the bucket is used to charge will not cause this bucket’s actual
value to change.