Example Custom Order Workflow Solution

Overview

In many e-commerce solutions, overriding the order workflow is impossible, if not difficult to do.  Hotcakes Commerce feels your pain and makes the process of injecting your own workflow steps or modifying the workflow entirely as easy as a few lines of code, depending on your project requirements.

Requirements

The following concepts and knowledge are required to complete the goals of this article:

• Familiarity with Visual Studio 2012 or newer
• Familiarity with C# programming language
• General understanding of frameworks
• Have a development site ready with Hotcakes Commerce installed

Getting Started

Download Sample Visual Studio Project

You are about to use a Visual Studio project to create the necessary code that you want to have used to change the way the default order workflow functions in Hotcakes Commerce.  A sample project can be downloaded on the right.  The remaining documentation will walk you through how to effectively leverage this project.

Make sure you have a development website ready to accept API calls from your project.  This would consist of the DNN CMS and Hotcakes Commerce.  Also, if you do not already have products in your store, you should consider adding some or adding the sample products.  This could even be a restored back-up of your production website.

SAMPLE CUSTOM ORDER WORKFLOW PROJECT

If you haven’t done so already, make sure your site is up and running and ready for you to develop on it.  We are about to have you set up your project.  Once you understand how this works, feel free to set up your project and solution in any way that works for you.  Also, please do not do this development work on your production website.

Open the download from above using your favorite zip utility.  Grab all of the files from the zip archive and unzip them into the root of your development site.

If you receive any prompts from Windows, it’s likely that you already have a set of Hotcakes project files added to your development site.  Go ahead and overwrite the files.  This should result in the MyWorkflow, References, and MyWorkflow.sln folders and files in your DNN folder like shown below.

Next, open the solution that is now in the root of your website.  Double-clicking on it will do the trick.  This will open Visual Studio and show your project open.  Your Solution Explorer view should look similar to the image below.

The sample solution comes with three (3) classes.  In the root of the solution, you’ll find the MyWorkflow.cs class.  This is the main class where you’ll make changes, as necessary.

There is also a folder labeled Tasks.  This folder has the remaining two (2) classes mentioned, MyOrderTask.cs and MySimpleTask.cs.  These two class files are simply examples of how you would implement your own task classes.

• MyWorkflow Task
• MySimpleTask Class
• MyOrderTask Class

MyWorkflow Task

There are twelve (12) different workflow tasks that you can plug into if you desire.  For each one that you want to override or add steps to, simply uncomment that specific task, and add the appropriate code.  The built-in tasks that run for each order can be thought of like events and are described in the table below.

Task Name	Description
LoadProcessNewOrderTasks	A new order is in the “New” state by default. If an order is moved to the “ToDo” state, this task will execute. This task is uncommented by default in the project and contains two example task calls, MySimpleTask, and MyOrderTask. Remove these two method calls in your production order workflow.
LoadVerifyOrderSizeTasks	This task is executed when your customer loads the checkout page.
LoadDropShipTasks	When an order is marked as “Shipped” this task is executed.
LoadPackageShippedTasks	A package can be shipped before the entire order is considered to be shipped. If you mark a package as “Shipped” this task will run.
LoadOrderEditedTasks	An order can be edited multiple times during its lifespan. This task will execute every time an edit to the order is made.
LoadPaymentChangedTasks	This task will execute each time a payment is made in the order view.
LoadPaymentCompleteTasks	On many stores, a credit card will not be processed until the product is actually shipped. Other stores will accept payment immediately. This task will execute whenever the payment is completed.
LoadProcessNewOrderPaymentsTasks	You can expect this task to run once an order has been accepted to process payments. This also is when PayPal Express, reward points, and gift cards are applied.
LoadProcessNewOrderAfterPaymentsTasks	Once your payments are applied, this task will run.
LoadShippingChangedTasks	This task will execute if you change the status of shipping.
LoadShippingCompleteTasks	Once you mark shipping as being complete, this task will run. This is a common place to update external systems, like your ERP to update inventory.
LoadThirdPartyCheckoutSelectedTasks	If you are using an external payment provider, like PayPal Express, this task will run to execute that payment provider.

If you want to add your own steps within the existing workflow, simply uncomment the desired task and add your custom task using one of the two types of tasks explained below.  They will be executed in the order specified in the order listed within each method.

MySimpleTask Class

If you want to execute a task that doesn’t require any order details, this task will work perfectly fine for you.  A great example of such a task is if you wanted to add the user to your e-mail marketing campaign.

This class inherits from the Task class in the Hotcakes API and has the following overrides that you must include.

Method Name	Description
Clone	This should return a new instance of the same task. If necessary, feel free to include other logic as well.
Execute	This method will be called when the order workflow is ready to run your task. The majority of your custom code should go here, or at least a method call to the rest of your code. An example message is included for your convenience. Add as many messages as necessary. This method must return true or false to indicate if it successfully executed.
Rollback	Like Execute, this method must return true or false to indicate if the Rollback method worked as expected. Use this to rollback any programmatically executed changes. If you don’t have anything to rollback, simply return false.
TaskId	This method must return a unique ID known as a GUID. You should change this to use your own GUID. There are a number of GUID generators out there, including extensions for Visual Studio.
TaskName	This should return the name of your task. Store admins may see this value, so it should be self-explanatory.

Execute Method

The Execute method accepts a parameter that you will use of type TaskContext. This parameter will allow you to access and use the following members.

Member Name	Description
UserId	This is the UserId of the customer. You will have a valid value for all customers, even if they used guest checkout. This value can be used to query for more user information using the API.
Inputs	This member will potentially contain a collection of the values input into the form by the customer.
Errors	This allows you to return a collection of errors to Hotcakes and optionally to show one or more of them to the customer.
Outputs	This member is not used at this time.
GetCustomerVisibleErrors	This will return a collection of the messages that the customer will see.

MyOrderTask Class

The OrderTask code sample is very similar but it includes the additional Rollback method and a second messaging example to illustrate how to add notes to the order as well as access information in the order using the API.  You should only use one of the Rollback methods and throw a NotImplementedException exception for the other.

Execute Method

This method is nearly identical to the method of the same name in the MySimpleTask class.  The only difference is that the parameter you’re given is of type OrderTaskContext.  This object has everything that the previous context object, but this one also includes members to allow for you to easily access information about your store and the order. Those members are described below.

Member Name	Description
Order	This is the main order object and it contains everything related to the order, including customer details, shipping, packages, line items, status, and more.
HccApp	This is the main object that contains the high-level configuration and other details and global store methods.

Deploying Your Code – Development Environment

If you are in your development environment, all you would need to do is:

1. Ensure that you are building to the /Bin directory of your website
2. Choose the integration you build in the Store Admin > Admin > Extensibility view  (see below for a screenshot)

Deploying Your Code – Production Environment

Once you are happy with the results of your custom workflow, build it in release mode and move the DLL you have built to the /Bin directory of your production website.  The name of the DLL will be whatever you have chosen to name it in your project properties.

Once you move the DLL file, choose the new integration(s) in your Store Admin > Admin > Extensibility view.  Select the new workflow you created in the appropriate drop-down list as shown below.

That’s it… We hope you think that this is as easy as we do!