Usage Suspense Management
When the usage processing (rating) engine processes usage records, some may error out. These records are genuine and ready for monetization, having passed mapping, mediation rules, and more. Records in error are called Suspended usage because processing suspends on error. The underlying issues must be resolved before reprocessing Suspended usage records. Allegro Usage Suspense Manager lets you view suspended usage details and reprocess records. To maintain the audit of what was sent from the source, Aria Allegro does not allow modifying the record to reprocess. For test or demo setups, or if the user expects a delta file for suspended usage records due to source data errors, Aria Allegro allows authorized users to discard suspended usage records. Maintaining the audit trail and reconciliation of each record through every processing phase is important.
Common Reasons for Usage Suspense
Most of the common reasons for usage suspense are wrong account setup, timing of the usage record around service activation and service suspension/termination. Some of the specifics reasons are listed below:
- No Service found for the service (provisioning) id: Allegro received a usage record with a start and end date/time for which the service id is not linked to any service-type in any subscription. Possible reasons include
- Missing plan instance setup for the account—Add the plan instance with the service id in core Aria with an effective date on or before the usage record's start/end date. After the plan instance associates with the account and service type in Allegro, reprocess the suspended usage record.
- Plan instance has not synchronized from core Aria to Aria Allegro. Check and correct the following:
- It is just delayed—Wait until the Subscription view shows the plan instance for the account, then reprocess the suspended usage record.
- Sync process error on Aria Allegro side—Check the “Reprocess sync Errors” section for errors. If resolved and the Account sync error reprocess completes, proceed accordingly.
- Message not sent from core Aria or not consumed by Aria Allegro—This may occur during initial setup/deployment. The Data Feed architecture uses KAFKA topics for synchronization.
- If the producer configuration is disabled or incorrect on core Aria, coordinate with Aria to enable it and configure Kafka topics. Save the plan instance data again to send a record to the Kafka topic. After synchronization, reprocess the suspended usage record.
- If the consumer configuration is incorrect, Aria Allegro cannot consume from the Kafka topic. Work with Aria and Aria DevOps to set up the consumer side. Once complete, queued messages will be consumed automatically. Confirm via the account subscription view, then reprocess the suspended usage record.
- No Service active for the service (provisioning) id—Aria Allegro received a usage record with a start/end usage date/time linked to a service by service ID, but the service is not in an ACTIVE state for processing. This may result from timing of the service activation, suspension, inactivation, or cancellation or synchronization issues between the Fulfillment system, Aria Billing, and Aria Allegro. Options to clear the error are:
- If the CRM or Aria Allegro allows undoing the action, reprocess the suspended usage and redo the action to resolve the error, or
- Discard the usage, then create a delta usage file with the usage record date/time on or after the activation date (for activation) or before the inactivation/cancellation date (for suspend/cancel).
- Price offer not configured completely for the usage type—Aria Allegro requires standard pricing configured for each usage type when saving the plan, plan rate schedule, and plan services in core Aria. The pricing admin likely missed setting up the Allegro pricing model. Complete the pricing model setup for the usage type and reprocess the suspended usage record. You may need to create a price-plan audit with an effective date matching the usage record's start/end date and time.
- No Price unit found for the usage type—The reason and resolution process are the same as those covered under “No Service found for the service (provisioning) id”. Resolve the issue and reprocess the suspended usage record.
- Future Dated usage record—This should happen only in a test/demo setup where the virtual time is allowed to be enabled. You can set the Aria Allegro Virtual time in System Properties under configuration section to a future date and reprocess the suspended usage record.
- System error—Possible causes include:
- A temporary system error during scheduled maintenance. Wait and reprocess the suspended usage record.
- Database errors—Despite exception handling, these may occur. Work with your support team to get the micro-services or pod logs reviewed to identify and resolve the issue. The support team should be able to contact the Knowledge Central team to update resolution documentation. Resolution should be relatively quick.
- S/w error—Software cannot be entirely error-free. Collaborate with support to analyze and resolve the issue before reprocessing.
The following table provides a summary of error codes with usage suspense:
| Error Code | Why | Resolution |
|---|---|---|
| START_OR_END_DATE_MISSING_IN_USAGE_CONTAINER |
|
If the entire file contains errors, correct the file mapping. You may need to copy and create a new mapping, as Allegro allows modifying existing file mappings only when the corresponding raw table has no data. Then, discard the suspense and reload the file. If some records contain errors, obtain or create a delta corrected file from the source, discard the usage, and load the delta file |
| SERVICE_TYPE_MISSING_IN_USAGE_CONTAINER | This error should not occur anymore, you should get a different error | - |
| REC_INDICATOR_MISSING_IN_USAGE_CONTAINER | This error should not occur anymore, you should get a different error | - |
| MISSING_MANDATORY_ACCNT_ID_OR_PROV_ID | Either the file mapping does not have any field to guide the usage to account or is not set as a mandatory parameter | If the entire file contains errors, correct the file mapping. You may need to copy and create a new mapping, as Allegro allows modifying existing file mappings only when the corresponding raw table has no data. Then, discard the suspense and reload the file. |
| APPLICABLE_PRICE_ALLOWANCE_ACCUM_NOT_FOUND_IN_PO | The price-unit-analysis module in the rating engine found no price unit or price offer with currency, accumulator, or allowance impact. Therefore, it could not monetize anything | Review the plan instance data in Aria and the subscription view, focusing on price units or the related price offer to identify any missing elements. The issue may be a missing service in a plan with a received usage record or an unset price offer. Resolve the error and reprocess the suspended record. |
| NO_SERVICE_FOR_THE_PROVISIONING_ID | This is explained before the table for more clarity | |
| NO_ACTIVE_SERVICE_FOR_THE_PROVISIONING_ID | This is explained before the table for more clarity | |
| INVALID_USAGE_RECORD_INDICATOR | This applies if you set up file mapping for a file record structure (as in the Telecom vertical) with HEADER, DETAIL, sub-structures, and TRAILER records configured. However, the usage file does not conform to this | If the file mapping setup is incorrect, then adjust it for a new source platform or copy and rename to create if usage data exists. If the usage file is incorrect, report it to obtain and reload a new file. |
| NO_MATCHING_PRICE_UNIT_FOR_THE_SERVICE | For the service ID in the usage record, the rating engine found the service but no price unit was associated with the usage type. | Check if the usage-type setup is missing. If so, add the usage-type to the plan in Aria, set its pricing in Allegro, and add the plan instance delta to the account. Ensure the price-plan setup predates the usage records and the plan instance setup predates the usage record dates. The plan may be set up correctly, but the account plan instance might not be associated properly. Resolve the issue and reprocess suspended usage records. |
| TIER_PRICING_NOT_FOUND | Aria tiered custom rates apply to the usage type. However, the price plan is not configured for tiered usage rating. Aria custom tiered rates work only with the tiered pricing mode. | Modify the price-offer with appropriate tiered pricing, save it and then reprocess the suspended usage record. |
| TIER_EVALUATION_FAILED | Tier evaluation has failed for the price offer during rating | Review the customized tier rates from Aria in the price unit to verify they match the tier pricing base setup in the Allegro price offer. Adjust the plan instance data or price-offer setup to align with usage dates when using audit to create a new version, then reprocess the suspended usage records. |
| NO_PRICE_OFFER_IN_DB_FOR_GIVEN_ID | This should only happen with database access (possible in a test/demo setup) where someone has removed the price offer. It is otherwise not possible | Restore the price offer for the id and reprocess the usage record. |
| NO_BILLING_PROFILE_IN_PRICE_UNIT | Allegro creates a billing profile to track the usage billing cycle. Each price unit for usage types references the billing profile. | This should occur only when using direct APIs in Allegro and data is not sourced from Aria Allegro. It is not recommended, as all account and subscription data should be mastered in core Aria and flow from core Aria to Allegro. Verify the setup in core Aria is correct, then reprocess the suspended records. |
| NO_BILLING_PROFILE_IN_DB_FOR_GIVEN_ID | This occurs only with database access (possible in test/demo setups) when someone removes the price offer. Otherwise, it is impossible. | -same-as-above |
| NO_BILL_UNIT_IN_BILLING_PROFILE | This should not occur. This would be a s/w bug. | Get the issue resolved and reprocess |
| NO_BILL_UNIT_IN_DB_FOR_GIVEN_ID | This should only happen with database access (possible in a test/demo setup) where someone has removed the price offer. It is otherwise not possible | Restore the price offer for the id and reprocess the usage record. |
| USAGE_TYPE_MISSING_IN_USAGE_CONTAINER | Usage type is a key attribute, either provided directly in the raw usage file or derived through mediation enrichment rules. The rating engine will reject the record if the usage type is missing, as it cannot determine the applicable pricing. | If the file lacks data, obtain the new file or a delta file for incorrect records. If the mediation rule should enrich and derive the usage type, configure and review the mediation rule setup. Resolve the issue and reprocess. |
| INVALID_USAGE_TYPE_OR_USAGE_TYPE_NO | Usage type received is invalid or a plan instance setup is missing the usage type | If the file lacks data, obtain the new file or a delta file for incorrect records. If the mediation rule should enrich and derive the usage type, configure and review the mediation rule setup. Resolve the issue and reprocess. |
| TRANSACTION_PRICING_NOT_FOUND | The price offer model uses transaction attribute-based pricing. However, the rating engine cannot find matching pricing for the time and zone model evaluation and usage record combination. | Fix the price plan setup and reprocess the suspended record. |
| COMPLEX_PRICING_NOT_FOUND | The price offer model uses composite pricing, but matching pricing for this model is unavailable. | Fix the price plan setup and reprocess the suspended record. |
| NO_MATCHING_PRICING_FOR_USAGE_RECORD | Missing setup for the usage record. The price-offer setup may be incomplete, or the account plan instance data may not cover the usage pricing for the record. | Fix the price plan setup and reprocess the suspended record. |
| MULTIPLE_PRICE_UNITS_RATING_NOT_ALLOWED | During rating, multiple price units may appear. The setup must select one price unit. Check the system property “Multi Price Unit Rating Behavior” to use the price unit that ends first; selection may be random if dates match or set to Suspend. | Determine if a multi-price unit setup is required, manage the property accordingly, ensure the plan configuration and plan-instance association align with the setup, then reprocess. |
| BILLING_NOT_RUN_FOR_PREVIOUS_CYCLE | Aria Allegro tracks the billing cycle to ensure allowances are available before processing usage records for the new cycle. | Check the job schedule configuration to confirm it includes the billing job, or verify the job schedule execution to identify if the billing job failed for this account. If it failed, resolve the issue, rerun the failed jobs, and reprocess the error. |
| MISSING_MANDATORY_CLIENT_ID | This occurs when adding a new client to an existing deployment | The setup may be incomplete. Resolve this with the deployment team, then reprocess. |
| PLSQL_EXCEPTION | explained in the section, before the table. | - |
View Usage Suspense Data
To view Usage Suspense data and details for a specific file with suspended usage records, follow these steps:
- Click the Usage switch (Usage/Account toggle) in the navigation pane.
- Click the Usage Activity option to expand its sub-menu in the navigation pane.
- Click the Usage Suspense menu option in the navigation pane.
- The system displays current or past files with at least one suspended usage record, showing one line per file.
This is shown in the following screenshot:
View Usage Suspense Details
To view Usage Suspense data for a file with suspended usage records, follow these steps:
- Navigate to the “View Usage Suspense Data” sub-section.
- Apply filters to locate your file.
- Expand the row in the table using the maximize icon on the left or click the File name link in the row to view details in a drawer.
- If using the maximize icon, the UI displays one line per suspense reason identified by the error code, showing:
- Status—set as Suspended
- Record count—number of records from the file that failed for the same reason.
- Error Code—an expandable text box with the error code for the suspense reason. Hover to see the full code.
- Error Message—an expandable text box with the error message. Hover to see the full message.
- Option to view individual records from the file that failed for the suspense reason.
- Options to reprocess or discard records for the suspense reason (covered separately).
- Quick info icon explains the reprocess action at that level.
- If using the File name link, the UI shows the same data as the maximize icon in a separate drawer.
- If using the maximize icon, the UI displays one line per suspense reason identified by the error code, showing:
- Click the View link in the ‘View Records’ header to display individual records from the file suspended for the specific suspense reason. This appears as a table in a separate drawer, showing attributes of the mapped Allegro Usage container record, including all raw attributes mapped via the File mapping configuration.
The following screenshots illustrate this:
Screenshot using the maximize icon:
Screenshot using the File name link option:
View transactions for suspense error code:
Reprocess Suspended Usage Records
Aria Allegro enables reprocessing of suspended usage records at three levels. Ensure the underlying suspense reason is resolved before reprocessing; otherwise, it will consume resources without clearing suspense. Refer to “Common reasons for usage suspense” for reasons and resolutions. Regular checks are advisable to maintain system integrity. The three levels supported for reprocessing suspended usage records are:
- Reprocess-All: Use the Reprocess-All button in the header bar to reprocess all usage records across all files for any reason. This suits temporary system errors or issues consistent across files when the resolution is in place.
- Reprocess-File: Use the Reprocess button at the individual file level. Use this when all errors for the file are resolved and ready for reprocessing.
- Reprocess-Error-Code: Use the Reprocess button at the error-code level within a file. Use this when the issue for a specific error code in the file is resolved.
Discard Suspended Usage Records
Only authorized users should be allowed to discard suspended usage record and if possible, only for a test/demo setup. You discard the suspended usage only if,
- There is a handshake and an agreement to ignore those records with the client and the business OR
- You know that there will be a corrected delta file provided for the discarded usage records.
Aria Allegro supports the discard usage suspense records at the following levels:
- Discard-File: Use the Discard button at the individual file level in the table. This will discard and remove all the suspended usage records for the file. Once successful, the data will auto-refresh to remove the line for the file. You can repeat this for other files.
- Discard-Error-code: Use the Discard button at the error code level for a given file. . This will discard and remove all the suspended usage records for that error code in the selected file. Once successful, the data will auto-refresh to remove the line for the file. You can repeat this for the other error code in the file, as required.
- Reprocess-Individual-Record: Use the View Transactions button in the drawer or the link in the maximize icon for the error code to see the individual records in a drawer. Identify the record that you want to discard. Click the Discard button with the record to discard the usage record. Once successful, the data will auto-refresh to remove the line for the record in the table. You can repeat this for the other records in the table.
Filter Attributes for the Usage Suspense Data
- File Name: Enter the partial or full file name to search using the naming convention. This is a case-insensitive partial match filter.
- Start date: Enter or select the start date to search suspended usage records. The start date is inclusive (≥ 00:00:00). This is a greater than or equal to filter.
- End date: Enter or select the end date to search suspended usage records. The end date is exclusive (< 00:00:00). This is a less than filter.
- Source Platform: Select the source platform from the drop-down list to search suspended usage data for that platform. This is an exact match filter.
- Service Type: Select the service type from the drop-down list to search suspended usage data for that service. This is an exact match filter.
- Error Code: Enter the error code to search suspended usage data for that code. This is a case-insensitive partial match filter.
Sort Attributes for the Suspended Usage Records
- Source Platform: Sort ascending or descending by source platform name.
- File Name: Sort ascending or descending by file name.
By default, the engine sorts by the latest files loaded.