Creating a Custom Pipeline Task

You will learn how to create a custom pipeline task, which can be used to do custom task when Ucommerce executes the basket pipeline or any other pipeline for that matter.

In Ucommerce there's primarily 4 pipelines out of the box getting executed:

• Basket pipeline
  • this is executed each time a user updates the basket (puts stuff into it, adjusts the quantity or removes an item)
• Checkout pipeline
  • this is executed when the user has entered his credit card information and the order is being fullfilled
• ToCompleted / ToCancelled pipeline
  • When the order goes from new order to completed or cancelled.

In this example we'll create a pipeline task that will get executed in the Checkout pipeline. The purpose of this task is to tell a store administrator every time an order goes through the system. To achieve this we first need to:

• Create a visual studio project
• Create a class that implements IPipelineTask<PurchaseOrder>
• Build and deploy the assemblies
• Configure the task in configuration file

On to the Code

Below is my class OrderCompletedTask which implements IPipelineTask. In the constructor it takes everything needed for sending an email. If you have dependencies that are not part of the core platform, just makes sure to configure them in your configuration file in your app folder in Ucommerce/Apps/MyApp, just like we'll do for this task later.

    namespace UCommerceCodeSamples.Pipelines
    {
    	public class OrderCompletedTask : IPipelineTask<PurchaseOrder>
    	{
    		
    		private readonly CommerceConfigurationProvider _provider;
    		private readonly IEmailService _emailService;
    		private readonly ICatalogContext _catalogContext;
    
    		public OrderCompletedTask(CommerceConfigurationProvider provider,
    								IEmailService emailService,
    								ICatalogContext catalogContext)
    		{
    			_provider = provider;
    			_emailService = emailService;
    			_catalogContext = catalogContext;
    		}
    		

The next step to achieve this is to implement the method Execute which Ucommerce will be responsible for calling, whenever the basketpipeline is executed.

    public PipelineExecutionResult Execute(PurchaseOrder subject)
    {
    	var localization = new CustomGlobalization(_provider);
    	localization.SetCulture(new CultureInfo(subject.CultureCode));
    
    	var queryStringParams = new Dictionary<string, string>();
    	queryStringParams.Add("orderguid", subject.OrderGuid.ToString());
    	queryStringParams.Add("orderid", subject.OrderId.ToString(CultureInfo.InvariantCulture));
    	var emailProfile = _catalogContext.CurrentCatalogGroup.EmailProfile;
    
    	_emailService.Send(localization, emailProfile, "Orders", new MailAddress("[email protected]"), queryStringParams);
    	
    	return PipelineExecutionResult.Success;
    }
    

Register the Task

To make Ucommerce use the task we've just created we need to register it as a component. Here's what the component registration looks like for our example:

    
    <configuration>
    	<components>
    		<component 
    			id="ToCompletedOrder.SendOrderCompletedMail"
    			service="UCommerce.Pipelines.IPipelineTask`1[[UCommerce.EntitiesV2.PurchaseOrder, UCommerce]], UCommerce"
    			type="UCommerceCodeSamples.Pipelines.OrderCompletedTask, UCommerceCodeSamples" />
    	</components>
    </configuration>
    

Put this file in /Ucommerce/Apps/MyPipelineTask where it will be automatically picked up when the application starts up.

Interested in more details about components? Please see Register a Custom Component.

Once added it must be added to the pipeline you want it to be executed as part of.

Configure the Pipeline

Partial components enable you to configure just the changes to the list of tasks of a pipeline, rather than overriding the entire component or modifying the pipeline files directly as was the case in previous versions.

Here is an example of how to add the new task we created above, as the last task in the "ToCompletetOrder" pipeline.

    
    <configuration>
    	<components>
    		<partial-component id="ToCompletedOrder">
    			<parameters>
    				<tasks>
    					<array>
    						<value insert="last">${ToCompletedOrder.SendOrderCompletedEmail}</value>
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

There are some important things to note:

• The id of the partial component must match the id of the pipeline component you wish to modify. In this case it is the "ToCompletedOrder" pipeline component that is modified.
• The value inserted is using the id of the new custom component added in the previous examples, "ToCompletedOrder.SendOrderCompletedEmail".
• Most important is the attribute "insert" with the value "last". This instructs the configuration to add this task as the last task in the pipeline. In this example it makes sense to have the send email task as the last task, since we only want to perform it, if all the previous tasks have completed successfully.

The attributes supported are:

• "insert", with value either "first" or "last".
• "insert-before", with a value of the castle service override notation "${COMPONENTID}".
• "insert-after", with a value of the castle service override notation "${COMPONENTID}".
• "remove", with a value of the castle service override notation "${COMPONENTID}".

It is very important to note, that when using "insert-before" or "insert-after", the task is added after every occurance of the service found in the pipeline. So be aware, that the task can be added more than once. Also note that "remove", will remove all instances of the matching tasks.

In the following example, a custom pipeline task called "MyCustomTask" is added to the basket pipeline after the task "Basket.CleanUp".

    
    <configuration>
    	<components>
    		<partial-component id="Basket">
    			<parameters>
    				<tasks>
    					<array>
    						<value insert-after="${Basket.CleanUp}">${MyCustomTask}</value>
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

And an example of removing the "SendConfirmationEmail" task from the "Checkout" pipeline.

    
    <configuration>
    	<components>
    		<partial-component id="Checkout">
    			<parameters>
    				<tasks>
    					<array>
    						<value remove="${Checkout.SendConfirmationEmail}" />
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

The configuration file should be placed in Ucommerce/Apps/MyApp folder. It will automatically be picked up when the application starts up.

All there's left to do is build and deploy the assemblies into your Application's bin folder.

We've now extended the ToCompleted pipeline with a custom pipeline task.

Performance measurements of pipelines

Setting the Debug parameter to the value "true" enables the logging of performance measurements for the tasks of piplines.

Using partial components configuration, enabling debug is very easy.

Simply add this partial component to the custom configuration file to enable debug for, in this example, the basket pipeline:

    
    <configuration>
    	<components>
    		<partial-component id="Basket">
    			<parameters>
    				<Debug>true</Debug>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

The end result is simply that the default pipeline implementationm, if configured with debug enabled like above, is writting the execution time of each task into the log files.