¶ 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.