Whitepaper: Custom Xml Response Extensions (.al)

Preface

In Microsoft Dynamics 365 Business Central the extension model is object-based; You create new objects, and extend existing objects depending on what you want your extension to do. The underlying Mobile WMS source code is now sealed and can no longer be modified directly.

This necessitated a refactoring of our model for making custom changes to the Xml Resquests and Xml Responses that is being communicated between the mobile devices and the Mobile WMS backend in Business Central. As a part of this refactoring, we are introducing new "accessor" layer to manipulate the Xml content, but with no need to manipulate the Xml Documents directly as to date.

Past model (C/SIDE)

Historically changes to Xml Responses was made directly in Mobile WMS document hander codeunits, e.g. codeunit "MOB WMS Receive". Changes implied writing directly to the Xml output, and required knowledge of the xml element, a case sensitive xml tag and using a correct namespace., 

Example:

// The choices are: None, Warn, Block
// MobXMLMgt.AddElement(XMLOrderLine, 'UnderDeliveryValidation', 'Warn', BaseDataModelNS, XMLCreatedNode);
MobXMLMgt.AddElement(XMLOrderLine, 'UnderDeliveryValidation', 'Block', BaseDataModelNS, XMLCreatedNode);

New model (AL)

Changes to Xml Responses now requires a new Event Subscriber procedure to be declared in your own code. Changes are now strictly in your own project, and the underlying Mobile WMS source code is no longer modified. You can subscribe to (among others) a number of  new "OnAfterSetFrom"-events that is now published by the Mobile WMS app,   The documention of exact available events can be found in the API Document Handlers documentation.

Rather than manipulating the Xml output directly, values is now set in new "accesssor table" that hides all underlying Xml considerations. By using Set/Get accessor methods in these accessor tables, content is automatically formatted and inserted at correct nodes and namespaces in the Xml documents.

Example:

[EventSubscriber(ObjectType::Codeunit, Codeunit::"MOB WMS Receive", 'OnAfterSetFromAnyLine', '', true, true)]
procedure OnReceiveOnAfterSetFromAnyLine(_RecRef: RecordRef; var _BaseOrderLineElement: Record "MOB Ns BaseDataModel Buffer")
begin
     // Under-/OverDeliveryValidation - The choices are: None, Warn, Block
     _BaseOrderLineElement.Set_UnderDeliveryValidation('Block');
end;

Accessor class (C#)

New "accessor tables" has been introduced to Mobile WMS. The accessor tables concept is derived from C# property classes.

From: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/using-properties

Properties combine aspects of both fields and methods. To the user of an object, a property appears to be a field, accessing the property requires the same syntax. To the implementer of a class, a property is one or two code blocks, representing a get accessor and/or a set accessor. The code block for the get accessor is executed when the property is read; the code block for the setaccessor is executed when the property is assigned a new value.

Properties have many uses: they can validate data before allowing a change; they can transparently expose data on a class where that data is actually retrieved from some other source, such as a database; they can take an action when data is changed, such as raising an event, or changing the value of other fields.

Example, C# syntax

class Person
{
    private string name;  // the name field
    public string Name    // the Name property
    {
        get
        {
            return name;
        }
        set
        {
            name = value;
        }
    }
}

Accessor table (AL)

In AL, codeunits (the AL equivalent for C# classes) cannot be parameters to procedures/methods, unlike in C#.  This makes AL codeunits a poor choice when temporary data needs to be stored and transferred between codeunits and procedures. Instead, we have introduced new "accesssor tables" in Mobile WMS, basically being C# style acccessor classes, but implemented at table level. 

Three new accessor tables has been introduced. Each table corresponds to a specfic part of the Mobile WMS Xml schema, and makes available get/set accessors for each node in corresponding namespaces.

• table 6181380 "MOB Ns Resp Element"
• table 6181381 "MOB Ns BaseDataModel Element"
• table 6181382 "MOB Ns WhseInquery Element"

"MOB Ns Resp Element" is the most simple of those, and includes only get/set-methods for one predefined property "description". Also, every accessor table includes get/set-methods to add custom elements not being a part of the standard schema, including as CDATA elements:

• Get_description(): Text
• Set_description(NewValue: Text)
  

• GetValue(_PathToGet: Text): Text
  
• SetValue(_PathToSet: Text; _NewValue: Text)

• SetValueAsCData(_PathToSet: Text; _NewXmlCData: XmlCData)

• SetValueAsCData(_PathToSet: Text; _NewCDataValue: Text)
  
  

Ns BaseDataModel Element (Accessor table, AL)

The "MOB Ns BaseDataModel Element" is used to build "<BaseOrder>" and "<BaseOrderLine>" elements in the BaseDataModel namespace. It is the most frequently used new accessor table by far. All 'GetXXXOrdes" and "GetXXXOrderLines" requests will make this accessor table available from a number of new "OnAfterSetFrom[...]"-events.

Sample use is i.e. OnGetReceiveOrders_OnAfterSetFromWarehouseReceiptHeader and OnGetCountOrders_OnAfterSetFromItemJournalBatch

At time of writing (August 2019) this accessor table supports these following tags:

• Get / Set_BackendID
• Get / Set_OrderBackendID
• Get / Set_LineNumber  (set by Integer or Text)
• Get / Set_FromBin
• Get / Set_ValidateFromBin  (set by Boolean or Text)
• Get / Set_ToBin
• Get / Set_ValidateToBin  (set by Boolean or Text)
• Get / Set_AllowBinChange  (set by Boolean or Text)
• Get / Set_ItemNumber
• Get / Set_ItemBarcode
• Get / Set_Description
• Get / Set_RegisterSerialNumber  (set by Boolean or Text)
• Get / Set_RegisterLotNumber  (set by Boolean or Text)
• Get / Set_RegisterExpirationDate  (set by Date or Text)
• Get / Set_RegisterQtyByScan
• Get / Set_SerialNumber
• Get / Set_LotNumber
• Get / Set_Quantity  (set by Decimal or Text)
• Get / Set_RegisteredQuantity
• Get / Set_UnitOfMeasure
• Get / Set_Status
• Get / Set_HeaderLabel1
• Get / Set_HeaderLabel2
• Get / Set_HeaderValue1
• Get / Set_HeaderValue2
• Get / Set_DisplayLine1
• Get / Set_DisplayLine2
• Get / Set_DisplayLine3
• Get / Set_DisplayLine4
• Get / Set_DisplayLine5
• Get / Set_UnderDeliveryValidation
• Get / Set_OverDeliveryValidation
• Get / Set_ItemImageID
  
  ... for Tote Picking only:
• Get / Set_TotePicking  (set by Boolean or Text)
• Get / Set_Destination
• Get / Set_Priority
  
  ... for sorting. Is never written Xml Response directly but used by the Mobile WMS base application to determine and populate <Sorting>-tag
  ... unlike versions prior to MOB5.00, the <Sorting> tag can no longer be set directly but is always populated by the system.
  
  
• Get / Set_Sorting1 (internal)   (set by Integer, Date or Text –> will be formatted and padded as needed to match sql sorting)
• Get / Set_Sorting2 (internal)   (- do -)
• Get / Set_Sorting3 (internal)   (- do -)
• Get / Set_Sorting4 (internal)   (- do -)
• Get / Set_Sorting5 (internal)   (- do -)

... for new (custom) tags:

• GetValue(_PathToGet: Text): Text
• SetValue(_PathToSet: Text; _NewValue: Text)

• SetValueAsCData(_PathToSet: Text; _NewXmlCData: XmlCData)

• SetValueAsCData(_PathToSet: Text; _NewCDataValue: Text)

Ns WhseInquiry Element (Accessor table, AL)

The "MOB Ns WhseInquiry Element" is used to build "<LookupResponse>"-elements in the WarehouseInquiryDataModel namespace. It is used from the "MOB WMS Lookup" codeunit.

Sample use is i.e. OnLookupOnLocateItem_OnAfterSetFromBinContent and OnLookupOnPostShipment_OnAfterSetFromWarehouseShipmentHeader

At time of writing (August 2019) this accessor table supports these following tags:

• Get / Set_Location
• Get / Set_ItemNumber
• Get / Set_Barcode
• Get / Set_DisplaySerialNumber  (Note: Text field to display SerialNumber including leading label)
• Get / Set_SerialNumber
• Get / Set_DisplayLotNumber  (Note: Text field to display LotNumber including leading label)
• Get / Set_LotNumber
• Get / Set_DisplayExpirationDate  (Note: Text field to display ExpirationDate including leading label)
• Get / Set_ExpirationDate  (set by Date or Text)
• Get / Set_Bin
• Get / Set_Quantity  (set by Decimal or Text)
• Get / Set_UoM
• Get / Set_DisplayLine1
• Get / Set_DisplayLine2
• Get / Set_DisplayLine3
• Get / Set_DisplayLine4
• Get / Set_DisplayLine5
• Get / Set_ExtraInfo1
• Get / Set_ExtraInfo2
• Get / Set_ExtraInfo3
  
  ... for "LookupPostShipment" only:
• Get / Set_ShipmentNo
  
  ...  for sorting. Is never written Xml Response directly but used by the Mobile WMS base application to determine and populate <Sorting>-tag
  ... Unlike versions prior to MOB4.50, the <Sorting> tag can no longer be set directly but is always populated by the system.

• Get / Set_Sorting1 (internal)   (set by Integer, Date or Text –> will be formatted and padded as needed to match sql sorting)
• Get / Set_Sorting2 (internal)   (- do -)
• Get / Set_Sorting3 (internal)   (- do -)
• Get / Set_Sorting4 (internal)   (- do -)
• Get / Set_Sorting5 (internal)   (- do -)
  
  

    ... for new (custom) tags with no preexisting Get/Set-methods:

• GetValue(_PathToGet: Text): Text
• SetValue(_PathToSet: Text; _NewValue: Text)

• SetValueAsCData(_PathToSet: Text; _NewXmlCData: XmlCData)

• SetValueAsCData(_PathToSet: Text; _NewCDataValue: Text)