TABLE OF CONTENTS


Overview

If you wish to include more data in your responses than in the standard schemas then you will need to map this data to fields in Shiptheory. 


For example, by default the schema returned by the "4- Warehouse Shipment" end point from your Business Central, does not include a sender tax number in it. This is a valid field in Shiptheory and one you may need for shipping internationally. By adding this field to your response and then telling Shiptheory about this addition you can save the value contained in this field against the sender tax number in Shiptheory.


Setting up field mapping

To add field mapping to your Microsoft Dynamics 365 integration, navigate to the settings page, open the advanced settings section and scroll down until you see the section called "Field Overrides". You can then use the interface to add and remove your override lines.


Each section is explained below:

  1. Dynamics 365 Object: This is the data point which Shiptheory will search for the field on. To understand this in greater depth see the "Understanding the response data structure" section. Please note that Warehouse Address is only valid if you have "Download and user warehouse address" enabled
  2. Field name: This is the key used to get a value from the field. In our above example the first row would search shipment level data for the "nopkg" key and capture its value.
  3. Shipment Property: This is the Shipment property in Shiptheory which the value will be applied to. "Shipment" and "Warehouse Address" can map to general shipment level fields and address fields, while fields pulled from "Product" can only apply to shipment products.
  4. Row controls: Click the green plus to add a new row and the red minus to remove a row.


Understanding the response data structure

Responses generated by the schema contain duplicate data. The response data will include an array of objects. Each object represents a shipment line/product. However for each object, data you would usually expect to be on the 1 side of a 1:N relationship is repeated.


For example, in the below example the address data is repeated (e.g. shipToAddress), but product level data varies (e.g. itemNo and qtyToShip):


Shiptheory deals with this in the following way, for data to be mapped when

  • Dynamics 365 Object = Shipment:  Shiptheory will pull the data from the first item in the "value" array only
  • Dynamics 365 Object = Product: Shiptheory will pull data from every item in the "value" array. This is helpful when you want to include product-level data and have Shiptheory map each item to its corresponding product.


{
    "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/434f1451-469a-4ef4-a6c9-3c0009eec453/Sandbox/ODataV4/$metadata#Company('My%20Company')/shiptheoryWhseShipments",
    "value": [
        {
            "systemIdWhseShipmentHeader": "5f416163-0f7c-ef11-a671-7c1e522e7c45",
            "whseShipmentNo": "WS00001235",
            "status": "Released",
            "shipmentDate": "2024-09-26",
            "shippingAgentCode": "DHL",
            "shippingAgentServiceCode": "DHLEXPECON",
            "locationCode": "30",
            "systemIdWhseShipmentLine": "61416163-0f7c-ef11-a671-7c1e522e7c45",
            "sourceNo": "SO001514",
            "lineNo": 10000,
            "itemNo": "tst-prod-1",
            "description": "Product 1",
            "quantity": 1,
            "qtyToShip": 1,
            "qtyShipped": 0,
            "unitOfMeasureCode": "PCS",
            "shiptheoryPTR": "",
            "shiptheoryStatus": "Queued",
            "systemIdSalesOrder": "b0ea9725-0f7c-ef11-a671-7c1e522e7c45",
            "shipToName": "Test Customer",
            "shipToAddress": "Test Street",
            "shipToAddress2": "",
            "shipToCity": "Bristol",
            "shipToCounty": "",
            "shipToPostCode": "BS1 1AA",
            "shipToCountryCode": "GB",
            "sellToEmail": "test@test.com",
            "sellToPhoneNo": "0123456789",
            "sellToVATRegistrationNo": "",
            "countryOfOriginCode": "",
            "weightPerUOM": 0.012,
            "heightPerUOM": 0,
            "widthPerUOM": 0,
            "lengthPerUOM": 0,
            "cubagePerUOM": 0,
            "commodityCode": "48149010",
            "commodityCodeDescription": "Testing Item 1",
            "AuxiliaryIndex1": "",
            "AuxiliaryIndex2": "",
            "AuxiliaryIndex3": "",
            "AuxiliaryIndex4": "",
            "AuxiliaryIndex5": "",
            "AuxiliaryIndex6": ""
        },
        {
            "systemIdWhseShipmentHeader": "5f416163-0f7c-ef11-a671-7c1e522e7c45",
            "whseShipmentNo": "WS00001235",
            "status": "Released",
            "shipmentDate": "2024-09-26",
            "shippingAgentCode": "DHL",
            "shippingAgentServiceCode": "DHLEXPECON",
            "locationCode": "30",
            "systemIdWhseShipmentLine": "61416163-0f7c-ef11-a671-7c1e522e7c45",
            "sourceNo": "SO001514",
            "lineNo": 10001,
            "itemNo": "tst-prod-2",
            "description": "Product 2",
            "quantity": 3,
            "qtyToShip": 3,
            "qtyShipped": 0,
            "unitOfMeasureCode": "PCS",
            "shiptheoryPTR": "",
            "shiptheoryStatus": "Queued",
            "systemIdSalesOrder": "b0ea9725-0f7c-ef11-a671-7c1e522e7c45",
            "shipToName": "Test Customer",
            "shipToAddress": "Test Street",
            "shipToAddress2": "",
            "shipToCity": "Bristol",
            "shipToCounty": "",
            "shipToPostCode": "BS1 1AA",
            "shipToCountryCode": "GB",
            "sellToEmail": "test@test.com",
            "sellToPhoneNo": "0123456789",
            "sellToVATRegistrationNo": "",
            "countryOfOriginCode": "",
            "weightPerUOM": 0.025,
            "heightPerUOM": 0,
            "widthPerUOM": 0,
            "lengthPerUOM": 0,
            "cubagePerUOM": 0,
            "commodityCode": "69149010",
            "commodityCodeDescription": "Testing Item 2",
            "AuxiliaryIndex1": "",
            "AuxiliaryIndex2": "",
            "AuxiliaryIndex3": "",
            "AuxiliaryIndex4": "",
            "AuxiliaryIndex5": "",
            "AuxiliaryIndex6": ""
        }
    ]
}