Sales Return

Functional documentation for the Aiden WMS sales return inbound mapper.

This document describes what happens after the mapper is installed: how a WMS sales return completion is enriched with SAP Business One (B1) return request data, which B1 document is posted (Returns or Credit Notes), and which field rules apply. It is intended for end-users and functional consultants.

1. Overview

After installation, when WMS finishes receiving a sales return, the integration:

1. Reads return request DocEntry values from the WMS message

2. Loads matching B1 return request line data

3. Maps WMS picked/saved quantities (serials, batches, plain lines, sales BOM) into B1 document lines

4. Posts either a Return or a Credit Note, depending on base type

Document type selection (runtime)

Base type 13 is the B1 object type for A/R Invoice. When the return is based on an invoice, WMS/B1 expect a credit note; otherwise a return document is posted against the return request (object type 234000031 in many line paths).

2. What the mapper uses as input

2.1 WMS message

Typical structure:

• transaction.id — WMS transaction id (external application id + U_AEN_WMS_TRANSID)

• transaction.type / dates — present on payload; type not used for endpoint routing in Java

• documents[]:

  • businessPartner.businessPartnerId → B1 CardCode

  • processDate → B1 DocDate

  • customFields.externalId — B1 base document entry used on lines (BaseEntry)

  • customFields.objectType — used in BaseType valuemap for some line paths

  • customFields.DocEntry — Return Request DocEntry(s) used for B1 GET filter

  • customFields.DocumentAdditionalExpenses[] — header expenses (map to B1 header DocumentAdditionalExpenses)

  • lines[] — planned/document lines (lineNum, salesBom, quantity, …)

  • lines[].customFields.DocumentAdditionalExpenses[] — line expenses (WMS name); on B1 output these become DocumentLines[].DocumentLineAdditionalExpenses[]

  • savedLines[] — actual received units (quantity, batch, serial, license, carrier, baseQuantity)

2.2 B1 Return Request enrichment (automatic)

Before mapping, the integration:

1. Splits documents[] and collects each customFields.DocEntry

2. Builds an OData filter: DocEntry eq <id> (or multiple or clauses for unique entries)

3. GET ReturnRequest?$select=DocEntry,DocNum,DocumentLines&$filter=…

4. Stores the response as the second MapForce input

Business impact: return request documents must already exist in B1, and WMS must carry the correct customFields.DocEntry. Wrong/missing DocEntry yields empty enrichment and incomplete base-line matching (especially for BOM).

2.3 Correlation / monitoring

3. Business behavior

3.1 Header of each B1 document

For each WMS documents[] entry, the mapper produces a B1 document object with:

3.2 How lines are built

WMS savedLines drive quantities and tracking (serial/batch). They are matched to document lines (via documentLine / lineNum) and, for sales BOM, to Return Request lines (DocEntry, LineNum, VisualOrder).

MapForce emits several parallel DocumentLines expansions (clones), similar to other inbound goods mappers:

Base document references on lines (typical):

3.3 BaseType valuemap (customFields.objectType)

Used on the serial (and related) path:

Many non-serial / BOM / expense base-type fields are forced to constant 234000031 (B1 Return Request object type), so returns against return requests keep a stable base type even when objectType valuemap does not apply.

3.4 Serial lines

• Filter: serial number not equal to empty

• Group-by document line; sum quantities

• B1 SerialNumbers[].InternalSerialNumber ← WMS serial

• B1 SerialNumbers[].Quantity ← saved quantity (per serial row path)

• Line Quantity ← aggregated sum for that base line

3.5 Batch lines

• Filter: batch number present (empty batch excluded from this path)

• Group-by document line; sum quantities

• B1 BatchNumbers[]: BatchNumber, ExpiryDate, Quantity from saved lines

• Line Quantity ← aggregated sum

3.6 Non batch/serial lines

• Intermediate JSON path labeled for non-batch/serial units

• BaseType often 234000031

• Quantity from aggregated saved quantities without serial/batch sub-structures

3.7 Sales BOM lines

When WMS lines carry salesBom (parent, parentLine, singleQuantity, respectSingleQuantity):

• Mapping joins B1 Return Request lines where:

  • Return request DocEntry matches WMS external/base document context

  • Return request visual order context matches (VisualOrder + 1 compared to parent line, etc.)

• Component quantities use singleQuantity and min/divide against WMS line quantities so BOM components stay consistent with kit structure

• Output lines use Return Request base type 234000031 on the BOM expansion

Consultant impact: Visual order and sales BOM flags on the original return request / WMS message must stay consistent. Broken parent/child links produce wrong component quantities or missing BOM lines.

3.8 Additional expenses

Header and line expenses use different B1 structures.

Header expenses from documents.customFields.DocumentAdditionalExpenses:

• Copied to B1 document-level DocumentAdditionalExpenses[]

• BaseDocEntry ← WMS externalId

• BaseDocLine ← expense LineNum

• BaseDocType ← constant 234000031 (typical)

• ExpenseCode, LineTotal, GroupCode, DistributionMethod, VatGroup copied

Line expenses from lines.customFields.DocumentAdditionalExpenses:

• Attached on matching DocumentLines expansions (serial / batch / non-batch-serial / BOM) as B1 DocumentLineAdditionalExpenses[] (not the header-shaped expense block)

• Mapped fields: ExpenseCode, LineTotal, GroupCode, DistributionMethod, VatGroup

• No BaseDocEntry / BaseDocLine / BaseDocType on line expenses (removed in the line-expense mapping)

• LineNumber exists on the output schema but is not mapped

• BaseGroup is only wired on the non-batch/serial path (from WMS GroupCode); serial, batch, and BOM line-expense paths do not map BaseGroup

3.9 Packages

DocumentPackages exists on the output schema. In the current MapForce definition, package fields are largely not wired (no reliable license/carrier package generation like the goods-delivery mapper). Do not expect SSCC packages from this mapper unless the MFD is extended.

4. Field mapping tables

Columns: B1 target field | WMS / ReturnRequest source | What happens | Notes

4.1 Header

4.2 Document lines (common)

4.3 Serials (conditional)

4.4 Batches (conditional)

4.5 Sales BOM (conditional)

4.6 Header additional expenses

Document-level B1 DocumentAdditionalExpenses[] (distinct from line-level DocumentLineAdditionalExpenses).

4.7 Line additional expenses

B1 target collection: DocumentLines[].DocumentLineAdditionalExpenses[].
WMS source collection: lines.customFields.DocumentAdditionalExpenses[] (name differs from B1 output).

5. Value translations (reference)

5.1 Endpoint routing

5.2 Object type → BaseType (valuemap)

5.3 Return request object type constant

5.4 B1 GET

6. What is not mapped / important omissions

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

1. WMS completes a sales return receipt and publishes a message with savedLines and return request DocEntry.

2. Integration GETs B1 Return Request line data.

3. Mapper builds B1 document(s): customer, date, WMS transaction id, lines with base refs, serials/batches/BOM as applicable, expenses.

4. If first line BaseType is 13 → POST CreditNotes; else POST Returns.

5. Support uses U_AEN_WMS_TRANSID / transaction.id and base document refs for reconciliation.

8. Example (illustrative shape)

Scenarios in-repo are placeholders. Expected shape from MFD + runtime:

WMS input (conceptual)

B1 output (conceptual)

9. Implementation checklist for consultants

1. Return requests exist in B1 before WMS confirmation.

2. WMS sends correct customFields.DocEntry (return request) and externalId / line numbers for base linking.

3. Set lines[].customFields.BaseType = 13 when the business case must post a Credit Note; otherwise expect Returns.

4. For serial/batch items, populate savedLines serial/batch/expiry completely.

5. For sales BOM, keep salesBom and return-request VisualOrder consistent.

6. Use transaction.id / U_AEN_WMS_TRANSID for support.

7. Do not expect package/SSCC generation from this mapper today.

8. Validate header expenses (DocumentAdditionalExpenses) and line expenses (DocumentLineAdditionalExpenses from WMS line DocumentAdditionalExpenses) if freight must copy to the B1 return/credit note.

10. Source artifacts (for reference)

Generated from the mapping definition and integration behavior in this project. If the MapForce mapping or routing 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.