BC Integration Worker

The BC Integration Worker (BCIntegration.Worker) is a .NET 9 hosted Windows Service. It runs on a 5-minute loop and does three kinds of work:

1. Inbound from BC — payment application data and ledger entries (read-only API calls into BC, writes into SMART SQL).
2. Outbound to BC — drains TransmissionMaster rows with Status = 'N' and posts custom API entities in Business Central.
3. Status bookkeeping — sets TransmissionMaster.Status to C (completed) or E (error) with ReturnMessage / ReturnCode.

SMART desktop and web apps enqueue work by inserting into TransmissionMaster and the child Transmission* tables below. This worker is the component that actually talks to BC.

For the business picture of transmissions across all SMART apps, see How SMART talks to Business Central. This page is the technical reference for what this worker implements today (source: Worker.cs, Api/ApiService.cs on main).

• 15 TransmissionMaster.TransType codes are processed (lot, vend, … cpcl, soap).
• 14 child Transmission* tables are read (plus TransmissionPaymentStatus on inbound pays).
• TransmissionPOGenerate and TransmissionLandDevBudgetActuals exist in the Core project but are not used by the worker.
• Ledger mirror tables BCJobLedger and BCGeneralLedger are filled from BC; they are not transmission queues.
• OAuth2 client-credentials against login.microsoftonline.com; company-scoped OData under ApiSettings:BaseUrl.

Worker cycle (normal mode)

When Sync:BCLedgersOnly is false (production default), each cycle runs in order:

Step	What happens
1	Payment status pull (pays) — For each calendar day not yet marked, GET BC projectAppliedEntries for yesterday (relative to Eastern time). Insert TransmissionMaster (TransType = pays, Status = N or C) and child TransmissionPaymentStatus rows when BC returned data.
2	BC job ledger sync — GET /jobLedgers in 5,000-entry windows; insert into BCJobLedger where PostingDate > 2025-12-31.
3	BC general ledger sync — GET /glEntries for entry numbers that exist on BCJobLedger but not yet on BCGeneralLedger (also after cutoff date).
4	Transmission drain — SELECT * FROM TransmissionMaster WHERE Status = 'N' AND TransType IN (...) — process each row (see catalog below).

Maintenance mode

When Sync:BCLedgersOnly = true, only steps 2 and 3 run. With Sync:RunOnce = true, the host exits after one ledger cycle.

Operator controls

While attached to a console:

• Ctrl + Shift + P — pause before the next transmission.
• Space — resume.

Transmission status codes

Code	Meaning in this worker
N	Queued; will be picked up on the next drain pass.
C	Completed — BC call succeeded (or pays day had no rows / payment update finished). DateSent set.
E	Error — see ReturnMessage, ReturnCode; may also log to TransmissionMasterErrorLog.
H	Hold — not selected by the worker (Status = 'N' filter only).

Other SMART status codes (X, R, q, …) are documented on Transmissions.

Add vs update (TransmissionMaster.Mode)

Mode	HTTP	When used
A	POST	New entity in BC.
U	PUT	Update existing entity.
D	DELETE	Remove entity (supported in API layer; uncommon in queue).

For comm, lot, vend, vetp, and vadr, the worker may flip A → U before posting: it GETs the BC record first (ResolveAddOrUpdateAsync). Batch types esti and acgr do the same GET-per-row inside ProcessBatchWithTransmissionAsync.

---

Transmission tables this worker uses

Only these SQL tables participate in the worker loop. Other Transmission* tables in SmithDouglasCommunities may be filled by SMART for other processes; they are out of scope for this service unless added to Worker.cs.

Child table	TransType	Direction	BC API (custom publisher)
TransmissionMaster	(all)	Control	—
TransmissionCommunity	comm	SMART → BC	/dimensionValues (COMMUNITY)
TransmissionLot	lot	SMART → BC	/dimensionValues (LOT), then /projects, /defaultDimensions on add
TransmissionDivision	divi	SMART → BC	/dimensionValues (DIVISION)
TransmissionVendor	vend	SMART → BC	/vendors
TransmissionVendorType	vetp	SMART → BC	/vendorPostingGroups
TransmissionVendorAddress	vadr	SMART → BC	/vendorRemitAddresses
TransmissionTerm	term	SMART → BC	/paymentTerms
TransmissionPOApprove	poap, soap	SMART → BC	/unpostedPurchaseDocs + /unpostedPurchaseDocLines
TransmissionContractPostClosing	cpcl	SMART → BC	/postClosingJobGLJrnlLines (one POST per amount column)
TransmissionInvoiceSubmission	inv1	SMART → BC	/unpostedPurchaseDocs + /unpostedPurchaseDocLines
TransmissionEstimate	esti	SMART → BC	/projects, /projectTasks
TransmissionLotActivityGroup	acgr	SMART → BC	/projects, /projectTasks
TransmissionLotStatus	lsts	SMART → BC	OData /$batch PUT on LOT dimensionValues
TransmissionPaymentStatus	pays	BC → SMART	GET /projectAppliedEntries (inbound); no BC POST on drain

Not used by this worker

Artifact	Notes
TransmissionPOGenerate	Model exists; no case in Worker.cs.
TransmissionLandDevBudgetActuals	Model exists; no handler in Worker.cs.
All other Transmission* tables	Legacy or unused by this worker — not listed on Transmissions.

Ledger mirror tables (not transmissions)

Table	Source	Purpose
BCJobLedger	GET /jobLedgers	Local copy of BC project ledger entries after cutoff.
BCGeneralLedger	GET /glEntries	G/L lines linked to job ledger via LedgerEntryNo / EntryNo.

Cutoff constant in code: BCLedgerSyncStartDate = 2025-12-31. Entries on or before that date are not backfilled.

---

Inbound: payment status (pays)

Trigger

Not created by SMART users directly. The worker creates one TransmissionMaster per calendar day being reconciled (Eastern time), starting the day after the last pays DateAdded.

Received from BC

GET {BaseUrl}/projectAppliedEntries with filter:

• systemModifiedAt on the target calendar day (BC “yesterday” relative to the run).
• $select: open, documentNo, postingDate, appliedDocNo, projectNo, projectTaskNo.

Mapped into TransmissionPaymentStatus:

BC field	SMART column	Use
documentNo	DocumentNo	Treated as PO number (must parse as integer for update).
postingDate	PostingDate	Check date written to SMART.
appliedDocNo	AppliedDocNo	Check / application document number.
systemModifiedAt	SystemModifiedAt	Audit from BC.
projectNo	ProjectNo	Lot/project key from BC.
projectTaskNo	ProjectTaskNo	Task on project.
open	Open	Loaded from API (not used in bulk update filter).

Written to SMART

1. TransmissionMaster — CompanyID = SGW, TransType = pays, Mode = A. Status = C if BC returned no rows (day marked done); Status = N if there are rows to process.
2. TransmissionPaymentStatus — bulk insert when data exists.
3. On drain (case pays): PermanentOrderLog updated — CheckDate = PostingDate, CheckNumber = AppliedDocNo where PONumber = DocumentNo (rows with valid integer PO and non-null AppliedDocNo only).
4. TransmissionMaster set to C — no outbound BC API call.

---

Outbound transmission catalog

For each type: SMART child row(s) → BC API payload highlights. Unless noted, success sets TransmissionMaster to C.

comm — Community

Table	TransmissionCommunity
Modes	A / U / D; may auto-switch to U after GET
Sent to BC	POST/PUT /dimensionValues: dimensionCode = COMMUNITY, code = CommunityID, name = Description
Key SMART columns	CommunityID, Description (also Subaccount, Status, CommunityName, AreaID on row — not all sent in API body)
Received	None

lot — Lot dimension + project setup

Table	TransmissionLot
Modes	A / U / D; may auto-switch to U after GET
Sent to BC	POST/PUT /dimensionValues: dimensionCode = LOT, code = formatted lot (CCC-BBB-UUU from 12-char LotAccountCode), name = ProjectDesc
On A only (extra calls)	POST /projects if missing (no, sellToCustomerNo, dimensions). PUT /defaultDimensions for LOT, COMMUNITY, DIVISION on table 167 (skipped for placeholder lots ending in XXXXXXX).
Key SMART columns	LotAccountCode, ProjectDesc, ProjectID, BuildingID, UnitID, address fields, status columns (APStatus, ARStatus, …) — dimension sync uses account code + description
Received	None

divi — Division

Table	TransmissionDivision
Modes	A / U / D
Sent to BC	POST/PUT/DELETE /dimensionValues: dimensionCode = DIVISION, code = DivisionID, name = DivisionName
Key SMART columns	DivisionID, DivisionName, Description, Status
Received	None

PerformPostAsync / PerformPutAsync implement TransmissionDivision, but ProcessTransmission<T>’s type guard does not list TransmissionDivision — verify in your build that divi rows are not logging “Unsupported type” before relying on this path.

vend — Vendor

Table	TransmissionVendor (+ join to Term, Vendor, vwUserAccount for DueTypeID, EmailAddress)
Modes	A / U / D; may auto-switch to U after GET on /vendors('{AccountingPackageVendorID}')
Sent to BC	POST/PUT /vendors: no, name, address, phoneNo, telexNo (fax), vendorPostingGroup, paymentTermsCode, postCode, state, blocked (from StatusName: All / Payment / not blocked)
Key SMART columns	AccountingPackageVendorID, VendorName, VendorTypeID, TermID, StatusName, address/remittance fields
Received	None

vetp — Vendor posting group

Table	TransmissionVendorType
Modes	A / U / D; may auto-switch to U
Sent to BC	POST/PUT /vendorPostingGroups: code = VendorTypeID, description
Key SMART columns	VendorTypeID, Description, Status
Received	None

vadr — Vendor remit address

Table	TransmissionVendorAddress
Modes	A / U / D; may auto-switch to U
Sent to BC	POST/PUT /vendorRemitAddresses: vendorNo, code (REMIT / 1099 / DEFAULT from AddressTypeID R/T/other), address lines
Key SMART columns	AccountingPackageVendorID, AddressTypeID, Address1, Address2, City, State, Zipcode
Received	None

term — Payment terms

Table	TransmissionTerm
Modes	A / U / D (no GET flip in worker)
Sent to BC	POST/PUT /paymentTerms: code = TermID, description = TermName, dueDateCalculation = DueInterval + 'D', discountPerc
Key SMART columns	TermID, TermName, DueInterval, DiscountPercentage, …
Received	None

poap / soap — PO / service order approval (purchase documents)

Both types use the same code path and TransmissionPOApprove child rows. soap is “service order complete”; poap is standard PO approval.

Table	TransmissionPOApprove (one or many rows per master)
Processing order	1) AddPOApproveHeader on first row. 2) POST each line to /unpostedPurchaseDocLines.
Header sent to BC (if document missing)	POST /unpostedPurchaseDocs: no = PONumber, documentType Invoice or Credit Memo (from sign of InvoiceAmount), buyFromVendorNo / payToVendorNo, paymentTermsCode, dimension shortcuts, documentDate
Line sent to BC	POST /unpostedPurchaseDocLines: documentNo, type = G/L Account, no = AccountID, projectNo, projectTaskNo, quantity = 1, directUnitCost = abs(InvoiceAmount)
AccountID	Resolved in SQL: PO starting with 1 → lot WIP account; 8 → variance account; 9 → service request type account; else default 14300
Key SMART columns	PONumber, InvoiceAmount, InvoiceDate, AccountingPackageVendorID, LotAccountCode, TaskID, CompanyID, ProjectID, BuildingID, UnitID
Received	None
Validation	Missing AccountingPackageVendorID → master E without calling BC

inv1 — Invoice approval (land dev / AP invoice submission)

Table	TransmissionInvoiceSubmission (one or many lines per invoice)
Processing order	1) AddInvoiceSubmissionHeader on first row. 2) POST each line.
Header sent to BC	POST /unpostedPurchaseDocs when missing: no = InvoiceNumber, vendor, terms, dimensions, documentDate
Line sent to BC	POST /unpostedPurchaseDocLines: documentNo = InvoiceNumber, no = AccountID, projectNo, projectTaskNo, directUnitCost = abs(TransactionAmount)
Key SMART columns	InvoiceNumber, TransactionAmount, AccountID, LotAccountCode, TaskID, AccountingPackageVendorID, InvoiceDate, CompanyID, TermID
Received	None

cpcl — Contract post-closing journal

Table	TransmissionContractPostClosing (single row; joined to ContractPostClosing, Contract, Community, Company, user name)
Modes	Uses master Mode on each line POST
Sent to BC	One POST per non-zero amount field to /postClosingJobGLJrnlLines: documentNo = ContractSysID, postingDate = ClosedDate, accountNo (G/L or bank), amount (sign rules per column), jobNo / jobTaskNo / dimensions vary by column (e.g. CashToSeller clears project; WorkInProgress uses task JOURN; land dev columns use D1015 / CLOTC)
Amount columns	PlanPrice, OptionRevenue, LotPremium, PriceAdj, CashToSeller, WIPLandDevDebit/Credit, LandDevelopmentLotCost, ConstructionCost, DepositReceived, closing costs, warranty, concessions, etc. (see AccountToColumns in ApiService.cs)
Key SMART columns	ContractSysID, ClosedDate, ClosingDesc, PostClosingBankAcct, CommunityID, financial columns on ContractPostClosing
Received	None

esti — Estimate / project task budget

Table	TransmissionEstimate (many rows per master)
Per row	GET /projectTasks; if missing → A, else U. AddProject first. POST/PUT /projectTasks: projectNo, projectTaskNo, description = TaskDesc, originalBudget = BudgetAmount
Key SMART columns	LotAccountCode, TaskID, TaskDesc, BudgetAmount, ProjectID, CommunityID, CompanyID
Received	None

acgr — Lot activity groups (project tasks)

Table	TransmissionLotActivityGroup (many rows)
Per row	Ensure /projects exists (POST if GET fails). POST/PUT /projectTasks: projectTaskNo = TaskID, description = TaskName
Key SMART columns	LotAccountCode, TaskID, TaskName, GroupsID, CompanyID
Received	None

lsts — Lot status on dimension

Table	TransmissionLotStatus (many rows per master)
Sent to BC	Single OData batch (POST {RootUrl}/$batch) of PUTs to dimensionValues('LOT','{community-building-unit}') with body { lotstatus: BCLotStatus }
Key SMART columns	ProjectID, BuildingID, UnitID, LotStatusID, BCLotStatus
Received	None
Completion	Entire batch must return HTTP 200 per sub-request; otherwise master → E

---

BC ledger sync (read-only)

Job ledger → BCJobLedger

API	GET /jobLedgers?$filter=entryNo gt {cursor} and entryNo le {cursor+5000} and PostingDate gt 2025-12-31
Stored fields	JobNo, PostingDate, JobTaskNo, EntryNo, DocumentNo, Description, DocumentDate, LedgerEntryNo, TotalCost, No
Cursor	MAX(EntryNo) in BCJobLedger; bootstrap uses first BC entry after cutoff

General ledger → BCGeneralLedger

API	GET /glEntries with same windowing on entryNo
Stored fields	EntryNo, PostingDate, GLAccountNo, DocumentNo, Description, Amount, Debit, Credit, DocumentDate, ExternalDocumentNo, SourceNo, ShortcutDimension3Code
Scope	Only inserts GL rows whose EntryNo matches a BCJobLedger.LedgerEntryNo not yet present in BCGeneralLedger (excludes LedgerEntryNo = 0 migration rows)

---

Configuration

BCIntegration/BCIntegration.Worker/appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=...;Database=SmithDouglasCommunities;..."
  },
  "Database": {
    "LedgerQueryCommandTimeoutSeconds": 120
  },
  "ApiSettings": {
    "BaseUrl": "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/{publisher}/{group}/v2.0/companies({companyGuid})",
    "RootUrl": "https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/{publisher}/{group}/v2.0/",
    "TokenEndpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
    "ClientID": "...",
    "ClientSecret": "...",
    "TenantID": "...",
    "CompanyGUID": "...",
    "EnvironmentName": "Production",
    "Scope": "https://api.businesscentral.dynamics.com/.default",
    "APIPublisher": "...",
    "APIGroup": "...",
    "GrantType": "client_credentials"
  },
  "Sync": {
    "BCLedgersOnly": false,
    "RunOnce": false
  }
}

Authentication: OAuth2 client credentials (grant_type from config). All company API calls use BaseUrl; OData batch (lsts) uses RootUrl + companies({CompanyGUID}).

Logging: Serilog → console and C:\Logs\BCIntegration.log (daily rolling).

---

Where the source lives

BCIntegration/
├── BCIntegration.sln
├── BCIntegration.Core/
│   ├── Interfaces/          IApiService, IDatabaseService
│   └── Models/              Transmission* + BCJobLedger, BCGeneralLedger
├── BCIntegration.Infrastructure/
│   ├── Api/ApiService.cs    BC REST mapping
│   └── Data/DatabaseService.cs
├── BCIntegration.Worker/
│   ├── Program.cs
│   ├── Worker.cs            main loop
│   └── appsettings.json
└── scripts/                 publish-win-x64.ps1, build manifest

---

Troubleshooting

Missing outbound data in BC

1. Find TransmissionMaster with Status IN ('N','E') for the business event.
2. Join the child table from the catalog above on TransmissionMasterSysID.
3. For E, read ReturnMessage (often BC OData error JSON).
4. Confirm the worker service is running and not stuck in BCLedgersOnly mode.

pays / check not updating in SMART

1. Locate TransmissionMaster where TransType = pays for the date.
2. If Status = C but checks wrong, inspect TransmissionPaymentStatus rows (DocumentNo must be numeric PO; AppliedDocNo required).
3. Verify PermanentOrderLog for that PONumber.

Ledger backfill stuck

• Check BCJobLedger max EntryNo vs BC UI.
• Entries on or before 2025-12-31 are intentionally skipped.
• LedgerEntryNo = 0 rows are excluded from GL pairing.

Pause / resume

Use console Ctrl+Shift+P and Space when running interactively; Windows Service deployments rely on log files only.

---

Related

• How SMART talks to Business Central — all queues in the database vs what this worker handles
• Transmission statuses — status code reference
• SMART 2.0 Accounting — operator-facing finance tools