This appendix describes the modified and custom attribute-value pairs (AVPs) used by Oracle Communications Billing and Revenue Management (BRM) Elastic Charging Engine (ECE) Diameter Gateway.
Oracle has modified several standard AVPs to include functionality that is not defined in the RFC or 3GPP specifications, such as top-up and balance-specific debits and refunds.
AVP code: 436
Type: Enumerated
The Requested-Action AVP is used by the Diameter Gateway to indicate the requested action in the Credit-Control-Request command. This AVP has been extended with Top-Up and Balance_Query enumerations.
Table A-1 shows the list of enumerations defined for the Requested-Action AVP.
Table A-1 Requested-Action Enumerations
| Enumeration | Value | Notes |
|---|---|---|
|
DIRECT_DEBITING |
0 |
See |
|
REFUND_ACCOUNT |
1 |
See |
|
CHECK_BALANCE |
2 |
Diameter Gateway does not support CHECK_BALANCE. |
|
PRICE_ENQUIRY |
3 |
See |
|
TOP-UP |
4 |
Indicates a request to recharge the end user's account with the information specified in the ORA-Account-Topup AVP. The balance valid on the end user's account after the top-up is returned in the ORA-Balance-Element AVP in the Credit-Control response. |
|
BALANCE_QUERY |
5 |
Indicates a request for the current valid balance of the end user, which will be returned in an ORA-Balance-Element AVP in the Credit-Control response. The level of detail of the response can be modified by the ORA-Balance-Query-Mode AVP. The balances returned can be filtered on the server to a product by specifying Service-Indicator and Rating-Group AVPs in the request. |
AVP code: 456
Type: Grouped
The Multiple-Services-Credit-Control AVP has been extended to include some Oracle specific AVPs, which are used to return additional information related to an event or a session.
The Multiple-Services-Credit-Control AVP supported by Diameter Gateway is defined as follows:
Multiple-Services-Credit-Control ::= < AVP Header: 456 >
[ Granted-Service-Unit ]
[ Requested-Service-Unit ]
* [ Used-Service-Unit ]
[ Service-Identifier ]
[ Rating-Group ]
[ Validity-Time ]
[ Result-Code ]
[ Final-Unit-Indication ]
[ ORA-Customer-Cost-Information ]
[ ORA-Remaining-Balance ]
[ ORA-Credit-Threshold-Breach ]
AVP code: 437
Type: Grouped
The Requested-Service-Unit AVP has been extended to include the CC-ORA-Balance-Element AVP to allow a specific balance type to be charged in a direct-debit request or refunded in a refund request.
The Requested-Service-Unit AVP supported by Diameter Gateway is defined as follows:
Requested-Service-Unit ::= < AVP Header: 437 >
[ CC-Time ]
[ CC-Money ]
[ CC-Total-Octets ]
[ CC-Input-Octets ]
[ CC-Output-Octets ]
[ CC-Service-Specific-Units ]
[ CC-ORA-Balance-Element ]
Note:
The CC-Money and CC-ORA-Balance-Element AVPs are only supported in the context of a direct-debit request or a refund request. They are not supported for event or session reservation scenarios.AVP code: 431
Type: Grouped
The Granted-Service-Unit AVP has been extended to include the CC-ORA-Balance-Element AVP to confirm that a specific balance type has been charged in a direct-debit response or refunded in a refund response.
The Granted-Service-Unit AVP supported by Diameter Gateway is defined as follows:
Granted-Service-Unit ::= < AVP Header: 431 >
[ CC-Time ]
[ CC-Money ]
[ CC-Total-Octets ]
[ CC-Input-Octets ]
[ CC-Output-Octets ]
[ CC-Service-Specific-Units ]
[ CC-ORA-Balance-Element ]
Note:
The CC-Money and CC-ORA-Balance-Element AVPs are only supported in the context of a direct-debit response or a refund response. They are not supported for event or session reservation scenarios.Diameter Gateway uses some Oracle-specific AVPs other than the standard AVPs defined in the supported RFC or 3GPP standards. The Oracle-specific AVPs contain ORA- in its name and the vendor ID for these AVPs is 3512.
AVP code: 233
Type: Unsigned32
The ORA-Balance-Element-Id AVP is used to indicate the unique ID of a requested or returned balance element. A balance element can represent a currency or noncurrency asset of economic value, such as U.S. dollars, or a counter, such as loyalty points. A currency balance has an ORA-Balance-Element-Id equivalent to the ISO-4217 currency number; a noncurrency balance has an operator defined ID, such as 1000050.
AVP code: 213
Type: Time
The ORA-Validity-Start-Time AVP is used to indicate the valid-from date of a balance instance returned by Diameter Gateway. ORA-Validity-Start-Time can also be used in a top-up request to provide a specific date that the recharged balance should be available to be used from.
Note:
Only the balances that are valid at the time of the request are returned by ECE.AVP code: 214
Type: Time
The ORA-Validity-End-Time AVP is used by the Diameter Gateway server to indicate the expiry date of a returned balance instance. This AVP can be used by a client in a top-up request to provide a specific date that the recharged balance should expire on.
AVP code: 236
Type: Grouped
The CC-ORA-Balance-Element AVP can be used in a debit or a refund to specify an exact balance against which the operation should be made.
The CC-ORA-Balance-Element AVP is defined as follows:
CC-ORA-Balance-Element ::== < AVP-Header: 236 3512 >
{ ORA-Balance-Element-Id }
{ Unit-Value }
AVP code: 248
Type: Enumerated
The ORA-Balance-Query-Mode AVP is used by the client to indicate the level of detail required in a balance query.
Table A-2 shows the list of values defined for the ORA-Balance-Query-Mode AVP:
Table A-2 ORA-Balance-Query-Mode Values
| Mode | Value | Notes |
|---|---|---|
|
SUMMARY |
1 |
Returns the total value for each balance instance and expiries. This is the default mode if ORA-Balance-Query-Mode is not specified. |
|
FULL |
2 |
Returns all balance information, including Credit Floor and Credit Ceiling limits, Thresholds, and Active reservations. |
AVP code: 249
Type: Grouped
The ORA-Balance-Details AVP is returned by ECE in response to a balance query and returns an array of all balances valid against the account (that is, the balance start date is in the past and the expiry date, if set, is in the future).
The ORA-Balance-Details AVP is defined as follows:
ORA-Balance-Details ::== < AVP-Header: 249 3512 >
* { ORA-Balance-Element }
AVP code: 241
Type: Grouped
The ORA-Remaining-Balance AVP is returned in the Multiple-Services-Credit-Control AVP and also as a response to a top-up request. This AVP indicates the remaining credit the end user has that is applicable to the service.
To have the ORA-Remaining-Balance AVP returned in a Debit/Refund response, you must set the remainingBalanceCalcMode variable of the ECE charging.server MBean to CURRENT_BALANCE. For information about setting this variable, see the discussion about configuring charging runtime options in BRM Elastic Charging Engine Implementation Guide.
The ORA-Remaining-Balance AVP is defined as follows:
ORA-Remaining-Balance ::== < AVP-Header: 241 3512 >
* { ORA-Balance-Element }
* [ ORA-Applicable-Services ]
[ ORA-Subscriber-Id ]
Note:
ORA-Subscriber-Id is used to indicate which account the remaining balance returned is applicable to. ORA-Applicable-Services is only returned in a top-up response, and ORA-Subscriber-Id is only returned in a Multiple-Services-Credit-Control response.AVP code: 242
Type: Grouped
The ORA-Applicable-Services AVP is returned as part of a top-up response to indicate which services the top-up could be used for. For every product applicable, Diameter Gateway does a reverse lookup of the Diameter Mediation table to convert the product into a Service-Identifier and Rating-Group pair.
The ORA-Applicable-Services AVP is defined as follows:
ORA-Applicable-Services ::== < AVP-Header: 242 3512 >
{ Service-Identifier }
{ Rating-Group }
AVP code: 243
Type: Grouped
The ORA-Balance-Element AVP is used in both balance query and remaining balance responses. It returns information on a single balance element. The Unit-Value AVP amount in the ORA-Balance-Element AVP is the total sum of all the end users' instances of the balance on ECE, with the individual balance instance values provided in the ORA-Balance-Item AVP. The Unit-Value AVP amount is the total available unreserved value of the balance.
The ORA-Balance-Element AVP is defined as follows:
ORA-Balance-Element ::== < AVP-Header: 243 3512 >
{ ORA-Balance-Element-Id }
{ Unit-Value }
* { ORA-Balance-Item }
[ ORA-Earliest-Expiry-Time ]
[ ORA-Credit-Floor ]
[ ORA-Credit-Ceiling ]
[ ORA-Percent-Credit-Threshold ]
[ ORA-Fixed-Credit-Threshold ]
[ Service-Identifier ]
[ Rating-Group ]
AVP code: 244
Type: Grouped
The ORA-Balance-Item AVP returns the details of a single balance element instance within a balance element. The Unit-Value AVP contains the available unreserved value of the balance element instance.
The ORA-Balance-Item AVP is defined as follows:
ORA-Balance-Item ::== < AVP-Header: 244 3512 >
{ Unit-Value }
[ ORA-Validity-Start-Time ]
[ ORA-Validity-End-Time ]
[ ORA-Consumed-Reservation-Amount ]
[ ORA-Active-Reservation-Amount ]
AVP code: 245
Type: Time
The ORA-Earliest-Expiry-Time AVP returns the earliest expiry time when an array of balance instances is returned by Diameter Gateway in the ORA-Balance-Item AVP, which has one or more balance instances with an expiry time.
AVP code: 250
Type: Grouped
The ORA-Active-Reservation-Amount AVP returns the unused reservation being held against the balance element.
The ORA-Active-Reservation-Amount AVP is defined as follows:
ORA-Active-Reservation-Amount ::== < AVP-Header: 250 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 251
Type: Grouped
The ORA-Consumed-Reservation-Amount AVP returns the used reservation being held against the balance element.
The ORA-Consumed-Reservation-Amount AVP is defined as follows:
ORA-Consumed-Reservation-Amount ::== < AVP-Header: 251 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 253
Type: Grouped
The ORA-Credit-Ceiling AVP returns the information on the maximum credit permitted for the subscriber for the balance element.
The ORA-Credit-Ceiling AVP is defined as follows:
ORA-Credit-Ceiling ::== < AVP-Header: 253 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 252
Type: Grouped
The ORA-Credit-Floor AVP returns the information on the minimum credit allowed for the subscriber for the balance element.
The ORA-Credit-Floor AVP is defined as follows:
ORA-Credit-Floor ::== < AVP-Header: 252 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 255
Type: Grouped
The ORA-Fixed-Credit-Threshold AVP returns all the fixed credit thresholds set against the balance element for the subscriber.
The ORA-Fixed-Credit-Threshold AVP is defined as follows:
ORA-Fixed-Credit-Threshold ::== < AVP-Header: 255 3512 >
* { ORA-Threshold-Value }
AVP code: 254
Type: Grouped
The ORA-Percent-Credit-Threshold AVP returns all the percentage credit thresholds set against the balance element for the subscriber.
The ORA-Percent-Credit-Threshold AVP is defined as follows:
ORA-Percent-Credit-Threshold ::== < AVP-Header: 254 3512 >
* { ORA-Threshold-Value }
AVP code: 256
Type: UTF8String
The ORA-Threshold-Value AVP provides detail on a single fixed or percent threshold. It contains individual values of threshold that form a collection of either percentage credit thresholds or fixed credit thresholds.
AVP code: 235
Type: OctetString
The ORA-Subscriber-Id AVP returns an ID representation for the subscriber that the balance is associated with.
The format of ORA-Subscriber-Id is as follows:
<subscriberId>:<productType>
where:
subscriberId is the subscriber identifier. It correlates with the Subscription-Id-Data AVP when the balance is directly associated with the requesting end user.
productType is the type of product (for example, TelcoGsm telephony).
AVP code: 231
Type: Grouped
The ORA-Customer-Cost-Information AVP returns the cost information for the requested reservation, charge, or refund. In the case of a reservation initiate, the cost indicated is units of entire reservation used. For a reservation update, the cost is the total of used units for the session and the cost of the entire granted reservation. For a terminate, debit, or refund, the cost is the total charge.
To have the ORA-Customer-Cost-Information AVP returned, you must set the adviceOfChargeNotificationMode variable of the charging.notification ECE MBean to PIGGYBACK. For information about setting this variable, see the discussion about configuring notifications for online charging in BRM Elastic Charging Engine Implementation Guide.
The ORA-Customer-Cost-Information AVP is defined as follows:
ORA-Customer-Cost-Information ::== < AVP-Header: 231 3512 >
{ ORA-Subscriber-Id }
* { ORA-Cost-Information }
AVP code: 301
Type: Grouped
The ORA-Credit-Threshold-Breach AVP is returned by Diameter Gateway whenever a threshold breach has occurred for a subscriber:
In the period since the last update for a session
As a result of the charge
As a refund for a direct event
The ORA-Credit-Threshold-Breach AVP is defined as follows:
ORA-Credit-Threshold-Breach ::== < AVP-Header: 301 3512 >
{ ORA-Balance-Element-Id }
{ ORA-Current-Balance }
{ ORA-Breach-Direction }
[ ORA-Fixed-Threshold-Values ]
[ ORA-Percentage-Threshold-Values ]
AVP code: 307
Type: Enumerated
The ORA-Breach-Direction AVP indicates the direction of a balance change that caused the credit threshold breach to occur.
Table A-3 shows the list of enumerations defined for the ORA-Breach-Direction AVP:
AVP code: 302
Type: Grouped
The ORA-Current-Balance AVP returns the post-breach value of the balance for which the threshold breach notification is generated.
The ORA-Current-Balance AVP is defined as follows:
ORA-Current-Balance ::== < AVP-Header: 302 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 303
Type: Grouped
The ORA-Fixed-Threshold-Values AVP returns all of the thresholds that have been breached as the result of the transaction that caused notification. In the case of multiple breaches, the ORA-Fixed-Threshold AVP appears for each threshold that is breached.
The ORA-Fixed-Threshold-Values AVP is defined as follows:
ORA-Fixed-Threshold-Values ::== < AVP-Header: 303 3512 >
* { ORA-Fixed-Threshold }
AVP code: 304
Type: Grouped
The ORA-Fixed-Threshold AVP returns a fixed threshold that is breached.
The ORA-Fixed-Threshold AVP is defined as follows:
ORA-Fixed-Threshold ::== < AVP-Header: 304 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 305
Type: Grouped
The ORA-Percentage-Threshold-Values AVP returns all of the percentage thresholds that have been breached. In the case of multiple threshold breaches, the ORA-Percentage-Threshold AVP appears for each threshold that was breached.
The ORA-Percentage-Threshold-Values AVP is defined as follows:
ORA-Percentage-Threshold-Values ::== < AVP-Header: 305 3512 >
* { ORA-Percentage-Threshold }
AVP code: 306
Type: Grouped
The ORA-Percentage-Threshold AVP returns the percentage threshold that is breached to cause the notification.
The ORA-Percentage-Threshold AVP is defined as follows:
ORA-Percentage-Threshold ::== < AVP-Header: 306 3512 >
{ Value-Digits }
[ Exponent ]
AVP code: 206
Type: Grouped
The ORA-Account-Topup AVP is used to submit recharge requests to ECE and returns a single unique recharge reference and one or more balance credits to apply to the account.
The ORA-Account-Topup AVP is defined as follows:
ORA-Account-Topup ::== < AVP-Header: 206 3512 >
{ ORA-Recharge-Reference }
* { ORA-Balance }
ORA-Recharge-Reference is used for correlating the initiating top-up system and BRM, to allow auditing of recharges. It is also used as part of the duplicate detection mechanism and must be unique for each recharge.
AVP code: 207
Type: UTF8string
The ORA-Recharge-Reference AVP must be included with a top-up and is used for correlation between the initiating top-up system and BRM to allow auditing of recharges. This AVP is also used as part of the duplicate detection mechanism and must be unique for each recharge.
AVP code: 208
Type: Grouped
The ORA-Balance AVP is used as part of a top-up request to specify the balance to recharge. ECE attempts to recharge the balance identified by using the ORA-Balance-Element-Id AVP for the amount specified in the Unit-Value AVP. The valid from and expiry information are optional. For a product-level recharge, the Service-Identifier and Rating-Group AVPs are used to reference the Diameter Mediation table to determine the target product type.
The ORA-Balance AVP is defined as follows:
ORA-Balance ::== < AVP-Header: 208 3512 >
{ ORA-Balance-Element-Id }
{ Unit-Value }
[ ORA-Validity-Start-Time ]
[ ORA-Validity-Start-Relative ]
[ ORA-Validity-End-Time ]
[ ORA-Validity-End-Relative ]
[ ORA-First-Usage-Validity ]
[ ORA-Extend-Bucket-Validity ]
[ Service-Identifier ]
[ Rating-Group ]
When associating a start date to the balance recharge, either ORA-Validity-Start-Time or ORA-Validity-Start-Relative should be provided, and the ORA-Extend-Bucket-Validity AVP should not be True. If no start date is provided, it is set to the time of the recharge. When providing an expiry date for the balance recharge, only ORA-Validity-End-Time, ORA-Validity-End-Relative, or ORA-First-Usage-Validity should be set. If ORA-Extend-Bucket-Validity is set to True, the recharge value is added to the first expiring existing balance, and the final expiry is the latest of either the current expiry or the provided expiry. If no expiry date is provided, the recharged balance never expires.
Note:
Setting an expiry date for a currency balance is not possible.AVP code: 228
Type: Enumerated
The ORA-Extend-Bucket-Validity AVP is used in a top-up to determine if the recharge amount is to be added in current balance or a new balance should be created. It is ignored for first-use recharges, if there is no balance present, and also if the validity start date specified in the request is in the future.
Table A-4 shows the list of enumerations defined for the ORA-Extend-Bucket-Validity AVP:
Table A-4 ORA-Extend-Bucket-Validity Enumerations
| Enumeration | Value | Notes |
|---|---|---|
|
TRUE |
1 |
ECE creates a new balance instance to persist the recharge in. This is the default behavior if ORA-Extend-Bucket-Validity is not specified for the recharge balance. |
|
FALSE |
0 |
ECE attempts to add the recharge balance to an existing balance instance if one is present, otherwise it creates a new balance instance. |
AVP code: 216
Type: Grouped
The ORA-Validity-End-Relative AVP is used by the top-up client to specify the desired offset for the end date of the balance being recharged. ECE uses this offset to calculate the expiry date, relative from the time the request is received by ECE.
The ORA-Validity-End-Relative AVP is defined as follows:
ORA-Validity-End-Relative ::== < AVP-Header: 216 3512 >
{ ORA-Validity-Offset }
{ ORA-Validity-Unit }
AVP code: 215
Type: Grouped
The ORA-Validity-Start-Relative AVP is used by the top-up client to specify the desired offset for the start date of the balance being recharged. ECE uses this offset to calculate the valid-from date, relative from the time the request is received by ECE.
The ORA-Validity-Start-Relative AVP is defined as follows:
ORA-Validity-Start-Relative ::== < AVP-Header: 215 3512 >
{ ORA-Validity-Offset}
{ ORA-Validity-Unit }
AVP code: 217
Type: Grouped
The ORA-First-Usage-Validity AVP is used by the top-up client to specify the desired offset for the end date of the balance being recharged. ECE stores this offset with the recharged balance; the first time the balance is used, it uses the offset to calculate and set the expiry date relative from the time of that first use.
The ORA-First-Usage-Validity AVP is defined as follows:
ORA-First-Usage-Validity ::== < AVP-Header: 217 3512 >
{ ORA-Validity-Unit }
[ ORA-Validity-Offset ]
AVP code: 218
Type: Unsigned32
The ORA-Validity-Offset AVP indicates the number of units (defined in the associated ORA-Validity-Unit AVP) that ECE should use in the start or expiry date calculations.
AVP code: 219
Type: Enumerated
The ORA-Validity-Unit AVP is used by the client to specify the units of offset for a relative validity recharge.
Table A-5 shows the list of enumerations defined for the ORA-Validity-Unit AVP:
Table A-5 ORA-Validity-Unit Enumerations
| Enumeration | Value | Notes |
|---|---|---|
|
SECONDS |
0 |
- |
|
MINUTES |
1 |
- |
|
HOURS |
2 |
- |
|
DAYS |
3 |
- |
|
MONTHS |
4 |
- |
|
ACC_CYCLE |
5 |
- |
|
BILL_CYCLE |
6 |
- |
|
ABSOLUTE |
7 |
- |
|
INFINITE |
8 |
- |
Note:
ABSOLUTE and INFINITE are only applicable for first-use top-ups. If ABSOLUTE is set, then the ORA-Validity-End-Time must be provided in the ORA-Balance AVP. INFINITE is interpreted as a top-up for a first-use balance if expiry is not set on first-use.For ACC_CYCLE and BILL_CYCLE, zero units specifies a date at the end of the current cycle, and one unit specifies the date at the end of the next cycle.