Setting up the Price Plan

In SAP Convergent Charging the price calculation logic is built by assembling decision trees containing simple components. These components are building blocks that you can put together to meet your business requirements.

In the figure above, the left part of the window shows an example tree structure. On the right the configuration of the selected component is displayed.

You will start with the rate level. Every price plan must start with a rate component. The rate defines what kind of fee will be calculated and charged. SAP Convergent Charging provides three kinds of rate components:

1. Usage rate

Usage rates process chargeable items of a certain chargeable item class. The price plan below such a rate has access to the properties of the chargeable item processed by the charge. For each chargeable item processed the charge can create one output transaction, that is sent to the billing system.

2. Recurring rate

Recurring rates calculate time-based fees on a recurring basis. They do not process chargeable items, but they can be triggered indirectly by chargeable items during the so-called "activation process". You will learn later, what this means.

3. One-Shot rate

One-Shot rates calculate fees at certain events, which usually only happen once for a charge. These events are the activation, suspension or resumption of a charge as part of a contract item.

A usage rate is simple to configure. It only needs to reference a chargeable item class. You can add several usage rates to a charge as long as each of them refers to a different chargeable item class. This way your charge can deal with different kinds of service usage, with each kind being represented by a dedicated chargeable item class.

Recurring rates represent fees, that are triggered on a regular basis without the need to process a chargeable item. SAP Convergent Charging will trigger these fees automatically when a contract is "activated". You will learn about the activation process later. For now, just think of it as an automated process, which will make SAP Convergent Charging calculate the fees on a recurring basis and create the corresponding charged items up to a certain point in time along the contract’s lifecycle.

When it comes to the exact recurrency pattern, SAP Convergent Charging offers a lot of flexibility. In the following video, you will go through increasingly challenging use cases, configure the recurring rate according to the requirement, and visualize the resulting changes to the system behavior.

One-shot rates– as the name implies – are rates, that are triggered once when a certain condition is met. SAP Convergent offers three different conditions:

Activation

A one-shot triggered at activation will charge a fee at the beginning of the first validity period of a contract item.

Suspension

When a contract item is ending, a suspension fee is triggered. When a contract item is ended, started at a later time again, and ended yet again after a while, a suspension fee is triggered each time the contract item is terminated.

Resumption

When a contract item is ended, but started at a later time again, a resumption fee is triggered. Is the contract item ended and restarted after a pause several times, each time the item is becoming valid again a resumption fee will be triggered.

The graphic below illustrates when each one-shot fee is triggered.

In SAP Billing Revenue and Innovation Management one-shot fees like activation fees are usually triggered by SAP Subscription Order Management and bypass SAP Convergent Charging completely. Therefore, one could get the feeling, that one-shot rates are useless. There are certain cases, however, where one-shot rates can prove useful. When calculating discounts in SAP Convergent Charging, these discounts can only be applied when all fees to be considered in the discounting process are processed by SAP Convergent Charging.

Each price plan tree branch must end with a function. A function can serve one of four purposes:

1. Assign a numeric property to the rated amount of a charge.

   As we will learn in this lesson, it can happen, that more than one function is adding to the overall rated amount of a charge. Usually this assignment is combined with support for a calculation of a certain type. The following functions have this purpose:

   • Flat
   • Generic
   • Linear
   • Polynomial
2. Terminate the fee calculation and suppress the creation of a charged item.

   This is usually done when a service is free of charge. The function used for this is called: Free.

3. Call a pricing macro

   Macros can be understood as ways to create reusable price trees. They are similar to subprograms in programming, that you can call from other programs, so that you don’t have to write them several times. We will learn how this component is used when we cover pricing macros. The function used for this purpose is called: Macro Function.

4. Raise an error and abort the rating process of the current fee.

   This is usually done when the price for a service could not be determined for some reason. The function used here is called: No Access.

   

Lets look at the four function types in more detail:

We will not go through all the four functions in detail. The most common function of the set is the "Flat" function. The components requests to select a numeric property as the "Fixed Amount". The value of the selected property will be added to the amount charged by the charge.

The Linear component allows to select an additional "Property Name" and "Scaled Amount", that are multiplied and added to a Fixed Amount. This function allows to execute a formula like:

A*B+C

Where A, B and C can be numeric properties. The result is added to the amount charged by the charge.

The same calculation can be made with the arithmetic calculation component we will learn about in the remained of this lesson. The advantage of the linear function is, that it combines the calculation and the assignment of the result to the charged amount in one component.

Whenever a service is free of charge, you have one of two options:

1. Create a charged item with an amount of 0 to explicitly state your service usage is free of charge.
2. Suppress the creation of a charged item in the first place.

The latter can be achieved by using the Free function. It has no specific settings.

Rating logics can run into conditions, that do not allow to calculate an amount successfully. This can be due to a failure to find the correct price, because mandatory input data is missing, or because the input data is inconsistent. In all these situations the rating process has to be terminated, and the error has to be communicated back to the caller.

The No Access component expects a message describing the problem the rating logic ran into. This message should be both descriptive and short. When SAP Convergent Charging is used in combination with SAP Convergent Invoicing, the error message will be sent back to SAP Convergent Invoicing, that will store it in its database for later reference. As there is a maximum message length SAP Convergent Invoicing can store, messages exceeding this maximum will be truncated, which can make error root cause analyzes difficult.

Below the message all properties available in the rating context are available for selection. You should tick the boxes of all properties, that are needed for a root cause analysis, but consider the maximum length of an error message. The names and runtime values of all properties you selected will be added to the error message. As a result, determining how many properties will fit into the message before SAP Convergent Invoicing will truncate the string is hard to tell, as it depends on the length of all property runtime values.

Comparators are components, that compare two or more values with each other, and branch the tree logic into two or more branches depending on the result. We will give you a detailed introduction to the most used comparator components. The remaining ones will be listed, but not explained in detail. The documentation will provide you with the necessary details whenever you need them later. Two of the most used components allow you to read from tables. These two components are described in the lessons Using Mapping Tables and Using Range Tables.

The following figure shows the list of available comparator components when you hover over the corresponding icon.

The most used components are:

• Mapping Table introducer
• Numbers
• Prefix Switching
• Range Table Introducer
• Strings

With the numbers comparator component, you can compare two numbers with each other.

As the property name select the number property to compare.

As the comparison value select the number property to compare the first property with. The comparison value also allows to enter a static number, which is not read from a property. As such numbers are fixed at design time this is rather uncommon and inflexible.

As the operator you can choose from a list of comparison operations at design time:

1. Is equal to
2. Is greater than
3. Is smaller than
4. Is greater than or equal to
5. Is smaller than or equal to

The statement checked will be:

For example:

The component has two branches to continue with. Each of them describes one of the possible results. Only the branch matching the comparison result will be executed after the comparison.

An example use case would be to always charge the larger amount of two available amounts.

The strings comparator component is similar to the numbers comparator component.

It compares two strings with each other. You will choose two strings to be compared (a "property value" and a "comparison value"), and select an operation from the following list:

1. Is equal to
2. Starts with
3. Ends with
4. Contains

Again, the comparison value allows to enter a static string as the comparison value, which is a rather static and inflexible setup and should therefore be prevented.

The statement checked will be:

<Property Name> <operator> <Comparison Value>

For example:

STRING1 starts with STRING2

The result can either be true or false. The component has two matching outbound branches, one for each of the possible results of the comparison. The branch matching the comparison result will be executed.

The prefix switching comparator component is similar to a string comparator component, but only allows to check if the value of a given string property starts with a set of prefix values, or none of the given prefixes. The prefixes must be stated explicitly at design time and cannot be provided by a property.

The component provides one outbound branch for each prefix you want to check for. An additional default branch is provided, which is executed when the property check did not start with any of the prefixes provided. Exactly one of the outbound branches is executed as a result.

The remaining comparators will not be explained in detail. The following list provides an overview of all components with a brief description of their purposes.

As opposed to comparators, splitters allow to execute several of the outbound branches of a component. In a manner of speaking splitters split the control flow into several branches based on a rule.

The most prominent splitter component is probably the number splitter. Its purpose is to split a numeric value into two parts at a given threshold.

Let’s look at an example:

Assume your customer used your service for a certain number of units. The subscriber of the service was given certain amount of free service usage units, that you need to settle against the usage reported by the metering system before you can determine how much to charge.

SERVICE_USAGE: X Units

FREE_USAGE: Y units

As your price calculation logic cannot tell whether the customer service usage is below or above the amount of free usage still available to the customer, it must make a comparison first. Depending on the result the correct arithmetic calculation needs to be made, so that the result can be processed properly. This calculation can be:

1. SERVICE_USAGE – FREE_USAGE if the free service usage volume still available is smaller than the consumed service quantity. The result can be charged for, and the free service usage balance will be set to 0.
2. FREE_USAGE – SERVICE_USAGE if the free service volume still available is larger than the consumed service quantity. The result will be deducted from the free usage balance and nothing will be charged.

This is rather complicated, and the splitter can help to simplify this calculation. In the configuration you will select a numeric "Property Name" containing the number to split in two parts. As the "Split Value" another numeric property needs to be selected, that contains the threshold at which to split the first property. Note, that you can also enter a static number here, but as this is rather static this is usually not done.

The component expects you to provide the names of the numeric properties it will write the result of the split operation to. The first property will be given the value of "Property Name" up to the "Split Value", while the second will be assigned any value of "Property Name" beyond the "Split Value".

Let’s see how the component would be configured for the example given above.

The property to split here is "SERVICE_USAGE". As the split value the counter "FREE_USAGE" has been provided. The result of the split is written into the properties "USAGE_FREE_OF_CHARGE" and "USAGE_TO_CHARGE" respectively.

Let’s be specific and assume the customer consumed 7 units, while the balance of FREE_USAGE is 5 units. From the 7 units used 5 units are below the threshold of 5 units still free. Therefore, the property USAGE_FREE_OF_CHARGE is given the value "5".

From the 7 units used 2 units are above 5 units still free. Therefore, the property USAGE_TO_CHARGE is given the value "2".

The component creates two outbound branches, which are both executed:

Note that the property "USAGE_FREE_OF_CHARGE" is only available in the outbound branch labeled "SERVICE_USAGE: Up to FREE_USAGE" while the property USAGE_TO_CHARGE is only available in the branch labeled "SERVICE_USAGE: Beyond FREE_USAGE". As you can see the remaining logic you need to implement is a lot simpler this way, as some of the arithmetic calculations have been made by the splitter component for you.

The following table gives an overview of all remaining splitter components.

Operator components do not split the control flow at all. Each operator component has exactly one outbound branch.

This component allow to make basic arithmetic calculations. The component supports the following operations

• Addition
• Subtraction
• Multiplication
• Division
• Modulo operation
• Power operation

The component expects a selection of a property or static value for the first and second operand, the selection of one of the listed operations to execute and the name of the property to write the operation result value to.

Depending on the operation selected a rounding mode must be chosen. SAP Convergent Charging supports the following rounding modes:

1. up
2. down
3. to the nearest value

Internally a precision of up to 12 decimals is supported.

The concatenate operator allows to combine an arbitrary number of string values to a new string property. The core element of its configuration is a list of elements making up the new string. You can add as many elements to the list as you want.

The control elements of the table allow you to add new elements, delete existing ones or change the sequence of existing elements as needed.

By default, the elements added to the table are concatenated without any separator character. However, the operator component allows to select from a predefined set of separator characters and even the option to use a custom one. When you have selected the semicolon as the separator character it will be added between the elements to concatenate. No separator will be placed before the first and after the last item.

The switch table is a quite versatile component, that can analyze a string or number property. Based on a set of rules an output string or number property is created and provided with a value. The data type of the output property is independent of the datatype of the property analyzed.

As an example, you can analyze a string property containing a top level domain and set a country name in a second property depending on the top level domain found. Th example of this is shown in the table below.

Not though, that the table containing the rules cannot be modified via an API during runtime. This means, that the rule set should be rather static. For dynamic data tables would be a better choice as they can be modified at runtime. Tables will be covered in a later lesson.

The counter update component is crucial when managing counters, as it allows to modify the counter value. As an "Counter Name" you must select the counter you want to change the value for.

The second step is to select one of four operations available to execute on the counter. You can:

• Reset the counter to its initial value.
• Set the counter to a specific value or a value read from a numeric property.
• Add a certain value to the counter.
• Subtract a certain value from the counter.

As the operation value you can either enter a specific number, that is used for the operation, or provide a numeric property the system will read the number from.

When a counter operation is executed as part of your rating tree logic, but the execution of the logic fails – either by reaching a No Access function or by failing otherwise – the counter modification will not be executed.

The following table lists all remaining operator components and briefly describes their purposes.

So far you learned about properties of the data types string, number and date. SAP Convergent Charging does support so called multi-valued properties. You can imagine these properties to be a list of values as opposed to one single value. Such a list of values could for instance be a list of email addresses derived from the recipient field of an email.

Imagine the string property ZZ_RECIPIENTS contains email addresses separated by semicolons, just as you would find it in the "to" field of your email program. This could look like this:

ZZ_RECIPIENTS = "gary_smith@testdomain.com; finn_swann@testdomain.com; eve_steward@testdomain.com"

A multi-valued string is a string, that is aware of the different email addresses and stores them as distinct string values within a single property. You can imagine a multi-valued string as a list of string values:

ZZ_RECIPIENTS_MV =

When a string contains a sequence of numeric values separated by semicolons, you can create a multi-valued number property from it. Let’s assume there is a property ZZ_DISTANCES with a set of distances in kilometers between a start and destination for different routes:

ZZ_DISTANCES = "36; 42; 12"

You can create a multi-valued number property out of this string, that looks like this:

ZZ_DISTANCES =

The multi-valued properties alone are not helpful. The added value comes from the components, that can work with multi-valued properties as you have seen in the tables above.

Multi-valued properties are created using the property type convertor operator component. As this course does not use these types of properties they will not be covered in further detail.

Now that you have a decent understanding of the components used to create price plans, let’s see how to create a new price plan in the system.