How to Guides

These walkthroughs assume you already installed the plugin and set J2Commerce Attachment folder path. They focus on repeatable admin tasks after the first sync works once.

How do I add a new extension product to the map?

Create or identify the J2Commerce downloadable product and note its numeric product ID. Create the package folder under free or pro on disk and drop at least one correctly named package_version.zip into it. Add a new map line with product_id|free/package or product_id|pro/package and optional keep_prior, changelog, and label fields. Save the plugin, open the Sync panel tab, and run Sync Now. Confirm product files in J2Commerce show the latest ZIP as the primary managed row.

How do I temporarily stop syncing one product?

Prefix the map line with hash or semicolon so the parser ignores it. Save and run Sync Now if you want to confirm the line is skipped. Remove the comment character when you are ready to sync that product again. Deleting the line works too, but commenting preserves your folder and ID notes for later.

How do I ship a new version without breaking downloads?

Copy the new package_version.zip into the same package folder on the server, overwriting nothing you still need if keep_prior registers older builds. Run Sync Now or wait for cron. Spot-check the product file list and download once. If shoppers use My Downloads or email links, confirm they receive the new filename path after sync, not the previous version string.

How do I register prior GPL ZIPs for transparency?

Set keep_prior to the number of older ZIPs you want retained as additional product files. Sync orders them newest first and stops at your limit. This is useful when GPL policy or customer trust expects older version filenames to remain reachable without manual Add Files clicks after every release.

How do I attach CHANGELOG.md to the product?

Place CHANGELOG.md in the same package folder as the ZIPs and set changelog=1 on that map line. Run Sync. When the file is missing, sync still updates ZIP rows; CHANGELOG attachment simply skips until the file exists.

How do I list versions on a public page?

Place the shortcode pair around a product ID in an article or product description: open brace rcafilesversions, the numeric product ID, close brace slash rcafilesversions. Actual downloads still flow through J2Commerce My Downloads, Direct Download, or your normal product download path after Sync registered the files. See the Frontend article for shopper-facing behavior.

How do I fix legacy paths that started with a slash?

Version 1.0.2 treats legacy J2Commerce save paths with a leading slash as managed rows and normalizes writes to the canonical no-leading-slash form. If Direct Download still read stale index zero before upgrade, run Sync Now after 1.0.2 is installed so the lowest-id row updates to the latest versioned ZIP.