One of the things you will need when building complex sites with uCommerce is the pipeline system.

A pipeline is a series of tasks, which will execute in a sequental order. You can use these tasks to execute whatever business logic you want, when working with baskets or orders. Currently, the pipeline system only applies to baskets and orders.

The Bits and Pieces of a Pipeline

A pipeline consists of three things:

• The pipeline configuration file itself (an XML file)
• An optional pipeline implementation (written in your favorite .net language)
• One or more pipeline tasks (also written in anything .net-ish)

The configuration file contains the type of the pipeline, each registered pipeline task and the order of which the tasks will be executed.

The file must be located in the /umbraco/ucommerce/pipelines folder. As you can see in the folder, uCommerce comes with a pipeline out-of-the-box – the basket pipeline. Take a look at basket.config to see how it is configured.

The Configuration File

The first component section contains the type of the pipeline, which is a generic type. As mentioned earlier, only baskets and orders are currently supported, which means that the generic type should be UCommerce.Entities.PurchaseOrder (which also applies to baskets). The pipeline type used in the basket pipeline is UCommerce.Pipelines.Basket.BasketPipeline. If you want to implement your own pipeline, you can use the generic type UCommerce.Pipelines.Generic.PurchaseOrderPipeline defined in the UCommerce.Pipelines assembly.

After the pipeline type, each pipeline step is defined, each in it’s own component section with an id. The id is then used in the <tasks> section under the pipeline type to add the task the pipeline, which will then execute the task.

Note: The order of which each task is registered in the <task> section, is the same as the order as they will be executed in.

Writing Pipeline Tasks

Ok, so enough with the XML for now.

To create your own pipeline task, simply implement the IPipelineTask<T> interface.

    /// <summary>
    /// Contains definition for a pipeline task.
    /// </summary>
    /// <typeparam name="T">The type on which the task operates on.</typeparam>
    public interface IPipelineTask<T>
    {
        /// <summary>
        /// Executes the task.
        /// </summary>
        /// <param name="subject">The subject for the task.</param>
        /// <returns></returns>
        PipelineExecutionResult Execute(T subject);

The task must return a member of the PipelineExecution Result enum.

    /// <summary>
    /// Result returned when executing a pipeline or a pipeline task.
    /// </summary>
    public enum PipelineExecutionResult
    {
        /// <summary>
        /// The pipeline or task executed sucessfully.
        /// </summary>
        Success,
        /// <summary>
        /// The pipeline or task has been executed, but with warnings.
        /// </summary>
        Warning,
        /// <summary>
        /// The pipeline or task generated an error.
        /// </summary>
        Error
    }

If the task returns Success, the execution of the pipeline will continue. If you return Warning, the execution will continue, but the overall execution result for the entire pipeline will be set to Warning. If the task returns Error, the pipeline execution will stop, and no additional tasks will be executed. If any exceptions is thrown in a pipeline task, to execution will stop with a PipelineException, with the exception from the task as the inner exception.

Executing Pipelines

There are two ways to execute your pipelines:

• From code
• From XSLT

Executing Pipelines From Code

Executing the pipeline from code using the PipelineFactory is pretty simple:

public PipelineExecutionResult ExecutePipeline(string pipelineName, 
   PurchaseOrder order)
{
    var basketPipeline = PipelineFactory.Create<PurchaseOrder>(pipelineName);
    var result = basketPipeline.Execute(order);
    return result;
}

Executing Pipelines From XSLT

To execute a custom pipeline from XSLT, call the ExecuteOrderPipeline(string pipelineName) method on the uCommerce XSLT library.

<xsl:value-of select="CommerceLibrary:ExecuteOrderPipeline('MyPipeline')">
</xsl:value-of>

If you want to execute the basket pipeline, you can call this nifty method instead:

<xsl:value-of select="CommerceLibrary:ExecuteBasketPipeline()"></xsl:value-of>

Both of the above methods will return the pipeline execution result as XML. If an exception has occured, the exception message will be included in the XML.

So What’s Up With That Basket Pipeline?

The basket pipeline is a built-in pipeline used by the uCommerce runtime. The pipeline will make sure that all e.g. all totals are recalculated. Please do not delete it, but feel free to add your own tasks, if there’s anything you need on recalculating the basket.

A Short Note On Order Statuses And Pipelines

Customization of order statuses is the topic for an upcoming post, but you should know that you can execute pipelines after order status changes. Order statuses are configured in the uCommerce_OrderStatus table. To run a pipeline when an order has been set to a given status, simply but your pipeline name in the “Pipeline” column. If you e.g. want to capture an online payment, this would be a great place to do it.

That’s it for the pipelines. Feel free to contact me if you need more info on the pipeline system.

uCommerce ucommerce, pipeline system