Auto Pack Fulfillment

Auto Pack an Item Fulfillment

When to use this skill

Use when the user says any of:

• "auto pack this IF" / "run auto pack for <fulfillment>"
• "why did it build 8 cartons" / "the carton count is wrong"
• "Auto Pack failed" / pastes an Auto Pack error
• "unpack and repack this fulfillment"
• "the cartons didn't show up after I clicked Auto Pack"

Configuring the pack rule is configure-packing-groups. This skill is for running the pack and explaining what came out.

Prerequisites

• A customer .env at ~/orderful-onboarding/<slug>/.env
• The items on the fulfillment resolve to a pack config — either a packing group or custitem_orderful_units_p_carton. Auto Pack hard-errors before writing anything otherwise
• The fulfillment is not already packed. Auto Pack refuses to add to an existing pack

Step 1 — Predict the carton count first

Predict before you run, so an unexpected result is visibly unexpected rather than quietly accepted.

Carton count does not depend on the strategy:

numberOfCartons = ceil(totalQuantity / unitsPerCarton)

Strategy only changes the distribution across that fixed count:

Even Distribution never produces fewer cartons. If someone wants fewer, larger cartons, the fix is a bigger unitsPerCarton, not a strategy change.

Resolve what config the items will actually use:

node ../configure-packing-groups/audit-packing-config.mjs ~/orderful-onboarding/<slug> --item <itemId> --customer <customerId>

It prints every assignment for the item, which one wins, and whether the result is the group or a silent fallback to the item field.

Then account for the grouping key — items are grouped by:

itemInternalId : locationInternalId : packingGroupId

The same item shipping from two locations yields separate cartons even with identical config. That is the usual answer to "why did I get twice as many cartons as I expected".

Step 2 — Run Auto Pack

Use the product path: the Auto Pack button on the Item Fulfillment, served by the buttonHandler Suitelet.

The SuiteApp's testHook RESTlet does expose autoPackFulfillment and unpack actions, but do not reach for them. Sandbox SuiteApp versions are routinely downlevel from the source repo, so an action that exists in source is often not deployed, and each probe costs a permission prompt and a round of log review. Use the RESTlet only if a script in this repo already invokes that action.

Above 20 cartons, the work is handed to orderful_bulkCartonCreation_MR and the button returns immediately:

Auto Pack initiated for N. This is being processed in the background and may take a few minutes to complete. Please refresh the page to see the created cartons.

The cartons do not exist yet when that message appears. Any script that packs and then reads cartons must poll rather than read once. Below 20 cartons the work is synchronous and complete on return. See monitor-mr and reference/mapreduce-monitoring.md.

Step 3 — Verify what was built

SELECT id,
       custrecord_orderful_carton_sequence AS seq,
       custrecord_orderful_carton_is_pallet AS pallet,
       custrecord_orderful_carton_length AS len,
       custrecord_orderful_carton_weight AS wt,
       custrecord_orderful_carton_pallet AS parent
FROM customrecord_orderful_carton
WHERE custrecord_orderful_carton_fulfillment = <ifId>
ORDER BY seq

Two signals tell you which config path actually won — useful when the carton count is right but you are not sure the group was applied:

If you expected a group and got null dimensions, the group silently failed to resolve. Run the audit script's --item mode to find out which of the four silent-null causes applied.

Step 4 — Unpack when you need to repack

Auto Pack refuses to run on an already-packed fulfillment, so iterating means unpacking first. Use the Unpack button.

Sales Order-packed cartons are handed back to the order, not deleted. Cartons packed pre-fulfillment carry custrecord_orderful_carton_sales_order; unpacking the IF clears the fulfillment reference and returns them to the Sales Order for re-transfer. Deleted-carton counts will not match your expectation on those, and that is correct behavior.

Error messages

Every message below is thrown before anything is written, so a failed Auto Pack leaves no partial cartons.

Two save paths, two validators

Auto Pack and the packing SPA both write via CartonRepository but validate differently — a carton shape accepted by one is not guaranteed acceptable to the other. This has drifted before in production. The comparison table is in reference/packing-groups.md.

The practical consequence: if a pack succeeds in the SPA and the same shape fails from Auto Pack, do not assume data corruption — check the validator differences first.

Behaviour rules

1. Predict, then run. State the expected carton count before packing. An unexplained count is a config problem, not a rounding quirk
2. Never conclude "no cartons were created" from a single read above the 20-carton threshold. Poll — the Map/Reduce may still be running
3. Do not use the testHook RESTlet for Auto Pack or unpack unless a script in this repo already calls that action on this account
4. Check dimensions to confirm the path. Correct carton count does not prove the packing group was used; null dimensions mean it silently was not
5. Unpack before repacking. Do not delete carton records by hand to work around the already-packed guard — the unpack path also handles the Sales Order hand-back
6. Check the partner's ASN hierarchy before introducing pallets. A Tare HL that a flat-ASN partner (BSN05 0001) does not expect will be rejected, and Orderful's validator will not catch it

Reference material

• reference/packing-groups.md — resolution precedence, distribution math, validator drift
• configure-packing-groups — setting up the pack rule
• build-mock-fulfillments — the IF→856 cycle this fits into
• monitor-mr — tracking the bulk carton creation Map/Reduce