Configure Agent Warehouse System in GWMS
Updated: 2026-08-06
1. Scenario
The agent warehouse module manages the integration between GWMS and external agent warehouse systems. Once a system is configured, GWMS can hand off inbound, outbound, and inventory sync operations to the agent warehouse, and write the results back to the local task page and log page.
Two agent warehouse systems are currently supported: HPK (Hipacking) and Ecang OMS (Ecang). General configuration and task-page behavior is the same for both, but the actual support scope for inbound, outbound, serial numbers, and inventory sync differs between them — read the system-specific guide before onboarding: HPK Guide, Ecang Guide.
This guide is for warehouse implementers, system administrators, and operations staff responsible for third-party warehouse integration. Common use cases include:
- Onboarding a new agent warehouse system;
- Completing warehouse mapping, channel mapping, or checking SKU mapping for an existing system;
- Manually triggering inventory sync for a specific warehouse mapping;
- Investigating why an order isn't continuing to sync, or why inventory doesn't line up.
1.1 How the Agent Warehouse Works End-to-End
Operations workflow overview
Using the agent warehouse breaks down into 3 stages:
Stage 1: Configure the agent warehouse system (first time only)
On the GWMS > Agent Warehouse > Agent Warehouse System page:
- Add an agent warehouse system and fill in connection details
- Set up warehouse mapping (important: virtual shelving location and defective product location are required)
- Set up channel mapping
- Once configured, daily business automatically pushes to the agent warehouse
- SKUs are automatically pushed the first time an agent warehouse inbound order is created
Stage 2: Daily business triggers agent warehouse actions
Operations staff keep working in GWMS as usual for inbound, outbound, and inventory sync. The system generates and tracks tasks in the background — no need to manually re-check repeatedly.
Inbound business:
- GWMS pushes the inbound order to the agent warehouse.
- The system creates a task record.
- The system keeps polling the agent warehouse's processing result on a schedule.
- Once the agent warehouse returns a completable status, GWMS automatically performs receiving, putaway, or cancel write-back.
- If the agent warehouse's result can't be recognized, or the local action's preconditions aren't met, the task moves to manual handling.
Inbound serial numbers:
- If the current agent warehouse route supports inbound serial number sync, once the inbound order is created successfully, the system automatically pushes the local serial numbers already bound to this order to the agent warehouse.
- If local serial numbers are later added, changed, or removed, the system syncs the change to the agent warehouse asynchronously after the local transaction commits.
- When the agent warehouse returns a final inbound result, the system also parses serial numbers out of the response and writes them back into GWMS local inbound serial number records.
- This is not a separate new task type. When troubleshooting, check the logs first, then cross-reference the inbound task status to judge whether the main flow has completed.
Outbound business:
- GWMS pushes the outbound order to the agent warehouse.
- The system creates a task record.
- The system keeps polling the agent warehouse's processing result on a schedule.
- Once the agent warehouse returns a completable status, GWMS automatically advances the local outbound status.
- If this outbound result from the agent warehouse includes serial numbers, the system tries to write them back into GWMS local outbound serial number records while advancing the local outbound status.
- If the agent warehouse has cancelled but the local side currently can't auto-cancel, or the local formal-outbound preconditions aren't met, the task moves to manual handling or waits for retry.
Outbound serial numbers:
- In the current code, outbound serial numbers are mainly handled through the "agent warehouse result written back to GWMS" path.
- In other words, when the agent warehouse returns a completed outbound result, the system tries to parse the serial number list for each product out of the response and write it back to local outbound serial number records.
- This is not a separate task type — it's attached to the status write-back stage of the main outbound flow.
- If outbound serial number write-back fails, the current code does not fail the main outbound flow because of it; the main flow's result is kept as-is, and the failure is logged for troubleshooting.
Inventory sync (unlike inbound/outbound, this doesn't rely on polling):
- Triggered manually or by the system's scheduled job.
- The system first tries to clear pending business tasks for the same warehouse, but this step has a budget on count and duration — it doesn't have to wait for every task to finish.
- The system pulls an inventory snapshot from the agent warehouse.
- Compares it against the inventory of GWMS's local proxy-warehouse-managed locations.
- Automatically corrects the discrepancy and saves the snapshot.
- Based on the execution result, the task is directly marked success, waiting for retry, or manual handling.
Stage 3: Review results and handle exceptions
Operations mainly watches two pages:
- Sync Tasks page: shows what step this business operation is currently at — waiting for automatic retry, already successful, or needs manual handling.
- Logs page: shows exactly what request was sent for this step and what the agent warehouse responded with.
Common handling scenarios:
- Task shows "waiting": The task hasn't finished. This may mean the agent warehouse hasn't reached a final state yet, or the system has already scheduled the next automatic query.
- Task shows "manual handling": The automatic flow has stopped — fix the master data, configuration, or business status per the error message first.
- Task shows "success": The task is complete — no further action needed.
- Not sure why: Check the sync task's execution summary first, then decide whether you need to check the raw request/response on the logs page.
Inbound/Outbound vs. Inventory Sync — key differences:
| Comparison | Inbound/Outbound Task | Inventory Sync Task |
|---|---|---|
| Task type | Create confirmation, cancel confirmation, query task | Inventory sync task |
| Execution model | Push, then poll the agent warehouse's processing result on a schedule | Pull inventory snapshot, then directly correct local managed inventory |
| Relies on polling | Yes | No |
| Duration | Depends on agent warehouse processing progress and local write-back | Depends on pre-processing task count, snapshot size, and correction volume |
| Typical result | Success, continue waiting, manual handling | Success, continue retry, manual handling |
| Typical use case | Hand an order to the agent warehouse and keep tracking the result | Re-correct GWMS's proxy-warehouse-managed inventory to match current inventory at the agent warehouse |
Key takeaways:
- The configuration page answers "can this be onboarded" and "which mapping does this run under".
- The sync tasks page answers "what step is this business operation at right now".
- The logs page answers "what exactly was in the raw request and response".
- Inbound/outbound doesn't end the moment it's pushed — a task keeps tracking it automatically afterward.
- Inventory sync doesn't strictly wait for every business task to finish first — it processes what it can within a budget, then continues.
- Whether a local cancel actually syncs to the agent warehouse depends on the business type and what the connected system currently supports.
- Serial-number-related flows currently do not generate a separate "serial number task" on the sync tasks page — they're attached to the main inbound or outbound flow.
1.2 Serial Number Overview
If you'll be troubleshooting "why is the serial number wrong" later, it helps to separate directions first. In the current code, agent warehouse serial numbers break down into at least these 4 scenarios:
| Direction | When it happens | Current code scope | Generates a separate task? | Does failure break the main flow? | Check here first |
|---|---|---|---|---|---|
| GWMS -> agent warehouse | After inbound order creation succeeds, push the currently-bound local inbound serial numbers | Inbound serial number push | No | A failure here usually shows up in the corresponding push/sync result — needs to be judged case by case | Logs |
| GWMS -> agent warehouse | When local inbound serial numbers are later added, changed, or removed | Inbound serial number incremental sync | No | Not a separate task — fired asynchronously per event | Logs |
| Agent warehouse -> GWMS | When the agent warehouse returns a final inbound result | Inbound serial number write-back | No | Does not fail the inbound main flow — can still be filled in later | Logs first, then Sync Tasks |
| Agent warehouse -> GWMS | When the agent warehouse returns a completed outbound result | Outbound serial number write-back | No | Does not fail the outbound main flow — the main flow keeps its success/advanced result | Logs first, then Sync Tasks |
3 key judgment calls when troubleshooting:
- First decide whether you're checking "did it push out" or "did it come back".
- Then decide whether you're looking at the inbound or the outbound flow.
- Finally decide whether this issue actually affects the main flow's status — don't treat a missing serial number as automatically meaning the task failed.
2. Steps
Prerequisites
Confirm the following before proceeding:
- Your account can access
GWMS > Agent Warehouse > Agent Warehouse System. - You have the connection details provided by the agent warehouse, such as system type, endpoint, account, or password.
- If setting up warehouse mapping, complete the warehouse, zone (storage and defective), and location master data in GWMS first.
- If setting up channel mapping, complete logistics channel master data in GWMS first.
- If checking SKU mapping status, make sure the target GSKU already exists in GWMS and has already had an agent warehouse inbound order.
2.1 Add an Agent Warehouse System
Menu path: GWMS > Agent Warehouse > Agent Warehouse System
- Open the agent warehouse system page.
- The top of the page lets you search by 【System Name】, 【System Code】, or 【Config JSON】.
- Click 【Add】.
- In the dialog, fill in 【System Name】 and 【System Type】:
- 【System Name】: A descriptive name for this agent warehouse system, used by operations to tell systems apart later
- 【System Type】: Currently supports "HPK (Hipacking)" and "Ecang OMS"
- Depending on the system type selected, the page shows a different set of configuration fields — fill them in accordingly.
- Click 【OK】. The system shows "Added successfully".
2.2 Set Up Warehouse Mapping and Trigger Inventory Sync
- Click 【Warehouse】 on the row of the target system.
- The "Paired Warehouse Information" dialog opens.
- The dialog table shows these columns:
- 【Agent Warehouse Code】
- 【GWMS Warehouse Code】
- 【Virtual Shelving Location】
- 【Defective Product Location】
- 【Actions】: three icon buttons — 【Bind GWMS Warehouse】, 【Sync Inventory】, 【Delete】
- Click 【Add Warehouse】 in the top right.
- In the new warehouse mapping dialog, fill in:
- 【Agent Warehouse Code】: required — enter the warehouse code as used in the agent warehouse system
- 【GWMS Warehouse Code】: required — select from the GWMS warehouse list
- 【Virtual Shelving Location】: required — select from the location list of the selected GWMS warehouse
- 【Defective Product Location】: required — select from the defective-zone location list of the selected GWMS warehouse
- Click 【OK】. The system shows "Warehouse mapping added successfully".
Run inventory sync
- Click 【Sync Inventory】.
- A confirmation dialog appears: "Confirm trigger inventory sync for this warehouse mapping immediately?"
- After confirming, the system shows "Inventory sync triggered".
- Check execution results on Sync Tasks — task type "Inventory Sync Task".
2.3 Configure Agent Warehouse Channels
- Click 【Channel】 on the row of the target system.
- The "Paired Channel Information" dialog opens.
- Click 【Add Channel】 in the top right.
- The system fetches the list of available channels from the agent warehouse.
- The list shows these fields:
- 【Agent Warehouse Channel Code】
- 【Agent Warehouse Channel Name】
- 【Carrier】
- 【Service Type】
- 【Available Warehouses】
- 【Self-pickup】
- Select the channels to onboard.
- Click 【OK】. The system shows "Channel added successfully".
Bind a GWMS channel
To map an agent warehouse channel to a GWMS logistics channel:
- Click the edit button on the paired channel row.
- In the dialog, select 【GWMS Channel Code】.
- Click 【OK】. The system shows "GWMS channel bound successfully".
Delete a channel mapping
To remove a channel mapping that's no longer used:
- Click the delete button.
- Confirm the deletion.
- The system shows "Deleted successfully".
2.4 Check SKU Mapping Status
- Click 【SKU】 on the row of the target system.
- The SKU information dialog opens.
- The table shows this information:
- 【SKU Code】
- 【Sync Status】
- 【Error Message】
- 【Actions】: includes resync, mark, and other actions
- The page supports filtering by 【SKU Code】, 【Sync Status】, and 【Error Message】.
- To refresh the current result, click 【Pull】 to check the latest status.
Understanding SKU mapping
Important notes:
- SKUs are not pushed manually for the first time on this page.
- The system automatically pushes the SKUs involved the first time an agent warehouse inbound order is created.
- A GSKU only appears in this SKU mapping list after it has been pushed via an inbound order.
- After a SKU push succeeds, the agent warehouse system records that SKU's sync status.
3. Additional Notes
3.1 Relationship Between System, Warehouse, Channel, and SKU
Agent warehouse configuration is maintained in layers:
- Agent warehouse system: defines which external system this integration is with;
- Warehouse mapping: defines which GWMS warehouse an agent warehouse code under this system maps to;
- Channel mapping: defines which GWMS channel an agent warehouse channel code maps to;
- SKU mapping: used to check whether a given GSKU has already been pushed via agent warehouse inbound, and to view its current sync status.
The other three mapping entry points only become available once a system record exists.
3.2 Why Inventory Sync Lives Under Warehouse Mapping
Inventory sync runs per "warehouse mapping", not per system as a whole. In other words:
- A single agent warehouse system can have multiple warehouse mappings;
- Each warehouse mapping's inventory sync task is generated independently;
- When a task runs, it only corrects the GWMS warehouse, agent warehouse code, virtual shelving location, and defective product location tied to that specific mapping.
If a mapping is missing the virtual shelving location or defective product location, the system will not allow inventory sync to be triggered directly.
3.3 Why Sync Inventory Doesn't Show a Result Immediately
Clicking 【Sync Inventory】 only submits a task — it does not mean the sync completes on the page right away. It still has to go through task creation, business pre-processing, inventory pull, inventory correction, and result write-back.
If you don't see a result right after clicking, check Sync Tasks first:
- Whether the task has actually been created;
- Whether it's currently waiting, successful, or in manual handling;
- Whether the execution summary already states a clear reason.
3.4 How to Read SKU Mapping Status
The records on the SKU page are not a complete list of every GSKU. Only SKUs that have already gone through an agent warehouse inbound push show up in this list.
If an error message appears on the page, check these first:
- Is the GSKU master data complete?
- Has an agent warehouse inbound involving this SKU actually happened?
- Is the agent warehouse system configuration correct?
- Has the corresponding request already shown up in Logs or Sync Tasks?
4. Common Questions
Q1: Why is the 【Sync Inventory】 button greyed out?
A1: This warehouse mapping usually hasn't completed one of 【GWMS Warehouse Code】, 【Agent Warehouse Code】, 【Virtual Shelving Location】, or 【Defective Product Location】. Open the warehouse mapping dialog and fill in all 4 fields first.
Q2: Why can't I select a location when adding a warehouse mapping?
A2: The location list follows the GWMS warehouse you've selected. If you haven't selected 【GWMS Warehouse Code】 yet, or that warehouse has no matching locations, the location dropdown will be empty.
Q3: I already added a channel — why do I still need to bind a GWMS channel?
A3: Pulling an agent warehouse channel into GWMS only creates an "available channel" record. Only after you bind 【GWMS Channel Code】 can outbound business map a GWMS channel selection to the agent warehouse channel.
Q4: The SKU already exists — why does it still show 【Not Synced】?
A4: The SKU existing only means the product record is present in GWMS — it does not mean it has been pushed to the agent warehouse. Currently, the system only auto-pushes the corresponding SKU the first time an agent warehouse inbound happens; as long as that hasn't happened yet, this SKU may not show up in the mapping list at all.
Q5: Inventory sync was triggered successfully — where can I see the result?
A5: The inventory sync entry point only initiates the task — it doesn't show execution detail directly in the warehouse mapping dialog. Go to GWMS > Agent Warehouse > Sync Tasks, filter by task type "Inventory Sync Task" or by warehouse, and check the execution result there.
Q6: I clicked cancel locally — why doesn't the agent warehouse necessarily cancel too?
A6: Whether it syncs to the agent warehouse depends on this order's business type and what the connected system currently supports. If the agent warehouse's cancel doesn't go through, this cancellation does not end as a success; and if this business type doesn't go through the agent warehouse cancel path at all, a local cancel should not be read as "the agent warehouse has also cancelled".
Q7: What should I read next after this page?
A7: Depends on which agent warehouse system you're integrating with — see the HPK Guide for HPK, or the Ecang Guide for Ecang OMS. Each page covers that system's current support scope, inventory interpretation, and common issues in one place.