ServiceUsageRule

Version: 1.33

Query ServiceUsageRule directly for information, or query and use through Service, FormulaServiceUsageRule, GlobalServiceUsageRule, and MatchAllServiceUsageRule. Also used in the commands AddServiceUsageRuleToService and RemoveServiceUsageRuleFromService.

Usage Events are governed by Usage Rules. Usage Rules detect a condition within a Usage Event and evaluate whether that condition is true or false. If the Usage Rule evaluates the condition as "true," an action occurs that could lead to a Customer charge. If the Usage Rule evaluates as "false," no action is taken and the event that is being evaluated passes to the next Usage Rule for evaluation.

To evaluate an event in the correct order, Usage Rules must be in a hierarchical order that you determine and change as needed. The customized Usage Rules and the order in which they are listed make up the Rate Plan.

Gotransverse has three types of Usage Rules:

  • Global Usage Rules -- complex Usage Rules that can be associated with, and used by any Product

  • Formula Usage Rules -- created as part of a Product definition and associated only with that Product, and uses equations and may use lookup tables

  • Match-All Usage Rules -- uses one of the following rates:

    • FlatUsageRate

    • PassThroughUsageRate - with the rate in the event

    • Table including RateTable and UsageLookupTable

Usage Rules process events using the amount of usage reported, applying conditions and predefined Rates to the usage, and adding the results to the Customer's Billing Account for invoicing.
Further Gotransverse API information for this entity of ServiceUsageRule:

Parameters

When you query an ServiceUsageRule, the following table provides information about the values returned from the query:

Elements
Element Name Query
Key		 Element Type Field
Length		 Description

queryScope

QueryScope

 - -

The depth of the query results, whether
they are SHALLOW or DEEP.
See QueryScope for details.

eid

Y

Long

System
Generated

System generated unique identity
number assigned to all entities in Gotransverse.

chargeCategory

UsagePriceCategory

 - -
Choice of one of the
following UsageRates:
-flatUsageRate
-tableUsageRate
-passThroughUsageRate

One of the following
UsageRates:
-FlatUsageRate
-TableUsageRate
-PassThroughUsageRate

 - -

Click on one of the following links
for more information:
-FlatUsageRate
-TableUsageRate
-PassThroughUsageRate

limit

decimal

As
Needed

usageUom

UsageDurationUom

 - -

Unit of measurement of the usage event to be measured
and charged to the Customer's BillingAccount.
See UsageDurationUom for list of units of measurement.

name

String

255

order

Int

As
Needed

proratedOnOrder

Boolean

Shown
either:

"true"
(Yes)
or "false"
(No)

Is this usage rate prorated on Order or not?

YES, this is prorated upon Order. If the Order date
is into the billing cycle, the bill will be less than that of a
regular time period. (For example the service is $20 per month
and the service is ordered 15 days into the bill cycle.
If prorated, then only $10 is charged, rather than $20.)

NO, this is NOT prorated upon Order. Any date in the billing cycle
this item is ordered it will be the full price for the time period.
(For example, the service is $20 per month and the service is
ordered 29 days into a 30 day bill cycle. The Customer
would pay $20 for the 1 day of service, then the next month,
pay $20 for the month.)

proratedOnCancel

Boolean

Shown
either:

"true"
(Yes)
or "false"
(No)

Is this usage rate prorated on Cancellation or not?

YES, this is prorated upon Cancellation. If the Cancellation
date is past the end of the billing cycle, the bill will be for the time
it was used. (For example the service is $60 per month
and the service is canceled 1 day past the end of a bill cycle.
If prorated on cancellation, then only $2 is charged, rather than $60.)

NO, this is NOT prorated upon Cancellation. Any date in
the billing cycle this item is canceled it will be the full price
for the time period. (For example, the service is $60 per month
and the service is canceled 1 day past bill cycle. The Customer
would pay $60 for the 1 day of service.)

rollOverType

RollOverType

255

One of the
following types:
- None
- Uncapped

The type of rollover.

allowanceType

AllowanceType

255
One of the
following types: - Unlimited
- Recurring
- OneTime

The type of Allowance. See AllowanceType.

validFrom

dateTime

See
Data Types page
for dateTime
formats

The date and time the ServiceUsageRule begins.

validTo

dateTime

See
Data Types page
for dateTime
formats

The date and time the ServiceUsageRule ends.

ruleType

RuleType

255 One of the
following types:
- TAPERED
- TIERED

The type of Rule. See RuleType.

Choice of one of the
following UsageRules:
-matchAllOrderItemUsageRule
-formulaOrderItemUsageRule
-globalOrderItemUsageRule

One of the following
UsageRates:
-MatchAllOrderItemUsageRule
-FormulaOrderItemUsageRule
-GlobalOrderItemUsageRule

 - -

Click on one of the following links
for more information:
-MatchAllOrderItemUsageRule
-FormulaOrderItemUsageRule
-GlobalOrderItemUsageRule

status

Y

ServiceUsageRuleStatus

255 One of the
following statuses:
- ACTIVE
- DEACTIVATED
- DRAFT

The status of the ServiceUsageRuleStatus.

Entity ServiceUsageRules

The entity ServiceUsageRules enables you to see multiple pages of the entity ServiceUsageRule.

ServiceUsageRule
Element Name Element Type Field Length Description

pageNumber

Integer

as needed

Shows the current page number.

pageSize

Integer

as needed

Shows the page size.

totalElements

Long

as needed

Shows the total number of items found.

elementCount

Integer

as needed

Shows the current count of the item
in the number of items that were found.

totalPages

Integer

as needed

Shows the total number of pages.

Select one:
-matchAllOrderItemUsageRule
-formulaOrderItemUsageRule
-globalOrderItemUsageRule

-MatchAllOrderItemUsageRule
-FormulaOrderItemUsageRule
-GlobalOrderItemUsageRule

 - -

Shows one of the following choices:
-matchAllOrderItemUsageRule
-formulaOrderItemUsageRule
-globalOrderItemUsageRule

Information for the related entity of ServiceUsageRules:

  • Entity ServiceUsageRules

How to Query for a ServiceUsageRule

Query Key Information for SOAP and REST

Querying to see ServiceUsageRules needs to include one of the following parameters. If you do not know the value for the parameter, query separately to learn the value.

Query Key Parameters

ServiceUsageRule
Query Key Value Definition

eid

Long

The unique eid number for the ServiceUsageRule.

serviceEid

Long

The unique eid of the Service.

status

The status of the ServiceUsageRule.
Query to Use
Query Query for Parameter Name and Value Returns

SimpleDataQuery

ServiceUsageRule

<parameter name><parameter value>

List of your ServiceUsageRules for that parameter name and value.

SOAP Example Query and Response

In the following example SOAP query, the parameter of serviceEid was used. The Service's EID value (in this example "30"), was learned through a previous query on Service.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:query xmlns="http://www.tractbilling.com/billing/1_31/domain"xmlns:ns2="http://www.tractbilling.com/billing/1_31/service">
            <ns2:queryRequest>
                <simpleDataQuery startIndex="0" size="50">
                    <type>ServiceUsageRule</type>
                    <parameter parameter="serviceEid" parameterValue="30"/>
                </simpleDataQuery>
            </ns2:queryRequest>
        </ns2:query>
    </soap:Body>
</soap:Envelope>

The response shows that this Service does not have any ServiceUsageRules. 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:queryResponse xmlns="http://www.tractbilling.com/billing/1_31/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_31/service">
            <ns2:return successful="true">
                <serviceUsageRules pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
            </ns2:return>
        </ns2:queryResponse>
    </soap:Body>
</soap:Envelope>

REST Mount Point and Parameters

Query
GET https://my.tractbilling.com/t/s/r/1.33/serviceUsageRules/<eid>

GET https://my.tractbilling.com/t/s/r/1.33/serviceUsageRules?eid=<eid>
GET https://my.tractbilling.com/t/s/r/1.33/serviceUsageRules?serviceEid=<serviceEid>
GET https://my.tractbilling.com/t/s/r/1.33/serviceUsageRules?status=<status>

REST Example Query and Response

The following example is a Query in REST for ServiceUsageRule using a parameter of Service. The Service's EID value (in this example "30"), was learned through a previous query on Service.

Query
GET https://my.tractbilling.com/t/s/r/1.33/serviceUsageRules?serviceEid=30

The response shows that this Service has a ServiceUsageRule of the Match-All Usage Rule type.

<?xml version="1.0"?>
			<serviceUsageRules pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
			<matchAllServiceUsageRule status="ACTIVE" limit="180.00000" usageUom="COUNT" name="Allowance Usage Rule" order="1" proratedOnOrder="false" proratedOnCancel="false" rollOverType="Uncapped" allowanceType="Recurring" validFrom="2016-01-01T00:00:00.000-06:00" ruleType="TAPERED" eid="9" queryScope="SHALLOW">
			<chargeCategory eid="28" queryScope="EID"/>
			<ableUsageRate eid="81" queryScope="EID"/>
			<matchAllOrderItemUsageRule eid="8" queryScope="EID"/>
			</matchAllServiceUsageRule>
		</serviceUsageRules>