Skip to main content

Additional Order (Line) Attributes

Commerce 365 is capable of processing additional order attributes. The most popular module to use for this, is the Amasty Order Attributes extension. https://amasty.com/order-attributes-for-magento-2.html 

This module allows you to add check-out fields like requested delivery date, comments, PO number or project references, with just a few clicks. And once values have been filled in, our software will automatically import these when importing the Magento order.

If you do not want to use this module, you can also accomplish similar results by doing some custom programming. (See below)

Once these values have been imported in to Business Central, the only thing left to do is to write a bit of custom code to take care of handling these values. By default our software doesn’t know what you want to accomplish with the order attributes you created on the Magento side. The values will just be imported. You can see them on the staging order page. But from here some coding is need.

Below is an example of further processing such values.

Here we are going to use the Sales Order API (codeunit 11260734) to extract the order attributes values, project_code, comments, file_upload and req_delivery_date. And next we will bring all the values over to their corresponding fields on the Business Central sales order we are creating.

[EventSubscriber(ObjectType::Codeunit, Codeunit::"NC365 Staging Order Events", 'OnAfterCreateSalesDocument', '', true, true)]
local procedure StagingOrderEvents_OnAfterCreateSalesDocument(var StagingOrderHeader: Record "NC365 Staging Order Header")
var
    SalesHeader: Record "Sales Header";
    SalesLine: Record "Sales Line";
    TempBlobHelper: Record "NC365 Blob Helper" temporary;
    SalesOrderAPI: Codeunit "NC365 Sales Order API";
    ProjectCode: Text[30];
    RequestedDeliveryDateStr: Text[30];
    RequestedDeliveryDate: Date;
    Comments: Text[1000];
    FilePath: Text[1000];
begin
    if not SalesHeader.Get(StagingOrderHeader."Created Doc. Type", StagingOrderHeader."Created Document No.") then
        exit;

    ProjectCode := SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderHeader, 'project_code');
    Comments := SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderHeader, 'comments');
    FilePath := SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderHeader, 'file_upload');
    //For now we'll add a fixed path to our website domain, so that we have a full path to create a proper link 
    FilePath := 'https://www.websitedomain.com/pub/media/amasty_checkout' + FilePath;

    //The order attributes module returns a date time, we only need a date, so we are splitting and taking the first element. 
    RequestedDeliveryDateStr := SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderHeader, 'req_delivery_date').Split(' ').Get(1);
    //Evaluate to convert string to date, and if that fails, we'll go for the default formula for delivery date calculation 
    if not Evaluate(RequestedDeliveryDate, RequestedDeliveryDateStr) then
        RequestedDeliveryDate := CalcDate('+5D', Today);

    //Convert our incoming text to BLOB
    TempBlobHelper.Init();
    TempBlobHelper.WriteAsText(Comments);

    SalesHeader.Validate("Work Description", TempBlobHelper."Blob");
    SalesHeader.Validate("Requested Delivery Date", RequestedDeliveryDate);
    SalesHeader.Validate("Your Reference", ProjectCode);

    SalesHeader.Modify(true);

    SalesHeader.AddLink(FilePath, 'Web order file upload');
end; 

Below is an example REST API order response message which contains some custom attributes that were created by using the Amasty module. This is the type of response which can be processed by Commerce 365. If you want add custom attributes without using the Amasty module, just make sure that you add your custom attributes to the extension_attributes object in the API response. 

 ...
 "status_histories": [],
    "extension_attributes": {
        "shipping_assignments": [
        ],
        "payment_additional_info": [
            {
                "key": "method_title",
                "value": "Check / Money order"
            }
        ],
        "amasty_order_attributes": [
            {
                "attribute_code": "project_code",
                "value": "PR FI 9293"
            },
            {
                "attribute_code": "comments",
                "value": "Delivery at the back side of the building"
            },
            {
                "attribute_code": "file_upload",
                "value": "/M/a/Magento2_Architecture_Whitepaper_Final_4.pdf"
            },
            {
                "attribute_code": "req_delivery_date",
                "value": "2023-05-31 00:00:00"
            }
        ]
    }
 

Custom attributes on order line level are also possible. At line level the application supports both the use of extension_attributes and the additional_data property. 

Working with order line attributes works exactly the same as with values on header level. Just make sure you supply a StagingOrderLine parameter.

var
    SalesOrderAPI: Codeunit "NC365 Sales Order API";
    JSONHelper: Codeunit "NC365 JSON Helper";
    AttributeObject: JsonObject;
    Inscription: Text[100];
    HexColor: Text[10];
begin
    Inscription:= SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderLine, 'inscription');
    AttributeObject.ReadFrom(SalesOrderAPI.GetStagingOrderAttributeValue(StagingOrderLine, 'color_picker_output'));
    HexColor := JSONHelper.Get(AttributeObject, 'hex_color').AsValue();

Fully automated installation and onboarding

Install via AppSource

Click on the AppSource button, install the free trial and just follow the instructions