External Service Shipments

What this guide covers

Sending stock out to external service providers (typically repair shops, but the same flow handles any third-party that takes parts out of your warehouse and returns them later). External Service Shipments are the system's name for Repair Order Shipments — same code path, customer-facing label is External Service.

For customer-bound dispatch see Sales Shipments; for internal warehouse moves see Local Shipments.

Where to find it

Open Operations → Shipments → External Service Shipments. The page lists every ROS (Repair Order Shipment), filterable by ROS number, customer, status.

Who can do what

• Warehouse staff — view, create, pick, dispatch, request a courier (Aramex), track waybills, download labels. Page access is by JSF gating; no specific AppPermission is enforced.
• Site admin (ADMIN) — full access.

The Courier Booked badge appears on the row when an Aramex waybill (LAR…) is attached and the shipment isn't yet Dispatched.

The lifecycle (different from other shipments)

Unlike Local / Sales Shipments, External Service Shipments don't have a draft → placed → dispatched workflow with holds. They appear as a single record tied to a Repair Order; you go straight from picking to dispatch when the parts are ready to ship out.

Picking and dispatching

1. From the list, open the row with Process.
2. The picking dialog opens — same UI as Sales Shipments. Pick a bin per line, collect the qty, repeat until every line is fully staged.
3. Click Dispatch to consume the staged stock. The shipment status flips and the linked Repair Order timeline records the outbound move.

Requesting an Aramex courier

The same Aramex dialog that powers Sales Shipments also handles ROS:

1. Click Request Courier on a row.
2. Receiver details pre-fill from the ROS delivery address. The references are slightly different:
   • reference1 — the customer ref on the ROS.
   • reference2 — the ROS number (so the courier label ties back to the ROS).
3. Specify service type, parcels (height / length / width required), pickup date.
4. Submit. The waybill (LAR…) and collection reference (D…) come back; the Courier Booked badge appears.
5. Track Waybill / Track Collection — fetch live status from Aramex.
6. Download Waybill — open the Aramex-hosted PDF.

See Aramex for the integration reference.

Common errors and fixes

The picking + dispatch errors are the same as Local Shipments — refer to that article for the full list. ROS-specific issues are typically Aramex API errors:

• Receiver delivery address is blank — the ROS was created without populated delivery fields. The Aramex form opens with empty receiver inputs; type them in by hand or fix the ROS upstream.
• Aramex API status_description text — surfaces verbatim when status_code != 0. Most common: malformed postal code, suspended account, invalid phone number format. Fix the field and resubmit.
• Mismatched tracking format — tracking is stored as "<waybill_number> | <collection_reference>" (pipe-separated) in customerRef / trackingNumber. If a row's tracking string doesn't parse, the Track buttons go grey; manually editing the field is not advised.

Tips and gotchas

• External Service Shipment is the system's name for "parts going to a repair shop / paint shop / cutting shop / etc." It's not a separate workflow from Repair Order Shipments — they're the same record, viewed from Operations rather than from Repair Orders.
• No holds, no draft state. Stock isn't reserved up front; you can only collect what's actually in the source bin at pick time. If the parts aren't there, the dispatch can't happen — raise a stock move request to bring them in first.
• Customer-bound delivery address is on the ROS, not the shipment. Editing the address means editing the parent ROS.
• Aramex booking shares the same hardcoded account as Sales Shipments — if Aramex suspends the account, ROS courier requests fail too until it's cleared.
• Tracking refs survive across the whole ROS lifetime. If you cancel and recreate the ROS, the old waybill/collection numbers are not auto-cleared; verify before printing.