Masterarbeit/QuellCode/CentronERP/docs/reference/receipts/Contract-Billing-RMM-Article-Logic.md

RMM-Article Logic in Contract Billing

Overview

The Remote Monitoring Management (RMM) Article functionality in c-entron.NET allows for automatic billing of usage-based services that are measured by an external RMM system. This document outlines the rules, workflow, and technical implementation of the RMM Article billing process.

Key Concepts

RMM System Integration

• The c-entron.NET application integrates with external RMM systems (e.g., "Riverbird") to retrieve usage statistics
• Usage data is collected for specified periods and used to calculate billing amounts
• Communication happens via the RiverConnectionBL class which connects to the RMM service

Contract Article References

• Each billable RMM item is defined as a ContractArticleReferenzes entity
• These references link articles in c-entron.NET to specific metrics in the RMM system
• Article references contain configuration for billing calculation rules

Workflow

1. Contract Configuration

1. A contract is configured to use RMM billing (WhetherRMM returns true)
2. Contract article references are configured, specifying:
   • Article type (e.g., server, workstation)
   • Article reference (linking to the inventory item)
   • Pricing rules

2. Invoice Generation Process

1. During the CreateInvoiceToContractComplete process, CheckRMMArticle is called
2. The system checks if the contract has RMM enabled
3. The system looks for a placeholder tag @@RMMArtikel@@ in the invoice template
4. Contract article references are retrieved for the specific contract
5. The system queries the external RMM service for usage data in the billing period
6. For each article reference with available usage data:
   • Usage amount is calculated using CalculateContractBillingAmount
   • An invoice line item is created with the calculated amount
   • Descriptive text is added explaining the service type
   • The item is inserted at the position marked by @@RMMArtikel@@ or near the end of the invoice

3. Placeholder Handling

• If the invoice template contains a text element with @@RMMArtikel@@, it serves as a position marker
• This placeholder is removed and replaced with the actual RMM article items
• If no placeholder is found, RMM items are inserted near the end of the invoice (count - 2 position)

Error Handling

External Service Unavailability

• If the RMM service is unavailable during invoice generation, and the contract requires RMM data:
  • An RMMServiceUnavailableException is thrown
  • The invoice creation process is aborted
  • An error message is logged with details about the failure
• This prevents invoices from being created with incomplete usage data, ensuring customers are billed correctly

Data Integrity Rules

• When a parent entity is deleted (State = 0), related child entities should also be marked as deleted
• This ensures data consistency when RMM configurations change

Technical Implementation Details

RMM Article Detection

var rmmItem = invoice.Items.FirstOrDefault(f => 
    (f.RichText != null && f.RichText.IndexOf("@@RMMArtikel@@", StringComparison.InvariantCulture) > -1) ||
    (f.Text != null && f.Text.IndexOf("@@RMMArtikel@@", StringComparison.InvariantCulture) > -1));

Usage Data Retrieval

var riverbirdStatisticsResult = new RiverConnectionBL(this.Session).GetContractBillingAmounts(
    billingParam.InvoiceFrom.Value, 
    billingParam.InvoiceTo.Value.AddDays(1), 
    invoice.CustomerI3D, 
    rmmArticleReferences);

Error Handling for Service Unavailability

if (riverbirdStatisticsResult.Status is ResultStatus.Error)
{
    // Only throw exception when RMM articles are expected
    if (rmmItem != null || rmmArticleReferences.Any())
    {
        string errorMsg = $"Die Rechnung kann nicht erstellt werden, da der RMM-Service nicht erreichbar ist. " +
                          $"Fehlermeldung: {riverbirdStatisticsResult.Message}";
        _logger.Error(errorMsg);
        throw new RMMServiceUnavailableException(errorMsg);
    }
    return;
}

Best Practices

1. Service Configuration

   • Ensure the RMM service URL is properly configured in application settings
   • Verify authentication tickets are valid for the RMM service

2. Contract Setup

   • Associate correct article references with appropriate RMM metrics
   • Set proper calculation rules for each article type

3. Invoice Templates

   • Include the @@RMMArtikel@@ placeholder in invoice templates where RMM items should appear
   • Ensure proper formatting and positioning for RMM article items

4. Monitoring

   • Monitor logs for RMM service connectivity issues
   • Periodically verify that usage data is being correctly retrieved and calculated

Troubleshooting

Problem	Possible Cause	Solution
No RMM items in invoice	RMM not enabled for contract	Check contract configuration
No RMM items in invoice	No usage data in RMM system	Verify usage data in RMM system
Invoice creation fails	RMM service unavailable	Check network connectivity and service status
Incorrect billing amounts	Calculation rules misconfigured	Review article reference configuration

Related Components

• AutomaticFacturaWebServiceBL - Main billing logic
• RiverConnectionBL - Handles communication with RMM service
• ContractArticleReferenzes - Defines article references for RMM billing