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 importOnecProductsWorkflow workflow (import-onec-products). It runs on every catalog batch of up to 100 products, before they're compared with Medusa products. A 10,000-product catalog calls it 100 times.

src/workflows/hooks/onec-catalog.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { importOnecProductsWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4importOnecProductsWorkflow.hooks.setProducts(async ({ products, properties }, { container }) => {
5  // ...
6
7  return new StepResponse({ products })
8})

The handler receives the batch's products and the classifier properties:

The exchange fills title, description, handle, external_id, type_id, status, metadata, category_ids and sales_channels in product, and thumbnail and images only when 1C sent images. It doesn't fill subtitle, weight, length, height, width, origin_country, hs_code, mid_code, material, collection_id and discountable. A handler can set them, and the import writes them the same way as the rest.

Return new StepResponse({ products }). The handler may edit product and remove a product from the batch. What it can't do:

• return a product that wasn't in the batch, or the same product twice;
• change existing;
• delete or change external_id and metadata.onec.id of a new product, because without them the next exchange creates the product again;
• change external_id and metadata.onec.id of an existing product. Deleting these keys is allowed, and the fields then stay as they are.

After the hook, the plugin compares product with existing and writes only the fields that differ. It creates a product that has no existing. A product removed from the batch is neither created nor updated in this exchange.

---

A hook of the importOnecPricesWorkflow workflow (import-onec-prices). The workflow runs inside the offers import, so the hook runs on every offers batch of up to 100 products with all their offers, before reconciling with Medusa.

src/workflows/hooks/onec-prices.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { importOnecPricesWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4importOnecPricesWorkflow.hooks.setPriceLists(async ({ priceLists }, { container }) => {
5  // ...
6
7  return new StepResponse({ priceLists })
8})

The handler receives one element per non-retail price type from offers.xml. The plugin writes the retail type to the variant price, and the hook doesn't get it:

Return new StepResponse({ priceLists }). A key the handler puts into priceList, such as rules or status, is written by the import if it differs from what's stored. The constraints are:

• you can't return a price type that wasn't in the batch, or the same type twice;
• you can't change existing;
• a price must belong to a variant from this batch, amount must be a number, and a variant can't have two prices in the same currency.

After the hook, the plugin creates price lists for new price types and marks them with metadata.onec.price_type_id. For existing ones, it writes the changed priceList keys and reconciles prices by variant and currency, adding new ones, updating changed ones and removing extra ones. A price type removed from the list isn't touched at all in this batch, neither the price list nor its prices.

---

A hook of the exportOnecOrdersWorkflow workflow (export-onec-orders). 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.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4exportOnecOrdersWorkflow.hooks.setOrders(async ({ orders }, { container }) => {
5  // ...
6
7  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 date, time, operation, role, currency, rate and sum fields. You can edit them as well, and they go into the XML as they are.

Return new StepResponse({ orders }). The handler may edit document and remove an order from the export. It can't return an order that wasn't in the export, return an order twice, or change document.id.

After the hook, the plugin builds orders.xml 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, exportOnecCatalogWorkflow (export-onec-catalog) and exportOnecOrdersWorkflow (export-onec-orders). It runs once per export, when the XML is already built. In the order export, it runs after setOrders. It's a fallback for what the product or document model doesn't cover, for example the schema version your 1C configuration expects.

src/workflows/hooks/onec-payload.ts
1import { StepResponse } from "@medusajs/framework/workflows-sdk"
2import { exportOnecCatalogWorkflow, exportOnecOrdersWorkflow } from "@gorgo-store/medusa-erp-1c/workflows"
3
4exportOnecCatalogWorkflow.hooks.setPayload(async ({ payload }) => {
5  // ...
6
7  return new StepResponse({ payload })
8})
9
10exportOnecOrdersWorkflow.hooks.setPayload(async ({ payload }) => {
11  // ...
12
13  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 new StepResponse({ payload }) with a string. Without a handler, the plugin's XML goes to 1C. setOrders decides which orders get the exported mark, not this hook.

---

@gorgo-store/medusa-erp-1c/hooks exports two functions that read the values of a 1C product the way CommerceML lays them out.

readRequisite(source, name): string | undefined

The first value of a requisite from ЗначенияРеквизитов, found by its Наименование. The name is compared exactly, including spaces and case. In 1C it's free text, and Полное наименование and ПолноеНаименование are different requisites. If there's no such requisite, the function returns undefined.

readProperty(source, properties, nameOrId): string[]

The values of a property from ЗначенияСвойств. The property is looked up by Ид or by name, and reference values are expanded through properties from the hook input. A lookup by name collects all properties with that name, because 1C may create its own "Бренд" (brand) property for each category. If there's no value, the function returns an empty array.

---