Imports, G/L rules, and recurring contracts

Not every commissionable event is a posted sales document. Bitta Commission can also take in rows from CSV files, events sent by your own systems through an API, selected G/L entries, and subscription events derived from recurring invoices. Every row passes through the same staging, validation and review steps before it becomes an immutable source fact.

Before you start

• Read Business Central sales sources first. It explains source facts and Commission Source Capture Setup.
• Maintaining mappings, rules, policies and contracts requires the Bitta Commission Setup Administrator or Bitta Commission Integration permission set.
• Every external source needs a Source System Code. Codes that start with NATIVE- are reserved for the built-in adapters.

How staging works

Every non-native row is first written to source staging. The app then:

1. Checks the row with any active data quality rules (see Exceptions and data quality).
2. Applies the late data policy for its source system.
3. Accepts the row into Commission Source Facts, or holds or quarantines it for review.

Each row carries an idempotency key and a payload hash. Sending the same row again returns the existing fact instead of creating a second one. Sending a changed row under the same key is rejected as a conflict.

Import rows from a CSV file

Set up an import mapping

1. Open Commission Source Capture Setup and turn on File Import Enabled.
2. Open Commission Source Import Mappings and create a mapping.
3. Fill in the header fields on Commission Source Import Mapping:

Field	What it does
Source System Code	Written on every imported row. Cannot start with NATIVE-.
Provider Code / Schema Version	Written on every imported row for traceability.
Mapping Version	Becomes part of each row's payload hash. Raise it when the column layout changes.
Source Fact Type Code	The default fact type, for example EXTERNAL-TRANSACTION or SUBSCRIPTION-EVENT.
Source Event Type Code	The default event type, normally IMPORTED.
Has Header Row	The first row holds column names and is skipped.
Status	Only Active mappings can be used.

1. In the Columns part, add one line per column. Set Target to Staging Field (with the Staging Field No. to fill) or Attribute (with an Attribute Code and Attribute Value Type). Mark Required for columns that must not be blank.

Run the import

1. On Commission Source Import Mappings, select the mapping.
2. Choose Dry Run CSV and select the file. Rows are staged and validated, but no source facts are created. Use this to find format problems first.
3. Choose Import CSV and select the same file. Valid rows are accepted into source facts. The message shows how many rows were processed and in which batch.
4. Choose Source Review to deal with any held or quarantined rows.

Importing the same file again reuses its batch and creates no duplicates. A corrected file creates a new batch. A blank required column or a value that cannot be converted marks that row as an error, and the other rows continue.

Receive events through the API

Your own systems, for example a point-of-sale or CRM system that you integrate yourself, can post events to the commissionSourceEvents API (publisher bittaApps, group commission, version v1.0). The API only inserts staging rows. It cannot change or delete them.

• Turn on External Events Enabled on Commission Source Capture Setup.
• Give the integration user the Bitta Commission Integration permission set.
• Each event must carry a source system code, a fact type, an idempotency key and at least one date. A foreign currency event must carry an exchange rate factor.

Bitta Commission does not ship ready-made connectors to third-party systems. The API is the documented entry point for integrations you build.

Capture selected G/L entries

Use G/L source rules when commission depends on amounts that only exist in the general ledger, such as manual adjustments.

1. Open Commission Source Capture Setup, turn on G/L Capture Enabled, and choose G/L Source Rules.
2. Create a rule on Commission G/L Source Rules:

Field	What it does
G/L Account Filter	Required for an active rule, for example 6100..6199.
Source Code Filter	Optional source code the entry must match.
Dimension Code / Dimension Value Filter	Optional dimension the entry must carry.
Fact Kind	Whether matches become Manual Adjustment or External Transaction facts.
Salesperson Code	A fixed salesperson for every matching entry.
Attribution Dimension Code	A dimension whose value is used as the salesperson code when no fixed salesperson is set.
Negate Amount	Reverses the sign so that credit balances become positive commission amounts.
Requires Review	Holds matching entries for review before acceptance.
Priority	Rules are tested in order and the first match wins.
Status	Only Active rules capture entries.

1. Choose Register Scanner Jobs on Commission Source Capture Setup and set the G/L scanner job to Ready. The G/L and recurring scanners only run while Native Capture Enabled is on in Bitta Commission Setup.

G/L entries posted by Bitta Commission itself are never captured, so commission postings cannot feed back into commission.

Derive subscription events from recurring contracts

1. Turn on Recurring Capture Enabled and review Churn Grace Days on Commission Source Capture Setup.
2. Open Commission Recurring Contracts and add a contract: Contract No., Customer No., optionally an Item No. (blank matches every item), Recurring Code, Salesperson Code (blank keeps the invoice attribution), Billing Interval, Start Date and End Date.
3. Set Status to Active.

Accepted invoice facts for that customer and item inside the contract window produce Subscription Event facts. The app classifies each one by comparing it with the previous invoice: NEW for the first invoice, then RENEWAL, UPGRADE or DOWNGRADE depending on whether the amount stayed the same, rose or fell. When no further invoice appears after the end date plus the churn grace days, a CHURN event is derived once. Plans can then pay on these events.

Handle late data

A row is late when its business date is older than the grace period. Turn on Late Data Policy Enabled on Commission Source Capture Setup and set Default Late Grace Days and Default Late Data Action. To override the default for one source system, add a line on Commission Late Data Policies.

Action	Result
Accept Into Current Period	The row is accepted with today's business date. The original date is kept as an attribute.
Hold For Review	The row is held with reason LATE-DATA until someone releases or excludes it.

Only Active policies override the setup defaults.

Review held and quarantined rows

Open Commission Source Review. It lists staged rows that were held or quarantined, with the Inclusion Reason Code (for example GL-REVIEW-REQUIRED, LATE-DATA or QUALITY- followed by the rule code) and the Validation Message.

• Release and Accept sets the row to included and accepts it into source facts with its preserved attributes.
• Exclude removes the row from commission processing with a recorded review reason. No fact is created.
• Quality Outcomes shows the data quality results for the row.

Related pages

• Business Central sales sources
• Exceptions and data quality
• Calculation runs and schedules