Manage and troubleshoot
Troubleshooting
Run the Setup and Data Health Check to find what will make billing, lifecycle actions or reports wrong, and fix the common Bitta Subscriptions messages.
updated: applies-to: 1.3.5.0
The Setup and Data Health Check lists everything that will make billing, lifecycle actions or reports wrong, each with what to do about it. Run it after setup, after an upgrade, and whenever something looks off.
To run the Health Check
- Choose the search icon, enter Bitta Subscriptions Setup, and then choose the related link.
- Choose Check Setup and Data. The Setup and Data Check page lists every error and warning, one per row, errors first. For a printable list, run the Setup and Data Health Check report (also in the Report Center, category Setup).
- Work through the rows, then choose Check Again until the page is empty. When there is nothing to fix, Check Setup and Data says so in a message instead of opening the page.
The Setup and Data Check page
| Column or action | What it shows or does |
|---|---|
| Severity | Error (shown in red): billing, the lifecycle or the reports are wrong now. Warning: they will be soon. |
| Area | The part of the setup or data, for example Job queue, Holds or Sales tax. Filter on it to work area by area. |
| Record | The record the finding is about, for example Hold HLD000034. |
| Description and How to Fix | What is wrong, and what to do about it. |
| One-Step Fix | The name of the fix that Fix runs, for example Schedule Jobs. Blank when the finding is fixed on its record. |
| Fix | Runs the one-step fix of the selected row, then checks again. |
| Open Record | Opens the record or page of the selected row, for example the hold that should have resumed. |
| Check Again | Runs the whole check again, for example after you fixed some rows. |
The page replaces the single message of earlier versions, which showed only the first few findings of a long list. Use the page's filters (for example Severity is Error) when a company has many findings, such as a test company with months of test data.
What it checks
| Area | Example findings | What to do |
|---|---|---|
| Microsoft prerequisites | Contract or subscription number series, billing template, contract accounts missing | Run Check Prerequisites on the setup page and use Fix |
| Setup | No number series for amendments, holds, terminations or reseller statements; no adjustment item; a fee method without a fee item; no commission account | Fill in the field on the Bitta Subscriptions Setup page |
| No email account | Set up an email account and assign it to the Renewal Notice and Reseller Statement scenarios | |
| Job queue | A daily task is not scheduled, or stopped with an error | Use Schedule Jobs, or open the job queue entry, fix the cause and set it to Ready |
| Contract analysis | No snapshot for the current month, or months missing | Update Contract Analysis; schedule Microsoft's Create Subscription Contract Analysis monthly |
| License | Not usable, or in its grace period | Open the Bitta Subscriptions License page |
| Holds | A hold should have resumed | Resume it, or check the hold task |
| Amendments | A scheduled amendment is past its date | Open it; fix the error it shows |
| Price increases | A proposal waits on Contract Price Update; an index value is missing | Apply or delete the proposal; enter the index value |
| Renewal notices | A notice failed; a contract has no recipient email | Fix the address, then Send Again |
| Subscription lines | Evergreen lines without a notice period; lines without term dates; old unbilled charges and credits; lines a billing period behind | Correct the lines or run Recurring Billing |
| Resellers | A reseller earns commission but has no vendor; a statement open for long | Fill in the vendor; create the payout |
| Promotions | Expired but not blocked; package assigned to no item | Block it; assign the package |
Common messages
When an action finds several problems at once, for example a charge without a type, a quantity and a date, the message says There are 3 problems to fix and lists each problem on its own numbered line. Subscription lines are named by their plan or add-on and the serial number of the device, for example Cloud Suite Pro on subscription SUB000581, not by an internal entry number. The actions in the message (for example Open Charge Type) belong to the first problem; the others have no action of their own. Fix them all, then try again. A background run that fails keeps the whole list in its Error field.
| Message or symptom | Cause | What to do |
|---|---|---|
| A lifecycle action says the license is not activated, has ended, or you have no seat | No usable license, or no seat for you | Choose Open Bitta Subscriptions License in the message (Permissions and seats) |
| "Subscription line ... is in a billing proposal", with Open Recurring Billing | The line is in an open billing proposal | Delete the billing lines in Recurring Billing, or create and post the documents, then try again |
| "Subscription line ... is on the unposted ...", with Open Document | The line is on an unposted invoice or credit memo | Post or delete the document |
| "Subscription line ... is billed by usage" | Usage-based lines are not changed by amendments, holds or promotions | Terminate the line, or change it in Microsoft's usage data |
| An action offers Open Hold | The line is on an active hold | Resume or cancel the hold first |
| An action offers Open Amendment | An amendment of the same subscription is open or scheduled | Apply or cancel it first |
| An action offers Open Planned Subscription Lines | Microsoft has a planned renewal or price update for the line | Post or delete the planned change |
| "Item ... is not a subscription item, so Microsoft Subscription Billing cannot carry a credit line for it", with Open Setup | No Adjustment Item No. for a non-subscription item | Fill it in on the setup page |
| The renewal cockpit shows Term Dates Missing | The line has an initial term but no term dates | Open the subscription and enter Term Until, or enter the start date again |
| Recurring revenue reports are empty for a month | No contract analysis snapshot for that month | Update Contract Analysis (current month only) |
| A daily task failed | One record could not be processed; the others were | The job queue entry and the record (hold, amendment) show the error |
| "Contract ... is locked (...), so it cannot be changed", with Show contract | The contract is locked against lifecycle changes | Ask a user with BAA SUBSCR LOCK to unlock it (Approvals and the contract lock) |
| A hold, termination or amendment did not happen, and the message says an approval request was sent | The change reaches an approval threshold and a workflow is enabled | Wait for approval, then choose Apply on the request (holds and terminations) |
| "This hold needs approval. Place it from the hold wizard..." (API or batch change) | The API and batch changes cannot send approval requests | Use the wizard |
| "Revenue allocation is off..." | Revenue Allocation is off on the setup | Turn it on in the group Revenue Recognition (Revenue recognition) |
| "Item ... has no standalone selling price on ...", with Open Standalone Selling Prices | Missing Standalone Price is Refuse the allocation | Add the price, or set Use the line price |
| "Obligation ... has no revenue account" | The general posting setup has no Cust. Sub. Contract Account (or Sales Account for hardware) | Fill it in, then choose Calculate on the allocation |
| A device stays Awaiting Activation with an Activation Error | The activation failed, for example on a locked contract | Read the error, fix it, and activate again |
| Failed Background Runs cue | A background hold, termination or batch change failed; nothing of a hold or termination was written | Open Background Runs, read Error, fix it and start the change again (Background runs) |
| Failed Webhook Messages cue | The receiver did not accept a device message after every retry | Fix the receiver, then Retry on Webhook Messages. In a sandbox, turn on Allow HttpClient Requests for the app |
| "Installment ... is in a billing proposal or on an unposted contract invoice, so the plan cannot be canceled" | An installment is being billed | Delete the billing lines in Recurring Billing, or the invoice, then cancel |
| "Contract ... already has the active prepaid balance ..." | A contract has one active prepaid balance | Top up that balance, or close it first |
Contact support
Email support@bittaapps.com, or use the contact form. Include the message text, the record it names and what you did before it appeared.