Walkthrough: Configuring and processing an inbound ASN in the new Warehouse management module

Introduction

An advance shipping notice (ASN) is used to notify a company that a delivery is on the way. ASNs are a common EDI document, and nowadays most ERP systems support their use. ASNs enable a sender to describe the contents and configuration of a shipment, as well as convey additional information about the shipment, such as the items for the orders that it includes, the type of packaging that it includes, and so on.

Earlier versions of Dynamics AX did not offer the ability to receive ASNs from vendors. This was a significant gap, considering the modern technologies that are used in other ERP solutions globally. In Dynamics AX 2012 R3 we added the ability to receive ASNs from vendors, store the shipment information, and then use the information to make receiving processes more efficient.

This functionality is as of today only available for products and warehouses that are enabled for advanced warehouse management processes (the so-called WHS-items and warehouses).

This blog describes how to prepare for and receive ASNs, provides the technical details that are necessary to perform the process, and describes what happens afterward.

Purchase orders

To process an ASN, you must first have a purchase order that a vendor shipment is going to fulfill. The information in the XML file of the ASN document must match the purchase order. Therefore, you must communicate the purchase order information to the vendor when the purchase order is confirmed. This requirement will be described in more detail later in this blog.

To support the walkthrough later in this blog, I’ve created a purchase order. The following image shows the information that I’ve entered for the purchase order. Note that item 000148_202 is a WHS-enabled item, as well as warehouse 42 is WHS-enabled.

Configuring the ASN service for inbound operations

An inbound ASN is a typical Application Integration Services (AIF) service, so I’ll only mention the key components and won’t go over the setup in detail.

Technical details about configuring the ASN service

The service that provides ASN capabilities is called WHSShipmentASNService, and the service operation you should add to the inbound port that you create is called WHSShipmentASNService.create.

The following image shows how the inbound port should look after it’s configured.

XML document schema

The following table shows the information that you must communicate to the vendor so that they can add it to the XML file for the ASN. If the vendor is unable/unwilling to include certain information, you can, of course, customize the information to suit the agreement with the vendor by using value mapping, an XSLT file, or other means such as writing custom X++ code to handle missing data or adjust the format of the incoming XML file. The table also includes several fields that could be candidates for inclusion in the XML file, but are currently not used by the ASN engine.

Note I’ve used an XPath-like notation in the table.

XPathDescription
/WHSShipmentASN/WHSShipmentTable/DeliveryNameDelivery name specified on the shipment.

Will not be used (field is read-only on the table).

/WHSShipmentASN/WHSShipmentTable/InventSiteIdSite specified on the shipment.

Will not be used (field is read-only on the table).

/WHSShipmentASN/WHSShipmentTable/InventLocationIdWarehouse specified on the shipment.

Will not be used (field is read-only on the table).

/WHSShipmentASN/WHSShipmentTable/DlvTermIdDelivery terms specified on the shipment.

Supports value mapping.

Optional.

/WHSShipmentASN/WHSShipmentTable/ShipmentIdCustomer Reference ID specified on the shipment will be populated with this value.
/WHSShipmentASN/WHSShipmentTable/OrderNumNot populated when importing an ASN. No need to specify in the XML file.
  
/WHSShipmentASN/WHSShipmentTable/ DirPartyPostalAddressView/…Sets the address of the shipment.

Mandatory.

  
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/…Note the packing structure could be nested (one or more cases on a pallet).
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/LicensePlateIdThe ID of the pallet/case. Will be created as a license plate in AX.

Mandatory

Note: This is really the only mandatory field here, the rest (ItemId, Qty) will be populated automatically when all the ASN item lines are added.

  
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/PurchIdField used to identify the purchase order that the ASN is for.

Mandatory. Muse be populated in the XML file.

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/InventDimIdOptional.

Suggestion: The required inventory dimensions should be specified in the below InventDim structure instead. The vendor should not need to specify this ID because it is internal to AX.

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/InventTransId  Will not be used (field is read-only on the
table).

The purchase order line is determined based on
the PO number, Item number, and dimensions.

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/ItemIdMandatory.
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/QtyMandatory.
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/UOMMandatory.
  
/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/InventDim/…  Specify only required information here.
Inventory dimensions like Site and Warehouse will default from the purchase order line.

InventDimId  will not be used.

The default inventory status is always used.

Batch and serial numbers are created in AX when you import an ASN

Note it’s mandatory to have the section in the XML, however, even if empty, like shown below in a sample ASN file.

You can view the XML schema for the document from the data policies setup on the inbound port. Here’s how it looks for an ASN document if you enable all of the fields. Note that only the fields that were mentioned in the table above are persisted when an ASN is imported.

Implementation

The following table describes the service, class, and query that are part of the implementation.

Service nameWHSShipmentASNServiceAlso the External service name and service class name.
Axd <document> classAxdWHSShipmentASNThis class contains the main business logic for handling the import of an ASN.
QueryWHSShipmentASNThe standard query for the service. Contains the tables listed in the XML schema above.

Note the self-outer-join of WHSUOMStructure, which enables the nesting of the packing structure cases on a pallet.

Also note that the Update settings on the data sources are set to Yes, meaning the service also supports an update operation.

Sample XML file

The following sample XML is taken from the ASN document file that I will use in my walkthrough. It contains only the bare minimum of information necessary to import the ASN for the purchase order that I described earlier.

 <Envelope xmlns="http://schemas.microsoft.com/dynamics/2011/01/documents/Message">
     <Header>
        <MessageId>{5603D03A-4473-404D-9F27-738BE0FEA99E}</MessageId>
        <Action>http://tempuri.org/WHSShipmentASNService/create</Action>
     </Header>
     <Body>
        <MessageParts>
             <WHSShipmentASN xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/WHSShipmentASN">
                <WHSShipmentTable class="entity">
                     <ShipmentId>CUSTREF-001</ShipmentId>
                     <WHSUOMStructure class="entity">
                         <LicensePlateId>LP9004</LicensePlateId>
                         <WHSASNItem class="entity">
                             <ItemId>000148_202</ItemId>
                             <PurchId>000411</PurchId>
                             <Qty>30</Qty>
                             <UOM>ea</UOM>
                             <InventDim class="entity">
                             </InventDim>
                         </WHSASNItem>
                     </WHSUOMStructure>
                     <DirPartyPostalAddressView class="entity">
                         <City>Redmond</City>
                         <CountryRegionId>USA</CountryRegionId>
                         <State>WA</State>
                         <Street>123 Coffee Street</Street>
                         <ZipCode>98052</ZipCode>
                     </DirPartyPostalAddressView>
                 </WHSShipmentTable>
             </WHSShipmentASN>
         </MessageParts>
     </Body>
 </Envelope>

Processing the received ASN document

Like other AIF services, you’d typically have a batch job that picks up new documents. For the sake of simplicity, I’ll use the following batch job, which I also mentioned in the links I provided above:

public static void processInboundDocuments()
{
    new AifGatewayReceiveService().run();
    new AifInboundProcessingService().run();
 }

Debugging the import process

Debugging AIF service operations in AX 2012 is relatively easy, and is well described on TechNet. The article also contains step-by-step instructions for configuring a selected service operation.

Result

After you run the code above (and assuming you did not get any errors, which you can check under System administration > Periodic > Services and Application Integration Framework > Exceptions), the result is that the ASN is imported, an inbound shipment is created, and a load is created and is associated packing structure.

You can view the shipment by clicking Warehouse management > Common > Shipments > All shipments, and searching on the Customer reference that the vendor provided in the ASN. You can see that the shipment created based on my sample ASN document, as shown above. Note that the address was populated based on the ASN information and physical characteristics of the shipment, such as weight and volume, were calculated based on the load lines. As of today, not much else is populated on this inbound shipment.

If you want to view the load that was created, you can click Warehouse management > Common > Loads > All loads. From there, you can also view the Packing structure that was created. The packing structure contains the description of the pallets on that load, and the items and quantities on each of the pallets and how they are packed (specifically, whether they are all on the parent license plate or packed in separate cases on it).

In the image below, my sample ASN was successfully imported, correctly lists the item on the shipment, and includes the license plate ID of the pallet that the item was on. The inventory dimensions, which you can view on the corresponding tab page, matches the corresponding purchase order line.

Proceed with caution

Since this is the first release version of the ASN, there are still some glitches here and there. Please familiarize yourself with the below list, and make sure your business requirements are not impacted. If they are, a support request or customization will be required.

  1. Importing the same (or modified) ASN for the same purchase order might result in inconsistent data.
    1. Integration with Transportation management around transferring transportation charges is also impacted.
  2. Importing an ASN that contains multiple lines for the same item with, e.g., different batch numbers might fail in certain cases.
  3. Over/Under delivery is not currently ensured for the load when importing an ASN

Conclusion

In my next blog post, I will cover a receiving flow that is based on the information in the ASN, and how that is different from the standard flow for receiving items for purchase orders.