The Input Processor is BillRun's mediation manager — the engine that handles all incoming usage data (input) to the billing system. It receives raw usage records (CDRs — Call Detail Records, or any other type of usage/transaction record), parses them according to a defined structure, identifies the customer and the product (rate) for each record, and prepares each line for rating, pricing, and ultimately invoicing.
Every distinct source of usage data — a switch, a roaming partner, an interconnect feed, an IoT platform, an API client — is typically configured as its own input processor, with its own field structure, mappings, and delivery method.
When creating a new input processor you first choose how the billable usage data is transferred to BillRun:
API-based (Realtime): usage events are pushed to BillRun via HTTP API calls in real time. This is the method used for real-time / online charging (OCS), and is the typical choice for prepaid scenarios. It can also be used for postpaid one-time charge notifications.
File-based (Batch): usage is collected periodically into files (CSV, delimited, fixed-width, or other formats) and pulled or pushed to BillRun for batch processing. When choosing file-based, you may either start from a predefined input processor template (a known input structure), or configure a fully custom input processor.
Both methods lead through the same wizard screens. The differences are in how the input structure is defined in the first step, and in the final step: file-based processors end with the Receiver screen (how files arrive), while API-based processors end with the Realtime Mapping screen (how realtime requests are interpreted).
The input processor is configured through a step-by-step wizard. This guide dedicates a chapter to each screen:
CDR Fields — define the structure of the incoming record: which fields exist and in what order/format.
Field Mapping — map the key billing fields: date/time, volume, and usage types.
Customer Mapping — identify the subscriber (and consequently the customer/account) for each usage type.
Rate Mapping — identify the product (rate) that will be used to charge each usage type.
Pricing (optional) — Relevant only for pre-priced inputs. Define which field on the input contains the price.
Receiver / Realtime Mapping — file-based: define where and how BillRun collects the input files; API-based: define how realtime requests (initial / update / final) are handled.
Navigate to Settings → Input Processors. The main screen automatically shows a table with all predefined input processors (the table shows each processor's Name, and actions to enable/disable, edit, or delete it).
To edit an existing input processor, press the pencil (edit) icon on the right side of its line in the table. The Edit screen opens, pre-filled with the selected processor's data, organized in the same tabs/steps described in this guide.
To add a new input processor, press the “Add New” button at the upper-right side of the table and follow the wizard.
Note: Field names, mappings, and receiver settings take effect for newly received records. Records already processed are not retroactively re-parsed unless reprocessed manually.
The CDR Fields screen defines the structure of the incoming usage record — the list of fields each record contains, their names, and their order. Everything in the following steps (mappings, rating, pricing) refers back to the field names defined here.
The screen behaves slightly differently depending on the processor type:
API-based: the input structure is defined in JSON format. You can upload a sample JSON structure from a file (the “Browse…” / “Select Sample JSON” control becomes available after filling in the processor Name), add the fields manually, or combine both.
File-based, by delimiter: the input is a delimited file (e.g. CSV). After entering the Name, checking the Delimiter option, and entering the delimiter character, you can upload a sample CSV to auto-detect the structure, add fields manually, or both.
File-based, fixed width: the input file has fixed-length fields. Only manual configuration is possible — each field must be defined with its static length (width).
| Field / Control | Description |
|---|---|
| Name | Mandatory. A unique name for the input processor. This name is also the file_type identifier used internally (and in realtime API calls). Other options on the screen only become available after the Name is filled in. |
| Delimiter (file-based) | Check this option for delimited files and enter the delimiter character (e.g. a comma for CSV, semicolon, pipe, tab). |
| Fixed width (file-based) | Check this option instead of Delimiter when the file has fixed-length fields. Each CDR field must then be given a static length. |
| Select Sample JSON / CSV | Optional. Lets you upload a sample structure file instead of defining the fields manually. Available only after the Name (and, for CSV, the Delimiter) is filled in. Fields parsed from the sample appear in the CDR Fields list and can then be adjusted. |
| Add Field | Each press adds a new field row to the structure. If a sample file was previously uploaded, new fields are appended at the end of the existing structure. |
| Field name | The name of each input field. Names must be unique, lowercase, with words separated by underscores (e.g. calling_number, record_opening_time). |
| Width (fixed width only) | The static character length of the field within the record. |
| Move up / Move down | Repositions the field within the structure — useful when the input layout changes, without redefining all fields. |
| Remove | Deletes the field row from the structure. |
Enter a unique, descriptive Name for the processor (e.g. switch_cdrs, roaming_tap, iot_usage).
For file-based processors, choose Delimiter (and enter the character) or Fixed width according to the file format.
Either upload a sample file (JSON/CSV) to auto-populate the field list, or press Add Field repeatedly and type the field names manually (lowercase, underscore-separated, unique).
Order the fields with Move up / Move down so they exactly match the order in the incoming record (critical for delimited and fixed-width files).
Remove any field rows that do not exist in the input, then continue to the next step.
Note: Field names defined here are the vocabulary for every later screen — choose clear names. The structure must match the input exactly: for delimited files, the number and order of fields; for fixed-width files, the exact widths.
The Field Mapping screen identifies and maps the important fields that the billing process relies on: when the usage occurred (Date Time), how much was used (Volume), and what kind of activity it was (Usage Types). These three mappings drive subscriber/plan/product resolution, rating, and invoice presentation.
| Field / Control | Description |
|---|---|
| Date Time | The input field that holds the date and time of the usage event. BillRun uses it during billing to find the subscriber, plan, and product revisions valid for that date and time, and it is also presented on the invoice. It can be the start or the answer date-time of a call. |
| Time in separate field | Check this when the input has separate date and time fields. The first dropdown maps the date field; once checked, a second dropdown becomes available to map the time field. BillRun concatenates both into a single date-time. |
| Volume | The input field holding the total amount of usage to be billed — duration (seconds), data volume (bytes), kg, km, distance, count, etc. The unit used here must be consistent through the whole configuration (products, includes, allowances). |
| Usage Types – Static | Use when the input contains only one type of activity type. Select Static and add a single activity name (e.g. call). If the activity does not yet exist in the system, type its name and press Add. |
| Usage Types – Dynamic | Use when the input contains several activity types, for example if both calls and sms can appear in the same input (on separate lines). the screen will expand to set the conditions to sort which CDR line is which activity type and also which field contains the volume of each activity type. |
| Add / Add Mapping | To add a new activity, type its name and press Add. After adding an activity, press Add Mapping before defining the next one — if Add Mapping is not pressed, the activity will not be saved when moving to the next stage. |
Map Date Time to the input field holding the event date-time. If date and time arrive in two separate fields, check “Time in separate field” and map both.
Map Volume to the field holding the billable quantity (duration, bytes, units, etc.).
Decide whether the source has one record type (Static) or several (Dynamic).
Static: add the single activity name (e.g. call) and continue.
Dynamic: select the input field that distinguishes record types (e.g. record_type), then map each Input Value to a Usage Type (e.g. value 01 → call, 02 → incoming_call, 08 → sms). Press Add Mapping after each one.
Note: Each usage type defined here generates its own section in the Customer Mapping, Rate Mapping, and Pricing screens — every activity must be told how to find its subscriber, its rate, and its charging method.
The Customer Mapping screen (the customer-identification part of the Calculator Mapping stage) tells BillRun how to identify the subscriber — and consequently the customer/account — from each input record. Every usage type defined in the Field Mapping step appears here, and each one must be mapped: the input field that holds the subscriber identifier is correlated to a predefined internal identification field.
Internally, the mapped value is resolved by the system to a subscriber ID (sid), which is connected to an account ID (aid). Because this value is a key in the billing system, the identifier on the input record must be unique per subscriber (e.g. MSISDN, IMSI, SIM ID, customer external ID).
| Field / Control | Description |
|---|---|
| Usage type sections | One identification section per usage type (activity) defined in Field Mapping. Each activity can use a different input field for identification. |
| Input field (source) | The CDR field that carries the subscriber's identifier for this activity. For example, for an outgoing call the calling number field (cid / source) identifies the subscriber, while for an incoming call the called number field (cld / destination) identifies the subscriber being billed. |
| Target identification field | The subscriber field in BillRun against which the input value is matched (a predefined internal value on the subscriber entity). The match resolves the record to a unique sid/aid. |
Activity call (regular outgoing call): the source field (cid) holds the unique subscriber identifier — the caller pays.
Activity incoming_call: the destination field (cld) holds the unique subscriber identifier — the receiving party is the system's subscriber.
For each usage type section, open the dropdown and select the input field that holds the subscriber identifier for that activity.
Select the subscriber field to match against (the internal identification value).
Repeat for every activity — no usage type may be left unmapped, otherwise its records cannot be assigned to a customer and will fail rating.
Note: The identifier must uniquely resolve to one subscriber at the record's date-time. Records whose identifier matches no active subscriber are not billed and are reported as unmatched lines — a common cause is a subscriber whose service started after the record's Date Time.
The Rate Mapping screen tells BillRun how to identify the product that will be used to charge each individual activity. For every usage type defined in the Field Mapping step, you build one or more conditions that match a value taken from the input record (a CDR field) against a parameter on the product. Internally, each condition becomes a filter that the rating engine applies when searching the Products collection for the line.
A usage type can use a single condition or a combination of several conditions that must all be satisfied, allowing precise matching (for example, longest-prefix on the destination number and an equality match on a service code).
It is also possible to set multiple alternative set of conditions as extra priorities, so if the first priority did not match to any Product the next priority will attempt to match to a Product that fits all of it's priorities.
If non of the priorities found a Product the CDR will not complete the processing and will not be priced. It will be saved in the queue collection and will attempt to map to a product again periodically (default is every 6 hours). If in the future a product will exist that fits the condition the CDR will continue the to the next processing calculator and eventually complete processing and be out of the queue.
Each condition maps a CDR field (the source) to a product parameter using one of four mapping functions. These correspond directly to the filter handlers in the rating engine:
| Mapping function | Matches when… | Typical use |
|---|---|---|
| Equal | The product parameter equals the value from the record (single value or one of a set of values). | Match a product by a key, code, service type, or record-type value. |
| Not equal | The product parameter does not equal the value from the record. | Exclude a specific value, or select the product that applies to "everything except" a given case. |
| Longest prefix | The product's prefix is the longest prefix that matches the start of the record value (best match wins). | Classic telecom destination rating — the dialled/called number is matched against product prefixes. |
| In range | The record value falls within a numeric/value range defined on the product. | Match to range type custom fields, usually used the time-based date function and other cases that a numeric value should be within a range |
Note: Product parameters are only Product custom fields that start with the prefix “params.” in the field key. For example “params.prefix”
The source of a condition does not have to be a literal field on the record — it can be a time-based field derived from the record's date-time. BillRun computes these values from the event time and matches them against the product parameter, which lets you charge differently by when the activity occurred (for example, peak vs. off-peak, weekday vs. weekend, or a specific day of the month).
The available time-based source values are:
| Time-based field | Meaning | Format produced |
|---|---|---|
| Minute of hour | Minute within the hour | 00–59 (leading zeros) |
| Hour of day | Hour within the day | 00–23 (leading zeros) |
| Time of day | Hour and minute together | HHMM |
| Day of week | Day of the week | 1 (Monday) – 7 (Sunday) |
| Day of month | Day within the month | 01–31 (leading zeros) |
| Month of year | Month within the year | 01–12 (leading zeros) |
| Month and day | Month and day combined | MMDD |
A time-based source is combined with any of the four mapping functions. For example, Hour of day with In range can match a "night rate" product for hours 22–06, while Day of week with Equal to 6 and 7 can route weekend traffic to a weekend product.
When the value needed for matching is not present directly on the record, a condition's source can be a computed field — a value derived from the CDR fields at rating time. The result of the computation is then matched against the product parameter using the selected mapping function. Computed fields are configured through the Computed Rate Key dialog, which offers two computation types:
The computed value is the result of applying a regular expression to a chosen field. Use this to extract or normalize part of a field (for example, strip a prefix, or pull a segment out of a longer identifier) before matching.
The computed value is determined by evaluating a condition and then returning one value when the condition is true and another when it is false. The dialog exposes:
| Field / Control | Description |
|---|---|
| First Field | The first operand of the condition — a CDR field. Its own Regex checkbox lets you apply a regular expression to the field's value before evaluation. |
| Operator | The comparison applied between the operands — for example Exists, equals, and similar operators. With operators such as Exists, the second operand is not required. |
| Second Field | The second operand of the condition (when the operator needs one) — another CDR field, with its own optional Regex. |
| Must met? | When checked, the condition is mandatory: if it is not met, the filter cannot handle the line (no value is produced for this condition, so the product will not match on it). |
| Value when True | The value the computed field returns when the condition is met. It can be a Hard coded literal, a field value, or a regex-extracted value. |
| Value when False | The value returned when the condition is not met. It can be the Condition result itself, a hard-coded value, a field, or a regex-extracted value. |
The Pricing screen (Pre-Pricing) is an optional step, relevant only for pre-priced CDRs — records that already arrive with their price on them. When Pre priced is checked for a usage type, the price is taken directly from the selected field on the record instead of being calculated by BillRun's rating engine.
If no pre-pricing is configured, simply press Next — lines for that usage type will be priced normally by BillRun, based on the matched product and the subscriber's plan.
The screen shows one section per usage type defined in the Field Mapping step (e.g. sms, mms), so pre-pricing can be enabled for some activities and not for others.
| Field / Control | Description |
|---|---|
| Pre priced (checkbox) | Enables pre-pricing for this usage type. When checked, the price of each record is taken directly from the record instead of being calculated. Checking it enables the price field selection. |
| Select price field | The CDR field (from the structure defined in CDR Fields) that contains the price of the record. |
| Multiply by constant | Optional. When checked, the value taken from the price field is multiplied by the entered constant — useful for unit conversions (e.g. the field holds the price in cents, or per-unit prices that must be scaled). |
| Tax is included | Indicates that the price arriving on the record already includes tax, so BillRun will not add tax on top of it during billing. |
Note: Pre-pricing bypasses the product's pricing steps for the charge amount, but the record still goes through customer identification and rate mapping — a product must still be matched for the line to be processed and reported correctly.
The final wizard step depends on the processor type chosen at initialization: file-based processors configure the Receiver (how input files reach BillRun), while API-based processors configure the Realtime Mapping (how realtime HTTP requests are interpreted).
The Receiver defines where and how BillRun collects the input files for this processor. BillRun's receive process runs periodically (via cron) and pulls new files from the configured remote location into the system for processing.
| Field / Control | Description |
|---|---|
| Connection type | The protocol used to collect the files — typically FTP, SFTP or SSH (SCP). The available fields adjust to the selected type. |
| Host | Hostname or IP address of the remote server from which files are pulled. |
| Port | Connection port (e.g. 21 for FTP, 22 for SFTP/SSH); usually pre-filled with the protocol default. |
| User | Username for authenticating against the remote server. |
| Password / Key | Password authentication, or a private key for SFTP/SSH key-based authentication, depending on the connection type. |
| Remote directory (path) | The directory on the remote server where the input files are placed and from which BillRun collects them. |
| File name pattern (regex) | A pattern/regular expression matching the names of files that belong to this processor — only matching files are pulled. This prevents one processor from consuming another processor's files when several feeds share a directory. |
| Post-receive behavior | Options controlling what happens after a successful pull — e.g. whether the file is deleted from (or marked as read on) the remote server, so the same file is not received twice. |
Received files are checked in (logged) by the system; each processed line keeps its source File name, which is visible in usage reports and useful for reconciliation.
The receive job is executed by the system scheduler (cron). If files are not being pulled, verify that the receive cron is running, that connectivity/credentials are valid, and that the file name pattern actually matches the files in the remote directory.
After receiving, files go through the processing chain automatically: parse (per CDR Fields), customer identification, rate identification, and pricing, as configured in the previous screens.
Realtime events are triggered by sending an HTTP request to: http://[HOST]/realtime?file_type=[INPUT_PROCESSOR_NAME]&request=[REQUEST_JSON_DATA], where the processor name is the Name configured in the CDR Fields step and the request JSON contains the fields configured for the processor. The Realtime Mapping screen defines how these requests are interpreted.
The realtime transaction announces that an activity has just ended and supplies the information needed to charge it. No allowance is requested — the entire activity is managed by the client and reported after the fact. In this mode most fields on the screen are disabled, except:
| Field / Control | Description |
|---|---|
| Request type pretend field | If a field is chosen here and its value on the request is “true”, the transaction is treated as a trial/test/check (e.g. checking service availability) and is not charged. |