Usage Collector Monitoring and Troubleshooting

Overview: Monitoring and Troubleshooting Usage Report Processing

To view usage report processing status, please see Managing Usage Data Import.

You can monitor and troubleshoot usage report processing in the following way:

Stage 1: Usage Data Import

Usage data is collected and imported to Usage Collector for processing in one of these ways:

For monitoring and troubleshooting:

  • Usage data delivered by VRD Collector:

    1. In the Provider Control Panel, go to Operations > Operations > Tasks > Periodic. Filter and inspect the Collect rated data and Transfer rated data to BSS Rating tasks. By default, each task is launched every 24 hours.
    2. Make sure that each task is scheduled (the task status is Rescheduled).
    3. Click the necessary task and inspect the task profile and logs. Troubleshoot as necessary.
    4. For errors in the imported data, contact the APS application owner or the vendor to correct the data on the APS application or vendor side:

  • Usage reports delivered from CloudBlue Connect:

    1. In the Provider Control Panel, go to Operations > Operations > Tasks > Periodic. Filter and inspect the CloudBlue Connect Extension <uuid> Connect Chunk Usage Files retrieval task. By default, the task is launched every 24 hours.
    2. Make sure that each task is scheduled (the task status is Rescheduled).
    3. Click the necessary task and inspect the task profile and logs. Troubleshoot as necessary. If there is an unidentified error, contact CloudBlue Connect Support.
    4. In the UX1 for Providers control panel, go to Usage Reports. The successfully imported usage reports are processed automatically. Reports that fail data validation (the Status value is Validation Failed) are rejected as a whole and are not processed by Rating Orchestrator.
    5. For a report that failed data validation, click ACTIONS, select Get error details, and save the error report file. For detailed information about errors and troubleshooting actions, please see Usage Report Import Troubleshooting.
    6. For data that has been rejected by Usage Collector (and has not reached the processing by Rating Orchestrator), contact the vendor to make the necessary corrections to the usage report on the CloudBlue Connect side or the vendor system side and resubmit the corrected report for processing using Batch Import API or File Import API.

  • Usage reports uploaded manually from the CloudBlue Commerce UX1 for Providers UI:

    1. In the UX1 for Providers control panel, go to Usage Reports. The successfully imported usage reports are processed automatically. Reports that fail data validation (the Status value is Validation Failed) are rejected as a whole and are not processed by Rating Orchestrator.
    2. For reports that fail data validation:
      • Runtime errors are displayed in the UI. For troubleshooting, please see Runtime exception (ErrorCode 500).
      • Other validation errors can be obtained from the error report: For a report that failed data validation, click ACTIONS, select Get error details, and save the error report file. For detailed information about errors and troubleshooting actions, please see Usage Report Import Troubleshooting.
    3. For data that has been rejected by Usage Collector (and has not reached the processing by Rating Orchestrator), make the necessary corrections to the usage report and resubmit it manually.

  • Usage data delivered to Usage Collector from vendor systems using Batch Import API:

    1. In the UX1 for Providers control panel, go to Usage Reports. The successfully imported usage reports are processed automatically. Reports that fail data validation (the Status value is Validation Failed) are rejected as a whole and are not processed by Rating Orchestrator.
    2. For a report that failed data validation, click ACTIONS, select Get error details, and save the error report file. For detailed information about errors and troubleshooting actions, please see Usage Report Import Troubleshooting.
    3. For errors in the imported data, contact the vendor to make the necessary corrections:

  • Usage data delivered to Usage Collector from vendor systems using File Import API:

    1. In the UX1 for Providers control panel, go to Usage Reports. The successfully imported usage reports are processed automatically. Reports that fail data validation (the Status value is Validation Failed) are rejected as a whole and are not processed by Rating Orchestrator.
    2. For a report that failed data validation, click ACTIONS, select Get error details, and save the error report file. For detailed information about errors and troubleshooting actions, please see Usage Report Import Troubleshooting.
    3. For data that has been rejected by Usage Collector (and has not reached the processing by Rating Orchestrator), contact the vendor to make the necessary corrections and resubmit the usage report to Usage Collector using File Import API.

Other troubleshooting scenarios:

Stage 2: Usage Data Processing by Rating Orchestrator

Rating Orchestrator processes usage reports that have been successfully imported by Usage Collector. Using the Rating Orchestrator <uuid> schedule periodic task, Rating Orchestrator:

  • Requests successfully imported usage reports from Usage Collector.
  • Sends usage reports to Rating Engine processing.
  • Identifies subscriptions with non-zero usage.

  • For usage reports with TR, PR, and CR models, requests Order Management to immediately create a billing order.

    Note: For usage reports with QT schema, billing orders are created by the Daily Billing Process.

For monitoring and troubleshooting:

  1. In the Provider Control Panel, go to Operations > Operations > Tasks > Periodic. Search the Rating Orchestrator <uuid> schedule. By default, each task is launched every thirty minutes.
  2. Make sure that each task is scheduled (the task status is Rescheduled).

  3. In the UX1 for Providers control panel, go to Usage Reports. For a report that failed data validation, click ACTIONS, select Get error details, and save the error report file. For detailed information about errors and troubleshooting actions, please see Troubleshooting the Usage Report File Processing.

Other troubleshooting scenarios:

Stage 3: Usage Data Processing by the Daily Billing Process (BSS)

Important: This stage is relevant only for usage reports with the QT model.

After a usage report with the QT model is processed by Rating Orchestrator without errors, the Daily Billing Process creates billing orders:

  • For subscriptions that are not canceled or terminated, on the next billing date.
  • For subscriptions that have been canceled or terminated, during the immediately following Daily Billing Process execution.

If a billing order is not created when expected, please submit a ticket to CloudBlue Commerce Support.

Stage 4: Usage Data Processing by Order Management

When a billing order is created for a subscription from a usage report, Order Management requests order details (including usage) for the subscription from Rating Engine. Then Order Management pushes the order through the standard order flow (applies loyalty points, taxes, and so on).

For help with billing order processing errors, please submit a ticket to CloudBlue Commerce Support.

Other troubleshooting scenarios:

Typical Troubleshooting Scenarios

This section contains typical error scenarios that may occur during usage data import and processing.

Symptoms Troubleshooting
Main Procedure Options Following Actions
1

A usage report was imported but its rating failed (the usage report status is Rating Failed)

Download error details, fix the errors, and re-run the usage report processing.

If you cannot fix the error, issue a ticket.

    
2

A usage report was rated but billing order placement failed (the usage report status is Billing Failed)

Download error details, fix the errors, and re-run the usage report processing.

If you cannot fix the error, issue a ticket.

    
  3  

A usage report was uploaded but hangs in the same status for a long time

   Act depending on the usage report status The usage report status is Validating

  1. Make sure that the Usage Collector ... guiding schedule periodic task is scheduled (the task status is Rescheduled).

  2. Wait for the next automatic execution of the Usage Collector ... guiding schedule task (by default, the task is launched every 30 minutes) or run it manually.

  3. If the task is completed successfully and the usage report status does not change, or if the task fails and you cannot fix the error, submit a ticket to CloudBlue Commerce Support.
The usage report status is Validated

  1. Make sure that the Rating Orchestrator <uuid> schedule periodic task is scheduled (the task status is Rescheduled).

  2. Wait for the next automatic execution of the Rating Orchestrator <uuid> schedule task (by default, the task is launched every 30 minutes) or run it manually.

  3. If the task is completed successfully and the usage report status does not change or if the task fails and you cannot fix the error, submit a ticket to CloudBlue Commerce Support.
The usage report status is Rating in Progress The usage report probably contains too many usage records. Wait for the rating to complete. If necessary, inspect the usage report source file.
The usage report status is Rated

  1. Make sure that the Rating Orchestrator <uuid> schedule periodic task is scheduled (the task status is Rescheduled).

  2. Wait for the next automatic execution of the Rating Orchestrator <uuid> schedule task (by default, the task is launched every 30 minutes) or run it manually.

  3. If the task is completed successfully and the usage report status does not change, or if the task fails and you cannot fix the error, submit a ticket to CloudBlue Commerce Support.
The usage report status is Billing in Progress The usage report probably contains too many usage records. Wait for the rating to complete. If necessary, inspect the usage report source file.
The usage report status is Canceled The usage report has been canceled manually and will not be processed. If necessary, you can re-import the same usage data using Batch Import API or File Import API.
4 An invoice contains wrong amounts for usage data reported with the TR rating model Check whether the usage report data is correct. The usage report has incorrect data.
  1. Inspect the problem on the vendor or connector side.
  2. If the connector is CloudBlue Connect,contact CloudBlue Connect Support.
  3. If necessary, submit a correcting usage report or create a correcting order.
The usage report data is correct.

Submit a ticket to CloudBlue Commerce Support.
5 An invoice contains wrong amounts for usage data reported with the PR or CR rating model Check the usage report data. The usage report has incorrect data.
  1. Inspect the problem on the vendor or connector side.
  2. If the connector is CloudBlue Connect,contact CloudBlue Connect Support.
  3. If the usage report status is Processed, submit a correcting usage report or create a correcting order.
The usage report data is correct.

  1. Make sure that sales margins or markups are configured correctly.

  2. If applicable, validate margin configuration against the usage report data.

  3. If the usage report status is Processed, submit a correcting usage report or create a correcting order.
6 An invoice contains wrong amounts for usage data reported with the QT rating model Check whether the usage report has the correct data. The usage report has incorrect data.
  1. Inspect the problem on the vendor or connector side.
  2. If the connector is CloudBlue Connect,contact CloudBlue Connect Support.
  3. If the usage report status is Processed, submit a correcting usage report or create a correcting order.
The usage report data is correct.

  1. Make sure that prices and discounts are configured correctly.

  2. If the usage report status is Processed, submit a correcting usage report or create a correcting order.
7 No invoice generated Check whether a billing order has been created. A billing order has been created. Submit a ticket to CloudBlue Commerce Support.
A billing order is absent. See 8
8 No billing order created Make sure that the usage report has the Processed status. The usage report has the Processed status and the rating model is TR, PR, or CR. Submit a ticket to CloudBlue Commerce Support.
The usage report status is Processedand rating model is QT.
  • For usage reported for an active subscription: wait for the next billing date of this subscription; the Daily Billing Process is going to place a billing order for this subscription.
  • For usage reported for a canceled or terminated subscription: wait for the next Daily Billing Process launch (by default once a day); check whether a billing order is created.
The usage report status is not Processed. See 1, 2, 3

 

Usage Report Import Troubleshooting

Note: The usage report format guidelines can be found in the usage report template.

This section applies to usage reports delivered from CloudBlue Connect or uploaded from the CloudBlue Commerce UI, or imported using File Import API.

During the usage report file import, the following errors may occur:

Error Type Error Message Troubleshooting

Runtime exception (ErrorCode 500)

These messages are visible in the UI.

Cannot find an account for one of the tiers for {record_id} = %s. Make sure that the corresponding provider or reseller account exists.

Check the usage report data. If there are no data errors, submit a ticket to CloudBlue Commerce Support.

Note: For each usage value (per MPN per subscription), in the usage report file, there are as many records as there are distribution tiers. Each tier 0 (customer) record has corresponding tier 1, 2 and so on records for the whole distribution chain, from the lowest-line reseller to the provider. The <subscription ID> field for all tiers has the same value: the customer's subscription ID. Tier X accounts (reseller accounts of the corresponding distribution levels) are determined based on the customer subscription ID and the tier number. If a tier X account cannot be determined for a customer's subscription, this error occurs.

Typical distribution chain tiers (levels):

  • tier 3 = provider
  • tier 2 = L1 reseller (provider's operating unit)
  • tier 1 = L2 reseller
  • tier 0 = customer

Unsupported Usage Schema value: {%s}.

Make sure that the Usage Schema field has one of these values:

Cannot find fields {%s} in the {general} tab.

Make sure that the fields specified in the error are configured in the ‘general’ tab of the report file.

Cannot parse the date. The date format must be 'yyyy-MM-dd HH:mm:ss'.

Make sure that all ‘date’ fields have the necessary format.

Invalid format: A tab with the name %s does not exist.

The 'records’ and ‘general’ tabs are required for the usage report.

Empty {records} tab.

Make sure that the 'records’ tab of the usage report is not empty.

One of these usage report format validation errors:

  • The 'record_id' field cannot be blank.
  • The 'record_note' value cannot exceed 255 characters.
  • The 'record_id' field cannot be blank.
  • The 'record_note' value cannot exceed 255 characters.
  • The 'start_time_utc' field cannot be blank.
  • The 'start_time_utc' value cannot be a future date.
  • The 'end_time_utc' field cannot be blank.
  • The 'end_time_utc' value cannot be a future date.
  • The 'item_mpn' field cannot be blank.
  • The 'item_unit' field cannot be blank.
  • The 'quantity' field cannot be blank.
  • The 'report_start_time_utc' value cannot be a future date.
  • The 'report_end_time_utc' value cannot be a future date.
Make sure that the usage report file meets the format requirements outlined in the instructions inside the downloaded report template.

Error Report (guiding issues).

These messages are visible in the error report.

Cannot map a subscription by its Reconciliation ID: {reconciliationId}.

The subscription reconciliation ID was not propagated to CloudBlue Commerce. Specify it in the UI.

Cannot map a resource by its MPN: {itemMpn}.

A resource with the MPN returned in the error does not exist in CloudBlue Commerce.

Troubleshooting the Usage Report File Processing

During the usage report file processing, the following errors can occur:

Note: Both in the Usage Report Template and error messages and troubleshooting actions below, the following abbreviations from CloudBlue Connect terminology are used for rating models (or rating schemas):
• TR - for Usage data rated by the vendor for all parties ('Tier Rated' or 'TR')
• PR - for Usage data rated by the vendor for the End Customer ('Price Rated' or 'PR')
• CR - for Usage data rated by the vendor for the Provider ('Cost Rated' or 'CR')
• QT - for Non-rated quantity-only usage data ('Quantity' or 'QT')

Error Message Explanation Troubleshooting
Can't find margin for plan {service plan APS ID} and price model {Price Model} For the PR model: There is no margin configuration for the service plan. Under the service plan owner, configure sales margins for the service plan.
For the CR model: There is no markup configuration for the service plan. Under the service plan owner, configure sales markups for the service plan.

Can't find default margin for plan {service plan APS ID} and price model {Price Model}

For the PR model: There is no default margin configuration for the service plan. Under the service plan owner, create the default margin configuration for the service plan.
For the CR model: There is no default markup configuration for the service plan. Under the service plan owner, create the default markup configuration for the service plan.
Can't find margin rates for resource {BSS resource APS ID} in margin {margin APS ID} For the PR model: There are no margin values for the margin configuration for the resource.

Under the service plan owner, set margin values for the margin configuration for the resource.

Check whether for the service plan there is a custom margin configuration for a reseller. If yes, make sure that all custom margin values are set for the resource.

For the CR model: There are no markup values for the markup configuration for the resource.

Under the service plan owner, set markup values for the markup configuration for the resource.

Check whether for the service plan there is a custom markup configuration for a reseller. If yes, make sure that all custom markup values are set for the resource.

Reseller margin value is not set

For the PR model: The YOUR MARGIN value is not set for the resource associated with a usage record whose processing failed.

  1. Find the failed usage record with this error in the failed usage report.

  2. Using the subscription ID from this usage record, find the service plan.

  3. Using the service plan delegation information, determine the distribution chain for the service plan.

  4. Make sure that the YOUR MARGIN value for the resource is set for all service plans across this distribution chain.
For the CR model: The YOUR MARKUP value is not set for a resource associated with a usage record whose processing failed.

  1. Find the failed usage record with this error in the failed usage report.

  2. Using the subscription ID from this usage record, find the service plan.

  3. Using the service plan delegation information, determine the distribution chain for the service plan.

  4. Make sure that the YOUR MARKUP value for the resource is set for all service plans across this distribution chain.

Total margin value is not set

For the PR model: The TOTAL MARGIN value is not set for the resource associated with a usage record whose processing failed.

  1. Find the failed usage record with this error in the failed usage report.

  2. Using the subscription ID from this usage record, find the service plan.

  3. Using the service plan delegation information, determine the top-level parent service plan.

  4. Make sure that the TOTAL MARGIN value for the resource is set for the top-level parent service plan.
For the CR model: YOUR MARKUP and RECOMMENDED TOTAL MARKUP are not set for a resource associated with a usage record whose processing failed.

  1. Find the failed usage record with this error in the failed usage report.

  2. Using the subscription ID from this usage record, find the service plan.

  3. Using the service plan delegation information, determine the distribution chain for the service plan.

  4. Make sure that the YOUR MARKUP value for the resource is set for all service plans across this distribution chain.

Viewing Usage Report Source Files

Important: You can view source usage reports only for usage reports imported though File Import API.

To view the source file of a usage report:

  1. In the UX1 for Providers control panel, go to Usage Reports.
  2. Click the necessary usage report imported though File Import API. In the Report tile, download and examine the source file.

Submitting a Ticket to CloudBlue Commerce Support

When submitting a ticket to CloudBlue Commerce Support:

  1. Add a clear description of what happened and what is expected.
  2. Attach the usage report document, if available.
  3. To report importing and processing issues, attach Usage Collector, Rating Orchestrator, and Rating Engine logs for the necessary period.
  4. To report invoicing issues, attach billing logs for the necessary period from the Billing application node (/var/log/pa/billing.log and /var/log/pa/billing.scheduler.log).

Applying Data Corrections to a Successfully Uploaded Usage Report

There can be situations where there are no technical errors during the usage data import but there are factual errors in the already imported data.

To apply corrections to data of an already uploaded usage report, you need to create and upload another report with respective corrections (a correcting report).

Warning:
• To avoid double-charging for the same usage, include in the report only the rows that need correction.
• To ensure correct charges, complete the quantity and amount fields with the corresponding positive or negative difference with the already uploaded values.

To apply corrections to an already uploaded usage report:

  1. Create another report whose report_id is the original report ID + a suffix, for example: UF-2019-12-9797-0764-correction-01.
  2. Include in the report only the rows that need correction:
    1. Complete the quantity and amount fields with the corresponding delta. For example, if the imported usage needs to be decreased by 5 units and the total by $10, enter '-5' in the quantity field and '-10' in the amount field. If the imported usage needs to be increased by 5 units and the total by $10, enter '5' in the quantity field and '10' in the amount field.
    2. Complete all the other fields with the same values as in the original report.
  3. Upload the correcting report.

© 2024 Ingram Micro, Inc. All Rights Reserved. Privacy Policy, Terms of Use and Legal

CloudBlue, an Ingram Micro business, uses cookies to improve the usability of our site. By continuing to use this site and/or logging in you are accepting the use of these cookies. For more information, visit our Privacy Policy.
I accept