Skip to content

Product Documents

You can maintain typed product documents on a BC item – datasheet, manual, declaration of conformity, safety data sheet, brochure, and more. The Shopware 6 connector uploads these documents into the shop's own media and links them via custom fields on the product. Customers find the downloads publicly on the product page.

Maintained centrally in the hub

The documents live centrally in the merchantCENTRAL Hub per BC item (ALN MC Product Document) and are therefore available to all marketplace connectors – not just Shopware. The connector transfers them to the shop.

Opening the page

  • Product documents are maintained on the BC item (hub feature "Product Documents").
  • Transfer happens during the item upload to the shop; the per-shop storage status is tracked internally in Shopware 6 Product Document Media.

Viewing and opening

On the Item Card, the Product Documents group starts with a gallery: one card per document with file type, title, document type, language, file name and where the file lives. One click on a card opens the document – a file in the media storage or behind an external URL opens in the browser, a file stored in Business Central is downloaded. Below it, the Edit Documents list is for type, language, order and files.

The same gallery opens from the Preview Product Documents action on the Item Card – and, in connectors that count documents (Icecat, for one), from a click on the count.

In the lists (Item Card and the global Product Documents list) clicking Open or the file name opens the document as well; Open Document is the first action. In the tile view of the global list each tile shows item no., document type, title, source and file name.

Sources

Each document line has a source – in all cases the file ends up in the shop media (no dead links, shop CDN/caching included):

Source Storage Route into the shop
Item Attachment Standard attachments (Document Attachment) on the item Business Central reads the file and uploads it
Hub File Media field directly on the document line in the hub – inside the BC database Business Central reads the file and uploads it
Media Storage The customer's Azure media storage, the same place the product images live; the line only holds the public URL Shopware fetches the file itself from the CDN URL (upload-from-URL)
External URL just the link (manufacturer PDF) Shopware fetches the file itself (upload-from-URL)

Why the route matters

For Media Storage and External URL the shop only receives the address and fetches the file itself — Business Central never touches the bytes. This requires the shop server to reach that address outbound; for the media storage that is the CDN hostname from the merchantCENTRAL Setup.

If the fetch fails for Media Storage, the connector uploads the file through Business Central instead — slower, but the documents arrive. An External URL has no such fallback: the file never lives in Business Central, and its failure is reported in the result message.

Where downloaded files go

"Hub file" and "Media storage" are not picked by hand — the hub sets them whenever a file actually enters it: through Upload File, through Fetch File from URL, or through a connector such as Icecat fetching it during enrichment. Where the file goes is decided by Document Storage in the merchantCENTRAL Setup:

Setting Effect
Business Central (default) The file sits in the document line's media field. It needs no further configuration but counts against the environment's database quota — the item that matters once a large item range carries datasheets.
Media Storage The file sits in the customer's Azure storage account and only its URL stays in the database. Requires a configured media storage.

Fallback rather than data loss

If the media storage is not configured, or the upload fails, the file is stored in Business Central rather than discarded. The bulk fetch reports such cases in its result message and the single fetch as a note — otherwise nobody would notice that files keep landing in the database against the setting.

The media storage is public

It is the same CDN container the product images use: anyone who knows the URL can fetch the file without signing in. For datasheets, manuals and brochures that is the whole point — for confidential documents it is the wrong place. Keep those in the database with Business Central as the document storage.

Deleting a document line takes its file in the media storage with it, and so does deleting the item, whose documents are cleaned up with it. A delete that bypasses the table trigger (a bulk DeleteAll(false) from other code) leaves the file behind.

Inside the container the path is documents/{company}/{item no.}/{line no.}.{ext}. The company segment matters: enter the same storage account and container in two companies and their files still stay apart.

Settings (setup / per shop)

Field Where Description
Sync Product Documents Shop (override) Whether product documents are uploaded to this shop on item push (Default (Setup) / Yes / No).
Product Documents Field Name Setup / Shop Technical Shopware custom field that receives the document list as JSON text (field type text – the Shopware admin offers no JSON field type; the theme decodes the text). Default ad_documents – set it to the target theme's custom field.
Datasheet URL Field Name Setup / Shop Custom field for the primary datasheet URL. Default ad_datasheet_url.
Upload Documents to Shop Setup / Shop (override) Separate toggle: uploads posted invoices/credit memos as PDF to the shop order (not to the product).

Only changed documents

Unchanged documents are skipped on re-upload (per-shop timestamp comparison). A newer document in the hub triggers a re-upload automatically.

Workflow

  1. Maintain the product documents on the BC item (choose a source per line).
  2. In the shop setup, set the matching custom field (theme) under Product Documents Field Name.
  3. Leave Sync Product Documents at Default (Setup) or Yes per shop.
  4. Upload the item – the documents are loaded into the shop media and linked on the product.
  5. Display the documents on the product page in the storefront/theme (theme-dependent).

Data format (for theme developers)

The custom field carries the document list as JSON text, an array of objects:

[
  {
    "type": "manual",
    "typeLabel": "Manual",
    "title": "User guide",
    "url": "https://shop.example.com/media/…/user-guide.pdf",
    "mediaId": "018f36cd6a1e7c9b…",
    "position": 1
  }
]
Key Meaning
type Stable, language-independent type key – the theme groups and translates by it (snippets). Values: datasheet, manual, certificate, safety_data_sheet, brochure, other. Unknown future types arrive as other.
typeLabel Type caption in the BC session language – readable fallback for themes without their own snippets.
title Document title (left empty → type caption).
url Public media URL of the file in the shop.
mediaId UUID of the media entity in the shop.
position Sort order from the BC document list.

The second field (Datasheet URL Field Name, default ad_datasheet_url) carries, as plain text, the URL of the first datasheet – for themes that show just one prominent datasheet link.