Developer Documentation

Commerce Server Integration Guide

After reading this guide you will know how to integrate Enticify with and existing Microsoft Commerce Server 2007 or 2009 website.

Guide Assumptions

  • You've installed Enticify.
  • You have working knowledge of Microsoft Commerce Server.
  • You understand pipeline components and pipeline component configuration files (*.pcf).
  • You have an existing Commerce Server site that uses pipeline configuration files.

Integrate Enticify with your Commerce Server site

Follow these instructions to replace the Commerce Server components OrderDiscount and OrderLevelDiscountApply with the Enticify Discount Components.

You must do this for each PCF file that uses the Commerce Server discount components OrderDiscount and OrderLevelDiscountApply. Usually, this will just be basket.pcf, but your site may be different.

1. Remove Components from the PCF that are no longer required

Remove all of these components as Enticify replaces their behaviour. Enticify will not work as expected if you leave these in.

Important: Make sure you keep a copy of your original PCF files or have them safely in source control.

  1. Open the PCF file (e.g. basket.pcf).
  2. Right click Commerce OrderDiscount and select Delete.
  3. Select Yes when asked if you are sure.
  4. Do the same for Commerce OrderLevelDiscountApply.
  5. Do the same for Commerce RequiredOrderAdjustPriceCy.

2. Ensure Commerce ReservePromoCodes is Included

Enticify requires that Commerce ReservePromoCodes is run before Enticify as it populates the discounts data structure.

  1. Identify Commerce ReservePromoCodes in the PCF file.
  2. If it does not exist, insert it at the beginning of the Order Adjust Price stage.

3. Insert "Enticify :: Promotion Engine"

This is the Enticify component that gives you all of the new discount goodness.

  1. Right click Commerce ReservePromoCodes and select Insert -> After.
  2. Select All in the Stages dropdown box.
  3. Select Enticify :: Promotion Engine in the Components list.
  4. Click the OK button.

4. Insert "Enticify :: Ensure Required Discount Line Properties Set"

This component sets discount amounts, unadjusted quantities and discount amounts for line items that did NOT get passed to Enticify.

  1. Right click the component that is last in the Order Adjust Price stage and select Insert -> After.
  2. Select All in the Stages dropdown box.
  3. Select Enticify :: Ensure Required Discount Line Properties Set in the Components list.
  4. Click the OK button.

5. Move Splitter and ShippingMethodRouter

Move the following components to before "Enticify :: Promotion Engine". These components are usually run after the CS discount components (in the total.pcf). However, Enticify supports more sophisticated shipping discount models and moving them enables this.

Note: these components are usually found be in another pipeline like total.pcf, rather than basket.pcf. You need to move these from there.:

  • Commerce Splitter
  • Commerce ShippingMethodRouter

5.a. Add "Enticify :: Init Basket Shipping"

The StepwiseShipping component is called by ShippingMethodRouter and requires the property _cy_oadjust_adjustedprice. Now that we've moved the shipping components to earlier in the process, this property may not be set. Adding this component, will make sure the value is set, so StepwiseShipping can correctly calculate the shipping costs.

  1. Right click the Commerce Splitter component in the PCF and select Insert -> Before.
  2. Select All in the Stages dropdown box.
  3. Select Enticify :: Init Basket Shipping.
  4. Click the OK button.

Older versions of Enticify did not have this component, so we used a scriptor to set _cy_oadjust_adjustedprice.

5.b. Assign a default ShippingMethodId

Assign a default shipping method id to all line items, even when your customer has not yet selected a shipping method. Splitter requires that all line items have a valid ShippingMethodID.

Alternatively, you can create two PCF files, one with shipments and one without. If the shipments collection is null, or contains zero shipments, Enticify will ignore it.

6. Remove ShippingDiscountAdjust

Remove the ShippingDiscountAdjust pipeline component from your PCF files and make sure that you don't have any of the shipping components left in your total.pcf (or similar).

Enticify populates most of the properties that ShippingDiscountAdjust would populate except for OrderForm["_shipping_discounts_applied"] and Shipment["_shipping_discounts_applied"]. The shipping discount application records are recorded against the line and order form in the order level discounts applied collections (with the discount_target of Shipping). This will be simplified in a future release.

7. Insert "Enticify :: Remove Auto-Added Basket Lines"

This is the Enticify component that handles the removal of gift with purchase line items.

  1. This should be the first component to run in the pipeline containing Enticify.
  2. Right click the first component in the PCF select Insert -> Before.
  3. Select All in the Stages dropdown box.
  4. Select Enticify :: Remove Auto-Added Basket Lines in the Components list.
  5. Click the OK button.

7. Save your PCF!

Save the PCF file with all of the changes you have just made.

OK. All done!

Optional: Create a Shipment Profile Definition

Why? Do this if you want to target shipment properties in the Discount Eligibility tab. This lets you do discounts like Free next day shipping, even in a multi-shipment store! Enticify applies these expressions to each shipment in turn. Multi-shipment aware Shipment expression eligibility! This profile does not need a backing store and the profile will never be persisted by Enticify.

Create the Shipment Profile Definition

  1. Open Commerce Server Manager.
  2. Navigate Profile Definitions for your site.
  3. Right click Profile Definitions and then click **New Profile Definition...*.
  4. Set Name to "Shipment".
  5. Set Description to "Shipment".
  6. Click Next.
  7. Click Finish.

Add the basic Shipment properties

  1. Select Shipment in the Profile Definitions list.
  2. In the Properties pain on the right, click the Add button.
  3. Leave the radion button selection on Add new property and click OK.
  4. Set the Name attribute to shipment_id.
  5. Set the Display name attribute to whatever you like.
  6. Set Advanced attributes > Key type to Dual (Primary and Join) Key. OK the warning.
  7. Click the Apply button.
  8. In the Properties pain on the right, click the Add button.
  9. Leave the radion button selection on Add new property and click OK.
  10. Set the Name attribute to shipping_method_id.
  11. Set the Display name attribute to whatever you like.
  12. Click the Apply button.
  13. Press the Save button.

Add any other Shipment properties you want to target

You can target any of the standard Commerce Server Shipment properties AND you can target any custom properties that you add to the Shipment pipeline dictionary. Just add them to the profile and you are good to go.

Add Shipment as a Targeting Profile

Tell Commerce Server you want to use the Shipment Profile in targeting expressions.

  1. Open Marketing Manager.
  2. Click the Expressions View link.
  3. Click the Set Targeting Profiles link.
  4. Select Shipment in the Profiles list.
  5. Click the Add button. Shipment should now be in the Targeted list.
  6. Click the OK button.

Running Enticify

If you have followed all of the steps above, Enticify is installed, integrated and ready to be used. Run up your site and see what happens (an IISReset might be a good idea first). If all has gone well, it should still be working as normal and all of your existing discounts should fire as you expect!

Removing Enticify

  1. Open "Programs and Features"
  2. Double click "Enticify"
  3. Follow the on-screen instructions.

Where can I get Enticify from?

Contact Us with your Commerce Server version number and Windows OS Version (inc. x86 or x64) and we'll send you an evaluation copy.