Using the Design Time Building Blocks of Allowances

To build your business, it is necessary to model allowances by creating the following master data:

Allowance Interface

The allowance interface contains the list of counters and parameters available for every allowance.

Allowance Event Classes

This class describes the data, that can be sent from a charge to the allowances of a contract and back again.

Allowance Logic

The allowance logic describes the calculation logic that is executed when an allowance event is processed, when an allowance is activated, when it expires, and so on. It also associates these logics with allowance event classes – just like usage rates of charges refer to a certain chargeable item class they are sensitive for.

Allowance Plans

Allowance Plans form the building plan of an allowance. They usually refer to one or more allowance logics. The combination of these allowance logics define how the allowance behaves when created based on the allowance plan.

In the following paragraphs, we will go through each of these object types and look at its purpose, how it is defined, and what options and flexibilities it provides.

The allowance event class is a structure stored in the catalog that is similar to a chargeable item class. It represents the format of messages that can be sent from a charge to a set of allowances. Such a message is called an "Allowance Event". The allowance event class is made up of a unique name, an optional description, and a set of fields the message can carry information in. Each field is assigned to one of three datatypes:

• String
• Number
• Date

The following image shows the definition of an allowance event class.

Normally, these fields are used to report a service consumption to the allowance that needs to be settled against the balance.

An important difference between chargeable items and allowance events is that the field values of an allowance event are modifiable by the allowance processing it. When the CONSUMED_AMOUNT field contains the monetary amount of service usage that is supposed to be settled by the allowances, the allowance can settle only part of that consumed amount and leave the remaining amount to be settled by subsequent allowances. To indicate how much is left to be settled, it can update the value of the field "CONSUMED_AMOUNT" with the amount it was not able to settle with its own balance. The allowance event will then carry over the modified value to the next allowance, which in turn can read the value, settle what it can, and modify the field value as needed until the field value reaches 0 or no more allowances are available to process further usage. When no more allowances are available to process the event, the message is passed back to the calling charge, which has access to all updated field values.

As you might have noticed, the allowance event class does not contain default properties. These are not needed as the allowance events are sent by charges. At that point in the rating process, the contract and the charge have already been identified.

Allowance event classes can be created in the Core Tool by selecting File → New → Allowance Event Class.

Allowance events can be sent using the operator component called Allowance Event Sender. In the component, you must select the allowance event class that you want to use for the message. In the definition tab of the component, you must then map the properties of your rating context to the properties defined in the allowance event class. For each property of the allowance event class, you can define the name of a property that will contain the updated value after the allowance event has been processed. In the example given below, the allowance event field CONSUMED_AMOUNT is provided with the value of the charge’s base amount while the REMAINING_AMOUNT field contains any amount that was not settled by the allowances.

In SAP Convergent Charging, the allowance logic is a reusable object that belongs to a catalog's master data. They are made up of a unique name, a description, and similar to charges, can contain parameters and transient, or persistent counters.

The calculation logics are defined as tree structures. Similar to the price plans of charges, allowance logic tree structures can be divided into three logical parts:

1. Trigger level

   The trigger component is the root of each tree. Here the type of trigger event is defined which can be event-based, recurring, or one-shot.

2. Algorithmic level

   On this level, the calculation logics are located. Several logical components are combined to form a calculation logic executed within the allowance. Each logical component is assigned to one of two categories (Splitters are not supported here!):

   1. Comparators
   2. Operators
3. Function level

   Functions are the leaves of your calculation tree logic. A function component defines whether a usage event is allowed to pass or not (where the latter creates an error message), and whether a charged item is supposed to be generated for a passing allowance event. When passing an allowance event, the allowance will let the event pass on to the next allowance after it has dealt with it as defined by the tree logic so far.

Event-Based Trigger

The event-based trigger allows the processing of allowance events of a certain allowance event class. The only setting this component expects is a reference to an existing allowance event class. The event-based trigger will only be executed when it receives an allowance event of this type. The tree logic below an event-based trigger component has access to all property values defined in the allowance event class referenced.

Recurring Trigger

The recurring trigger is similar to the recurring rate in the price plan of a charge. Its configuration defines a recurring pattern. The tree logic below the recurring trigger is executed following this pattern. The way the configuration of a recurring pattern follows the same rules and structures as the configuration of recurring rates in price plans. The setup of recurring triggers does not support proration though.

One-Shot Trigger

One-shot triggers allow the execution of tree logic at; creation, activation, or expiration of an allowance. This way the balance of allowances can be created, messages about allowance readiness can be sent, or remaining balances can be depleted and reported to SAP Convergent Invoicing to be posted as revenue.

The middle part of a tree logic defines the calculation logic. You can freely combine comparator and operator components to implement a logic that meets your requirements. An example of such a logic could be to compare the balance within the allowance and–if there is balance left–deduct as much of it as necessary, or possibly settle the usage reported in the allowance event. Once done, the allowance event property is updated with the remaining balance still to be settled.

The most important operator and comparator components that can be used have already been introduced in the course. Allowances, however, support a set of special components that are only available in the allowance logic context. Those components are:

• Allowance Event Sender
• Allowance Event Updater
• Allowance Property Introducer
• Allowance Validity Period Updater

Allowance Event Sender

The allowance event sender was already introduced when dealing with allowance event classes. Although allowance events are usually sent by charges, they can be sent by allowances as well.

Allowance Event Updater

The allowance event updater component can be used to update the field value of the allowance event that is processed. In the example given below, the allowance event updater component is used to set the field value of the allowance event property CONSUMED_AMOUNT to 0 and set the field value of the allowance event property PROCESSED to TRUE. The remaining allowance event properties are mapped to their actual values, so that they remain unchanged.

The allowance event updater component is only available as subcomponents of event-based triggers.

Allowance Property Introducer

The allowance property introducer component allows you to select a certain group of allowances by a set of selection criteria, and then apply basic mathematical evaluations on these allowances and their properties.

Let’s look at an example:

The sales department of the O2C company selling the cloud selection service has an idea: All customers with contracts associated with a total allowance balance of at least 100,- € valid for at least one more month should be sent a message informing them about the latest service offerings to foster service usage. This means that for each contract, the allowance with a validity of at least four more weeks must be selected, and the balances of all matching allowances must be summed up. This is what an allowance property introducer component could do in one tree step.

The component’s setup requires three steps:

1. Set the selection scope.
2. Define the selection criteria.
3. Define the calculations to be made.

The first step is to define the scope that the allowances are to be selected from. The options are:

1. All allowances of the given contract.
2. All allowances of the given contract and all allowances of its parent contract.
3. Only shared allowances with a specific sharing ID.

We haven’t dealt with shared allowances yet, so don’t be confused by the third option.

When you have selected the scope, you can (but don’t have to) provide a set of selection criteria to only select a subset of allowances matching certain conditions. Depending on the datatype of the property used as a selection criterion, there are different operators available:

Operators

Datatype	Available Operators
Date	Equals Before Before or Equals After After or Equals
Number	Equals Greater Than Greater Than or Equal To Lower Than Less Than or Equal To Not Equal
String	Equals Starts With Ends With Contains

By default, the component counts the number of allowances in the selected result set. You must define a property name that the component stores this number in.

Additionally, you can define a set of mathematical operations to be executed on properties of the allowances in the result set. The operations supported depend on the datatype of the property:

Datatypes

Datatype	Available Operators
Date	Greatest Lowest
Number	Greatest Lowest Sum

Using these operators you can, for instance, select a numerical property "BALANCE" and let the component calculate the sum of that property across all allowances in the result set.

Note though that the properties used as selection criteria, and as generated properties, must be part of the allowance interface, which can be a significant drawback. As the allowance interface wasn’t covered yet, just keep this fact in mind.

Allowance Validity Period Updater

The allowance validity period updater allows you to modify the validity start date and / or validity end date of an allowance. The date which can be modified depends on the state of the allowance, and the trigger component the updater component is in respectively. The following table shows which trigger components and configurations allow for which modifications.

Combination between Trigger component, Configuration and allowed Modification

Trigger Component	Validity Start Date	Validity End Date
Event-based Trigger	Cannot be updated	Modifiable
Recurring Trigger	Cannot be updated	Modifiable
One-Shot Trigger (Creation)	Modifiable	Cannot be updated
One-Shot Trigger (Activation)	Cannot be updated	Modifiable
One-Shot Trigger (Expiration)	Cannot be updated	Cannot be updated

An example situation would be a company that associates a certain validity to a purchased allowance balance. Top-up operations on existing and valid balances extend the validity of these balances leading to an incentive to purchase more balance. The extension of the validity period could even increase based on the amount the allowances is topped-up with.

Allow

The Allow function allows the allowance event to be passed on to the next allowance if there is any, or otherwise be returned to the calling charge.

The only option it provides is to decide whether a charged item is to be created (checkbox Generate Charged Item is checked) or not (checkbox unchecked).

No Access

The No Access function has the same function as it has in charges: It terminates the rating process, rolls back any counter updates made during the process so far, and returns an error message with a set of rating context properties names and their current runtime values that can be selected by the user at design time.

An allowance plan defines a type of allowance. It combines one or more allowance logics that jointly define the behavior of this allowance type. Allowance logics can be referenced by several allowance plans at the same time, just as several charge plans can reference the same charges. And just like charge plans, allowance plans can contain counters and parameters to tune the runtime behavior of allowances created based on them.

Counters created within an allowance plan can be linked to counters in allowance logics. This way, it is possible to link the values of counters handled in different allowance logics together. This way, a modification of a counter value in one allowance logic of an allowance plan will be reflected in linked counters of other allowance logics of the same allowance plan.

Linking counters works similarly for counters in charge plans: You define a counter in the allowance plan, add allowance logics to the allowance plan, and from these, allowance logic references link the counters with the counter on the allowance plan level.

Linking parameters works in the same way. You add a parameter to the allowance plan, which must match the data type of the parameters you want to link on the allowance logic level. When you have added the allowance logics, you can point their parameters to the parameter on the allowance plan level.

You will notice that in allowance plans, parameters or counters are not associated with a visibility level. There are also no dependency relationships between the allowance logics of an allowance plan.

An allowance plan has a status that can have one of the following values:

• Open

  This status allows the allowance to be modified as needed. An allowance in this status cannot be used to create allowances though.

• Released

  This status freezes many settings in the allowance plan. Allowance plans in this status can be used by the "Create Allowance" component to create new allowances from a price plan tree.

The status is selected on the definition tab of the allowance plan. Once an allowance plan has been set to the status Released, it cannot be set back to Open again.

Each allowance logic linked to an allowance plan provides a tab to configure the output item mapping. It works in the same way as the output item mappings of charge plan items do. Within the mapping, a charged item class must be selected that is used to create billable items for this allowance logic. The selection is made at design time. For each field of the charged item class, a mapping needs to reference a corresponding type-compatible value from the rating context or a fixed value. The mappings can be updated and extended as necessary, even when the allowance plan was already released.