QuickBooks Online Connector - ItemUpdate
This function synchronizes item data from QuickBooks Online into the App4Sales platform. It retrieves items, their categories, and associated images and tax information, then transforms this data into the internal App4Sales item structure before updating the database. The process runs periodically to keep item information up-to-date.
Data Source Configuration
Item data is pulled from the QuickBooks Online API. The connector queries the 'Item' entity, filtering for types 'Inventory', 'Service', and 'NonInventory', excluding 'Category' type items. Attached images are retrieved as 'Attachable' entities with a 'ContentType' like 'image'. Tax codes and rates associated with items are also fetched from the QuickBooks Online API.
Data Mapping Table: Items
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
|
| Determined by connector settings:
|
|
| Direct mapping from QuickBooks Online's internal item identifier. |
|
| Direct mapping from QuickBooks Online's item description. |
|
| Direct mapping from QuickBooks Online's item SKU. |
|
| Direct mapping from QuickBooks Online's item unit price. |
|
| Direct mapping from QuickBooks Online's item type (e.g., "Inventory", "Service"). |
|
| Direct mapping from the item's associated sales tax rate. |
|
| Maps to 'I' if |
|
| Direct mapping from the item's quantity on hand. |
|
| Maps from the item's creation timestamp in QuickBooks Online metadata. Only set if metadata is available. |
| Derived (unknown string/object elements, | Populated by extracting unspecified string and object elements from the QuickBooks Online item, treating them as categories. The item's sales tax code ID is also added as a category named "TaxId". |
| Derived (QuickBooks item categories) | Transformed from QuickBooks Online item categories, especially handling hierarchical categories, into App4Sales' ItemClass and ItemClassValue structure. |
|
| If images are available for the item in QuickBooks Online, their byte data is added. |
Special Logic & Filters
**Item Filtering:** Only items of type 'Inventory', 'Service', and 'NonInventory' are synchronized. Items categorized as 'Category' in QuickBooks Online are excluded.
**Image Download:** Images are downloaded from QuickBooks Online's 'Attachable' entities. The connector specifically requests attachments with a content type indicating an image. Downloads occur in parallel for efficiency.
**Tax Information:** Sales tax codes and their corresponding rates are fetched from QuickBooks Online and linked to the respective items.
**Category to ItemClass Conversion:** The connector attempts to convert QuickBooks Online's flat or hierarchical category structure into App4Sales' `ItemClass` and `ItemClassValue` model. This involves identifying parent-child relationships within categories and mapping them to `ItemClass` descriptions and `ItemClassValue`s for specific items.
**Unknown Elements as Categories:** Any data elements from the QuickBooks Online item that are not explicitly mapped to standard fields are treated as potential item categories. This allows for flexible mapping of custom fields from QuickBooks Online.
Domain Specifics (Expanded)
Price Logic
The base sales price is directly mapped from the UnitPrice field in QuickBooks Online. The connector determines if VAT is included or excluded based on the SalesTaxIncluded flag from QuickBooks Online.
Image Handling
Images associated with items in QuickBooks Online are retrieved as 'Attachable' entities. The connector queries for attachables that have an 'image' content type and links them to the corresponding items using the item's ID. The byte data of these images is stored in App4Sales. The decision to download images is controlled by the 'Use images only from PIM' setting in the administration session; if that setting is enabled, images are not fetched by the connector.
Stock & Availability
The quantity on hand is directly mapped from the QtyOnHand field in QuickBooks Online. There is no explicit logic for multi-warehouse handling, reserved stock deductions, or safety stock buffers within this specific update method.
Matrix & Attributes
QuickBooks Online categories are processed to create App4Sales ItemClass and ItemClassValue entries. This includes logic to handle parent-child category relationships: if a category is a sub-item, its parent category's name might be used as the `ItemClass` description, and the sub-item's name as an `ItemClassValue` for the item.
Related Settings & Prerequisites
The following connector settings influence the Item Update process:
**Use item SKU as ItemCode:** (Boolean) If enabled, the QuickBooks Online SKU is used as the App4Sales ItemCode.
**Include Item ID to ItemCode:** (Boolean) If enabled (and 'Use item SKU as ItemCode' is false), the QuickBooks Online Item ID is prepended to the item name to form the App4Sales ItemCode.
**Use images only from PIM:** (Boolean) Located in the administration session settings. If true, the connector will not download images, deferring image management to a Product Information Management (PIM) system.
Known Limitations
This documentation is based on the provided code. Specific limitations observed include:
ItemCode generation has three distinct modes based on settings, which should be clearly understood by administrators.
Advanced price logic (tier pricing, volume discounts, customer-specific pricing) beyond a single
UnitPriceand tax rate is not explicitly handled in this method.Multi-warehouse stock management is not evident in the provided code for item updates.