Allegro FAQ

How Is Service Type Linkage Managed?

If a client or business unit (BU) does not use the service-type concept, set the system property to DEFAULT as the service type. If a client or BU has only one service type, set it as the default.

The following explains service-type association throughout the system:

• Source platform—one key attribute for a source platform is service type. A source platform can provide usage records for multiple service types. Ingested usage records link to a specific service type, and Aria Allegro requires this configuration for each service type.
• Mapping configuration—set per source platform and service type. This links usage records to the service type. By the time files load and usage records proceed to mediation, the service-type association is established, and raw usage data includes this association.
• Usage processing stream—the tailored rating engine is configured per usage source and service type.
• Billable services—each service defined in core Aria for catalog management maps to a service type. This prevents reuse of the same service across service types and ensures better separation.
• Plan services—when services are added to a plan, service-type association occurs automatically via Billable service mapping. When Aria Allegro creates a shell price offer for each plan, plan rate schedule, and plan service (with Aria Allegro pricing), each price offer also associates with the service type.
• Plan instance—when a plan instance is added to an account or subscription, the plan services and their service-type associations create a service unit for each unique service type.
• Service ID—a service ID (client plan instance ID, provisioning ID, or fulfillment ID) links to the service unit object. This links raw usage to the service unit, subscription, and account.
• Monetized usage record—a transaction unit in Aria Allegro maintains service-type association through references to service ID, service unit ID, billable service, and usage type.

All configurations and setups establish the service-type linkage.

Why Does a File Fail to Upload or Process?

Aria Allegro uses AWS S3 to store, process, and manage files. The Apache NiFi process checks the input file folders for each usage source platform, service type, and usage record type. AWS S3 folders are created automatically when the source platform is configured.

Possible causes of file upload failures include:

• The Aria Allegro deployment region and the AWS S3 region differ. AWS typically resolves this within 12–24 hours as it synchronizes folders across regions. If the issue persists, contact DevOps to align the AWS S3 folder region with the Aria Allegro deployment.
• Apache NiFi cannot read from or write to the configured AWS S3 folders. Contact DevOps to ensure correct permissions are set. Configuring a new usage source platform without correct permissions produces similar errors. Mismatched AWS S3 and Aria Allegro deployment regions can also prevent Apache NiFi from accessing mediation folders; ensure the regions match.

These errors occur most often during new deployments or subsequent releases and hotfixes and typically resolve after a few deployments.

Why Does a File Show Zero Counts in the UI?

If a file appears in the Usage Data section of Usage Operations and shows zero counts for all phases when expanded, the source platform configuration and mapping configuration are valid. However, the file does not conform to the mapping configuration.

Check the following in the usage file:

• The number of fields in the usage file must exactly match the mapping configuration.
• The delimiter used in the usage file must exactly match the delimiter in the mapping configuration for that record.
• Attribute values in the usage file must conform to the data types configured in the mapping configuration.
• The default date and time format is yyyy-mm-dd HH:MM:SS; the time component is optional. You can normalize date formats using mediation rules. Opening a TXT or CSV file in Excel can change the date format to the Excel default. Open and edit the usage file in Notepad or another plain-text editor to avoid format changes.
• Column header record is present. Aria Allegro expects the file to exclude the column header row. If a column header row that conforms to the data types in the file mapping configuration is present, it may load as a usage record, which will fail and add noise to the data.
• File delimiter. Aria Allegro adds attributes to the file mapping to track raw usage record status and reference details such as file name, ID, and creation date. In R67 and R68, these fields use a comma delimiter. Using a different delimiter in the mapping causes raw data load failures. This fix was backported to R68 as a hotfix and is included in R69 and later releases.

To resolve, correct the usage data in the file, rename the file, and upload it again.

Does Aria Allegro Support Pooling or Sharing?

Yes. Core Aria supports pooling within a Master Plan Instance Hierarchy. Aria Allegro creates a separate subscription and balance group for each Master Plan instance. The hierarchy can include any number of Add-On or Supplemental plans for pooling. Supported pooling scenarios include:

1. Sharing one or more allowances with any subset of usage types in a Master Plan Instance Hierarchy—add the necessary allowances to the price offers for the usage type.
2. Usage tier across usage types in a Master Plan Instance Hierarchy—add the necessary accumulators to the price offers and use the Accumulator balance-based Tiered pricing model. Each usage type can have different tier rates but uses the accumulated value to determine tiers.
3. Shared commitment across usage types in a Master Plan Instance Hierarchy—each commitment uses two accumulators: one with the recurring service to hold the static commitment value, and one with the usage service price offers to accumulate usage toward commitment. Add the usage-service accumulator to the respective usage-type price offers.

Does Aria Allegro Support Customized Rates?

Key points to understand customized rates for end-customer contracts:

• For all Aria clients, the external CRM application or core Aria acts as the Product Catalog master.
• Aria Allegro monetization models are not part of the Product Catalog.
• Aria Allegro APIs create Aria Allegro catalog components.
• Because Allegro models are not part of the Product Catalog, customized rates for those models are not supported. Unified Catalog Management—combining core Aria and Aria Allegro models—is a planned roadmap item requiring changes in core Aria.
• Core Aria supports customized tier rates for each usage type.
• R68 and the R67 hotfix support core Aria customized tier rates for each usage type. This works when the corresponding price offer in Aria Allegro uses the TIERED pricing model only. The pricing model can also use allowances and accumulators. The feature covers:
  • Customized tiers and rates for usage services.
  • Customized rates for recurring services that map one-to-one to an allowance or accumulator. For example, a $10,000 minimum commitment requires an accumulator or allowance value of 10,000 for the account. Rates can vary across plan instances and accounts.

To enable this feature:

1. Do not set Advanced Usage Pricing in core Aria.
2. Enable the property in Aria Allegro under Configurations > System Properties > Usage Processing for Customized rates.

Does Aria Allegro Support XML Files for Usage Ingestion?

Yes. XML files are supported with minimal pre-work by writing an XML parser or using Apache NiFi with additional setup for XML. The goal is to convert the XML file to CSV format so raw usage data can be searched and reported easily.

Does Aria Allegro Support an API for Usage Ingestion?

Starting with Aria R70, Aria Allegro supports an API similar to the core Aria bulk_records_usage_m API.

What File Transfer Mechanisms Are Supported?

Each client requires a one-time setup for file transfer. Supported options include:

• Allegro pulls from client S3—Allegro pulls files from one or more client S3 sources. The client provides access and authorization; the DevOps team assists with setup.
• Client pushes to Allegro S3—the client pushes files to the Allegro deployment S3. Aria DevOps provides access and authorization for file transfer.
• S3-to-S3 transfer—Aria DevOps sets up a link between the client S3 and the Allegro deployment S3 for file transfer.
• Other protocols (such as SFTP)—Aria DevOps or the client provides access and authorization; DevOps assists with setup.

Does Aria Allegro Provide a Running View of Balances?

This depends on the resource configuration for currency, allowance, and accumulator. Key points:

• Aria Allegro creates a subscription object for each Master Plan Instance hierarchy.
• A balance group is created for each subscription.
• Price offers include currency, accumulator, and allowance resources as needed.
• Usage records update resource impacts in the balance group when rated.
• Currency impact in Aria Allegro is not relevant because the balance does not reset with accounts receivable (AR) activity in core Aria. To view the account currency balance for a period, use Monetized Usage Summary in the Account section.
• For each allowance and accumulator, a balance bucket is created with a validity period (for example, allowance or accumulator for January, February, and so on). Check the corresponding buckets in the balance group for the running balance.

How Does Aria Allegro Manage Start and End Dates?

Start and end dates apply in Aria Allegro for many objects and scenarios, including:

• Start and end date of a billing cycle
• Start and end date of an accounting cycle for a multi-month billing cycle
• Start and end date of a recurring charge cycle
• Start and end date of the applied recurring charge within a recurring cycle
• Start and end date of raw usage records for voice call duration or other session-based usage records
• Start and end date for a plan instance (price unit)
• Validity period (start and end dates) for each allowance and accumulator bucket
• Indirect start and end dates with two versions of any object and their effective dates

Aria Allegro applies the same rule to all start and end dates. For a billing cycle with an anniversary date of 1, the following rules apply:

• Start date/time is inclusive—evaluated as >= Start Date 00:00:00. For example, the input date is evaluated as >= “2025-01-01 00:00:00”.
• End date/time is exclusive—evaluated as < End Date 00:00:00. For example, the input date is evaluated as < “2025-02-01 00:00:00”.
• Where applicable, no end date or a NULL end date means the object never ends.

How Does Aria Allegro Manage Tier Ranges?

Aria Allegro treats tier evaluation as a decimal value, making tier ranges continuous. For example: Tier 1 is 0 to 100, Tier 2 is 100 to 1,000, and Tier 3 is 1,000 to 0 or null (infinity). The following rules apply:

• Start of the tier range is inclusive—for example, >= 100 for the second tier.
• End of the tier range is exclusive—for example, < 1,000 for the second tier.
• The first tier always starts at 0.
• The last tier’s end range must be 0 or NULL to indicate infinity. This prevents unrated usage beyond the maximum set value.

If the tier reference is a decimal value, a decimal value may fall between two core Aria tier ranges. Decimal tier references are processed correctly against the tier reference.

How Does Aria Allegro Manage Rounding and Decimal Places?

Rounding rules and decimal precision are managed as follows:

• Pricing rates are configurable to any decimal precision.
• Usage quantity can be passed or evaluated to any decimal precision.
• Other decimal values in various configurations support any decimal precision.
• The blended rate calculation for monetized usage aggregation also supports any decimal precision.
• When rating results apply to gross or net amounts for currency, allowance, or accumulator, the resource configuration controls the rounding method and decimal precision. Values in monetized usage records and subscription balance groups are applied and aggregated accordingly when sent to core Aria.
• Rate Unit model configuration includes a Scaled Quantity checkbox. If the rate unit calculates quantity as a decimal, this rounds it up to the next integer (for example, 42.158 rounds to 43).
• Aviator mediation rules support additional rounding options for other usage record attributes.

Does Aria Allegro Support Volume Rating?

Yes. Volume rating (also called 2-pass rating) applies a fixed tier rate to all usage. In Aria Allegro, this is detailed in Monetization Models under the Prospective Tier model.

• A price offer can enable volume rating for all customers.
• If some accounts require volume rating and others do not, configure two sets of plans and manage account associations accordingly.

Is Jobs Management Required for Usage Files?

Jobs management is not required for usage files. No job adds usage files to a job schedule.

The Allegro S3 root node sets automatically during deployment. Each client receives a folder under the S3 root node. Adding source platforms for usage sources creates corresponding mediation folders under the client node.

If clients do not have direct access to Allegro S3 folders due to Aria security policy or other restrictions, DevOps sets up SFTP push/pull and file movement to Allegro S3 folders. Alternatively, DevOps can set up S3-to-S3 transfers to make files available in Allegro S3 folders.

If files land in S3, set the source platform file configuration frequency to ON-DEMAND. As files arrive in the source platform’s usage folder in Allegro S3, Apache NiFi picks them up automatically. If SFTP push/pull is set up, other file frequencies apply. SFTP scripts use the source platform frequency to find or pull files from client SFTP folders and then copy them to Allegro S3 folders for processing. An additional cron job or equivalent can be set up for file frequencies with SFTP setup.

What Is Jobs Management Used For?

Core Aria runs batch jobs for invoicing, statement generation, payments, dunning, and more. Aria Allegro manages equivalent processes via job management.

Allegro allows you to create one or more job schedules per client—for example, daily, month-end, quarter-end, and year-end schedules. Because clients may have multiple anniversary dates across up to 31 billing days, the Allegro daily batch job schedule runs each day.

A job schedule configuration adds jobs to the schedule, and each day’s execution adds work items for each job. For example, if billing runs for 50,000 accounts, 50,000 work items are added for that day’s execution. Common jobs in Allegro job schedules include:

• Billing job—provides recurring allowances or accumulators (for example, recurring minimum commitment) for customers billed that day. Also handles term-end event triggers such as minimum commitment true-ups when actual usage falls below the commitment.
• Bill-time usage—for accounts on their anniversary date that require 2-pass rating, the job schedule execution adds work items and executes the second pass to apply uniform tier pricing.
• Sync job—synchronizes pending or error records to core Aria, including monetized usage (via the bulk_usage_m API) and term-end event triggers (via the create_order_m API with a no-service order (NSO)).

Starting with R68, batch job dependencies between core Aria and Aria Allegro are supported. As a pre-process, core Aria calls an API to run the job schedule in Aria Allegro. If the schedule is already complete, it returns success; otherwise, it executes the schedule. Core Aria then periodically checks the schedule status until completion or error. Once complete, core Aria triggers its daily batch jobs, ensuring all Allegro dependencies are met before invoicing and other tasks run.

Can You Modify the File Mapping After Usage Has Been Processed?

You can modify the file mapping configuration only if no usage has been loaded. If usage data exists, Aria Allegro blocks modifications.

The mapping configuration creates a database table to store raw usage records. If usage data exists, Aria Allegro cannot process the modification because it cannot determine how to handle existing raw usage data.

To modify the mapping, use Copy-To-Create to make a new file mapping with your edits and begin using the new mapping. You can inactivate the previous mapping. Contact DevOps to purge the old file mapping if you decide to discard the earlier raw usage data.

How Should You Set Up a Plan for Minimum Commitment?

Aria Allegro requires a recurring service to determine the commitment value. Whether the service carries a charge or a discounted charge does not affect the commitment value; it comes from the plan instance association. If an account lacks a recurring service or the commitment value is zero, this indicates no customer commitment.

Each commitment uses two accumulators. Usage service price offers must include the counter accumulator for the commitment. If the recurring service provides a commitment value but usage price offers lack the accumulator, the billing trigger for true-up applies the full commitment as a true-up, reflecting no usage that month. Allegro’s true-up is managed via NSO setup to synchronize each true-up with core Aria for invoicing.

Each commitment setup includes:

• Two accumulators: one for the commitment and one for the counter
• A service and an NSO for the true-up (the commitment can be shared across usage types)
• A recurring service and related price offer for the commitment value (dollar or quantity) with the commitment accumulator
• Usage service(s) with the counter accumulator

Aria Allegro supports both dollar commitment and unit commitment values. The accumulator setup controls whether the accumulator tracks quantity or amount.

For minimum commitment true-up, note the following:

• If the true-up is for a monetary commitment, Allegro calculates the monetary shortfall to true up automatically.
• If the true-up is for a unit commitment:
  • Allegro allows multiple usage types from a Master Plan Instance (MPI) vertical to participate in the same commitment value.
  • Each usage type participating in the commitment can have independent rates.
  • If a shortfall exists, Allegro applies the true-up using the unit price from the NSO service price offer for the true-up units.

What Should You Keep in Mind for Requirements and Use Cases?

From a catalog setup perspective, define two key points before configuration:

1. How the client expects to sell the service or plan
2. How the client wants to present lines or details on the invoice

These points determine the approach and use-case setup, prevent terminology confusion, and ensure consistent understanding across teams.

From an account perspective with MPI and Supplemental Plan Instance (SPI), determine:

1. Which elements vary between accounts for the same plan, including:
   • Contract price differences
   • Eligibility differences for key capabilities
   • Other account-specific details
2. What the standard or default contract pricing should be

Do You Always Need to Enable Advanced Usage Pricing?

See Does Aria Allegro Support Customized Rates? for details on customized rates.

• If you do not require account-specific customized rates, enable Advanced Usage Pricing.
• To manage customized contract rates, do not enable the Advanced Usage Flag for the plan. Instead, enable the property in Aria Allegro under System Properties > Usage Processing for Customized rates.

How Do You Manage Account-Specific Eligibility for Commitment?

Account-specific eligibility controls which usage services in the plan qualify for commitment per account. Two accounts on the same plan can have different eligible usage service subsets.

In core Aria:

1. Add a Boolean custom field at the plan instance level to manage account-specific eligibility for the plan’s usage services. Aria Allegro defaults this to eligible, which is the common assumption. If the account is not eligible, set the field value to false.
2. Ensure APIs that manage the plan instance—such as create_order_m—reflect this field’s eligibility status for the account’s commitment.

In Aria Allegro:

1. Set the system property skipCommitmentFieldName under Configurations > System Properties > Subscriptions to the supplemental field name added above.
2. When updating the plan instance for commitment enablement and synchronizing with Aria Allegro, the supplemental field value appears in the Skip Commitment field of the corresponding price units.
3. If skipCommitment is enabled, the Allegro rating engine skips accumulation for the commitment accumulator for the corresponding price offer.

How Does Aria Allegro Determine What to Aggregate and When?

Aggregate for Billing (or Synchronize Allegro monetized records for usage or true-up) synchronizes monetized records from Aria Allegro to core Aria.

One of the following activities triggers the synchronization of monetized records:

1. You trigger the sync for monetized usage records manually via the Allegro UI at Usage > Usage Activity > Usage Data using the Aggregate for Billing tab.
2. You run the job schedule via the Allegro UI for days with aggregated records pending synchronization. The two jobs involved are:
   • Billing Sync job—triggers remaining usage records not yet synchronized for the day.
   • Billing job—determines whether a true-up applies for minimum commitment. If required, it applies the true-up and sends it to core Aria via the NSO framework.
3. Starting with R69, running the billing job in core Aria triggers job schedule execution in Aria Allegro. The same jobs as in option 2 handle synchronization.
4. In production or similar setups, the Allegro scheduler (for example, a cron job) runs the job schedule on time, resulting in execution as described in option 2.

The following monetized records synchronize from Aria Allegro to core Aria:

• Monetized usage records—these records can aggregate usage before synchronization, controlled by the Aggregate for Billing configuration. Aggregated or individual monetized usage records are sent to core Aria using the bulk_usage_m API.
• Monetized non-usage records—currently limited to minimum commitment true-ups applied in Aria Allegro when usage falls below commitment. These synchronize via the NSO service using the create_order_m API with the true-up amount.

Aria Allegro determines monetized record synchronization as follows:

• The minimum commitment true-up always triggers via the billing job; no additional configuration is required.
• When running daily job schedules (or a scheduled sync frequency) in production, records are picked up automatically.
• For test or demo phases using manual Allegro UI options:
  • Allegro uses the created date of the monetized usage record, not the start or end date of the raw usage record. For test setups, this date may be the current date or a virtual date if enabled.
  • Aggregate for Billing requires a Start date and End date as input. It selects records where START DATE (input) ≤ CREATED DATE < END DATE (input). For example, to select records created on February 15, set Start date to February 15 or earlier and End date to February 16 or later. This range can include multiple days.
  • Aggregation targets usage records with PENDING status (not yet sent) or ERROR status (previous send attempts failed).

To reprocess sync errors, go to Usage > Usage Data > Billing Sync Reprocess > Aggregated Usage.

How Does Aria Allegro Authenticate and Enable the UI?

Aria Allegro relies on the core Aria framework for authentication and authorization. The following steps complete user authorization for a new Allegro UI session:

1. User login—when the user provides a user ID and password, Aria Allegro uses the Key Cloak shared services for the deployment to authenticate the user. If the user has an active session with a core Aria UI, the client of reference from the latest session becomes the default.
2. Core Aria API calls—Allegro calls the core Aria API to retrieve:
   • User permissions and role—core Aria configurations map to Aria Allegro permissions for each role type. A static mapping in Aria Allegro determines all user permissions upon retrieval. The permission map auto-inserts for new deployments when a client is added or when additional clients join the deployment.
   • User client list—Allegro calls the core Aria API to obtain the list of clients accessible to the user in the deployment. Not all clients are enabled for Allegro by default. The core Aria API supports pagination; if the user accesses more than 50 clients, it fetches all clients. This list is matched against clients enabled in Aria Allegro for usage processing, allowing the user to select and switch clients in the Allegro UI.
3. Session management—the session management framework matches that of core Aria UI. Initial sessions last 15 minutes and can renew for additional 15-minute intervals. Sessions time out after inactivity.
4. Allegro UI tokens—the Allegro UI uses tokens to authorize API calls to Aria Allegro services. Tokens remain active for two minutes. The Allegro UI automatically fetches new tokens as needed.

Common issues that require DevOps support include:

• For new deployments, shared services parameters may be misconfigured for Allegro microservices, preventing user authentication.
• If no client is enabled for the Allegro deployment, the user may be authorized but see a blank screen due to no matching clients.
• A new client not added cleanly in the Allegro deployment may cause partial screen access and missing permissions.

When Do Recurring Transactions Happen in Aria Allegro?

Recurring transactions in Aria Allegro manage allowances or accumulators linked to plans and plan rate schedules with recurring services.

Aria Allegro makes allowances and accumulators instantly available after a service activates, supporting real-time receipt of usage records from network elements or post-processing.

Allegro triggers recurring transactions in two ways:

1. Immediately after a plan instance with a recurring service is added and synchronized via Data Feed to Aria Allegro, a forward recurring charge applies.
2. The Allegro Billing job triggers recurring allowances and accumulators for the next billing cycle.

For both triggers, check the Monetized non-usage tab for the account with type FORWARD_RECURRING immediately after plan purchase or billing trigger. Rate changes or customized rate switches apply to future monetized non-usage records.

How Do Usage Records and Price Offer Versions Interact?

A price offer is created for a unique combination of core Aria plan, plan rate schedule, and service—equivalent to defining rates for a service in core Aria, but in Aria Allegro. Allegro allows multiple versions of a price offer, for example, to set a price change with a future effective date. Allegro also supports the core Aria "one future rate with a future date" model within a price offer. You can perform an inline modification on any price offer version.

Each price offer version has an associated effective date. When a usage record is rated, the Allegro rating engine’s Price Offer Analysis module fetches the price offer version valid for that usage record.

For example, consider three versions of a price offer:

• Version 1: Effective date January 1, 2026
• Version 2: Effective date March 15, 2026
• Version 3: Effective date January 1, 2027

The following rules apply:

• A usage record dated March 10, 2026, uses Version 1.
• A usage record dated March 20, 2026, uses Version 2.
• A usage record dated March 15, 2026, uses Version 2—the usage date/time is greater than or equal to the effective date/time of the version.

How Are Numbers and Client-Defined IDs Managed for Usage Type and Plan Instance?

Aria Allegro defines a service type (for example, Voice Data or SMS). Billable services in Allegro (Aria services) link to a configured service type. When a plan with these services is purchased, Allegro creates a service unit for each service type under a subscription. The service unit object stores provisioning data for mobile numbers (Telco), meters (Utilities), devices (Internet of Things (IoT)), set-top boxes (Cable), modems and routers (High-speed internet), and more. Allegro can store multiple identifiers per service unit.

By default, each SPI’s provisioning data stores the following from core Aria:

• Client-defined plan instance ID of the SPI
• Plan instance number of the SPI
• Client-defined plan instance ID of the corresponding MPI
• Plan instance number of the corresponding MPI

Usage records can use any of these attributes to identify the correct account and subscription.

Allegro stores both the usage type number and the client-defined ID. Either field can be used during file mapping in mediation setup. This allows price-unit analysis to find the correct price unit and offer for rating by searching for the usage type number or its client-defined ID.

Why Do Catalog Sync Messages Appear in HOLD Status?

The Aria Allegro sync service synchronizes catalog data from core Aria to Aria Allegro. Data feed messages from core Aria can arrive with a status of HOLD. Aria Allegro cannot process messages of this type.

HOLD status typically occurs when duplicate objects exist in the core Aria environment, causing the data feed to return multiple objects instead of one. One example is duplicate Chart of Accounts entries in an environment. Other objects may also have duplicates; investigate the root cause on the core Aria side to determine the duplicate object.