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


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. If you aren’t familiar with the AIF in AX 2012, see TechNet. You can also take a short-cut and set up AIF automatically by using the tool that I recently posted in my blog.

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.




Delivery name specified on the shipment.

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


Site specified on the shipment.

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


Warehouse specified on the shipment.

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


Delivery terms specified on the shipment.

Supports value mapping.



Customer Reference ID specified on the shipment will be populated with this value.


Not populated when importing an ASN. No need to specify in the XML file.



/WHSShipmentASN/WHSShipmentTable/ DirPartyPostalAddressView/…

Sets the address of the shipment.




/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/…

Note the packing structure could be nested (one or more cases on a pallet).

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/LicensePlateId

The ID of the pallet/case. Will be created as a license plate in AX.


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/PurchId

Field used to identify the purchase order that the ASN is for.

Mandatory. Muse be populated in the XML file.

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/InventDimId


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

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

/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/ItemId


/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/Qty


/WHSShipmentASN/WHSShipmentTable/ WHSUOMStructure/WHSASNItem/UOM




/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.



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

Service name


Also the External service name and service class name.

Axd <document> class


This class contains the main business logic for handling the import of an ASN.



The 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 (you can download the file here).

 1: <?xml version="1.0" encoding="utf-8"?>
 2: <Envelope xmlns="http://schemas.microsoft.com/dynamics/2011/01/documents/Message">
 3:     <Header>
 4:         <MessageId>{5603D03A-4473-404D-9F27-738BE0FEA99E}</MessageId>
 5:         <Action>http://tempuri.org/WHSShipmentASNService/create</Action>
 6:     </Header>
 7:     <Body>
 8:         <MessageParts>
 9:             <WHSShipmentASN xmlns="http://schemas.microsoft.com/dynamics/2008/01/documents/WHSShipmentASN">
 10:                 <WHSShipmentTable class="entity">
 11:                     <ShipmentId>CUSTREF-001</ShipmentId>
 12:                     <WHSUOMStructure class="entity">
 13:                         <LicensePlateId>LP9004</LicensePlateId>
 14:                         <WHSASNItem class="entity">
 15:                             <ItemId>000148_202</ItemId>
 16:                             <PurchId>000411</PurchId>
 17:                             <Qty>30</Qty>
 18:                             <UOM>ea</UOM>
 19:                             <InventDim class="entity">
 20:                             </InventDim>
 21:                         </WHSASNItem>
 22:                     </WHSUOMStructure>
 23:                     <DirPartyPostalAddressView class="entity">
 24:                         <City>Redmond</City>
 25:                         <CountryRegionId>USA</CountryRegionId>
 26:                         <State>WA</State>
 27:                         <Street>123 Coffee Street</Street>
 28:                         <ZipCode>98052</ZipCode>
 29:                     </DirPartyPostalAddressView>
 30:                 </WHSShipmentTable>
 31:             </WHSShipmentASN>
 32:         </MessageParts>
 33:     </Body>
 34: </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:

 1: public static void processInboundDocuments()
 2: {
 3:     new AifGatewayReceiveService().run();
 4:     new AifInboundProcessingService().run();
 5: }

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.


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


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.

Until then, please let me know if you have any questions or feedback.


You can download the above post in a Word document here

Comments (24)

  1. Matt Conard says:

    Great post, Vanya.

    Any chance you will be covering an Outbound ASN scenario? ASN Labels? Thanks.

  2. Hi Matt

    Yes, Outbound ASN is on my list right after I finish up with the inbound flow (License plate receiving of the above)

    What do you mean by ASN Labels?

  3. Matt Conard says:

    Hello Vanya,

    Sorry for the delayed response. Were looking for printing out shipping labels containing the SSCC code.  We're having difficulties finding where in AX this happens.  Further, the little bit of information we have found it appears that the data tables necessary to create an SSCC label don't populate until packing slip is generated.   This is too late in the process for us.  We need to generate these SSCC labels when we create a pick list.

    We are planning to use the ContainerID field from the WHSContainerLine table with our companies GS1 prefix to build out the SSCC code.   It looks like ContainerID isn't populated until Pick slip is generated thou. Is there a parameter to be able to print the Packing Slip prior to "Confirm Outbound Shipment" as there is for the B.O.L.? The Packing Slip is generally printed and utilized during the staging process. Regards.

  4. Abhinav Gupta says:

    Hi Vanya,

    In case we perform the receiving based on the information on ASN, does that means, Arrival Journal process will be bypassed and one the ASN (Shipment is verfied and closed), Purchase order status will be receieved.



  5. rub says:

    How can you add two POs to the same ASN?  I tried few things with not much luck?  Do you think the xml below will work?

    14:                         <WHSASNItem class="entity">

     15:                             <ItemId>000148_202</ItemId>

     16:                             <PurchId>000411</PurchId>

     17:                             <Qty>30</Qty>

     18:                             <UOM>ea</UOM>

     19:                             <InventDim class="entity">

     20:                             </InventDim>

     21:                         </WHSASNItem>

     22:                     </WHSUOMStructure>

    14:                         <WHSASNItem class="entity">

     15:                             <ItemId>000148_203</ItemId>

     16:                             <PurchId>000412</PurchId>

     17:                             <Qty>30</Qty>

     18:                             <UOM>ea</UOM>

     19:                             <InventDim class="entity">

     20:                             </InventDim>

     21:                         </WHSASNItem>

     22:                     </WHSUOMStructure>

  6. rub says:

    I was able to add another PO to the same WHSUOMStructure  by adding ASNItem.   However the License plate does not get populated as part of the UOM structure.. I would like to have same LP if possible.

  7. Praveen says:

    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.

    Please provide me the link for next blog post.

  8. Hi Abhinav,

    To answer your question from Aug 11,

    The arrival journal is not used as part of the License Plate receiving method.

    Instead, the items are physically registered at the inbound dock (default receiving location for the work user warehouse), and work is created to put away the items that arrived to the appropriate locations based on location directive setup. This is true for LP receiving and all other receiving methods available on the mobile device, such as PO item receiving, Load item receiving, etc.

    The purchase order status will be changed to Received at the same point in time as in the flow where an arrival journal is used, more specifically, when the product receipt document is posted in the system.

  9. Hi rub,

    To answer your question from Aug 12 (with a small correction – my system had a bug in data),

    It is in fact possible to import an ASN for multiple purchase orders, that are shipped on the same license plate.

    The items need to be part of the same shipment, targeted for one warehouse, meaning that the warehouse/site specified on the purchase order lines of the two purchase orders need to be the same.

    Note: In RTM, there are a number of illegal ASN xml combinations that will result in successful data creation, but are incorrect. The best way to check yourself against such files is to try creating the same packing structure manually.

    Here's a link (http://1drv.ms/1nCWCEM) to a sample XML file that is based on 2 purchase orders for 2 different items, that are part of the same shipment. As you can see, both lines are placed on the same license plate.

    Depending on your location directives, location stocking limits and location profile configuration, the items on the above ASN will either be placed on the same location, in which case they will stay on the same license plate as specified in the ASN, or will need to be split up into multiple locations, and you'll need to enter target license plates for each of the locations.

  10. Abhinav says:

    Thanks Vanya for your response.

  11. Thierry says:


    very interesting post

    i'm also interested by outbound ASN

  12. Thanks Thierry,

    The outbound ASN description is on the backlog for writing, not ETA though

  13. Alfred says:

    Hi Ivan,

    I tried to setup my database to run this tutorial, but I can't achive it, the load doesn't generate any shipments and it has no item lines.

    What need to configure, (Wave templates, location directives, Work templates)??



  14. Hi Alfred,

    If you share your ASN file with me (through OneDrive or whatever), I'll take a look and try to help you figure out the issue

  15. ibfredi says:

    Hi Ivan,

    In my sample I use your .xml file, just changed the product and the purchase order number.

    And I setup these:

    I setup two locations directives (put and pick) defining the location profile id.

    A wave template with activated checks (Wave creation, process wave at release warehouse, Automate wave release)

    A load template

    And a work template with pick and put works.

    I follow all the steps in this walkthrough, I run the process checked the exception log and I can't found any error, but still not working.

    Thank you for your comments.

  16. Hi ibfredi,

    "but still not working" — what exactly is not working? can you be more specific? what are you expectations?

    The data you set up does not yet play a role. You need a purchase order that matches what you have specified in the ASN document. Location directives, work templates will only come into play when you do the actual receiving. Wave templates only apply to outbound orders.

  17. Joe_Gramann says:

    Hi Vanya,

    very interesting and helpful blog(s). A question to the packing structure and license plates. The Inbound ASN would be very interesting for our business as we receive many containers 40 FT a day. The Inbound ASN would help us to proceed those more efficiently.

    A 40 ft container is typically floor stacked so my question is how would you see the packing structure? How about license plates – 1 per carton or 1 for the full container? We usually have one PO per container.

    In on of your replies you mentioned that if 1 license plate  (physically two pallets) would be put on two different locations that LP needs to be split in the put away process. Is there any guide for that to make it work?


  18. Hi Joe,

    Having 1 LP for the full container is not something I would recommend, since that would result in a very large work order. Since you can't really split the work when using the LP receiving method, it would just be 1 work order that would need to be executed by 1 person, which probably would be too much.

    So you are probably better off receiving 1 carton at a time.

    During work creation, if your items are not allowed or do not fit into 1 location, they will be split into multiple put work lines, and you'll need to provide the LPs when executing the work.

  19. Emily says:

    Nice blog, and good functionality!

    Are there any improvements on the functionality available in the meantime, considering the points of attention mentioned?


  20. I believe #3 was addressed with a recent hotfix.

    Not much changed around #1 or #2, even though there were smaller fixes in this area.

    What in particular are you looking for Emily?

    Are you currently using the ASN out of the box and having issues?

    1. Hi Ivan

      I have an instance (as you mention above) where I have the same item on the same license plate, but with different batch numbers. When I try add it to the packing structure, it gives an error: Cannot Edit a Record in Unit Structure WHSUOMStructure.

      I’m running AX 2012 R3 – CU12.

      Any ideas?

      1. You’ll need to open a support request, it’s pretty hard to troubleshoot without seeing the data you try to import and the specific error you encounter.

  21. Roberto says:

    Hi Ivan, when I lauch TMS costification from the Purch load, where does departure address come from?

Skip to main content