This reference describes when each hook runs, what its handler receives and may return, and what the plugin does with the result. The rules shared by all hooks are on the Workflow Hooks page.
A hook of the workflow (). It runs on every catalog batch of up to 100 products, before they're compared with Medusa products. With a 10,000-product catalog, it runs 100 times.
src/workflows/hooks/onec-catalog.ts1import { StepResponse } from "@medusajs/framework/workflows-sdk"2import { importOnecProductsWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"34importOnecProductsWorkflow.hooks.setProducts(async ({ products, properties }, { container }) => {5 // ...67 return new StepResponse({ products })8})
The handler receives the batch's products and the classifier properties:
The exchange fills , , , , , , and in , and and only when 1C sent images. A new product has , and an existing one has it only when Update the handle when a product is renamed in 1C is on and the name changed in 1C. The exchange sets to on every product, including one unpublished by hand. To keep some products as drafts, set in the handler, as in the Draft for Products Hidden on the Site example. It doesn't fill , , , , , , , , , and , but a handler can set them, and the import writes them like the rest.
Return . The handler may edit and remove products from the batch. It can't:
After the hook, the plugin compares with and writes only the fields that differ. The plugin creates a product that has no . A product removed from the batch is neither created nor updated in this exchange.
A hook of the workflow (). The workflow runs inside the offers import, so the hook is called on every offers batch (up to 100 products with all their offers). It runs after the plugin has matched the offers to Medusa variants and decided their SKUs, and before the comparison with Medusa.
src/workflows/hooks/onec-variants.ts1import { StepResponse } from "@medusajs/framework/workflows-sdk"2import { importOnecVariantsWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"34importOnecVariantsWorkflow.hooks.setVariants(async ({ products, properties }, { container }) => {5 // ...67 return new StepResponse({ products })8})
The handler receives the batch's products that already exist in Medusa, along with the offers package properties. The plugin skips the offers of a product that isn't in Medusa yet before calling the hook:
The exchange doesn't fill , , and , but a handler can set them, and the import writes them like the rest.
Return . The handler may edit variants, remove variants from and remove products from the batch. It can't:
After the hook, the plugin derives the product's options from the resulting variants. An option with the same title as before the hook keeps its link to the 1C property and its dictionary, and a value missing from the dictionary is added to it. An option with a new title is created without a link to a property, with the values found in the variants. The plugin then compares the variants with and writes the set only when something in it changed. Medusa deletes a variant removed from . A product removed from the batch keeps its variants and options unchanged in this exchange.
The plugin finds an option with a new title by that title only within one batch. In the following batches the title is already taken, and their products get a separate option instead of the shared one. So rename options in 1C, and change variant fields and values in the handler.
A hook of the workflow (). The workflow runs inside the offers import, so the hook runs on every offers batch (up to 100 products with all their offers) before reconciling with Medusa.
src/workflows/hooks/onec-prices.ts1import { StepResponse } from "@medusajs/framework/workflows-sdk"2import { importOnecPricesWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"34importOnecPricesWorkflow.hooks.setPriceLists(async ({ priceLists }, { container }) => {5 // ...67 return new StepResponse({ priceLists })8})
The handler receives one element per non-retail price type from . The plugin writes the retail type to the variant price, so the hook doesn't get it:
Return . If the handler puts a key into , such as or , the import writes it when its value differs from the stored one. The constraints are:
After the hook, the plugin creates price lists for new price types and marks them with . In existing ones, it writes the changed keys and reconciles prices by variant and currency. The plugin adds new prices, updates changed ones and removes extra ones. If you remove a price type from the list, the plugin touches neither its price list nor its prices in this batch.
A hook of the workflow (). It runs once per order export to 1C, before the XML is built. The export includes orders that aren't canceled, haven't been exported yet, and didn't come from 1C.
src/workflows/hooks/onec-orders.ts1import { StepResponse } from "@medusajs/framework/workflows-sdk"2import { exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"34exportOnecOrdersWorkflow.hooks.setOrders(async ({ orders }, { container }) => {5 // ...67 return new StepResponse({ orders })8})
The handler receives every order together with the CommerceML document it goes to 1C as:
The document also has the , , , , , and fields. You can edit them as well, and they go into the XML unchanged.
Return . The handler may edit and remove orders from the export. It can't return an order that wasn't in the export, return the same order twice, or change .
After the hook, the plugin builds from the documents and hands it to 1C. Orders get the exported mark only once 1C confirms it received them. An order removed from the export doesn't get the mark and goes out with the next export.
Two workflows have this hook, () and (). It runs once per export, when the XML is already built, and in the order export it runs after . It's a fallback for changes that the product or document model can't express, for example the schema version your 1C configuration expects.
src/workflows/hooks/onec-payload.ts1import { StepResponse } from "@medusajs/framework/workflows-sdk"2import { exportOnecCatalogWorkflow, exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"34exportOnecCatalogWorkflow.hooks.setPayload(async ({ payload }) => {5 // ...67 return new StepResponse({ payload })8})910exportOnecOrdersWorkflow.hooks.setPayload(async ({ payload }) => {11 // ...1213 return new StepResponse({ payload })14})
These are two separate hooks, and each one is registered on its own workflow. The handler receives the XML as a string:
Return with the resulting XML string. Without a handler, the XML built by the plugin goes to 1C. decides which orders get the exported mark, not this hook.
exports two functions that read the values of a 1C product the way CommerceML lays them out.
readRequisite(source, name): string | undefined
Returns the first value of a requisite from , found by its . The name is compared exactly, including spaces and case. In 1C a requisite name is free text, so and are different requisites. If there's no such requisite, the function returns .
readProperty(source, properties, nameOrId): string[]
Returns the values of a property from . The function looks the property up by or by name, and expands reference values through from the hook input. A lookup by name collects all properties with that name, because 1C may have a separate "Бренд" (brand) property for each category. If there are no values, the function returns an empty array.