Zoomed Image
USA
800 691 9120
UK
01225 704844

Testing Rule Changes Safely

Software Asset Management Guide
Customizing the Calculation

Testing Rule Changes Safely

Editing the calculation rules in production without testing is the fastest way to break compliance reporting. This page covers the safe-rollout workflow.

The Three Rules of Safe Editing

  1. Back up the current rules before any change. There is no version history in the editor.
  2. Recalculate only the open period after a change. Do not recalculate historical periods unless you intend to rewrite history.
  3. Verify on a small, known product first. Confirm the rule does what you expect before assuming it works at scale.

Before You Edit: Back Up

Open the Configure dialog. Select all the text in each block (Calculated Fields, Requirements, Affinity) and copy it into a text file. Date-stamp the file and keep it somewhere outside xAssets.

If your edit goes wrong, paste the backup back into the dialog and save. The original behavior is restored.

For a more durable backup, copy the source from Admin → Transformations → Calculate Software Licensing — the rules block is part of the transformation's source. Export the transformation to a file (or to a peer environment) before editing.

If you have a non-production environment (a UAT, dev, or test database), follow this cycle:

1. Edit rules in test environment
2. Recalculate test environment for the current period
3. Spot-check 3-5 products that should be affected
4. Spot-check 3-5 products that should NOT be affected
5. If both sets behave correctly, promote rules to production
6. In production, recalculate the current period only
7. Spot-check the same products

If you do not have a non-production environment, follow the same cycle in production but with extra care:

1. Back up current rules to file
2. Edit rules
3. Save
4. Recalculate the current period only
5. Spot-check; if anything wrong, restore from backup, save, recalculate

What "Spot-Check" Means

For each product you check, verify:

Check What To Look At
The compliance position is what you expect Licensing Position page, the product's Outstanding Requirement column
Allocation is going to the right licenses Click the product, see the per-license breakdown
No unintended deficits appear New deficits on products you did not touch indicate a side effect
Per-license utilization makes sense Open a representative license, check it is allocated as expected

If the product looks right, the rule worked for that case. Repeat across enough products to be confident.

Diagnosing a Bad Change

If after a change you have:

  • More deficits than before — the change has excluded valid licenses. Most likely a new requirement is too strict. Check by reverting the requirement and recalculating.
  • Allocations going to unexpected licenses — affinity weights may be wrong. Look at the engine's debug output (advanced) or sanity-check by comparing scores manually.
  • The calculation throws "Missing required field in affinity rules" — a field referenced in a rule is not present on every row in the data source. Check the source query.
  • The calculation runs but the results are unchanged — the rule may not be reaching the iteration. Confirm the rule was saved (re-open the dialog), and that the fields you reference are present.

Engine Debug Output

The engine produces debug output during calculation showing which licenses were considered for which consumptions and what scores they received. This is the authoritative diagnostic:

--- PRODUCT: 56 Microsoft 365 Apps for Business ---
Licenses:
License "Test License" has ID 129
    Possible consumptions for this license:
        Consumption "DONNA" has ID 18

--- Final Assignments by Consumption ---
Consumption "DONNA"
    License: Test License id 129 Score=7200 Rules=
        Consumption.DepartmentID = License.DepartmentID type: affinity score: 3000
        Consumption.LocationID = License.LocationID type: affinity score: 800
        Consumption.CustodianID = License.CustodianID type: affinity score: 1000

This output is captured in the calculation's batch job log. If your change is not behaving as expected, find the relevant product in the log and see exactly which licenses were considered, which were excluded, and why.

Rolling Back

If the change is wrong, rolling back is two clicks:

  1. Open Configure.
  2. Paste your backup over the current rules.
  3. Save.
  4. Recalculate the period you want restored.

The data is not damaged — only the allocation transactions for the periods you have recalculated are different. Recalculating with the original rules restores the original allocations.

When Rollback Is Hard

The one scenario where rollback is hard: you ran the bad rule against historical periods (recalculated from a year ago) and the new transactions have rewritten months of history. Rolling back the rules is fast, but you then need to recalculate the same historical periods to restore the prior position — which means accepting that those periods now have a different transaction history than they did before.

This is why the safe-rollout cycle says recalculate the current period only. Historical recalculation is destructive and should be a deliberate, infrequent action.