Skip to content
Bitta Apps

Chapter 7 of 8Page 1 of 2

Integrate and migrate

Migration kit

Move subscriptions from another billing system: import a file with price rules and running holds, preview the contracts, run it again safely, and reconcile MRR.

updated: applies-to: 1.3.5.0

The migration kit brings subscriptions from another billing system into Microsoft Subscription Billing: customer contracts, subscriptions and their lines, with the date each line was billed through, so nothing is billed twice. It also carries over a contract's price increase rule and a hold (a pause) that is running in the old system. A preview checks every line first, a rerun never creates anything twice, and a reconciliation report compares monthly recurring revenue (MRR) with the old system.

Use it when you move to Business Central from another subscription or billing system, or when you consolidate several systems.

Before you start

  • The customers, items (subscription items, plans and add-ons), currencies, contract types, resellers, promotions, escalation rules and reason codes that the file names exist in Business Central.
  • Microsoft's number series for contracts and subscriptions are set up.
  • You have the Bitta Subscriptions - Admin permission set.

To migrate subscriptions

  1. Choose the search icon, enter Migrate Subscriptions, and then choose the related link. It is also on the Assisted Setup page.
  2. Batch. Enter a batch code and the source system. The source system plus each source key identifies a record, so a rerun finds what it created before.
  3. Import. Choose Download Template, fill it in (one row per subscription line), and choose Import File (CSV or Excel).
  4. Preview. Every line is checked, and every problem is listed at once: required values, unknown customers or items, dates in the wrong order, a duplicate line key, lines of one contract with different customers, currencies or escalation rules, or a hold that the old system billed. The preview shows the counts: lines ready and in error, and the contracts, subscriptions and lines to create, update or leave unchanged, with the source MRR total. Nothing outside the staging lines is written.
  5. Migrate. Each source contract runs whole or not at all, in its own transaction: its contract, subscriptions and lines, then its escalation rule, then its hold. A contract with an error line is skipped, and its lines show the error.
  6. Reconcile. Run Migration MRR Reconciliation: per contract and line, the source MRR against the MRR of the created line, the difference, and the lines not created. A line that the migration put on hold says so in the Error or Note column, because the old system may show a paused line with no MRR.

Every step can be repeated. You can leave the guide and reopen it on the same batch.

The file

The header row uses the column names below, in any order; unknown columns are refused.

Column Required Meaning
sourceContractKey yes The contract key in the old system; lines with the same key form one contract
sourceSubscriptionKey no Lines with the same key form one subscription; blank means one subscription per line
sourceLineKey yes Unique per batch; the rerun key of the line
customerNumber, billToCustomerNumber yes, no The end customer, and the parent account that pays
itemNumber, description, quantity yes, no, yes The subscription item and its quantity
serialNumber no A device serial number on the subscription
startDate, endDate, billedThroughDate yes, no, no First and last day of service, and the last day the old system billed
billingBasePeriod, billingRhythm yes, no For example 1M, 3M or 1Y
initialTerm, extensionTerm, noticePeriod no Microsoft's term formulas
unitPrice, discountPercent yes, no Price per unit and billing base period, in the contract currency
contractTypeCode, currencyCode, resellerNumber no Contract fields
promotionCode, promotionStartDate no A Bitta Subscriptions promotion to grant
sourceMrr no MRR in the old system; blank means it is computed from the price
escalationRuleCode no The price increase rule of the contract; every line of a source contract has the same rule, or none
nextEscalationDate no The next price increase of the line, when the old system knows it; blank means it is calculated from the rule and the start date
holdFrom no The first day of a pause that runs in the old system; the line's subscription is put on hold from this date
holdResumeOn, holdReasonCode no The day the hold ends (blank: you resume it yourself) and its reason code

What happens in Microsoft Subscription Billing

  • Subscriptions and lines are created through Microsoft's own import of subscriptions and contract lines.
  • Next Billing Date is the billed-through date plus one day, so Microsoft bills from there; the old periods are not billed, posted or deferred again. Revenue already recognized in the old system stays there.
  • A rerun updates quantity, price, discount and the billed-through date of a line that has not been billed in Business Central yet. A billed line is refused for a change; amend it instead.

Price increase rules and running holds

  • Escalation rule. The contract gets the rule of escalationRuleCode. Each line gets its next escalation date from nextEscalationDate, or from the rule counted from the line's start date. A rerun sets another rule on the contract, and another next escalation date on a line, also when the line has been billed, because neither changes a billed amount. A blank escalationRuleCode leaves the contract's rule as it is.
  • Hold. All held lines of a source contract share holdFrom, holdResumeOn and holdReasonCode: a contract gets one hold, placed through the same engine as the Hold wizard, on the subscriptions of its held lines. Their lines end the day before holdFrom, and billing restarts when the hold is resumed, by the daily job on holdResumeOn or by you.
  • No credits. A migrated hold credits nothing, so billedThroughDate must be before holdFrom: credit the billed days of the pause in the old system first. holdFrom must be after startDate.
  • Reruns. The Migration Map keys the hold by the source contract, so a rerun never places a second hold. A rerun with another holdResumeOn moves the end of the active hold. A different holdFrom is refused: resume or cancel the hold in Business Central. A subscription that was not on the hold cannot join it later.
  • The approval of holds does not apply to a migrated hold: the decision was made in the old system. The hold sends the usual holdPlaced event.

Limits

  • The kit migrates customer lines only; vendor lines, usage-based lines and deferral history are not migrated.
  • A migrated contract gets the source contract key as its description and Your Reference. Microsoft keeps the automatic contract dimension value in step with the description only through its own contract page, so a migrated contract does not get that dimension value; add it by hand if you use it (a request to Microsoft is open).
  • Escalation rules are migrated per contract; a rule of its own on one line is set in Business Central after the migration.
  • The same import is available through the API (migrationBatches and migrationLines, see APIs and events).

See also

Next step

Ready to try Bitta Subscriptions?