¶ Products
¶ Products screen usage
Product Catalog - each product in this catalog should be correlated with the input record/transaction. The products are used for the ongoing rating of each record/transaction separately and preparing them for billing.
The products are correlated to the input record/transaction by definitions in the Input Processors section.
In this screen you will be able to add new products or edit existing ones.
Products will be rated according to predefined values.
The products can be identified and correlated with the input record/transaction by one or combination of the following methods:
- Identifying the originating/destination longest prefix in case of a call (incoming/outgoing respectively). Prefixes are defined in this screen and will arrive on the input record/transaction fields that mentioned.
- Product’s “Key” which can be defined while creating a new Product (unique and cannot be changed after definition).
- Product’s “Unit Type” - which refers to the Usage/Unit of the input record/transaction (e.g: call/data/sms/km/cm/kg etc.). This case should be combined with other cases when the “Unit Type” is not unique.
- Product’s “Param” - which is a customized input on the product, defined by the user and enables the extending of the product’s key. The customized fields will be defined in the Products screen (New/Edit). There can be none or several new Params.
¶ Products screen fields
Main Products (Rates) screen - Automatically shows a table with all the predefined products.
From this screen it is possible to view all revisions of a product, including Closed, Active and Planned, Define new (Active) and future (Planned) products, and editing existing (Active) and future (Planned) products .
What is the information shown in the Product Catalog table ?
State: product’s state and revision picker (manager).
- Gray - indicates “Closed” Product (past);
- Green - indicates “Active” Products (current);
- Yellow - indicates “Planned” Products (future);
Title: product’s name.
Key: product’s key. A unique key to use by the system and can be used when building key identifier for the product in the input processor.
Unit Type: product’s usage / unit type which the products will be grouped into, and will be charged by it.
External Code: product’s code - Can be used to match to product codes used by other systems such as ERP.
Modified: product’s creation or edit date and time. The product is valid from this date until 100 years since this date or until a new revision of the product will be active.
How to search for an existing product ?
Products can be found by searching a value in the “Search for…” input field above the products table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
After having the list of products, it is possible to see a short “Revision History” preview for a specific product and manage its history, by pressing the coloured “State” button left sided to the Product’s Title, and then in the “Revision History” pop-up press the “Manage Revision”.
After pressing the “Manage Revision”, a full “Revision History” pop-up window that contains all the available Products Revision History list - will be displayed and will enable picking the Future (Planned) Product or the Current (Active) Product in case a Future (Planned) Product doesn’t exist.
At any time, only the last active Product in the “Revision History” can be edited no matter if it’s a future activated Product or currently active Product.
It is also possible to predefine the Product’s States for search by using the “States” drop down list at the upper right corner above the Products table.
The available statuses are “Closed”, “Active” and “Planned”, while all of the statuses can be checked and create a combination of all statuses for selection. After marking the requested statuses for selection and pressing “States” button once again, the Products table will be updated and show only the requested statuses.
Full “Revision History” pop-up example when there is NO Future Product:
Full “Revision History” pop-up example when there IS Future Product:
The short “Revision History” preview shows the same info, in a different view and up to 5 last revisions.
While it is possible to pick a Product for edit or remove from the Full “Revision History” (as shown above), the Short “Revision History” is for display purposes, and Products can be picked and edited after pressing the “Manage Revisions” and moving to the Full “Revision History”.
Short “Revision History” pop-up example when there is NO Future Product:
Short “Revision History” pop-up example when there IS Future Product:
How to edit or delete an existing product ?
Products values can be edited in two ways:
- By pressing the pencil on the right side of each line in the products table.
- By pressing the pencil on the right side of the available revision of a Product in the Full “Revision History”.
Only future revision of a product can be deleted by pressing the recycle bin on the right side of the available revision of a Product in the Full “Revision History”.
Edit Product screen - Filled with the selected product’s data when in edit mode.
On the upper right side of the selected Product’s revision screen, there is a short revision history ruler preview of the latest three revisions: Closed, Active, Planned (If available).
The current open revision screen will be marked with a bolded circle on the ruler.
Current Product’s revision - can’t be edited because there is a future Product’s revision:
Future Product’s revision - can be edited because it’s there last available revision:
It can be deleted from the list in the Full “Revision History” screen.
If there is NO Planned (future) revision - the current revision will be editable and will allow creation of new revision by choosing a different date on the left side of the upper frame.
Saving the Product, after changing the date and other values in the product will create a new Future revision.
What are the fields shown in the Edit Product screen ?
General
Name: product’s name. This value is a reference to the input CDR in industries other than telecom.
Code: product’s code - currently not in use.
Description: product’s description.
Unit Type: product’s usage/unit type which the products will be grouped into, and will be charged by it.
Prefixes: for rating use in telecom industry. Identifies the call’s destination by using best match on the destination (dialled/called) number. This value is a reference to the input CDR in telecom.
From: product starts/effective from this date-time (valid from).
To: product ends/expire at this date-time (valid to).
Pricing
From: current interval’s step start point - 1st step will always start at 0.
To: current interval’s step endpoint - will use as upper border for each step and the beginning of the next step if exists.
Interval: number of units that will be used for rounding up in each step.
Price Per Interval : each rated unit (rounded interval) in each step will be charged by multiplying by this value.
Add New: will add new step to charge.
Additional Parameters
Add New: will add new parameter to use as part of the key to identify the input record/transaction. Each press on the “Add New” button will pop-up window which contains the name and value of the new key field. Each new field can be edited or deleted.
How can I add new product ?
Press the “Add New” button on the upper right side of the Product Catalog table in the main Products screen.
Fill up all the fields as described in “What are the fields shown in the Edit Product screen” section, and press Save.
¶ Prepaid
This menu is relevant for Prepaid Customers/Subscribers only.
¶ Plans
¶ Prepaid Plans screen usage
Prepaid subscribers plans.
Prepaid subscribers are not charged for their plans.
A plan is a kind of membership, and any subscriber must have one.
The plan determines a prepaid subscriber behaviour - restrictions, permissions, amounts/volumes, periods, thresholds, notifications etc.
¶ Prepaid Plans screen fields
Main Prepaid Plans screen - Automatically shows a table with all the predefined customer plans.
What is the information shown in the Prepaid Plans table ?
Title: plan’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - Not editable.
(External) Code: reference to the old system - identifier for the user in case of API usage.
How to search for an existing plan ?
Plans can be found by searching a value in the “Search for…” input field above the Plans table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing plan ?
Prepaid Plans values can be edited by pressing the pencil on the right side of each line in the plans table.
Edit Prepaid Plan screen - Filled with the selected plan’s data when in edit mode.
What are the fields shown in the Edit Prepaid Plan screen ?
See details below in tabs explain.
What is the use of each tab in the Edit Prepaid Plan screen ?
Details tab:
Usage:
Define the Plan’s name, code and key.
Fields:
Title: plan’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - this field exist and editable only in edit mode.
External Code: reference to the old system - identifier for the user in case of API usage.
Override Product Price tab:
Usage:
Changing the market (original) price of a selected product for subscriber who is registered on a specific plan. See the Product Pricing section to learn more about editing a product.
Fields:
In the “Select Products to Override Price” panel, start typing (auto completion) the product you want to use. Select from the predefined products list.
The product definitions panel will be added automatically.
The product is now available for editing, the same way as products in the Products screen.
Notifications:
Usage:
Define thresholds and message for sending notification to the customers who have the current plan, when reaching the lower limit of s specific bucket (balance). Each bucket has it’s own limitation (if defined).
Fields:
In the “Select prepaid bucket” panel, start typing (auto completion) the bucket you want to use. Select from the predefined buckets list.
The bucket notification panel will be added automatically.
The bucket notification is now available for editing.
Value: when the balance/amount/volume in the bucket reach this value - a notification will be sent to the C subscriber.
Type: the notification sending method. Currently for API use only, by the B customer/carrier.
Message: the message that will be sent by the B customer/carrier the the C subscriber.
Blocked Products:
Usage:
Products (destinations) listed in this tab will be blocked for use by the C subscribers who have this plan.
Fields:
In the “Blocked products” panel, start typing (auto completion) the product you want to block. Select from the predefined products list.
The product that should be blocked will be added automatically.
Charging Limits: (name should be changed to Recharge)
Usage:
Define the maximum amount/volume that can be recharged in a bucket.
Exceeding this amount/volume will cause a loss of the exceeded amount/volume.
When no bucket is defined there will be no limitations.
“0” value will prevent any recharge to the bucket.
Fields:
In the “Select prepaid bucket” panel, start typing (auto completion) the bucket you want to limit. Select from the predefined buckets list.
The bucket that should be limit will be added automatically.
Fill the limitation amount/volume.
How can I add new plan ?
Press the “Add New” button on the upper right side of the Prepaid Plans table in the main Prepaid Plans screen.
Fill up all the fields as described in “What is the use of each tab in the Edit Prepaid Plan screen” section, and press Save.
¶ Charging
¶ Prepaid Buckets Group screen usage
Build charging plans for prepaid subscribers.
Charging plan contains package of bucket(s) - at least one bucket. Recharge of buckets to a subscriber can be done by recharge the requested amount/volume directly to a bucket or by recharge a charging plan that contains one or more buckets.
Each bucket in the charging plan has a value for the amount/volume the name and id of the bucket and a validity period - usually in days. The amount/volume in the bucket will be valid from the recharge date till the date at the valid period (recharge date + validity period).
Bucket is also called Balance.
¶ Prepaid Buckets Group screen fields
Main Prepaid Charging Plans screen - Automatically shows a table with all the predefined charging plans.
What is the information shown in the Prepaid Charging Plans table ?
Title: charging plan’s name for identification.
Key: unique plan’s key - for use by the system - Not editable.
External Code: reference to the old system - identifier for the user in case of API usage.
Operation: Type of action to apply on a bucket -
- Set: override all values including amount/volume, in existing bucket or create new bucket if not exist. Bucket’s expiration date will be the latest between the existing expiration date and the new expiration set by the recharge.
- Increment: will add the new recharge amount/volume to the existing bucket amount/volume or create new bucket if not exist. Bucket’s expiration date will be the latest between the existing expiration date and the new expiration set by the recharge.
- New: create new bucket unconditional (even if there is existing bucket or not).
Charging value: the charging plan code. Represent the charging plan.
How to search for an existing charging plan ?
Charging plans can be found by searching a value in the “Search for…” input field above the Charging Plans table. The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing charging plan ?
Charging plans values can be edited by pressing the pencil on the right side of each line in the plans table.
Edit Charging Plan screen - Filled with the selected charging plan’s data when in edit mode.
What are the fields shown in the Edit Charging Plan screen ?
See details below in tabs explain.
What is the use of each tab in the Edit Charging Plan screen ?
Details tab:
Usage:
Define the Plan’s name, code and key.
Fields:
Title: charging plan’s name for identification.
Key: unique charing plan’s key - for use by the system - this field exist and editable only in edit mode.
External Code: reference to the old system - identifier for the user in case of API usage.
Operation: Type of action to apply on a bucket -
- Set: override all values including amount/volume, in existing bucket or create new bucket if not exist. Bucket’s expiration date will be the latest between the existing expiration date and the new expiration set by the recharge.
- Increment: will add the new recharge amount/volume to the existing bucket amount/volume or create new bucket if not exist. Bucket’s expiration date will be the latest between the existing expiration date and the new expiration set by the recharge.
- New: create new bucket unconditional (even if there is existing bucket or not).
Charging value: the charging plan code. Represent the charging plan.
Prepaid buckets tab:
Usage:
Define the buckets and its attributes in the charging plan.
Fields:
In the “Select prepaid bucket” panel, start typing (auto completion) the bucket you want to add. Select from the predefined buckets list.
The selected bucket will be added automatically.
You can add one or all of the predefined buckets to the list.
Fill all the requested fields in each bucket.
Volume: the amount/value to recharge for the subscriber’s bucket. We use negative values for accounting reasons. Each use from the bucket’s volume will reduce the negative - inclining direction towards “0”, which means no volume/units credit left in the bucket and therefore won’t be given allowance to execute an activity.
Duration: the period that this bucket will be valid starting from the moment of recharge. The number in the duration will be added to the start date-time in order to determine the end date-time.
- Left input field: the amount/number of units from the type that should be selected from the right dropdown field, in order to add to the start date-time and define the end date-time.
- Right dropdown field: the type of the unit amount/number that should be selected, in order to add to the start date-time and define the end date-time.
How can I add a new charging plan ?
Press the “Add New” button on the upper right side of the Charging Plans table in the main Prepaid Charging Plans screen.
Fill up all the fields as described in “What is the use of each tab in the Edit Charging Plan screen” section, and press Save.
¶ Buckets
¶ Prepaid Buckets screen usage
Build all available buckets in the system.
Buckets built to use as a different logical wallet/balance - each bucket is used for a specific, different activity (e.g bucket for sms, calls {inbound, outbound, etc.}, data, etc.). This buckets have a limited time period for use - after this time period, the bucket will not be available for any use.
Core balance bucket is exceptional and consist of currency units (not volume or duration like the others), and therefore can be used for all type of activities. This backed has no time limitation.
Buckets can be shared between all C subscribers within a B customer account, or be unlimited.
Buckets can be limited to use for specific products for a certain plan (e.g restrict the sms bucket for “unique_plan_#01”, so it would be able to send sms only to products/destinations that starts with 123…).
The use of buckets can be prioritized.
¶ Prepaid Buckets screen fields
Main Prepaid Buckets screen - Automatically shows a table with all the predefined buckets.
What is the information shown in the Prepaid Charging Plans table ?
Name: prepaid bucket’s name for identification.
Charging by: the charging of each bucket can be by one of the following (Indicating the system how to rate each bucket/activity):
usagev: for activity involves volume, duration, amount/unit.
cost: for activity involves currency for a specific bucket.
total_cost: currency bucket for any activity.
Charging by usaget: allocating the relevant bucket to rate and charge an activity (call, sms, data, etc.)
Priority: usage prioritization between buckets (e.g use bonus bucket before calls bucket before core balance bucket). Prioritization defined by a number. The highest will be the 1st.
How to search for an existing bucket ?
Buckets can be found by searching a value in the “Search for…” input field above the Prepaid Buckets table. The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing bucket ?
Buckets values can be edited by pressing the pencil on the right side of each line in the plans table.
Edit Prepaid Buckets screen - Filled with the selected bucket’s data when in edit mode.
What are the fields shown in the Edit Prepaid Buckets screen ?
See details below in tabs explain.
What is the use of each tab in the Edit Prepaid Bucket screen ?
Details tab:
Usage:
Define the bucket’s details as explained in Usage and Fields.
Fields:
Name: prepaid bucket’s name for identification.
External ID: Id that will be used by 3rd party system to charge the bucket.
Priority: usage prioritization between buckets (e.g use bonus bucket before calls bucket before core balance bucket). Prioritization defined by a number. The highest will be the 1st.
Charging by: the charging of each bucket can be by one of the following (Indicating the system how to rate each bucket/activity):
usagev: for activity involves volume, duration, amount/unit.
cost: for activity involves currency for a specific bucket.
total_cost: currency bucket for any activity.
Usage type: allocating the relevant bucket to rate and charge an activity (call, sms, data, etc.)
Shared bucket: the bucket will be shared by all subscribers associated with an account.
Unlimited: change the bucket behaviour so it won’t be limited by time period (like Core Balance).
Limited Products tab:
Usage:
Define the bucket’s use limitations by plan and product/destination (e.g restrict the sms bucket for “unique_plan_#01”, so it would be able to send sms only to products/destinations that starts with 123…).
Allow specific products (destinations) for a specific customer plan (C subscriber) in a specific bucket. In case where no limitations defined - all products (destinations) are allowed in this bucket. If BASE is defined with specific products in a bucket - all C subscribers will be able to use only those specific products in this bucket. BASE in this case is equivalent to market limitations on a bucket.
Fields:
In the upper panel, start typing (auto completion) the prepaid plan you want to add. Select from the predefined prepaid plans list.
In the new “PLAN_NAME” panel, start typing (auto completion) the product(s) you want to add. Select from the predefined prepaid plans list.
Save.
How can I add a new bucket ?
Press the “Add New” button on the upper right side of the Prepaid Buckets table in the main Prepaid Buckets screen.
Fill up all the fields as described in “What is the use of each tab in the Edit Prepaid Bucket screen” section, and press Save.
¶ Postpaid
This menu is relevant for Postpaid Customers/Subscribers only.
¶ Plans
¶ Postpaid Plans screen usage
Postpaid subscribers plans.
Postpaid subscribers are charged for their plans.
The plan determines a postpaid subscriber behaviour - restrictions, permissions, amounts/volumes, periods, thresholds, notifications etc.
¶ Postpaid Plans screen fields
Main Postpaid Plans screen - Automatically shows a table with all the predefined customer plans.
What is the information shown in the Postpaid Plans table ?
Title: plan’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - Not editable.
External Code: reference to the old system - identifier for the user in case of API usage.
Trial: OPTIONAL - number of month (cycles) free of charge (trial period).
Recurring Charges: number of charged cycles. Each cycle period determines in the Billing Frequency.
Billing Frequency: the time period of each cycle.
Charging Mode: determines when the plan will be charged:
- Arrears: payment after the usage/billing cycle.
- Upfront: payment before the usage/billing cycle.
How to search for an existing plan ?
Plans can be found by searching a value in the “Search for…” input field above the Plans table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing plan ?
Postpaid Plans values can be edited by pressing the pencil on the right side of each line in the plans table.
Edit Postpaid Plan screen - Filled with the selected plan’s data when in edit mode.
What are the fields shown in the Edit Postpaid Plan screen ?
See details below in tabs explain.
What is the use of each tab in the Edit Postpaid Plan screen ?
Details tab:
Usage:
Edit the Plan’s name, code and key.
Fields:
Title: plan’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - Not editable.
External Code: reference to the old system - identifier for the user in case of API usage.
Billing Frequency: the time period of each cycle.
Charging Mode: determines when the plan will be charged:
- Arrears: payment after the usage/billing cycle.
- Upfront: payment before the usage/billing cycle.
Trial Period (Panel): OPTIONAL (can be Removed) - number of month (cycles) free of charge (trial period). Defining period with X cycles and X price in “Recurring Charges Panel” will have the same effect.
Period: indexing each period of cycles with a specific price.
Cycles: how many cycles will run through this period with this price.
Price: the price of this period of cycles.
Recurring Charges Panel: number of charged cycles. Each cycle period determines in the Billing Frequency. Must have at least one period. Can have N periods. The 1st period can be used for trial.
Period: indexing each period of cycles with a specific price (will start with 2 if there is a trial period).
Cycles: how many cycles will run through this period with this price.
Price: the price of this period of cycles.
¶ Plan Proration:
- Prorated start:
This flag determines whether A new subscriber will be charged from the beginning of the month or prorated from his subscription day.
Example: A new subscriber registered a plan on 15/03/2019.
Checked: Subscriber is partially charged starting from 15/03/2019.
Unchecked: Subscriber is charged at full plan cost for March.
- Prorate change on termination:
When a subscriber is deactivated ,this flag determines whether a subscriber will be charged for the entire termination month or for the number of days until termination.
Example: A subscriber is deactivated on 15/03/2019.
Checked: Subscriber is partially charged until 15/03/2019.
Unchecked: Subscriber is charged at full plan cost for March.
- Prorate old plan charge on plan change:
This flag can be used whenever a plan ends. When checked, the current plan will be prorated until it’s termination date. When Unchecked, the current plan will be fully charged (even though it expires before the end of the month).
Example: Bob is a new client who registered on 1.2.2019 to “PLAN_A” which costs 20$ per month. 10 days later, Bob decides to upgrade his plan to “PLAN_B” which costs 40$ per month, not prorated.
Checked: Bob will be charged for (20/28)*10 = 7.14$+40$ = 47.14$.
Unchecked: 20$ + 40$ = 60$
Flag combination:
In the last example (Bob’s registration), if “Prorate old plan charge on plan change” is checked in PLAN_A, and “Prorated start” is checked in PLAN_B. The total charge in the billing cycle will be:
(20/28)*10 = 7.14$ for PLAN_A
(40/28)*18 = 25.14$ fro PLAN_B
Total: 32.85$
Override Product Price tab:
Usage:
To override to product’s original values.
Enable the change of product’s original values, such as intervals and price per interval for the users of a specific plan.
Check for more info in “Products” section.
Fields:
In the upper panel “Select Products to Override Price”, start typing (auto completion) the product you want to add. Select from the predefined product list. The product will be automatically added to the list.
From: current interval’s step start point - 1st step will always start at 0.
To: current interval’s step endpoint - will use as upper border for each step and the beginning of the next step if exists.
Interval: number of units that will be used for rounding up in each step.
Price Per Interval : each rated unit (rounded interval) in each step will be charged by multiplying by this value.
Add New: will add new step to charge.
Plan Includes tab:
Usage:
Enable the definition of usage free units.
The defined units are of the same type as through all the process (e.g seconds, bytes, etc.)
A plan can include free units for use by the subscriber (e.g. free 500 seconds to use when dialing to UK, or to Germany, or to any country in europe.
After the units predefined in this tab for a product in a plan will be ended, the product will start behave as appears in the “Override Product Price” tab - if predefined, or will behave as planned originally if not predefined in the “Override Product Price” tab.
The free units in “Plan Includes” can be shared by all subscribers under the same customer.
Fields:
Name: group’s name.
Unit Type: product’s usage / unit type which the products will be grouped into, and will be charged by it.
Include: the amount of free units - from “0” to Unlimited by checking the box.
Products: one or more (N) products that are free of charge, limited by the amount in the Include.
Shared: indicates if the group can be shared by the customer’s subscribers (only subscribers with the same plan under the same customer can share the amount in the Include.
How to edit an existing Plan Includes ?
Plan Includes values can be edited by pressing the “Edit” button on the right side of each line in the Plan Includes table.
Edit Plan Includes screen - Filled with the selected Plan Includes data when in edit mode.
What are the fields shown in the Edit Postpaid Plan screen ?
Fields:
Include: the amount of free units - from “0” to Unlimited by checking the box.
Products: one or more (N) products that are free of charge, limited by the amount in the Include.
Shared: to make this group of units included potentially shared by the subscribers under a customer.
How can I add a new Plan Includes group ?
Press the “Create New Group” button on the lower left side of the Plan Includes tab under Plan Includes table .
Fill up all the fields following the the wizard and press Save.
Step 1 - Set Name:
Give a unique name to the group and press the Next button.
Step 2 - Set Usage Type:
Select a Unit Type from the predefined drop down list and press the Next button. This will help identify the product’s usage/unit type.
Step 3 - Set Includes:
Define the amount of units to be included (free of charge) from “0” to Unlimited.
Check the box if you want this group to be shared by the subscribers that using this plan under a customer.
Step 4 - Set Products:
In the input field, start typing (auto completion) the product you want to add. Select from the predefined product list. The product will be automatically added to the list.
Press Add when done - The new group will be added to the table list.
Press save in the main screen to save the new group to the list of groups.
How can I add new plan ?
Press the “Add New” button on the upper right side of the Postpaid Plans table in the main Postpaid Plans screen.
Fill up all the fields as described in “What is the use of each tab in the Edit Postpaid Plan screen” section, and press Save.
¶ Services
¶ Postpaid Services screen usage
To add services - extra abilities to the subscriber.
Unlike the plans, subscriber can have 1-N services and each service can occur 1-N cycles. It means that a service can be charged only once.
Like the plans, a service can include free of charge units.
¶ Postpaid Services screen fields
Main Postpaid Services screen - Automatically shows a table with all the predefined services.
What is the information shown in the Postpaid Services table ?
Title: service’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - Not editable.
Price: the price for each cycle/occurrence of the service.
Cycles: How many cycles/occurrences this service will be used and charged during the time of use.
How to search for an existing service ?
Services can be found by searching a value in the “Search for…” input field above the Plans table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing service ?
Postpaid Services values can be edited by pressing the pencil on the right side of each line in the services table.
Edit Postpaid Services screen - Filled with the selected services data when in edit mode.
What are the fields shown in the Edit Postpaid Service screen ?
See details below in tabs explain.
What is the use of each tab in the Edit Postpaid service screen ?
Details tab:
Usage:
Edit the Service’s name, code and key.
Fields:
Title: service’s name - to be presented in the bill.
Key: unique plan’s key - for use by the system - Not editable.
Price: the price for each cycle/occurrence of the service.
Cycles: How many cycles/occurrences this service will be used and charged during the time of use.
Service Includes tab:
Usage:
Enable the definition of usage free units.
The defined units are of the same type as through all the process (e.g seconds, bytes, etc.)
A service can include free units for use by the subscriber (e.g. free 500 seconds to use when dialing to UK, or to Germany, or to any country in europe.
After the units predefined in this tab for a product in a service will be ended, the product will start behaving as planned originally.
The free units in “Service Includes” can be shared by all subscribers under the same customer.
Fields:
Name: group’s name.
Unit Type: product’s usage / unit type which the products will be grouped into, and will be charged by it.
Include: the amount of free units - from “0” to Unlimited by checking the box.
Products: one or more (N) products that are free of charge, limited by the amount in the Include.
Shared: indicates if the group can be shared by the customer’s subscribers (only subscribers with the same service under the same customer can share the amount in the Include.
How to edit an existing Service Includes ?
Service Includes values can be edited by pressing the “Edit” button on the right side of each line in the Service Includes table.
Edit Service Includes screen - Filled with the selected Service Includes data when in edit mode.
What are the fields shown in the Edit Postpaid Service screen ?
Fields:
Include: the amount of free units - from “0” to Unlimited by checking the box.
Products: one or more (N) products that are free of charge, limited by the amount in the Include.
Shared: to make this group of units included potentially shared by the subscribers under a customer.
How can I add a new Plan Includes group ?
Press the “Create New Group” button on the lower left side of the Service Includes tab under Service Includes table.
Fill up all the fields following the the wizard and press Save.
Step 1 - Set Name:
Give a unique name to the group and press the Next button.
Step 2 - Set Usage Type:
Select a Unit Type from the predefined drop down list and press the Next button. This will help identify the product’s usage/unit type.
Step 3 - Set Includes:
Define the amount of units to be included (free of charge) from “0” to Unlimited.
Check the box if you want this group to be shared by the subscribers that using this plan under a customer.
Step 4 - Set Products:
In the input field, start typing (auto completion) the product you want to add. Select from the predefined product list. The product will be automatically added to the list.
Press Add when done - The new group will be added to the table list.
Press save in the main screen to save the new group to the list of groups.
How can I add new service ?
Press the “Add New” button on the upper right side of the Postpaid Services table in the main Postpaid Services screen.
Fill up all the fields as described in “What is the use of each tab in the Edit Postpaid service screen” section, and press Save.
¶ Discounts
Discounts can be defined in the Discounts screen under the Postpaid tab.
What is the information shown in the Discounts table ?
Title: discount’s name - to be presented in the bill.
Key: unique discount’s key - for use by the system - Not editable.
Type: how the discount will be calculated - there’s 2 options:
- Monetary - The mentioned amount will be subtracted from the bill amount.
- Percentage - The mentioned percentage will be the discount by percentage.
How to search for an existing discount ?
Discounts can be found by searching a value in the “Search for…” input field above the Discounts table.
The value will be searched by a specific field that should be checked in the “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting the “Search for…” input field.
How to edit an existing discount ?
Discount values can be edited by pressing the pencil on the right side of each line in the Discount table.
Edit Discount screen - Filled with the selected discount’s data when in edit mode.
What are the fields shown in the Edit Discount screen ?
Title: discount’s name - to be presented in the bill.
Key: unique discount’s key - for use by the system.
Cycles: the number of billing cycles in which the discount will be active.
Prorated: flag to determine if the discount will be prorated, “inherited” value means that
discount will be prorated depending on the definition on the plan/service.
prorated discount and “no” value otherwise.
Priority: which discount will be granted first.
Discount Overall Limit: max amount of the discount.
Max Subscribers:discount will be given for an account only if it has less or equal
subscribers that uphold the discount conditions than the mentioned amount in this field.
Min Subscribers: discount will be given for an account only if it has more or equal
subscribers that uphold the discount conditions than the mentioned amount in this field.
Excludes: array of discounts which will not be granted with the mentioned discount,
Discount can exclude another discount only if it has higher priority than the discounts
mentioned in the excludes array.
Conditions: conditions in which the discount will be valid.
For adding a new condition group, click on “Add conditions group".The Logic connection between conditions groups is by an “OR” condition.
In each condition group it’s possible to add:
- Customer condition - conditions on account level.
- Subscriber condition - conditions on subscriber level.
- Service condition - conditions on subscriber services.
In service condition it’s possible to define different service groups, in the above screenshot it’s possible to see that there’s only one service group for that discount and it means that only if the subscriber has the
the service mentioned in the conditioned service group he will be able to get the discount.
Each condition added to a service group means a subscriber must have a service that fulfills all of the added conditions.
In order to add conditions which will imply different services, another service group should be added.
In the above screenshot there’s 2 service groups and this means that the subscriber must have the 2 services defined in the services groups in order to receive the discount.
Screen of defining condition groups for discount:
Each added condition inside each one of the mentioned condition types will be treated as an “AND” condition which means that all added conditions will have to be met.
The actual discount is determined by the “Plans Discount Values” tab and “Services Discount Values” tab
It’s possible to select plans/services and for each one it’s possible to define the amount of discount that should be given on that plan/service.
It’s important to notice that the defined conditions determine if the subscriber should get the discount and that the actual discount operates independently.
For example it is possible that a subscriber will be eligible to get some discount by the discount conditions but the discount is on a plan that the subscriber does not have, so of course that he couldn’t get that discount.
As implied from the above the actual discount(subject) can be defined only on a plan or a service.
Plans Discount Values
The selected discount amount(monetary/percentage) given to plans.
Services Discount Values
The selected discount amount(monetary/percentage) given to services.
How can I add a new Discount ?
Press the “Add New” button on the upper right side of the Discounts table in the main Discounts screen.
Fill up all the fields as described in “What are the fields shown in the Edit Discount screen” section, and press Save.
Discount Examples:
- “Upgrade” discount: A company wishes to apply a discount for subscribers who upgrade a specific service/plan. Assuming a company has a basic plan which costs 50$ per month -“PLAN_50”. Later, the company decides to grant a single award of 75$ to every subscriber who upgrades his “PLAN_50” to the newest plan - “PLAN_100”. This discount plan will be named as “PLAN_100_UPGRADE_DISCOUNT”.
In order to configure this plan, A new discount should be created as follows:
- Number of Cycles - 1. The discount will be initiated only for 1 billing cycle for every subscriber who’s assigned to “PLAN_100_UPGRADE_DISCOUNT” .
- Prorated - No. Since we intend to grant a full 75$ discount, no matter when the subscriber upgraded his plan. If we pick “Inherited”, it means the discount will inherit it’s prorated preferences from it’s plan, and if the plan is prorated the discount will also be prorated, meaning the 75$ will be splitted according to the number of days “PLAN_100” is activated. For example, if a subscriber is assigned to “PLAN_50” and after 20 days he decides to upgrade to “PLAN_100”,assuming this month has 30 days, he will only receive the discount for the number of days “PLAN_100” was activated. (75/30) * 10 = 25$ discount. This, we would like to avoid.
- “Former plan”- “equals”- “PLAN_50” - this assures the discount will only apply to subscribers who upgraded their plans and not to new subscribers who acquired “PLAN_100”. Former plan is a subscriber’s field which holds the previous plan used before applying the current plan.
- Plan discount value = 75$ - the granted amount.
2 ) Subscriber has a discount and terminates: A client is assigned to a 50$ price plan “SIMPLE”. This subscriber is granted a monthly discount of 15$ and the subscriber is deactivated 10 days after his registration. For easier calculations, let’s assume the current month has 30 days.
What will be the subscriber’s final bill on the upcoming billing cycle?
There are several options for this situation.
- Plan is prorated & discount is inherited.
The bill will be calculated as follows:
(50 /30) * 10 = 16.6667$ - Plan price.
(15/30) * 10 = 5$ - Discount rate.
Final charge = 16.6667-5 = 11.666$
- Plan is prorated & discount is not inherited.
The bill will be calculated as follows:
(50 /30) * 10 = 16.6667$ - Plan price.
15$ = Discount rate
Final charge = 16.6667-15 = 1.666$
- Plan is not prorated.
50$ - Plan price.
15$ - Discount rate.
Final charge = 50-15 = 35$.
3 ) Conflicting Discounts ("excludes" field) :
Supposing two conflicting discounts exists, each one suits the subscriber’s granting conditions. They will both be granted. However, if we want to avoid multiple discounts, we can configure the “excludes” field. This field assures that the excluded discounts will not be activated in parallel to the configured discount.
Postpaid->Discounts.
Assuming 2 discounts appear in the list “FIRST_DISCOUNT_30” and “SECOND_DISCOUNT_50”.
“FIRST_DISCOUNT_30” has the following properties:
- Discount range: 01/05/2020 - 19/05/2020
- Type: monetary
- Prorated: inherited.
- Plans Discount Values-> Select Plans: “PLAN_100” - the plan to which the discount applies.
- PLAN_100: “30” - the discount rate.
“SECOND_DISCOUNT_50” has these properties:
- Discount range: 10/05/2020 - infinitely.
- Type: monetary
- Prorated: No.
- Plans Discount Values-> Select Plans: “PLAN_100” - the plan to which the discount applies.
- PLAN_100: “50” - the discount rate.
¶ This assures that “FIRST_DISCOUNT_30” will only apply up to 10/05/2020. From then on, only “SECOND_DISCOUNT_50” will be activated.
4 ) Plan switch during month:
A customer has a 30% discount for SIMPLE plan (25 Euro monthly fee) and upgrades on 10th of the month to a 40_EURO_PLAN plan with 20% discount. Assuming current month has 31 days and plan + services are prorated:
Analysis: The final bill includes 2 parts. First part from first day to 9th with SIMPLE plan + discount (9 days). Second part from 10th - 31th (22 days).
Days 1 - 9: (plan price / days in month)*(days in plan) * ( discount value)
(25/31)*9 = 7.258 * 0.7 (plan value after 30% discount) = 5.08 Euro.
Days 10 - 31: (40/31)*22 = 28.387 * 0.8 (plan value after 20% discount) = 22.709 Euro
Sum: 5.08+22.709 = 27.789 * 1.19 (tax) = 33.069 => 33.07 (rounded)
¶ Custom fields
Enables custom fields to be added to the discounts screen.
What is the information shown in the Custom fields - “Discounts” table ?
Key: The system field name in db.
Title: discount’s title - as shown in the screen.
Type: field’s type - text/boolean etc.
How can I add new custom field for discounts?
Press the “Add New Field +” button on the left bottom corner of the Custom Fields table.
Fill up all the fields on the “Create New Discount Field” window:
Key: unique field’s key - for use by the system - Not editable.
Title: discount’s name - to be presented in the bill.
Field Type: field’s input type - text, boolean, percentage etc.
Description: field’s description - appears when you mouse over the question mark to the left of the field’s name.
Help Text: short text - will appear below the field’s name.
Options: Check the required attributes for the field.
Preview and Default Value: insert default value, if needed.
Press Save.
¶ Discounts tab in subscriber screen
This type of discount is defined for specific subscriber and only he can get this discount, this of course differs from general discounts which applies to anyone who adheres to the defined conditions on the discount.
On subscriber screen you can find the “Discounts” tab, in which you can edit and create discounts for a subscriber:
- Edit existing discount: Discount values can be edited by pressing the pencil on the right side of each line in the Discounts table.
- Create new discount: click on “Add Discount” to create a new discount for a subscriber.
¶ Conditional Charges
Charges can be defined in the Conditional Charges screen under Postpaid tab.
This can be used for example to define a cancelation fee.
What is the information shown in the Conditional Charges table ?
Title: charge’s name - to be presented in the bill.
Key: unique charge’s key - for use by the system - Not editable.
Type: how the charge will be calculated - there’s 2 options:
- Monetary - The mentioned amount will be added to the bill amount.
- Percentage - The mentioned percentage will be the charge by percentage.
How to search for an existing charge ?
Charges can be found by searching a value in the “Search for…” input field above the Conditional Charges table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing charge ?
Charge values can be edited by pressing the pencil on the right side of each line in the Conditional Charges table.
Edit Charge screen - Filled with the selected charge’s data when in edit mode.
What are the fields shown in the Edit Charge screen ?
Cancellation fee of 20 euro example:
There’s of course an option to define different conditions, for example condition on subscribers so only subscribers form Cyprus will get the discount.
Basically Charges and Discounts are pretty much the same besides obviously the fact that one is a
charge and the other one is discount.
Another difference is “general” attribute in “subject” object in root, it’s available only for monetary
charges and it can be used to define cancellation fee for example.
¶ Running a billing cycle
- under the ‘Billing Cycle’ → ‘Run’ tab you can select the desired month to run a billing cycle for.
- Cycles are going by date-ranges depending on the system configuration field
‘charging day’ in the settings. You can only run a billing cycle after the cycle end-date. - You can choose whether you wish to produce PDF files for the invoices created.
- This process might take some time, depending on the size of your DB - you can view the percentage of the progress while it is running.
- Once the aggregation process is over, you will be able to go over each invoice (in case you chose to produce a PDF for them) and verify charge amount etc.
¶
¶ Settings
¶ General Setting
¶ General Settings Usage
To define General company information and other attributes.
¶ General Settings Fields
What is the use of each tab in the General Settings screen ?
Company tab:
Usage:
General company’s information to be shown on the bill and for identifying.
Fields:
Name: company’s name.
Address: company’s address.
Phone: company’s phone number.
Email: company’s email.
Website: company’s website.
Logo: company’s logo.
Locale tab:
Usage:
General definitions.
Fields:
Time Zone: company’s Time Zone.
Charging Day: bill cycle day. In this day every month - the billing cycle will run and create a bill to the customer.
Currency: currency to be used.
Menu tab:
Usage:
To edit the visibility and permissions of the main menu.
Security tab:
Usage:
This code is automatically generated upon the account/tenant creation.
You should keep it secret and not share it with anyone else.
The transaction/request initiator uses this key to sign the data that he sent to BillRun.
This way BillRun identifies the company/tenant when external API calls are made.
¶ Input Processors
¶ Input Processors Usage
To define all the input file’s / API requests’ structures, related and required information.
¶ Input Processors Fields
Main Input Processors screen - Automatically shows a table with all the predefined input processors.
What is the information shown in the Input Processors table ?
Name: Input Processor’s name.
How to edit an existing input processor ?
Input Processors values can be edited by pressing the pencil on the right side of each line in the Input Processors table.
Edit Input Processors screen - Filled with the selected Input Processor’s data when in edit mode.
Bottom of the same screen:
Best way to learn how to edit input processor is first of all create a new input processor.
How can I add a new input processor ?
Press the “Add New” button on the upper right side of the Input Processors table in the main Input Processors screen.
Follow the instructions.
¶ Input Processor Wizard
¶ Wizard’s initialization
Choose the method you prefer to transfer your billable usage data to the system - through API-based for real time (also Pre-paid) billing, or File-based for batch billing.
Both, the API-based and File-based methods will lead you through the same configuration path windows when the differences will be in the way that BillRun will receive and process the input information, and is going to be described in the following steps.
¶ API-based method
Usage:
Using for real-time measurable ongoing usage billing - mainly prepaid customers (but not limited to).
Prepaid subscribers:
Records will be sent by BillRun’s client to BillRun before the beginning of an activity in order to check if there is an available balance and receive confirmation (permission) to start the activity, and before any part (during) of the activity, in order to request further usage allowance to continue the activity.
Postaid subscribers:
Records will be sent by BillRun’s client to BillRun at the end or after any part (during) of the activity, applying BillRun with the usage information about the activity AFTER it took place, without the need to request any usage allowance at any stage of the activity. The entire activity duration and process is managed by the BillRun’s client.
¶
¶ Wizard’s 1st stage - CDR-Fields
Usage:
Define the input structure in JSON format, either by uploading the structure from a file by using the “Browse…” button (will be available after filling the structure name - mandatory), or adding the fields manually, or both.
Fields:
General
Name: Mandatory unique name for the input processor.
Select Sample JSON: Optional. Will be available after filling the “Name” field. Enable uploading a predefined JSON structure instead of manual definition.
CDR Fields
Add Field: Each press on the button will add new field to the manually configured structure. In case a JSON structure was previously uploaded, the new field(s) will be added to the existing ones at the end of the structure. The field name have to be in lowercase and separated by underscore. Field names have to be unique.
Move up: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Move down: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Remove: To remove the current field (the same line of the button) from the structure in case of input changes without needing new definitions.
¶ Wizard’s 2nd stage - Field Mapping
Usage:
Identify and map important fields that will be used by the billing process.
Fields:
Date Time: The input field that holds the date and time of the call and is used by BillRun for the billing process (e.g find available subscribers, plans and products for this date and time in the DataBase). It will also be presented in the invoice.
It can can be the start or the answer date and time.
In case there are separated fields for date and time, the first dropdown field will map the date, and after checking the “Time in separate field” the other dropdown field will be available map the time. BillRun will concatenate both fields.
Volume: The input field that holds the total amount of usage to be billed - by duration, volume, kg, km, distance etc.
Usage types: Usually mapped by field called “record type”.
It refers to the Usage/Activity/Unit of the input record/transaction (e.g: call/data/sms/km/cm/kg/incoming call/queue etc.). This field should help distinguish between activities and charge differently for each activity.
If there is only one record type available, it is mostly common to use the “Static” option, and then add an activity (e.g. call). If an activity doesn’t exists, it can be added easily be typing the activity name and then press “Add”.
If there are several record types available, the “Dynamic” option should be selected.
There are two columns:
The left one - Input Value: This is the value that appears on the incoming record.
The right one - Usage Type: Value that will be used on the next step for the rating part - correlate each activity to its subscriber by the information on the input record and to correlate each activity to its product by building a key that will be correlated to a product.
If an activity doesn’t exists, it can be added easily be typing the activity name and then press “Add”. After adding an activity press the “Add Mapping” in order to map the next activity. If “Add Mapping” was not pressed, the activity will not be saved when moving to the next stage.
¶ Wizard’s 3rd stage - Calculator Mapping
Usage:
This stage is the Rating Calculator mappings.
The values in this stage enabling the correlation between the subscriber and it’s activity that appears on the cdr to the subscriber and the product/rate that appears in BillRun billing system.
Fields:
Customer Identification
To identify the Subscriber (and consequently the customer) by the relevant value on the input record for any activity.
Each activity defined in the previous stage will appear at this stage, in order to correlate during the process between the Subscriber on the input record to the Subscriber in the BillRun system, by mapping the input field that holds the value of the Subscriber in each activity to predefined internal value.
This predefined value will be mapped internally by the system to a system sid (Subscriber ID) that is connected to aid (Account ID).
Since it’s a unique value and a key in the billing system, the SID on the input record has to be a unique value identifier.
For example in the above screenshot:
In “call” activity, which is a regular outgoing call, the “previously defined_source” (cid) will hold the unique Subscriber ID.
In “incoming_call” activity, which is a regular incoming call, the “previously defined_destination” (cld) will hold the unique Subscriber ID.
Rate by
To identify the product that will be used to charge any individual activity (usage).
For any activity, there are four options to identify and match a product (rate) by the value on the input record, and there can be a combination between the identifiers for each activity in order to identify and match a product (rate).
For example in the above screenshot:
In “call” activity, which is a regular outgoing call, the “previously defined_destination” (cld) will hold the destination number which will be used to identify the relevant product (rate). In case of regular dialing, the prefix of the dialled (or called) number will be found by best match (longest prefix) in the Products list.
In “incoming_call” activity, which is a regular incoming call, the “previously defined_source” (cid) will hold the originating number which will be used to identify the relevant product (rate) - if there is a charge for incoming calls. In case of regular incoming call, the prefix of the calling (or source) number will be found by best match (longest prefix) in the Products list.
Creating a combination of conditions for an activity can be done by pressing the “Add” in each activity section.
For example: Identifying the destination prefix best match, only for specific products (by product key).
It means that two different fields on the input record will be used to perfectly match a Product to the specific record.
¶
¶ Wizard’s 4th stage - Real-time Mapping
There are two Real-time mapping options
One time charge requests:
Will be used for Postpaid - real time transactions will announce the BillRun system that the activity has just ended, and supply the relevant information as described above to charge the activity.
Most fields will be disabled, except “Request type pretend field”.
Request type pretend field - If chosen and the field value will be “true” - the transaction will be treated as a trial/test/check (test/check availability of service) and won’t be charged.
Allocation based requests:
Will be used for Prepaid - real time transactions will check for service availability according to relevant balance existence (Buckets) in the BillRun system, and will request an allocation for the continuity of the service for the activity in use (call, data, etc.).
Usually a Real-time prepaid activity composed from more than one transaction:
Initial Request - the request that initiate the activity. The 1st usage allocation. If there IS a balance in the relevant Bucket for the activity, the activity will start at this point with the predefined allowance answer to the request. If there IS NO balance in the relevant Bucket for the activity, a negative answer will be sent back to the request, and the originator will not allow the establishment of the activity/session.
Update Request - the continuation of an activity depends on an ongoing requests for renewing the allowance by new allocation request. Each time, before the previous allowance is about to end, a request for a new allowance will be sent. If there IS a balance in the relevant Bucket for the activity, the activity will continue, otherwise, a negative answer will be sent back to the request and the activity/session will end by the originator. It should contain the information for rebalance if needed.
Final Request - this transaction will end the activity/session. In addition to the regular information on the transactions, it should contain the information for rebalance if needed (in cases when not all the allowance was used by the subscriber when he ended the activity/session).
Required Fields:
Request type field: indicates the type of the request as mentioned above (Initial Request = 1; Update Request = 2; Final Request = 3).
Request type pretend field: if chosen and the field value will be “true” - the transaction will be treated as a trial/test/check (test/check availability of service) and won’t be charged.
Rebalance field: by this field, BillRun makes calculation for the real usage. Example: the subscriber was given an allowance of 10M for the browsing request, and when the system came back to request another allowance (current session ran out of time before ended the data) the subscriber used only 5M - the 5M will appear in this field so BillRun will be able to recalculate (rebalance) the subscriber’s balance in the relevant Bucket and return 5M to his Bucket’s balance (10M-5M=5M).
Group requests fields: key to identify all the transactions that belong to the same activity/session. Can contain one or more fields.
Optional Fields:
If one of the fields below will hold a value, BillRun will use the value. Otherwise BillRun will use the “Default” value in the last field.
The value uses the same units as used all over and appears in the duration/volume field.
Initial request: the maximum allowance that will be given to the subscriber for initiation. If the relevant Bucket’s balance is lower - it will be given as is.
Update request: the maximum allowance that will be given to the subscriber for ongoing usage (continuation of an activity/session). If the relevant Bucket’s balance is lower - it will be given as is.
Final request: the maximum allowance that will be given to the subscriber for finalizing an activity/session (will be 0 most of the times). Activities, usually comes with a value in the “Rebalance Field” at this stage, after knowing all the duration/volume of the activity/session.
Default: if one of the fields above will hold a value, BillRun will use the value. Otherwise BillRun will use the “Default” value in this field.
¶
¶ File-based method
Usage:
Using for batch measurable ongoing usage billing.
When immediate billing is not needed, and billable usage is gathered once in awhile and then being transferred to BillRun as a file for batch processing.
There are two options for file based:
- I will use predefined input processor - enables choosing from a predefined template of known input structure.
- I will configure a custom input processor - enables configuring a brand new input structures and his behaviours.
Both, the API-based and File-based method will lead you through the same configuration path windows when the differences will be as mentioned above and on the Receiver configuration wizard - the way BillRun will receive and process the input information.
¶ Wizard’s 1st stage - CDR-Fields
When choosing the option: “I will configure a custom input processor”
By delimiter
Usage:
Define the input structure in delimited (e.g. CSV) file format, either by uploading the structure from a file by using the “Browse…” button (will be available after filling the structure name - mandatory, choosing the “By delimiter” option and adding the delimiter type), or adding the fields manually, or both.
Fields:
General
Name: Mandatory unique name for the input processor.
Delimiter: Choose if the file field delimited and add the delimiter type.
Select Sample CSV: Optional. Will be available after filling the “Name” and “Delimiter” fields. Enable uploading a predefined delimited field file structure instead of manual definition.
CDR Fields
Add Field: Each press on the button will add new field to the manually configured structure. In case a CSV file was previously uploaded, the new field(s) will be added to the existing ones at the end of the structure. The field name have to be in lowercase and separated by underscore. Field names have to be unique.
Move up: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Move down: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Remove: To remove the current field (the same line of the button) from the structure in case of input changes without needing new definitions.
Fixed width
Usage:
Define the input structure in fixed length format. This options will allow only manual configuration on the input file structure.
Fields:
General
Name: Mandatory unique name for the input processor.
Delimiter: Will remain unmarked.
Fixed width: Should be marked.
CDR Fields
Add Field: Each press on the button will add new field to the manually configured structure. Each field should have a static length. The field name have to be in lowercase and separated by underscore. Field names have to be unique.
Move up: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Move down: To place the current field (the same line of the button) in other position in the structure in case of input changes without needing new definitions.
Remove: To remove the current field (the same line of the button) from the structure in case of input changes without needing new definitions.
When choosing the option: “I will use predefined input processor”
All next steps that mentioned above are predefined and should only be updated in specific cases.
¶ Reports
Use reports to analyze your data. Reports can be either "Simple" (a subset of the data) or "Grouped" (for statistical analysis)
When building a new report you have several steps:
¶ Basic Details:
In the “Basic Details” section, you can choose the report’s name, the entity that you want to build the report on (Usage, Bills, etc), and the report type: simple (will present all the relevant rows), or grouped (will present grouped rows).
¶ Columns:
In the “Columns” section, you can choose the columns that you want to add to the report, from the entity’s relevant fields. If the report is “grouped”, you’ll have to choose for each of the columns it’s “group function”. For example, you can create a report on the usages that you collected from a CDRs files, and group the report by “File name” field:
¶ Conditions:
In the “Conditions” section, you can choose to filter the data that you want to see in your report.
You’ll choose the field/fields that you want your conditions to be on, and build the condition using “Operator” and “Value”. For example, if you want to build a report on the usages you collected from a CDRs files, and see only the CDRs that were received from a certain file, you can do it using a condition on the file name :
¶ Sort:
In the “Sort” section, you can sort the report’s result. For example, if you build a report on the usages you collected from a CDRs files, and one of the columns that you chose to display on your report is “File name”, you can sort the report results in ascending/descending format, according to the file name:
¶ Formatting Style:
In the “Formatting style” section, you can choose to display chosen fields, according to some format. For example, if one of your reports fields is a date field, you can choose how to display the date in your report :
¶ Usage report:
You can run usage-based reports which apply to CDRs, charges / refunds and any plan / service for which a subscription has been charged in any of the billing cycles, or in short - all the subscriptions' "lines".
Fields which start with "Customer:" / "Subscriber:" relate to the latest customer / subscription known (and not necessarily to the customer / subscription data at the time of the CDR.
¶ Common Fields
- Activity volume - Total volume consumed in the CDR
- Billing cycle - Invoice period in which the line is included
- Billing cycle status - Same as "Billing cycle" but contains dynamic values:
- Current - Active cycle (by billing cycle date range)
- Last Confirmed - Last billing cycle that was confirmed
- First Unconfirmed - First cycle following the last confirmed one
- Confirmed - All confirmed billing cycles
- Campaign inclusive units - For campaigns (groups), this is the total free (not charged) volume out of the CDR total volume
- Campaign name - If the CDR benefited from a campaign (group), its name
- Charge before taxes - Total charge for the billing line, without taxes
- Customer ID - BillRun unique identifier for the customer
- File name - Source filename of the billing line (when relevant)
- Process Time - Time when the line was processed by BillRun
- Product key - Product matched for the line
- Record time - Time of the CDR
- Record unique ID - Unique BillRun identifier for the line
- Subscriber ID - BillRun unique identifier for the subscription
- Subscriber's plan key - Subscription's plan at the time of the CDR
- Total charge - Total charge for the billing line, including taxes
¶ Tax:
¶ Rates:
¶ Tax Rates screen usage:
To define all the taxes rating, related and required information.
¶ Tax Rates screen fields:
Main Tax Rates screen - Automatically shows a table with all the predefined tax rates.
What is the information shown in the Tax Rates table ?
Title: tax’s name - to be presented in the bill.
Key: unique tax’s key - for use by the system - Not editable.
How to search for an existing tax rate ?
Taxes’s rates can be found by searching a value in the “Search for…” input field above the Rates table.
The value will be searched by a specific field that should be checked in “Search in fields” drop down list button.
Press Enter or the magnifier (search) button to activate the search.
The eraser button next to the magnifier (search) button is for resetting “Search for…” input field.
How to edit an existing tax rate ?
Taxes’s rates values can be edited by pressing the pencil on the right side of each line in the Rates table.
Edit Tax Rate screen - Filled with the selected tax’s data when in edit mode.
What are the fields shown in the Edit Tax screen ?
Title: tax’s name - to be presented in the bill.
Rate: the tax rate, as a percentage field.
How can I add new Tax Rate ?
Press the “Add New” button on the upper right side of the Rates table in the main Tax Rates screen.
Fill up all the fields as described in “What are the fields shown in the Edit Tax screen” section, and press Save.
¶ Custom fields:
Enables custom fields to be added to the tax rates screen.
What is the information shown in the Custom fields - “Tax” Rates table ?
Key: tax name.
Title: tax title - as shown in the screen.
Type: field’s type - text/boolean etc.
How can I add new Tax Rate ?
Press the “Add New Field +” button on the left bottom corner of the Custom Fields table.
Fill up all the fields on the “Create New Tax Field” window:
Key: unique field’s key - for use by the system - Not editable.
Title: tax’s name - to be presented in the bill.
Field Type: field’s input type - text, boolean, percentage etc.
Description: field’s description - appears when you mouse over the question mark to the left of the field’s name.
Help Text: short text - will appear below the field’s name.
Options: Check the required attributes for the field.
Preview and Default Value: insert default value, if needed.
Press Save.
¶ Tax tab(products/plans/services):
(Screenshots are taken from plan tab, but it refers to each of the entities - plan/service/product).
On each one of the entities: products/plans/services, you can find the “Tax” tab, in which you can define the tax mapping, for this entity:
- The entity isn’t subject to taxation. (tax isn’t relevant at all).
- Use global mapping rules. (mapping will be only according to your definition at “Tax->Mapping”).
- The entity implies a specific tax rate. (specific tax for this entity):
Choosing this option, you need to select (using the drop down) one of the taxes you defined in “Tax” -> “Rates”, or the default tax.
Also, choose:
1. “Override global mapping rules” - this option means that when calculating tax, for this certain entity, the tax rate will be the one you chose here, regardless of the “Tax-> Mapping Rules”.
2. “Apply if tax rate not found via global mapping rules” - this option means, that when calculating tax, the first priorities to be considered by the tax calculator, will be those from the “Tax-> Mapping Rules”. If no priority is relevant, then the tax you defined here, will be considered.
4. Use default tax rate. (for this entity, the tax will be the default tax rate).
¶ Mapping Rules:
The first 3 priorities represented are:
- Use product/service/plan override tax rate if defined - this priority chooseschoose the entity’s “Tax” tab choice you made, first. (in case you chose thechose at the relevant entity, on theon “Tax” tab - “Entity implies a specific tax rate”, this priority will be considered only if you alsoyou chose also “Override global mapping rules”).
- Use tax rate referenced by product/service/plan - this priority chooseschoose the “Tax -> Mapping Rules” priorities, first. Only if non of the Mapping Rules isn’t relevant, it checks the entity’s “Tax” tab choice you made. (in case you chose thechose at the relevant entity, on theon “Tax” tab - “Entity implies a specific tax rate”, this priority will be considered only if you also chosechose also “Apply if tax rate is notrate not found via global mapping rules”).
- Use default tax rate - in case non of the priorities above was relevant, you can choose that the calculator will rate the tax, for the relevant entity, using the default tax rate.
¶ Adding custom priorities:
You can add custom priorities, that will be added between the first and second initial priorities.
When adding a new priority, you can choose any of your CDR fields, and give it a priority, using the tax fields.
For example:
You can take a CDR field, “Tax explanation”, which contains the tax explanation, for example: “VAT Out Of Scope”, and choose that the tax calculator will check if the CDR line has “Tax explanation”, and if it does, it will choose it’s tax according to the tax explanation. If the CDR doesn’t have “Tax explanation” - it will get tax according to the next priority, in this case - the default one.
¶
Tax in reports:
Building a new report, you can insert tax information to the report, and also choose the report data, using conditions on taxes.
Tax information in the report:
¶ Columns:
At “Reports” -> “Add new” -> “Columns” - one of the fields you choose to display on report, can be one of the tax’s basic/custom fields.
Now, after you chose the wanted field, you can pick it’s label for your report.
For example, at the screenshot, the wanted field is “Tax key”, and it’s label on the report will
be “Usage’s Tax key”.
¶ Conditions:
At “Reports” -> “Add new” -> “Conditions” - one of the fields you choose for your report’s conditions, can be one of the tax’s basic/custom fields.
Now, depending on the field you have selected, you can select an operator, as well as a second field. For example, you can filter and display in the report only the lines whose tax key is a particular key:
Also, you can filter and display in the report only the rows whose tax amount is under the amount you choose:
Building a report, you can find a variety of operators to choose from, depending on the field selected.
¶ Tax settings:
¶ General Settings -> Tax:
To define the default tax rate.
¶ Custom:
Working with “Tax -> mapping.
Choose one of the tax rates you defined, to be the default tax rate.
For example:
