Skip to main content

Scenario: Import journals in bulk with set-based data management

Goal. Load a large file of journal lines (thousands to hundreds of thousands of lines) into D365 as ready-to-post journals, in minutes instead of hours, and know exactly which lines were refused and why. The lines land in journals of the right type, numbered from the journal name's number sequence, and post with the standard posting.

When to use. Use the set-based import entities when the volume is too big for one service call per journal: a nightly store or warehouse feed, a count upload, a lockbox or payment file, a month of invoices from a billing platform, a timesheet or expense feed, a price list, an MES feed, a migration. They cover inventory, customer payment, customer invoice, vendor payment, vendor invoice, project expense, project hour and fee, trade agreement, and production picking list, report as finished and route card journals, plus demand forecast lines, BOM lines, bank statement lines and fixed asset books.

Use the posting services instead when your system needs one journal posted and its number back in the same call (Inventory journals, Customer payment and settlement, Project journals and invoicing and the others). A set-based import creates the journals; posting them is a separate step (below).

Prerequisites​

  1. Security. The user or application that runs the import needs data management access (for an integration, an application registered on System administration > Setup > Microsoft Entra ID applications with a user that can run imports) and the entity's ...Maintain privilege, for example MGCLatticeSetBasedInventoryJournalLineEntityMaintain. The privileges are in the duty MGCLatticeDataEntitiesMaintain of the roles MGCLatticeIntegrationAdministratorRole and MGCLatticeIntegrationOperatorRole. See Security model.
  2. The entity is registered set-based. On Data management > Data entities, find the entity (for example Inventory journal lines (set-based)) and check that Set-based processing is selected. It is by default; if someone turned it off, the import refuses every row and says so.
  3. Journal names. One journal name per journal type you import, with its number sequence and voucher series (for example USMF IMov for inventory movements, CustPay for customer payments, GenJrn for customer invoices, S_Price for sales price agreements). The entity's section in Set-based imports lists what each one needs.
  4. Master data. The items, accounts, projects, inventory dimension values and financial dimension values the lines name must exist. The import checks each one and refuses the lines that name one that does not.

Steps​

  1. Build the file. One row per journal line, with the entity's field names as the header (the column tables in Set-based imports). For each line:

    • JournalNumber: an existing open journal to add the line to, or a grouping key of your own (a store number, a batch id, a date). Every distinct key becomes one new journal.
    • JournalNameId: the journal name, for new journals.
    • LineNumber: greater than zero and unique within the journal. Keep it stable for a line, so that sending the same file again is refused line by line instead of duplicating it.
    JournalNumber,JournalNameId,LineNumber,TransactionDate,ItemNumber,InventorySiteId,InventoryWarehouseId,InventoryQuantity,OffsetMainAccountId
    STORE-0417-2026-10-16,IMov,1,2026-10-16,D0001,1,11,-3,601500
    STORE-0417-2026-10-16,IMov,2,2026-10-16,D0003,1,11,-1,601500
    STORE-0522-2026-10-16,IMov,1,2026-10-16,D0001,1,13,-2,601500

    This file creates two movement journals, one per store.

  2. Import it. Either:

    • in the Data management workspace: create an import project, add the entity with your source format, upload the file and select Import in batch; or
    • through the package REST API: zip the file with a Manifest.xml and PackageHeader.xml naming the entity, get an upload URL with GetAzureWriteUrl, upload the package, start it with ImportFromPackage and poll GetExecutionSummaryStatus until it finishes.

    Name the entity by its data management name, for example Inventory journal lines (set-based).

  3. Read the outcome. The execution ends Succeeded when every row was written, PartiallySucceeded when some rows were refused, and Failed when none were. Refused rows and their messages are in the staging data (View staging data > Validation errors) or, through the API, in GetExecutionErrors.

  4. Post the journals. The import creates open journals, so you can review them first. Post them from the journal forms, with the standard batch posting of the journal type, or from your system with the journal number: postLedgerJournal, postInventoryJournal, postProjectJournal, postProductionJournal or postTradeAgreementJournal post a journal that already exists, as its page's Post does (Post an existing journal). The new journal numbers are in the staging rows (the grouping key in JournalNumber is replaced with the journal it went to).

How to verify​

  • The execution summary shows the number of rows written per entity.
  • The new journals are listed on the journal page of their type (for example Inventory management > Journal entries > Items > Movement) with the number of lines you sent.
  • Every staging row is either Completed or Error; none are left Not started after a successful run.

When it goes wrong​

What you seeWhyWhat to do
Every row refused: "<entity> imports only with set-based processing"Set-based processing was turned off for the entityTurn it on (Data management > Data entities) and import again
Some rows Error with a messageThose rows broke a rule (unknown item, line number already used, journal posted...)Fix the rows in your source and send just them again; the other rows were written
The execution failed with no row-level message, rows still Not startedSomething failed while writing; the whole transfer was rolled backFix the cause in the execution log and run the import again; nothing was written twice
Rows refused with "The journal already has a line with this line number."The file was sent twice, or two files used the same lines for one journalNothing to undo: the first import's lines stand. Use new line numbers only for new lines
ImportFromPackage cannot find the entityThe entity is registered under its AOT name on this environment (typically a development box where it was registered before its labels)Use the name shown on Data management > Data entities, for example MGCLatticeSetBasedInventoryJournalLineEntity
New fields of an entity are missing after a deploymentData management keeps the entity's old field listRefresh entity list in Data management and regenerate the project's mapping