Checkout activities like calculating cart totals, updating inventory, and processing payments are handled outside of the core API using Windows Workflow Foundation workflows. Each workflow contains a number of activities, each with a distinct purpose such as calculating discounts; the activities may be re-used among workflows. This division allows for greater flexibility and easier business rules management. The Windows Workflow Foundation technology (WF) is shipped with the .NET 3.0 Framework. If you want to change the business rules associated with checkout, ECF allows you to incorporate your own workflows.
CartValidateWorkflow - This workflow is executed every time the cart view page is loaded. It is called in the CartViewModule.ascx control, which renders the cart. It uses the following activities, in order:
- RemoveDiscountsActivity - Discounts are removed so that pre-discount totals can be calculated in the next step
- CalculateTotalsActivity - This second calculation of totals includes discounts.
CartPrepareWorkflow - This workflow is executed just prior to completing the order. It performs all of the calculations necessary to ensure the cart includes all relevent discounts and ancillary costs (e.g. taxes, shipping charges). It uses the following activities, in order:
- RemoveDiscountsActivity - Discounts are removed so that pre-discount and pre-tax totals can be calculated in the next step
- CalculateTotalsActivity - This second calculation of totals includes discounts and taxes.
CartCheckoutWorkflow - This workflow is executed upon submission of the cart for processing. It uses the following activities, in order:
AdjustInventoryActivity - If Inventory tracking is enabled, will adjust SKU inventory after purchase.
CalculateDiscountsActivity - Calculates the discounts associated with each lineitem, shipment discounts, and order discounts. Discounts are saved in line item Discounts, Shipment's Discounts collection, and OrderForm Discounts collection.
CalculateTaxActivity - Calculates tax associated with order. For more information on this, see this link about Taxes.
CalculateTotalsActivity - Calculates total for cart based on lineitem price, quantity of each lineitem, shipping totals, handling totals, and taxes. OrderForm, Cart, and lineitem properties regarding totals are updated.
CheckInventoryActivity - If inventory tracking is enabled, determines whether sufficient stock is on hand for each lineitem. If not, quantities of SKUs greater than stock are removed and warnings returned to indicate the cart change.
ProcessHandlingActivity - No implementation is included.
ProcessPaymentActivity - Calls the ProcessPayment method associated with the payment providers associated with the cart.
ProcessShipmentsActivity - Determines the shipping rates associated with an order by calling the GetRate method associated with each Shipment of line items in a Cart.
RecordPromotionUsageActivity - Saves promotion usage data to the PromotionUsage table, where its used to track each promotion entry for enforcement of promotion redemption limits.
RemoveDiscountsActivity - Empties the discount collections associated with LineItem, Shipment, and OrderForm instances.
ShipmentSplitActivity - Associates items in cart with the shipments they've been added to previously. List of items in each Shipment are stored in LineItemIndexes field.
ValidateLineItemsActivity - Transfers catalog entry inventory properties to each LineItem, returns an error message if the price for a lineitem has changed. returns an error message if the quantity of a LineItem is reduced due to an inventory shortage, and removes SKUs (with an error message returned) that are no longer active or are members of inactive catalogs.
In order to replace or customize an existing workflow, the basic steps you need to perform are:
1. Create and build a new sequential workflow in a Visual Studio project and add existing or new activities to a workflow.
2. Update the ecf.workflow.config file to use the new workflow assembly.
Workflow configuration is found in \Configs\ecf.workflow.config. The default content of ecf.workflow.config is below:
In the following example, we create a new workflow activity and then utilize it in a new workflow. We then use this workflow to replace the shipped CartCheckout workflow. The new activity sends an automated email to store customers after an order completion. The main aim of this example is to illustrate how a workflow can be updated and customized.
Create a new Activity
1. Create a Workflow Activity Library project in Visual Studio, in this example we have named the project CustomActivityLibrary1.
2. Add a new activity to the activities project for the email. Name the Activity SendNotification.
3. Set the inheritence for the activity to System.Workflow.ComponentModel.Activity .
4. Add references to the CommerceLib project and Mediachase.MetaDataPlus dll in the Components folder.
5. Add the code into the new activity's code-behind file (SendNotification.cs) from the Code Sample section in this document. Ensure the naming is correct and that you create the stub of the method to send the email and that your method is called in the activity Execute method. A stub for the method is provided in the SendEmailNotification() method. See the SendEmails method code in the PublicLayer/SDKs/B2CSampleSite/Templates/Everything/BusinessControls/CheckoutControls/CheckoutWizardModule.cs file.
- Note that you should use the activity OrderGroup object reference to retrieve the information about the order that you want to put in the email. To generate the formatted copy of the email body text with the order information, use the Mediachase.Commerce.Engine.Template.TemplateService. Documentation for how to setup and use this template service can be found here: Sending Order Notifications.
6. Build the project.
7. Ensure that the activity has been added to the Visual Studio Toolbox. For information about this see the article on MSDN: How to: Add Activities to the Toolbox on MSDN:
Here we shall add the activity (created above) along with other activities contained in the Mediachase.Commerce.Workflow.Activities.dll in a new workflow. We will then use this workflow to replace the CartCheckout workflow (Mediachase.Commerce.Workflow.CartCheckoutWorkflow).
1. Create a Workflow project (.NET 3.5, blank project) in Visual Studio, in this example we name the project MyCustomCartCheckout.
2. Add a sequential workflow to the project customCartCheckout - in this example we name the workflow customCartCheckout.
3. Here we re-create the original CartCheckout Workflow and add the SendNotification activity created above. From the Toolbox, drag and drop activities onto the workflow design area in the following sequence:
4. In the workflow code-behind file (in this example named customCartCheckout.cs), add the properties OrderGroup and Warnings. See the relevant code in the code sample section in this document.
5. For each activity in the design view of the workflow, set the OrderGroup and Warning properties to the workflow OrderGroup and Warning properties. When you click on each activity in the workflow design view, you see the option to set this in the properties window.
6. Add a reference to the CommerceLib project. Also add a reference to the Common.Logging and Mediachase.MetaDataPlus dlls in the Components folder.
7. Build the project.
8. Locate the newly built assembly and copy it to the bin folder of the project.
9. Change the Configs\ecf.workflow.config file to point to the new assembly (workflow) which will handle the CartCheckout process. Update the CartCheckout element.
The configuration for this example is below:
<add name="CartCheckout" displayname="Cart Checkout" description="Processes credit card information" type="MyCustomCartCheckout.customCartCheckout, MyCustomCartCheckout" xomlpath="" rulespath="" />
10. Finally - recompile, reset IIS, and access the website where this activity is used during checkout.
Here's the starting code for the SendNotification activity.
Here are the properties to be added to the workflow .cs file.
Mediachase.Commerce.Workflow - contains the workflows
Mediachase.Commerce.Workflow.Activities.Cart - contains the activities