Sales Return Request

Functional documentation for the Aiden WMS sales return mapper.

This document describes what happens after the mapper is installed: which SAP Business One (B1) sales return / return request data is sent to Aiden WMS, how values are translated, and which business rules apply. It is intended for end-users and functional consultants.

1. Overview

After installation, when a return document is published to the integration, the mapper produces a WMS document that contains:

• Document identity (with SO- prefix) and type labels for returns

• Customer (business partner)

• Ship-to address

• Return lines for picking-enabled warehouses only, with remaining open quantity

• Line references back to the base B1 document (BaseType / BaseEntry / BaseLine)

• Optional sales BOM structure on BOM-related lines

• Optional freight/expenses

• Correlation id for tracking

Fixed business defaults

These values are always set by the mapper (not taken from B1):

Note: A constant SalesReturn also exists in the mapping near header fields historically associated with baseType. Header data.receiveDate is present in the output schema but is not wired in the current MapForce mapping. Line receiveDate is mapped from ShipDate.

Key differences vs sales-order mapper

2. What the mapper uses as input

2.1 Main payload — B1 return document

The primary input is the full B1 document JSON (schema named input_sales_order in MapForce for historical reasons), including for example:

• Header: DocNum, DocEntry, CardCode, CardName, DocumentStatus, PartialSupply, DocObjectCode, PickRemark, NumAtCard

• Ship-to address: AddressExtension.ShipTo*

• Lines: DocumentLines[] (including RemainingOpenQuantity, VisualOrder, BaseType / BaseEntry / BaseLine, UoM, warehouse, tree type, etc.)

• Header additional expenses: DocumentAdditionalExpenses[]

• Line additional expenses: DocumentLineAdditionalExpenses[]

2.2 Warehouse list (automatic)

The integration periodically loads warehouses from B1:

• WarehouseCode

• U_AEN_WHS_Picking (Y / N)

• (also retrieved but not used in field mapping: EnableBinLocations, DefaultBin)

Business impact: only return lines whose warehouse is marked as picking-enabled (U_AEN_WHS_Picking = Y) are sent to WMS.

2.3 Sales BOM helper data (automatic)

From the same document, the integration builds a helper list of lines where:

• TreeType = iSalesTree (sales BOM parent lines)

That list is used only to calculate sales BOM parent/child quantities and parent line references on the WMS lines. Consultants do not need to supply this separately.

2.4 Correlation id

The message correlation id (integration message key / Kafka key) is written to:

• correlation.correlationId

Use this to trace a WMS document back to the integration message.

3. Business behavior

3.1 Which lines are sent to WMS?

A B1 document line is included in data.lines only when its WarehouseCode matches a warehouse with U_AEN_WHS_Picking = Y.

Lines for warehouses with U_AEN_WHS_Picking = N (or unknown warehouse) are not sent to WMS.

Configure picking warehouses correctly in B1 (U_AEN_WHS_Picking) before go-live. Otherwise returns may arrive in WMS with missing lines.

3.2 Document id prefix

WMS data.documentId is built as:

1. Constant prefix SO-

2. Concatenated with B1 DocNum

Example: B1 DocNum = 950 → WMS documentId = SO-950.

3.3 Document and line status

B1 statuses look like bost_Open / bost_Close.

The mapper:

1. Removes the bost_ prefix → Open / Close

2. Translates Close → Closed (other values stay as-is, e.g. Open)

Applied to:

• Header: DocumentStatus → data.status

• Line: LineStatus → lines[].status

3.4 Partial delivery flags

B1 tYES / tNO flags are converted to booleans:

3.5 Object type (data.objectType)

Separately, custom object type on header and lines is always the constant SalesReturn (not driven by DocObjectCode).

3.6 Quantity on lines

For returns, WMS receives what is still open to receive/return. Fully closed quantities will appear as zero (or whatever B1 reports as remaining open).

Ordered Quantity is still used inside sales BOM single-quantity calculations when BOM parents apply (see §3.10).

3.7 Document line number

So WMS documentLine is visual-order based (1-based offset), while customFields.lineNum keeps the original B1 LineNum.

3.8 Unit of measure on lines (uomCode)

For each line:

1. If UoMEntry is not -1 → use UoMCode

2. If UoMEntry is -1 → use "m" + MeasureUnit

   • If MeasureUnit is missing, an empty string is used after m (result can be just m)

UoMEntry is also copied unchanged to lines[].customFields.UoMEntry.

3.9 Ship-to address

Address is taken from ship-to fields on the document (AddressExtension), not bill-to.

3.10 Sales BOM structure (lines[].salesBom)

B1 tree types used:

When is salesBom present on a line?

• Only if the line is a sales BOM parent or ingredient (iSalesTree or iIngredient).

• Otherwise the salesBom object is omitted.

Fields:

Practical expectation for consultants:

• Sales BOM parents and ingredients are flagged in WMS via salesBom.

• Parent kit lines get parent = true and respectSingleQuantity = true.

• Quantity/parent-line calculations depend on VisualOrder ordering of sales-tree lines on the B1 document.

• Non-BOM lines do not get a salesBom block.

3.11 Base document references on lines

For each included line, B1 base document fields are copied into line custom fields:

These support tracing a return line back to the originating B1 document/line (e.g. delivery or invoice base).

3.12 Customer reference (NumAtCard)

If filled in B1, NumAtCard is sent as a dynamic custom property:

• Property name: NumAtCard

• Property value: the B1 NumAtCard value

(Output schema path: dynamic property / property.name under header customFields.)

3.13 Additional expenses

• Header DocumentAdditionalExpenses → data.customFields.DocumentAdditionalExpenses[]

• Line DocumentLineAdditionalExpenses → lines[].customFields.DocumentAdditionalExpenses[]

Copied fields: ExpenseCode, LineTotal, GroupCode, DistributionMethod, VatGroup, and line number (LineNum).

3.14 Special lines

DocumentSpecialLines exists on the B1 input schema but is not mapped in this MapForce definition. Text/special lines are not sent to WMS by this mapper.

3.15 Integration endpoint

After mapping, the Camel route sets the outbound HTTP/WMS endpoint header to:

• InboundReturnRequest

This is an inbound return flow for WMS (not an outgoing pick document).

4. Field mapping tables

Legend:

• WMS output field — path in the Aiden WMS return document

• B1 / source input — field on the return document or other source

• What happens — copy or transformation

• Notes — consultant-relevant remarks

4.1 Correlation

4.2 Document header (data)

4.3 Business partner

4.4 Address (data.address)

4.5 Lines (data.lines[])

Only lines for picking-enabled warehouses (§3.1).

4.6 Sales BOM on lines (lines[].salesBom)

Only for TreeType in (iSalesTree, iIngredient) — see §3.10.

4.7 Line additional expenses

4.8 Header additional expenses

5. Value translations (reference)

5.1 Yes/no flags

5.2 Warehouse picking flag

5.3 Status

5.4 Document object code

5.5 Sales tree types

5.6 Fixed constants

6. What is not mapped / important omissions

Consultants should not expect the following from this mapper:

7. End-to-end expectation (happy path)

1. A sales return / return request is created or updated in SAP B1 and published to the integration.

2. Integration loads picking warehouse configuration from B1 (hourly).

3. Integration builds a sales-tree helper body from lines with TreeType = iSalesTree.

4. Mapper converts the document to a WMS return document:

   • Header + BP + ship-to address

   • documentId = SO- + DocNum

   • Only lines on picking warehouses

   • Quantity = remaining open quantity

   • documentLine = visual order + 1

   • Status / partial-delivery / UoM / BOM / base refs applied

   • Custom object type SalesReturn

5. WMS receives an InboundReturnRequest ready for inbound warehouse processing.

6. correlation.correlationId, header customFields.DocEntry, and line base refs support support/troubleshooting.

8. Example (illustrative)

Illustrative values based on mappings/input_sales_order.example.json and confirmed MapForce rules.
Project scenario files under scenario_files/1_mainRoute are schema placeholders and are not reliable expected I/O samples.

B1 input (excerpt)

WMS output (expected shape)

9. Implementation checklist for consultants

1. Warehouses: set U_AEN_WHS_Picking = Y on every warehouse that must create WMS return work.

2. Open quantities: ensure B1 remaining open quantities reflect what should still be received in WMS.

3. Ship-to address: maintain AddressExtension ship-to fields on the return document.

4. UoM: understand -1 UoM entry fallback (m + measure unit).

5. Sales BOM: use iSalesTree / iIngredient and consistent VisualOrder if WMS must receive BOM structure.

6. Base document links: maintain BaseType / BaseEntry / BaseLine on return lines when WMS or support needs origin tracing.

7. Tracking: use correlation.correlationId, header customFields.DocEntry, and line base refs for support.

8. Defaults: expect handling=Manual, priority=3, custom object type SalesReturn, and document id prefix SO- on every document.

9. Do not expect special text lines or header receive/pick dates from this mapper.

10. Source artifacts (for reference)

Generated from the mapping definition and integration behavior in this project. If the MapForce mapping changes, this document should be reviewed and updated.

Maintaining this document

For the original documentation intent, when to update, source-of-truth checklist, and a ready-made refresh prompt, see README.md and the repository AGENTS.md.