How to use CustomFields in Email template

[dandersonMLT]

I am new to AbleCommerce.
I have added a CustomField for OrderShipment named "RequestedArrivalDate."
I have this field loading and saving correctly in my application.

How do I add this field to email template for customer order notification?
I'd like to be able to include it on the email back to the customer.

Thank you.

[mazhar]

I am not sure how you implemented the your custom field. If you have used ac_CustomFields table (CustomField class) then I am not sure if its possible to directly access this information in template context. In order to get data in Email template you need to insert this information in BasketItem.CustomFields which will be transferred to OrderItem.CustomFields upon successful checkout. In Email template you can locate following code

Code: Select all

<div style="padding-left:30px;">
            $shipment.ShipMethodName
        </div>

and then update it like

UPDATED CODE TO USE ORDER ITEMS FROM ORDER OBJECT TO MAKE SURE IT FINDS CUSTOM FIELDS

Code: Select all

<div style="padding-left:30px;">
            $shipment.ShipMethodName
        </div>
#foreach($orderItem in $order.Items)
        #if (($orderItem.OrderItemType == "Shipping") && ($orderItem.OrderShipmentId == $shipment.Id))
                #foreach($customField in $orderItem.CustomFields)
                    #if($customField.Key == "ArrivalDate")
                    Arrival Date: $customField.Value
                    #end
                #end
            #end
        #end

Now in order to test if you edit order items table of an existing order and then put this information in CustomFields column

Code: Select all

ArrivalDate=Friday, 9 October 2015

Finally go to admin order summary page and click on customer's Email address. This will provide you with option to preview and resend notifications. Choose the Customer Order Notification template and check its preview. You should be able to see the arrival date right under shipping method name.

[dandersonMLT]

Thank you.
I am using the CustomFields class.

Is there really no way to access these in a template, or to pass them in. I guess for arrival date I could attach it to each basket item, but really the date applies to the order, not each item in the order.
Especially if that value is user changeable.

There could be other instances in the future where it would make even less sense to attach the field to the item, so I worry about relying on that technique.

[jguengerich]

I think this would work:
You could extend the OrderShipment class to include your own property, and the getter for it could retrieve the custom field. I don't know if you could do this with a partial class in the App_Code folder, or if you would have to have full source and modify the OrderShipment class directly. Assuming it works, then you could access that OrderShipment property in the template just like the other OrderShipment properties.

[dandersonMLT]

Thanks.
I did try setting up an extension method previously and using that.
However, it seemed that NVelocity engine didn't have access to the extension method.

I inherited this project so I am not sure I have the source code to modify the OrderShipment class.
I will try to find out though

[jmestep]

What table are you using for the custom fields? Is it a new table? A field added to the shipments table? If you are using Able's custom field table, mazhar's solution should work.

[jguengerich]

Since you only need one date per order instead of per item, another option would be to use an OrderNote (set from your custom field) that has it's NoteType set to NoteType.SystemPrivate, IsRead set to true, and starts with a token. For example, "RequestedArrivalDate=10/31/2015". Then, since the template already has access to $order.Notes, you could just find the note that starts with the token and only print the rest of the note.

EDIT: If you need one date per shipment, you could add a shipment number to the token part of the note and use one note per shipment. So an order with 3 shipments would have 3 notes.

[dandersonMLT]

What table are you using for the custom fields? Is it a new table? A field added to the shipments table? If you are using Able's custom field table, mazhar's solution should work.

dbo.ac_CustomFields

Thanks!

[dandersonMLT]

Since you only need one date per order instead of per item, another option would be to use an OrderNote (set from your custom field) that has it's NoteType set to NoteType.SystemPrivate, IsRead set to true, and starts with a token. For example, "RequestedArrivalDate=10/31/2015". Then, since the template already has access to $order.Notes, you could just find the note that starts with the token and only print the rest of the note.

EDIT: If you need one date per shipment, you could add a shipment number to the token part of the note and use one note per shipment. So an order with 3 shipments would have 3 notes.

Thank you for the help. I will look into this approach to see if I can get it working.
I will likely need to go through old orders and update them as well.

[dandersonMLT]

Thanks jguengerich. I was able to get your method of using order notes to work so I will go with that.
I still with there was a way to get this value directly from ac_customfields, without having to duplicate the data into an order note, but that will work for now.
I'll just have to remember to add order note every time I change the requested arrival date custom field, or add a database trigger to do this for me.

Thanks again,
Dave

[jguengerich]

You'd probably want to modify the existing note if the date changes, not add a new one.

[jguengerich]

Another possibility is to add your own parameters to the template at the same place the other parameters (store, order, etc.) are added, but I don't remember where the template is loaded for order confirmation emails during the checkout process. I think it is in the source code because it is initiated by a trigger.

Code: Select all

// template is retrieved from database
// standard parameters are added
theTemplate.Parameters["rad"] = // code to get the appropriate custom field based on order #

Then in the template, you would access it using $rad

[dandersonMLT]

Another possibility is to add your own parameters to the template at the same place the other parameters (store, order, etc.) are added, but I don't remember where the template is loaded for order confirmation emails during the checkout process. I think it is in the source code because it is initiated by a trigger.

Code: Select all

// template is retrieved from database
// standard parameters are added
theTemplate.Parameters["rad"] = // code to get the appropriate custom field based on order #

Then in the template, you would access it using $rad

Yes this would be the ideal solution. I'm just not sure I have access to inject the parameters without source code.
I looked for all references to the customer order notification trigger enum in code and didn't find any.

[jguengerich]

I suppose you could remove the trigger for the template and load/send it (or a similar custom template) yourself at the appropriate place in the checkout process. But then you would have to make sure to load the template and get the parameter added properly when placing an order from the admin side, or sending that template from the admin side (i.e. /admin/usercontrols/sendmail.ascx.cs). Of course 2 years from now when you forgot you customized that and something is not working right after an AC update ... .

[dandersonMLT]

Where can I add the order note to the order to ensure it is there when the Order Notification Email is sent.

Currently, I'm creating the order note in paymentwidget.ascx.cs HandleCheckoutResponse.

This creates the note fine, but it seems to happen after the email is sent, as the email received by the customer does not have my order note.
If I then go back and resend the email by going to order in admin section, clicking email address, and choosing my email template, the order note is included as expected.

I assume the order notification email is being generated in checkoutService.ExecuteCheckout(checkoutRequest);
However, the order also seems to be created in that call. I can't find a way to access the order create the order not until after that method runs.
But since the email seems to be getting triggered in that method, the note hasn't been added by the time the email is sent.

Where can I inject the order note to ensure it is included on the order notification email?

[mazhar]

You can put your code in CheckingOutHandlerof ConLib/Checkout/PaymentForms/PaymentWidget.ascx.cs file. This way it will always called while checking out using any of available payment methods.

[dandersonMLT]

You can put your code in CheckingOutHandlerof ConLib/Checkout/PaymentForms/PaymentWidget.ascx.cs file. This way it will always called while checking out using any of available payment methods.

Thanks, but how do I access the order at that point?
when i check e.Payment.Order it is null, as is this.Order.

[mazhar]

Looks like I forgot about order being not available at this point . Well you can't really add note before system generated Email unless you unhook the notification in merchant email triggers and then send it manually in CheckedOutHandler by loading template yourself.

[jguengerich]

Thanks, but how do I access the order at that point?
when i check e.Payment.Order it is null, as is this.Order.

Sorry, it has been a while since I looked into using the OrderNotes this way, and I forgot that there wasn't a way to get an OrderNote added before the email is sent without changing source code or sending it manually instead of using the trigger.

It looks like Mazhar's original recommendation (setting a custom field on the shipping BasketItem right before ExecuteCheckout) is probably best - everything else seems more complicated and/or requires source code.

I did think of another possibility, but Mazhar's original recommendation is probably better:
Use the LineMessage property of the Shipping BasketItem, which should get transferred to the LineMessage property of the Shipping OrderItem - basically the same as Mazhar's recommendation, but you only have one LineMessage; with CustomFields, you can have more if you need to in the future. Also, the LineMessage property may be used by some of the Tax add-ins, perhaps someone from AC can comment on that if you are interesting in trying this option.

[dandersonMLT]

Ok, I'm really confused now.
I went back and used Mazhar's original suggestion and I am adding the arrival date to BasketItem.CustomFields in the CheckingOutHandler of PaymentWidget.ascx.cs so that it would be available on the orderItem.CustomFields in the email template.

However, I am still not seeing it on the initial email send. It is acting as if it still doesn't have the value at the time the email trigger sends the email.
If I go back and edit the order, click on email address, and choose Order Notification Template, I do see the arrival date I added to basketItem.CustomField.

Is there an earlier event handler I need to use to add it to the basketItem.CustomFields collection?
Or is there a different object other than $orderItem.CustomFields in the template?

I know the template logic is correct, as I see the custom field if I preview the template when editing an order in admin.

[mazhar]

Make sure you are adding field to BasketItem of type Shipping. Try following code

Code: Select all

BasketItem shippingItem = AbleContext.Current.User.Basket.Items.Find(bi => bi.OrderItemType == OrderItemType.Shipping);
            if (shippingItem != null)
            {
                shippingItem.CustomFields.Add("ArrivalDate", "Friday, 16 October 2015");
                shippingItem.Save();
            }

[dandersonMLT]

Still not working. It will show on edit, but not on the initial email.

C#:

Code: Select all

private void CheckingOutHandler(object sender, CheckingOutEventArgs e)
{
           
                var requestedArrivalDate =
                        Session["RequestedArrivalDate"] == null ?
                        string.Empty :
                        Session["RequestedArrivalDate"].ToString();

                if (!string.IsNullOrEmpty(requestedArrivalDate))
                {
                    var shippingItem = this.Basket.Items.Find(bi => bi.OrderItemType == OrderItemType.Shipping);
                    if (shippingItem != null)
                    {
                        shippingItem.CustomFields.Add("RequestedArrivalDate", requestedArrivalDate);
                        shippingItem.Save();
                    }
                }
           
}

Email Template:

Code: Select all

#foreach($orderItem in $shipment.OrderItems)
      #if (($orderItem.OrderItemType == "Shipping"))
            #foreach($customField in $orderItem.CustomFields)
                  #if($customField.Key == "RequestedArrivalDate")
                        <br />Requested Arrival Date: $customField.Value
                  #end
            #end
       #end
#end

[dandersonMLT]

Any other ideas?

[mazhar]

Any other ideas?

I just updated the NVelocity code I shared earlier. Please check my first post. It seems like NVelocity was having some trouble locating custom fields from shipment items so I had to iterate over entire order items and then restrict over shipment. This should make the above fix work for you

NOTE Not sure if you are using Delivery Instructions feature. If you go to Administration -> Store -> General page and find this setting

Delivery Instructions - allow users to enter special shipping information.

This setting when turned on show a message box along shipment on ship method page which allows customer to enter any custom note for shipment. This field is already included in Customer Notification Email template. So if you are not using this feature then you can simply add your arrival information in

Code: Select all

shipment.ShipMessage

field and it should appear in Emails.

[dandersonMLT]

Thank you mazhar. The updated code above solved the problem. Thanks to everyone for all of your help!