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
```csharp
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
```csharp
var riverbirdStatisticsResult = new RiverConnectionBL(this.Session).GetContractBillingAmounts(
    billingParam.InvoiceFrom.Value, 
    billingParam.InvoiceTo.Value.AddDays(1), 
    invoice.CustomerI3D, 
    rmmArticleReferences);
```

### Error Handling for Service Unavailability
```csharp
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