Dynamics 365 Business Central Item XML
The XML format documented here is used for both the import and export of items in Dynamics 365 Business Central.
We recommend that the ExternalId field be populated with the unique ID of the items from the external system, Zynk uses this field to track items already imported to prevent duplicates being created in Dynamics 365 Business Central.
Tasks
- Exporting Items from Dynamics 365 Business Central
- Importing Items into Dynamics 365 Business Central
XML
Any fields not documented below are not supported with our imports / exports. Examples of where in the XML the fields should appear are shown in the samples below.
Sample item file:
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<Id>2499d7da-549e-ed11-988a-000d3a3885d3</Id>
<ExternalId>1896-S</ExternalId>
<ODataETag>W/"JzIwOzEzNzc1NTQyNTYwMTE3ODMwMTE5MTswMDsn"</ODataETag>
<Number>1896-S</Number>
<DisplayName>ATHENS Desk</DisplayName>
<Type>Inventory</Type>
<ItemCategoryId>b58f3bdf-549e-ed11-988a-000d3a3885d3</ItemCategoryId>
<ItemCategoryCode>TABLE</ItemCategoryCode>
<Blocked>false</Blocked>
<Gtin />
<Inventory>4</Inventory>
<UnitPrice>649.4</UnitPrice>
<PriceIncludesTax>false</PriceIncludesTax>
<UnitCost>506.6</UnitCost>
<TaxGroupId>00000000-0000-0000-0000-000000000000</TaxGroupId>
<TaxGroupCode />
<BaseUnitOfMeasureId>2d8c3bdf-549e-ed11-988a-000d3a3885d3</BaseUnitOfMeasureId>
<LastModifiedDateTime>2023-01-27T15:14:17.27Z</LastModifiedDateTime>
<ItemCategory>
<Id>b58f3bdf-549e-ed11-988a-000d3a3885d3</Id>
<ODataETag>W/"JzIwOzE0NTM3Mjc4ODY4Nzk2OTAwODkzMTswMDsn"</ODataETag>
<Code>TABLE</Code>
<DisplayName>Assorted Tables</DisplayName>
<LastModifiedDateTime>2023-01-27T15:12:05.163Z</LastModifiedDateTime>
</ItemCategory>
<Picture>
<Id>2499d7da-549e-ed11-988a-000d3a3885d3</Id>
<ODataETag>W/"JzIwOzExNTY5NDg5Mjk3NzMzMzM1Nzg0MTswMDsn"</ODataETag>
<ParentType>Item</ParentType>
<Width>500</Width>
<Height>375</Height>
<ContentType>image/jpeg</ContentType>
<PictureContentEditLink>https://api.businesscentral.dynamics.com/v2.0/PRODUCTION/api/v2.0/companies(bba482b8-549e-ed11-988a-000d3a3885d3)/items(2499d7da-549e-ed11-988a-000d3a3885d3)/picture/pictureContent</PictureContentEditLink>
<PictureContentReadLink>https://api.businesscentral.dynamics.com/v2.0/PRODUCTION/api/v2.0/companies(bba482b8-549e-ed11-988a-000d3a3885d3)/items(2499d7da-549e-ed11-988a-000d3a3885d3)/picture/pictureContent</PictureContentReadLink>
<PictureContent><!-- base 64 encoded content here --></PictureContent>
</Picture>
<DefaultDimensions />
<ItemVariants />
</Item>
</Items>
In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the Items schema is used below as a reference of where fields should be in the object model.
Item
The following information can be found within the 'Item' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| - | Id | Guid | Optional | Used for matching existing items |
| - | ExternalId | string | Optional | Stored in Zynk's internal DB and used for matching existing items |
| No. | Number | string | Optional | Used for matching existing items. The next number will be used when creating a new item if not specified |
| Description | DisplayName | string | Optional | |
| Blocked | Blocked | bool | Optional | |
| Type | Type | string | Required | Can be 'Inventory', 'Service', or 'Non-Inventory' |
| Base Unit of Measure | BaseUnitOfMeasureId | Guid | Optional | |
| Base Unit of Measure | BaseUnitOfMeasureCode | string | Optional | Performs a lookup for the unit of measure based on code |
| Last Date Modified | LastModifiedDateTime | DateTime | Read-only | |
| GTIN | Gtin | string | Optional | |
| Item Category Code | ItemCategoryId | Guid | Optional | |
| Item Category Code | ItemCategoryCode | string | Optional | Performs a lookup for the category based on code |
| Item Category Code | ItemCategory/Code | string | Optional | Used to auto create categories |
| Item Category Code | ItemCategory/DisplayName | string | Optional | Used to auto create categories |
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<Id>2499d7da-549e-ed11-988a-000d3a3885d3</Id>
<ExternalId>1896-S</ExternalId>
<Number>1896-S</Number>
<DisplayName>ATHENS Desk</DisplayName>
<Blocked>false</Blocked>
<Type>Inventory</Type>
<BaseUnitOfMeasureId>2fb4e6b3-611d-ea11-bb2d-000d3a4884fc</BaseUnitOfMeasureId>
<BaseUnitOfMeasureCode>PCS</BaseUnitOfMeasureCode>
<LastModifiedDateTime>2020-03-16T17:12:43.153Z</LastModifiedDateTime>
<Gtin>12345678</Gtin>
<ItemCategoryId>b58f3bdf-549e-ed11-988a-000d3a3885d3</ItemCategoryId>
<ItemCategoryCode>TABLE</ItemCategoryCode>
<ItemCategory>
<Code>TABLE</Code>
<DisplayName>Assorted Tables</DisplayName>
</ItemCategory>
</Item>
</Items>
Inventory
The following information can be found within the 'Inventory' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Inventory | Inventory | decimal | Read-only |
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<Inventory>4</Inventory>
</Item>
</Items>
Costs & Posting
The following information can be found within the 'Costs & Posting' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Unit Cost | UnitCost | decimal | Optional |
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<UnitCost>506.6</UnitCost>
</Item>
</Items>
Prices & Sales
The following information can be found within the 'Prices & Sales' section.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| Unit Price | UnitPrice | decimal | Optional | |
| Price Includes VAT | PriceIncludesTax | bool | Optional |
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<UnitPrice>649.4</UnitPrice>
<PriceIncludesTax>false</PriceIncludesTax>
</Item>
</Items>
Miscellaneous
The following information is not visible within Dynamics 365 Business Central.
| Dynamics Field | XML Field | Type | Input | Notes |
|---|---|---|---|---|
| - | ODataETag | string | Optional | Specify the last value to prevent updates if the record has since been modified |
| - | TaxGroupId | Guid | Optional | |
| - | TaxGroupCode | string | Optional | Performs a lookup for the tax group ID based on name |
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Item>
<ODataETag>W/"JzQ0O1NzWWgzTUw1VG53TW5vdlpiM0lPVlZpYkVUcVhhV2k4elhWVWpqUzJsVGc9MTswMDsn"</ODataETag>
<TaxGroupId>00000000-0000-0000-0000-000000000000</TaxGroupId>
<TaxGroupCode />
</Item>
</Items>