Uniconta - Item Update

This function synchronizes item data from Uniconta ERP to the App4Sales platform. It retrieves various item-related information, including basic item details, prices, stock levels, images, categories, and descriptions, and maps them to the internal App4Sales item structure. The synchronization process can handle both standard items and items with variants, and it considers several connector settings to tailor the data transfer.

Data Source Configuration

The connector retrieves item data directly from the Uniconta ERP system via its API. Key data sources include:

Items: All active items (`InvItemClient`) are retrieved.
VAT Codes: VAT percentages (`GLVatClient`) are fetched based on configured VAT codes.
Item Categories: Item group definitions (`InvGroupClient`) are retrieved.
Price Lists: Customer price lists (`DebtorPriceListClient`) are retrieved and updated in App4Sales.
Item Prices: Specific item prices per price list (`InvPriceListLineClient`) are retrieved.
Selected Variants: Configured item variants (`InvVariantCombiClient`, `InvVariantDetailClient`) are retrieved. This is controlled by the 'Disable selected variants' setting.
Standard Variants: Standard item variants (`InvStandardVariantClient`, `InvStandardVariantCombiClient`) are retrieved. This is controlled by the 'Disable standard variants' setting.
Variant Stocks: Stock levels for item variants (`InvItemStorageClient`) are retrieved if selected or standard variants are not disabled.
Item Notes: User-defined notes (`UserNotesClient`) linked to items are retrieved.
Item Descriptions: Multi-language item descriptions (`InvItemTextClient`, `InvItemNameGroupClient`) are retrieved.
Item Pictures: Image attachments (`UserDocsClient`) associated with items are retrieved. This feature respects a daily request limit of 5000 and can be disabled.

Data Mapping Table: Items

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`InternalItemCode`	`InvItemClient._Item`	Uniconta's internal identifier for the item.
`Sysmodified`	`InvItemClient.UpdatedAt`	Timestamp of the last modification in Uniconta.
`Currency`	`InvItemClient._Currency1`	The primary currency of the item. Converts the Uniconta currency enum to a string.
`Description`	`InvItemClient._Name`	The main name or description of the item.
`EanCode`	`InvItemClient._EAN`	The European Article Number for the item.
`ItemCode`	`InvItemClient._Item`, Variant values	If `UseVariantsAsPartOfItemCode` is enabled, the `ItemCode` is composed of `InvItemClient._Item` followed by variant values (e.g., `ITEMCODE~VARIANT1~VARIANT2`). Otherwise, it's just `InvItemClient._Item`.
`SalesPrice`	`InvItemClient._SalesPrice1`	The first sales price defined in Uniconta.
`LastAvailableStock`	`InvItemStorageClient.Available`, `InvItemClient.Available`	Available stock. Prioritizes variant-specific stock if found; otherwise, uses the stock from the base item.
`Unit`	`InvItemClient._Unit`	The unit of measure for the item.
`VatIncluded`	Connector Setting: `ItemsAreVatIncluded`	Set to 'I' if `ItemsAreVatIncluded` is true, 'E' otherwise.
`VatPercentage`	Derived from `GLVatClient.Rate`	The VAT percentage associated with the item's configured VAT code.
`ItemType`	`InvItemClient._ItemType`	The type of item (e.g., 'Inventory', 'Service'). Converts the Uniconta item type enum to a string.
`PurchasePackageSize`	`InvItemClient._SalesQty`, `InvItemClient._PurchaseMin`, `InvItemClient._PurchaseQty`, Connector Settings	If `UseDefaultSalesQuantityAsPps` is true, uses `InvItemClient._SalesQty`. Else if `UseMinimumPurchaseQuantityForPackageSize` is true, uses `InvItemClient._PurchaseMin`. Else, uses `InvItemClient._PurchaseQty`.
`PicturesBytes`	`UserDocsClient` (image attachments)	Raw byte data of item images from Uniconta attachments (PNG, JPEG, BMP, GIF).
`NextDelivery`	User-defined field (`InvItemClient.UserFields`)	Date retrieved from the user-defined field specified by `ItemUserFieldForNextDeliveryDate` setting. Must be a valid date format.
`ItemStatus`	User-defined field (`InvItemClient.UserFields`)	Status retrieved from the user-defined field specified by `CustomFieldForItemStatus` setting.
`Description2`, `Description3`, `Description4`, `Description5`	`InvItemTextClient.Text`, `InvItemNameGroupClient._Language`	Additional descriptions populated based on retrieved multi-language descriptions and the configured language codes for description fields.

Data Mapping Table: Item Categories

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ProductCategory`	`InvItemClient._PrCategory`	Product category from Uniconta.
`CategoryGroup`	`InvItemClient._CategoryGroup`	Category group from Uniconta.
`Weight`	`InvItemClient._Weight`	Item weight.
`Volume`	`InvItemClient._Volume`	Item volume.
`PurchaseMin`	`InvItemClient._PurchaseMin`	Minimum purchase quantity.
`PurchaseQty`	`InvItemClient._PurchaseQty`	Standard purchase quantity.
`Item group`	`InvGroupClient.Name` (lookup by `InvItemClient._Group`)	The name of the item group to which the item belongs.
`Discount group`	`InvItemClient._DiscountGroup`	The discount group assigned to the item.
User-defined fields	`InvItemClient.UserFields`	All user-defined fields configured in Uniconta for items are mapped as item categories.
`Variant1` to `Variant5`	`ItemSelectedVariants.VariantXValue`	Values for up to 5 variants if `UseVariantsAsPartOfItemCode` is enabled.
`Notes`	`UserNotesClient`	Concatenated text from all user notes associated with the item.

Data Mapping Table: Price Lists and Prices

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`PriceList.Id`	Derived from `Currency`	A hash code generated from the currency name (e.g., EUR, USD) is used as the PriceList ID.
`PriceList.Code`	Currency (e.g., EUR)	The currency name is used as the PriceList Code.
`PriceList.Currency`	Currency (e.g., EUR)	The currency name is used as the PriceList Currency.
`PriceList.Selectable`	Hardcoded	Always `false` for these generated price lists.
`PriceList.ExternalCurrency`	Currency (e.g., EUR)	The currency name is used as the External Currency.
`PriceListPrice.ItemCode`	Item Code	The item code to which this price applies.
`PriceListPrice.Price`	`InvPriceListLineClient.Price`, `InvPriceListLineClient.Discount`, `InvPriceListLineClient.Pct`, `InvItemClient.SalesPrice1`/`SalesPrice2`/`SalesPrice3`	Prices are determined based on a hierarchy: direct item price, discount group price, then item group price. Parent price lists are also considered. Calculation: `basePrice - unicontaPrice.Discount - basePrice * unicontaPrice.Pct / 100`. If only discount/discount percent is specified, the item's default sales price is used as `basePrice`. Otherwise, `unicontaPrice.Price` is used as `basePrice`.
`PriceListPrice.PriceListId`	Derived from Currency	Matches the ID of the generated PriceList.

Special Logic & Filters

Item Filtering (ShouldSyncItem): Items can be filtered based on a boolean user-defined field. If the setting OnlySyncItemsWithCheckedUserField is configured, only items with this user field checked (true) will be synchronized. If the setting is empty, all items are synchronized.
Item Picture Synchronization: Item pictures are retrieved from Uniconta attachments. This process is automatically disabled if AdministrationSession.CurrentSession.PimSettings.UseImagesOnlyFromPIM is true. Additionally, to prevent hitting Uniconta's daily request limit (5000 requests), picture synchronization is automatically disabled unless it's a Sunday (DateTime.Now.DayOfWeek == DayOfWeek.Sunday) or the setting SyncItemPictures is explicitly true. If disabled, a key setting named Uniconta_SyncItemPictures is saved with value "0".
Variant Handling: The system can generate unique item codes for variants by appending variant values (e.g., ITEMCODE~VARIANT1~VARIANT2) if the UseVariantsAsPartOfItemCode setting is enabled.
Language-Specific Descriptions: The connector attempts to populate additional description fields (Description2-5) based on the most populated languages found in item descriptions, excluding the main language. The default language for description field 1 is determined by AdministrationSession.CurrentSession.Administration.DefaultLanguageCode or overridden by LanguageCodeForDefaultItemNames setting if valid.
Stock Calculation (ToItemStocksDictionary): Stock values consider both base item stock (`InvItemClient`) and variant-specific stock (`InvItemStorageClient`). If the setting DetermineNextDeliveryDateAndToBeReceivedAmountBasedOnPurchaseOrders is enabled, next delivery dates and 'to be received' quantities are calculated based on Uniconta purchase orders and lines.

Domain Specifics (Expanded)

Price Logic

Uniconta item prices are retrieved from InvPriceListLineClient and InvItemClient. The system constructs custom price lists in App4Sales based on the currency of the sales prices (SalesPrice1, SalesPrice2, SalesPrice3) defined in Uniconta. The price determination follows a hierarchy:

Direct Item Price: Price defined explicitly for the item in a price list.
Discount Group Price: Price defined for the item's discount group within a price list.
Item Group Price: Price defined for the item's item group within a price list.

Prices can also be inherited from parent price lists (DebtorPriceListClient.LinkToPricelist). When multiple prices apply, the one with the highest priority (Direct > Discount Group > Item Group) and lowest quantity threshold is chosen. Price calculation subtracts any specified discount amount and percentage from the base price.

Image Handling

Images are sourced from Uniconta's attachments functionality, specifically UserDocsClient records linked to items. The connector only processes image files with extensions PNG, JPEG, BMP, or GIF. There is no explicit filename-to-item matching logic other than the attachment being linked to the item's RowId in Uniconta. The system performs no resize or compression; raw byte data is transferred. Synchronization is subject to a daily API request limit (5000) and is automatically managed by the connector to avoid exceeding it, potentially disabling sync on non-Sundays.

Stock & Availability

Stock information (`LastAvailableStock`) is determined by looking at available stock on the `InvItemClient` and, if variants are used, on the `InvItemStorageClient`. If DetermineNextDeliveryDateAndToBeReceivedAmountBasedOnPurchaseOrders is enabled, the 'To Be Received' quantity and `NextDeliveryDate` are calculated from Uniconta purchase orders (`CreditorOrderClient`) and their lines (`CreditorOrderLineClient`), specifically considering quantities not yet delivered. Otherwise, 'To Be Received' comes from `InvItemClient.QtyOrdered`.

Matrix & Attributes

Variant handling is supported for both selected variants (`InvVariantCombiClient`, `InvVariantDetailClient`) and standard variants (`InvStandardVariantClient`, `InvStandardVariantCombiClient`). When variants are used, the App4Sales ItemCode will include the variant values. Up to 5 variant values (Variant1 to Variant5) can be mapped as item categories. Item attributes are primarily mapped from Uniconta's item categories (`_PrCategory`, `_CategoryGroup`, `_Group`, `_DiscountGroup`) and all user-defined fields associated with an item. Item notes are also concatenated and mapped as an 'Notes' item category.

Related Settings & Prerequisites

Company ID: Uniconta Company ID (Settings.CompanyId).
Uniconta API Key: (settings.UnicontaApiKey).
Uniconta Username & Password: Credentials for Uniconta API access (settings.UnicontaUsername, settings.UnicontaPassword, or Session.Administration.Username, Session.Administration.Password).
Use variants as part of item code: (UseVariantsAsPartOfItemCode) - If enabled, variant values are appended to the item code.
Disable selected variants: (DisableSelectedVariants) - If true, selected variants are not processed.
Disable standard variants: (DisableStandardVariants) - If true, standard variants are not processed.
Only sync items with checked user field: (OnlySyncItemsWithCheckedUserField) - Specifies a boolean user-defined field in Uniconta. Only items where this field is checked will be synced.
VAT Code used for items: (VatCodeUsedForItems) - Specifies the VAT code to use for items.
Items are VAT included: (ItemsAreVatIncluded) - Determines if sales prices include VAT.
Use default sales quantity as purchase package size: (UseDefaultSalesQuantityAsPps) - If true, uses the default sales quantity for purchase package size.
Use minimum purchase quantity for package size: (UseMinimumPurchaseQuantityForPackageSize) - If true and UseDefaultSalesQuantityAsPps is false, uses the minimum purchase quantity for package size.
Item user field for next delivery date: (ItemUserFieldForNextDeliveryDate) - Specifies a user-defined field in Uniconta that contains the next delivery date.
Custom field for item status: (CustomFieldForItemStatus) - Specifies a user-defined field in Uniconta that contains the item status.
Language code for default item names: (LanguageCodeForDefaultItemNames) - Overrides the default language code for item descriptions.
Determine next delivery date and to be received amount based on purchase orders: (DetermineNextDeliveryDateAndToBeReceivedAmountBasedOnPurchaseOrders) - If enabled, stock calculations consider open purchase orders for 'to be received' and next delivery dates.

Known Limitations

Image Sync Frequency: Due to Uniconta API limitations (5000 requests/day), image synchronization is throttled and potentially disabled on most days, being fully enabled only on Sundays.
Image Processing: No resizing or compression of images is performed; images are transferred as raw byte data.
Hardcoded PriceList Selectable: The automatically generated price lists in App4Sales (based on Uniconta currencies) are marked as non-selectable.

Uniconta - Item sync