What Makes An "Outbound User Post"

The "Outbound User Post" is the most common archetype we've come across; indeed this is the model we originally designed our payment gateway integration framework to support.

The premise is the HTTP post with a twist: The gateway expects an HTML form to be generated on the store end, which in turn issues a HTTP post to the payment gateway accomplishing two goals in one go:

Payment details such as currency, amount, etc. are sent to the gateway

Customer is redirected to the payment gateway's hosted payment form

The upshot is that it's pretty simple to work with as it relies solely on HTTP; as such it can readily be integrated using pretty much any technology. All you need to do is get the target URL for the post and the predefined form values right and you're good to go.

More Is Less

As it turns out combining the submission of information and the redirect as the sole integration point requires the form to be sent to the customer's browser and submitted from there by the customer herself.

The general purpose payment framework generally has two options for handling this type of integration:

A) Displayed Form, which displays actual information such as the final order confirmation to the customer, or

B) Transparent Form carrying only the required payment information without displaying any details to the customer, which is auto posted to the gateway.

Next up we’ll take a closer look the two options for handling integration.

Displayed Form

The displayed form is essentially embedded on a page displayed to the customer; generally speaking the last page displayed before handing over control to the payment gateway. The form contains predetermined values for amount, currency, and all the other required information to get the payment process going.

The issue obviously becomes one of dealing with ensuring that all the required values are present and named according to the specification and to avoid having to redo the same form over and over again.

In a scenario where a designer or developer control what is displayed to the customer this approach can become quite tricky to handle, i.e. the classic e-commerce "confirm order and proceed to payment" page.

Generally speaking getting this right is a huge part of getting the integration working. As it turns out this is cumbersome at best and downright daunting at worst unless you do this sort of integration work on regular intervals.

Building the form from scratch seems to be what the payment gateways requiring the "Outbound User Post" integration model had in mind when they designed it.

Transparent Form

The second option is an auto generated transparent form, which has no other purpose than to carry the payment information required by the payment gateway. It will never be displayed to the customer, but rather transparently be submitted to the payment gateway.

To achieve a transparent redirect JavaScript is required to auto submit the form on behalf of the customer. Most sites out there today require JavaScript to even function properly, which makes it a reasonable assumption to build a framework on.

The upside is very tight control over the payment information sent to the payment gateway and essentially allows a general purpose payment framework deal with the payment without concern for the actual store pages; as such it comes pretty close to being a "real" web service.

In turn designers and developers have an easier time building the store frontend as payment is handled almost as a pure web service although the intermediate form is still there albeit transparently so.

In Summary

The "Outbound User Post" archetype seems archaic in the assumptions made for the integration model. It's simple, yes, but either requires developers integrating using it to completely redo the integration form for each online store or introduce intermediate forms to achieve a transparent integration model.

The uCommerce e-cpmmerce platform handles the outbound user post via a standard transparent form, which is injected into the checkout flow, sent to the customer, and submitted transparently, seamlessly handing over control of the checkout flow to the payment gateway.

The observant customer will notice an intermediate page displayed for a fraction of a second before being handed over to the page gateway.

Surely there must be a better way. It is so happens there is. Read on a discover "Outbound Placeholder".

With so many integrations under our belt I realized that we inadvertently developed ad-hoc archetypes to describe the various types of gateways.

When dealing with a new payment gateway the archetypes let us quickly determine which type of gateway we're dealing with and what the requirements will be for integration with it.

This is the first in a series of article describing the various archetypes we've found so far.

A Little Background

Back in the day there was just one way of integrating with a payment gateway: Good old direct API call. The premise was simple; call a remote API with credit card details entered on your website and get a "yay" or "nay" response back from the gateway with some transaction details. Forms were easy to design, integration was straightforward. All was good in the land of online payments.

It did in fact manage to increase security, but increased the complexity integrating with payment gateways as well. “But how?”, you might ask.

Online stores would no longer be able to store or even have customers enter credit card information on their websites without a costly certification of the operating environment.

As a result the payment form found a new home away from home: Payment gateways started offering hosted payment forms to overcome the requirement for the PCI certification. Thus the hosted payment forms were born.

What Sets the Gateways Apart

The authorization process and more specifically authorization using a hosted payment form is really what sets payment gateways apart today. It turns out that APIs for acquiring, voiding, and refunding are pretty much all based on the same principle: Direct API integration based on tokens issued during authorization.

It seems that payment gateways all came up with their own variation over the same theme for dealing with hosted payment forms. No standard exists for handling the process although archetypes have emerged over time as we discovered.

Before we dive into the archetypes let's take a look at why the hosted payment form exists and why so many online stores are using it today.

The Hosted Payment Form

The primary reason for introducing the hosted payment form was, as we discussed previously, to avoid handling credit card information locally on the online store's own servers. The responsibility is handed over to the gateway.

This makes hosted payment forms great for avoiding security issues with credit card information and generally speaking is the way to go for online stores large and small. Depending on the gateway the hosted payment form allows for the same flexibility as the direct integration combined with a local payment form method so it's really a win-win situation.

What's the Downside

Integrating a hosted payment form is generally more tricky. There are more concerns in the way payment information such as amount due is transmitted as many of the available solutions require that information to be submitted by the customer herself to the gateway.

Commonly the process works like this: The online store sends payment information to the customer's browsers, which in turn submits that information to the gateway.

When information is passed to the customer and then on to the gateway a huge can of worms concerning tampering with the payment information is opened up. What's to stop the customer from changing the amount to a big fat zero and getting their order for free?

Thus the total sum of required moving parts to make hosted payment work is increased making for a more complex integration model, e.g. redirects between multiple servers, encryption of payment information, and secure processing of payment gateway responses; more commonly known as callbacks.

Outbound vs. Inbound

When figuring out which archetype a payment gateway we're dealing with we need to consider two aspects: The outbound call and the inbound callback.

It's important to note that when using outbound/inbound we're looking at the process from the point of view of the online store, i.e. the customer is outbound from the store to gateway and vice versa.

The outbound call deals with passing the customer and relevant payment information from the store to the payment gateway.

The inbound call deals with passing the customer back from the payment gateway along with the all important "yay" or "nay" for the status of the transaction.

In Summary

Hosted payment forms offer tangible benefits over direct API integrations when it comes to security and in some cases flexibility like when dealing with additional security features like 3D Secure.

The benefits come at the price of a more complex integration model, which seems to have as many variations as there are payment gateways.

Despite this we decided to make hosted payment forms the default for built-in payment providers in uCommerce to minimize requirements for online stores running our software.

Hence archetypes evolved because we have a very real need for terminology to enable us to easily talk about the gateways.

uCommerce comes with built-in support for Ogone payments. This guide will walk you through getting uCommerce to work with Ogone for payment processing.

With the Ogone payment provider you can do authorization of payments, instant acquire, acquire and perform refunds both via our automatic uCommerce solution and manually via the back-end office of your Ogone subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Ogone”.

Now we’re ready to configure your new payment method. Click the newly created node and select “Ogone” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

Settings in Your Back-end Office at Ogone

First you need to log in with your “pspid” and password.

Click “Technical information” at the menu to the left of the page. At the center screen 7 tabs is displayed. Use the settings as used on the screenshots representing each tab.

1. Global Security Parameters

Set the first hash algorithm to SHA-1 as our system uses this hash algorithm for payment requests and maintenance requests.

Set the character encoding to the first option.

2. Data and origin verification

You need a password in this field. This password is used in the communication between your uCommerce shop and Ogone payment provider for security reasons. This pass phrase is used when the system requests a payment at Ogone.

The password must follow rules given by Ogone. Press the blue information button for information regarding those rules.

3. Transaction feedback

The first four URLs in the “http redirection in the browser” section can be left blank, as we configure this in our configuration file later on.

The next step is to link from the secure payment page to your page which processes the payment.

Please note that “/<PARAMVAR>/PaymentProcessor.axd” is required at the end of your URL.

Next step is to tell Ogone which parameters they need to send back to our site. There’s quite a few available, just select them all. This is a good idea as that information is logged, should any problem occur, problem solving is made a lot easier.

The last part in this section is to put in the SHA-OUT pass phrase. This is the same method as before but for security reasons you should use another phrase this time.

When Ogone makes the callback to our server, this pass phrase is used in a hash algorithm in order to test for corrupt requests.

Now we need to make an “admin without user management” but with access rights to make direct link requests.

Click Users at the back end office menu to the left and click new users in that section.

Fill out the required fields and put your PSPID password in the password field and click create. At the next page you’ll get a password.

Now we need to change the password to something that doesn’t contain special characters (use “a-z” and/or “0-1”.

Under the password section, simply select the user you’ve just created and put in the old password and together with the new you want and click submit.

This is it in the back-end office at your configuration.

Configuring Acquire and Cancel Payments

The Ogone payment provider comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

The pipeline configuration is found in /umbraco/ucommerce/pipelines.

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

Configuring the “Ogone.config” File

Now we need to edit the ”Ogone.config” file in order to match your environment.

You’ll find the configuration file at “rootdir\umbraco\UCommerce\Configuration\Ogone.config” where rootdir is the location on your computer, where Umbraco is installed.

Some values need to be found in the back-end office. All of those can be found under technical information.

Parameter list for the configuration file:

Parameter name

Value

pspid

The pspId of your Ogone account.

Find it at the bottom of the menu to the left at the back-end office.

Userid

The Userid of the user you’ve just made.

Password

The password for the user you’ve just made.

acceptUrl

The URL the customer is redirected to after an accepted payment.

cancelUrl

The URL the customer is redirected to after a canceled payment.

backUrl

The URL the customer is redirected to if the customer clicks the back button on the payment page.

declineUrl

The URL the customer is redirected to if the payment is declined.

exceptionUrl

The URL the customer is redirected to if a problem occours in the payment process .

All the urls are a local webs in your website such as “yourshop.com/orderconfirmation.aspx”.

Debug

Tells the system weather this is in debug mode. This should be set to false.

shaSignOut

The shaSign used when Ogone redirects to the payment processor.

Under technical information, go to the bottom of the “transaction feedback” tab to find the SHA-OUT pass phrase

shaSignIn

The shaSign used when your uCommerce website requests a payment at Ogone.

Under technical information, go to the “Data and origin verification” tab to find the SHA-IN pass phrase

language

Must follow the right language codes otherwise it’s set to the default value “en_US”.

instantAcquire

Is set to “true” if you want instant acquire.

Is set to “false” if you want to only authorize a payment.

testMode

Tells the system weather this is in test mode. This should be set to false.

Congratulations - your website now includes payments with the Ogone payment provider.

uCommerce comes with buil-in support for MultiSafepay. This guide will walk you through getting uCommerce working with MultiSafepay for payment processing.

Settings in uCommerce

Add a new payment method, under “uCommerce -> Settings -> Orders -> Payment Methods”. You can call it whatever you like, here I have used “MultiSafepay”.

Click the newly created node and select “MultiSafepay” in the Service drop down list. Choose Checkout ast he pipeline. Fill out the rest of the required information, like where it’s available from under the “Access” tab, pricing and the language tabs. When you are done click “Save”.

That’s everything in the uCommerce interface.

Settings in MultiSafepay back office.

Create a back office at MultiSafepay with the MultiSafepay Connect.

Create a new website under Setttings -> Sites.

Category

Choose the category your site belongs to

Description

Can be anything, just a name you give your website.

Base URL

The URL for your website

Notification URL

MultiSafepay notifies uCommerce about new payments and changes to existing payments using the notification URL. The URL you receive notifications from MultiSafepay will be in the format https://www.mystore.com/id of your payment method/PaymentProcessor.axd

To find the PaymentMethodId you need to search the database. If you used the name “MultiSafepay” for the payment method name, you can run this SQL query in the SQL Server Management Studio:

select PaymentMethodId from uCommerce_PaymentMethod where Name='MultiSafepay'

A sample URL for a payment method with an ID of 10 would be https://www.mystore.com/10/PaymentProcessor.axd

PrivatePay

An option so MultiSafepay won’t give you information regarding the consumer. Name and address will be excluded.

SecondChance

Should the consumer cancel midway, they will receive an email giving them a second chance to complete the process.

Editing the MultiSafepay.config file

Now we need to edit the MultiSafepay.config file.

You will find the MultiSafepay.config file in the following location, where “rootdir” is the directory on the computer where you installed Umbraco: “rootdir\umbraco\UCommerce\Configuration\ MultiSafepay.config”. Usually “rootdir” is c:\inetpub.

TestMode

If set to “True” the MultiSafepay test site will be used, not their live site. If not testing, this should be set to “False”.

Account Id

SiteId

The ID provided by MultiSafepay when creating a new site. (See picture below)

SiteSecurityCode

The SiteSecureCode provided by MultiSafepay when creating a new site. (See picture below)

CallbackUrl

Leave setting at (auto) unless you want to handle callbacks yourself.

Accept

The URL you return to when completing a payment.

CancelUrl

The URL you return to when cancelling a payment.

Click Settings è Websites to find the screen below.

MultiSafepay back office

In the MultiSafepay back office you have options to refund and cancel, this cannot be done without using the MultiSafepay back office.

Use the green refund button to start a refund or the red cross to cancel a pending payment.

Please note that any changes to a payment in the back office will cause a notification to be sent to uCommerce. The notification will cause uCommerce to update the status of the order the payment belongs to to “Requires Attention”.

Add a new payment method, under “uCommerce –> Settings –> Orders –> Payment Methods”. You can call it whatever you like, here I have used “iDEAL (ING)”.

Click the newly created node and select “iDEAL (ING)” in the Service drop down list. Fill out the rest of the required information, like where it’s available from under the “Access” tab, pricing and the language tabs. When you are done click “Save”.

On the Menu on the left side, click “Signup process –> Configuration”. Make sure that there is a key in the “Secret key” field and the click “Start upload”. The “Certificate upload successful” should be marked with a green sign upon success.

Configure Return URLs

uCommerce performs validation of the payment information when iDEAL (ING) performs the callback. To get the callback, for verify the payment, you need the set the “Notification” to XML and the “Notification URL” to you shops URL ending with “/PaymentMethodId/PaymentProcessor.axd”.

To find the PaymentMethodId you need to search the database. If you used the name “iDEAL (ING)” for the payment method name, you can run this SQL query in the SQL Server Management Studio:

You will find the Ideal_Ing.config file in the following location, where “rootdir” is the directory on the computer where you installed Umbraco: “rootdir\umbraco\UCommerce\Configuration\Ideal_Ing.config”. Usually “rootdir” is c:\inetpub.

Some of the below information are found in the iDEAL (ING) Dashboard, so start by logging in you aren’t already.

Finding subId

To get the customer redirected back to your page after the payment is completed, you have to specify a return URL depending on payments result: Success, Error and Cancel.

Finding debug

If set to “True” you will be prompted to click a button before posting the information to “iDEAL” otherwise it will do an autosubmit using Javascript. When running in production, you will want this set to “false”.

Finding testMode

Test mode will toggle the payment method service to use a test environment where applicable. Usually this implies working against another URL.

Excecuting a Pipeline on Callback

Running a pipeline once payment is authorized can be helpful if you need to complete the order once the customer returns to your site.

To run a “pipeline” once the callback if received and processed, open Umbraco click “Commerce” select the payment method (“iDEAL (ING)”). In the pipeline drop down list select Checkout and then click “Save”.

Now the default pipeline that comes with uCommerce will be run after each successful callback. This sets the Basket to an Order, gives it an OrderNumber, and other things.

uCommerce comes with built-in support for Google Checkout payments. This guide will walk you through getting uCommerce to work with Google checkout for payment processing.

With the Google Checkout you can do authorization of payments, acquire payments, refund and cancellation of payments both via uCommerce and the back end office of your Google checkout subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Google Checkout”.

Now we’re ready to configure your new payment method. Click the newly created node and select “Google Checkout” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

This is a passphrase needed in the communication between your shop and google checkout.

Find it on the integration page in the back end office at “Google Checkout”, at the right side of the page.

successUrl

This URL redirects your customer back to a specific page at your site after a successful authorization.

editBasketUrl

This URL redirects your customer to the basket on your site.

testMode

Tells our system weather the application is in test mode or not. This must be set to false.

debug

Tells our system weather the application is in debug mode or not. This must be set to false.

FAQ

Ensure that uCommerce uses the same currency as your Google Checkout seller account

During our test of Google Checkout we found that transactions made with currencies other than the main currency of the seller account will always result in rejected authorizations. If you create the seller account with GBP please make sure that any test transactions are made with the same currency.

Failed transaction will appear with the message ”Cancelled by Google: Payment declined” in the seller account and the messages ”Cancelled” and ”Your order has been cancelled.” in the buyer account.

Please note that this applies to the sandbox only.

Ensure that “testMode” is set to “true” when using the Google Checkout sandbox for testing

If your GoogleCheckout.config is set to testMode=”false” Google Checkout will return HTTP code 400 bad request when accessing sandbox. Make sure that you’re operating in test mode when calling the sandbox.

uCommerce comes with built-in support for eWAY payments. This guide will walk you through getting uCommerce to work with eWAY for payment processing.

At the moment, the eWAY API only supports instant payment, which means that refunds or cancel payments is not possible.

Settings in uCommerce

Add a new payment method, under “uCommerce à Settings à Orders à Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like, I have used “EWay”.

Now we’re ready to configure your new payment method. Click the newly created node and select “Eway” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

Pleasenot that eWAY only supports Australian dollars (“AUD”).

if AUD does not appear under the pricing tab follow the next step ”Setting up Australian dollars at currencies” to add Australian dollars under currencies. Otherwise click the save icon and you’re done.

Setting up Australian Dollars at Currencies

Right click the currencies leaf and click create. The ISO code for Australian dollars is “AUD”. When you’re done, click the save icon. That’s everything in the uCommerce interface. Proceed to “2.0 Editing the EWay.config file”

Editing the EWay.config file

Now we need to edit the EWay.config file in order to match your environment.

You’ll find the config file at “rootdir\umbraco\UCommerce\Configuration\EWay.config” where rootdir is the location on your computer, where umbraco is installed.

customerId: must be found at your sandbox environment at the bottom of the page after you have logged in using your account credentials :

username: corresponds to your eWAY account username

debug: no need to configure

callbackUrl: no need to configure

cancelUrl: this is the page the customer would be redirected to after a cancellation at the secure payment page at eway.

acceptUrl: this is the page the customer would be redirected to after a successful payment at the secure payment page at eway.

Both the cancelUrl and acceptUrl is a local web in your website such as “orderconfirmation.aspx”

Now everything is configured to your webpage and should work as intended.

uCommerce comes with built-in support for Braintree payments. This guide will walk you through getting uCommerce to work with Braintree for payment processing.

With Braintree you are responsible for hosting the payment form. A simple form is provided by uCommerce, but it will need a better look and feel. Acquire, cancel, and refund are available. This is implemented with the Transparent Redirect method.

A wide range of currencies available, but you decide which currency to use when you create a merchant account. Each merchant account can only process a single currency.

Add a new payment method, under “uCommerce –> Settings –> Orders –> Payment Methods”. You can call it whatever you like, here I have used “Braintree”.

Click the newly created node and select “Braintree” in the Service drop down list. Fill out the rest of the required information, like where it’s available from under the “Access” tab, pricing and the language tabs. When you are done click “Save”.

You will find the Braintree.config file in the following location, where “rootdir” is the directory on the computer where you installed Umbraco: “rootdir\umbraco\UCommerce\Configuration\Braintree.config”. Usually “rootdir” is c:\inetpub.

Some of the below information are found in the Braintree gateway, so start by logging in you aren’t already.

Finding paymentFormTemplate

To get the customer redirected back to you page after ended payment, you have to specify a return url depending on payments result: Accept or decline.

Finding debug

If set to “True” you will be prompted to click a button before posting the information to “Braintree” otherwise it will do an autosubmit using Javascript. When running in production, you will want this set to “false”.

Finding testMode

Test mode will toggle the payment method service to use a test environment. A sandbox account is used in testMode.

Valid values “true” or “false”.

Excecuting a Pipeline on Callback

Running a pipeline once payment is authorized can be helpful if you need to complete the order once the customer returns to your site.

To run a “pipeline” once the callback if received and processed, open Umbraco click “Commerce” select the payment method (“Braintree”). In the pipeline drop down list select Checkout and then click “Save”.

Now the default pipeline that comes with uCommerce will be run after each successful callback. This sets the Basket to an Order, gives it an OrderNumber, and other things.

Set Look and Feel on the Payment Form

The payment form is populated with the contents of paymentFormTemplate file chosen in the config file, no matter which way you choose to integrate it.

The HTML inputs that have a name specified in the default file are needed to submit the form to Braintree. It is possible to changes types of the fields, add other attributes and move the fields around, but they must retain the names assigned to them.

The Braintree provider will insert values at runtime by replacing placeholder values, e.g. “##XX##” tags. You can safely remove these placeholders if you wish to handle the form values yourself.

Integrate the Payment Form into Your Own Page

If you want to integrate the payment form into one of your pages you’ll want to modify the template HTML to include only the form element and get rid of the html and body tags.

uCommerce comes with built-in support for Authorize.Net payments. This guide will walk you through getting uCommerce to work with Authorize for payment processing.

With the Authorize.Net you can do authorization of payments, acquire payments and cancellation of payments both via uCommerce and the back end office of your Authorize.Net subscription.

Settings in uCommerce

Add a new payment method, under “uCommerce => Settings => Orders => Payment Methods”, by right clicking the “Payment Methods” leaf and use “Create”. You can use any name you like; I have used “Authorizedotnet”.

Now we’re ready to configure your new payment method. Click the newly created node and select “Authorizedotnet” in the Service drop down list and select “Checkout” in the pipeline drop down list. Remember to fill out the rest of the required information in the rest of the Tabs.

When you’re done, click the save icon. That’s everything in the uCommerce interface.

Settings in Your Back-end Office at Authorize.NET

We need to configure your MD5-Hash used for secure communication between your server and Authorize.NET. Click MD5-Hash and create and submit. You need to have this ready by your hand in one of the following steps.

Next we need to configure the payment form.

Click “Form fields” in the page you enter after clicking “Payment Form” on the page above.

Check the following boxes off:

Now we need to visit “API Login ID and Transaction key” section.

Now you need to create a Transaction Key by answering your secret question which you created upon creating your Authorize.NET account.

Make sure you have the “API Login ID” and “Transaction Key” by your hand as you need them in the last step on configuring your configuration file.

Configuring Auto Acquire and Cancel Payments

Authorize.Net comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

The pipeline configuration is found in /umbraco/ucommerce/pipelines.

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

Configuring the “Authorizedotnet.config” File

Now we need to edit the ”Authorizedotnet” file in order to match your environment.

You’ll find the configuration file at “rootdir\umbraco\UCommerce\Configuration\authorizedotnet.config” where rootdir is the location on your computer, where Umbraco is installed.

Parameter list for the configuration file:

Parameter name

Value

apiLogin

The API login ID from the backend. Please refer to section of settings in Authorize.NET backend

TransactionKey

The transaction key you’ve created in the back-end configuration.

Md5Hash

You’ll have to define this hash key yourself. Please refer to section of settings in Authorize.NET backend

acceptUrl

This URL redirects your customer back to a specific page at your site after a successful authorization.

declineUrl

This URL redirects your customer back to a specific page at your site if an authorization is declined.

payType

Tells our system what command to send to Authorize.NET

testMode

Application is in test mode. This must be set to false.

debug

Application is in debug mode or not. Set to false for live environments

instantAcquire

Perform instant capture on payment or authorization of a payment.

sandboxMode

Set to true for the sandbox environment and false for test/live environments.

Congratulation - your website now includes payments with the Authorize.NET.

Important: When authorization has been succesfully completed, Authorize will redirect the customer to the acceptpage but notice this page will be under the Authorize.Net’s URL. This is not an error.

A box will appear. Here you can enter any name you like but it’s recommended to use “Amazon FPS” so you easily can find it again.

Now we have to configure the payment method. Click on the node with the name you have chosen. In the service dropdown list you choose “Amazon FPS” and select “Checkout” in the Pipeline dropdown list. Remember to give the service a “Display name” which you find in your language tab in the same window.

Amazon FPS does only support US Dollars at this point, so if USD doesn’t appear under the “Pricing” tab you have to follow the next step “Setting up US Dollars at currencies”. Otherwise click the save icon and skip the next step.

Setting up US Dollars in Currencies

Right click the currencies leaf and click create. The ISO code for Australian dollars is “USD”. When you’re done, click the save icon.

Signing up for a Amazon FPS account

To use the Amazon FPS with uCommerce you have to register first. Go to https://payments.amazon.com and go to the “Developer” tab in the top menu. Under the “Developer” tab click “Sign Up For Amazon FPS”. Create a new account or use an existing account if you already got one you wish to use.

Follow the instructions on the screen to complete the registration. When the registration is complete you receive a confirmation to the e-mail address you used for the registration.

Setting up the Amazon FPS config file

Now we need to edit the Amazon.config file in order to match your environment. You will find the config file at “(root dir)\umbraco\UCommerce\Configuration\Amazon.config” where “root dir” is the location on your computer where umbraco is installed.

debug: Not used by this provider.

testMode: Indicates whether the Amazon FPS is using the Sandbox or production environment. If you want to test your payment service this setting MUST be set to “True” otherwise the Amazon FPS will be in production environment and will charge a customer.

awsSecretKey: This key is used to create your signature and it’s important to keep this secret from people who is not in need of this. You can also find this key at the security credentials at amazon. Use the same link above.

acceptUrl: This is the page the customer will be redirected to after a payment has been authorized at Amazon. In the picture above there is an example how it can look like.

cancelUrl: This is the page the customer will be redirected to if the customers abandons payment at Amazon.

callbackUrl: this need to be configured. You need to know what id the payment method has in the database. Look at the next step to see how to find this id. The URL should be on the form of: http://(domain name)/(id)/PaymentProcessor.axd

How to find your payment method id in your database

To find your payment method id you need to make a query. One way to make this query is using SQL Mangement Studio. Connect to your SQL server. In SQL Management click “New Query” in the tools menu right under the file menu. Choose the database where you have your umbraco/uCommerce installed.

In the text editor in write the following:

SELECT * FROM ucommerce_paymentmethod WHERE Name = 'Amazon FPS'

The text between ‘’ is the name of the service you choose in step 1.1. Then press “F5” on your keyboard to execute the query. In the bottom of the text editor window a result window should appear.

The number which is in the column “PaymentMethodId” is the number you need in your Amazon.config file.

Setting up the Instant Payment Notification messages in Amazon FPS.

Amazon FPS sends notifications when a status on a transaction changes. That can be when a transation is changing from “Pending” to “Success”. To setup this you need to go to your account management. Navigate to https://payments.amazon.com in your browser. Click on “Your Account” tab and type in your login credentials.

In your control panel go to “Edit My Account Settings à Manage Developer and Seller Preferences”. In the textbox right for “URL for Instant Payment Notification” type in the url in the following format: http://(domain name)/(paymentmethodId)/PaymentProcessor.axd

Note: The URL you type in this field has to match the callbackUrl in the Amazon.config file or Amazons signature will be rejected and payments will not be available.

Configuring Auto Acquire and Cancel Payments

The Amazon FPS provider comes with the ability to do automatic acquire and cancel payments. In order to make this work you need to enable a pipeline task.

To enable auto acquire edit the “ToCompletedOrder” pipeline.

To enable auto void/refund edit the “ToCancelled” pipeline.

The pipeline configuration is found in /umbraco/ucommerce/pipelines.

Simply remove “<!-- “ and “-->” at the highlighted line. These are HTML comment sections.

“Buy More Than”-target

In this article you will learn how to extend Marketing Foundation with a “Buy more than”-target, which is what uCommerce calls an Act target. The “Buy more than”-target will be an order line level target, which will be combined with a “Buy product”-target to create a discount triggered.

It can be used stand-alone as well in which case the customer just needs to “Buy more than” of whatever product she decides. Not the most common discount type, but it does show the power of being able to combine targets.

Advertise and Act Targets

uCommerce supports two kinds of targets: The advertise target and the act target. Display targets are used in the process of targeting campaign items for specific customers, i.e. these are the ones you set up under the “Advertise” section of a campaign item.

Act targets are evaluated against a cart to determine whether the customer actually “acted” the way we wanted them to and thus trigger an award.

A target might be either an advertise target, an act target, or both, e.g. a product target is actually both an advertise target and an act target as it works for both scenarios.

As mentioned advertise targets are used to determine which campaign items a customer should see using the XSLT extension:

Act targets are executed by the basket pipeline using the pipeline task Basket.ApplyAwards.

Our “Buy more than”-target will be an act target targeting individual order lines. Before we get to that though let’s take a look at what’s required to create an advertise target or IDisplayTarget as they’re called internally in uCommerce.

Implementing IDisplayTarget

To implement a display target you’ll implement the interface called IDisplayTarget, which has a single method called IsSatisfiedBy. This is the method invoked by uCommerce to determine whether the target is satisfied by the current targeting context.

Basically you’ll evaluated the targeting context and see if it fits with what you want your target to do, e.g. is the customer viewing a particular product, is the customer logged, etc..

Pretty simple.

A Word On The TargetingContext

The targeting context is gathered by uCommerce during runtime and tells you all manner of interesting information about what the customer is currently viewing, e.g. what’s the current page, store, catalog, category, list of products being viewed, etc.. You can add your own information to the targeting context if you require additional information. We’ll cover that in another article.

Implementing An Act Target: IPurchaseOrderTarget, IOrderLineTarget

Act targets are evaluated against the customer’s cart to verify that the customer actually bought or did what we wanted her to do. You can opt into two interfaces depending on whether you’re targeting the entire order or individual order lines: IPurchaseOrderTarget and IOrderLineTarget.

For our “Buy more than” target we’ll implement the IOrderLineTarget because that’s where we’ll find the quantity of a particular item. Our new “Buy more than”-target would probably be combined with a “Buy this product”-target in most cases, which would require a customer to buy a certain amount of the product.

As you can see the logic is pretty simple. We’re receiving an order line from Marketing Foundation and our job is to figure our whether the target is satisfied by this particular order line. In our case the customer just needs to buy more than the configured quantity on the our target.

This leads us to the next question: How do we actually configure a target? Enter the ITargetUi and IConfigurable…

Implementing Configuration UI for the Target

The configuration UI for our new target is responsible for creating a new instance of our particular target and saving it the data store of your choice. Also it serves to reconfigure existing targets of the type that we’re working with; in this instance QuantityTarget.

To add a config UI for our new target we need to create a new user control in .NET. Let’s put it in /umbraco/ucommerce/marketing/targets, which is where the standard target UIs are located. Also remember to put the generated DLL in the /bin folder.

Our user control needs to plugin into the UI framework defined by uCommerce. All that’s required to do so is to inherit ViewEnabledControl<IEditCampaignItemView> and implement IConfigurable.

Inheriting ViewEnabledControl<IEditCampaignItemView> gives us access to the context in the UI, i.e. the campaign item currently being configured.

IConfigurable is the interface which lets uCommerce create your target and subsequently reconfigure it when a user wants to edit it.

For our target we need a specialized version of IConfigurable called ITargetUi. This is due to the fact that the target might be used as both an advertise target, an act target, or both.

uCommerce will tell you whether it’s one context or the other by assigning the EnabledForDisplay and EnabledForApply values on your UI.

So our user control ends up looking like this. Please note that the New() method acts not only as a factory method for our target, but has the responsibility for storing that instance in the data store also. If this doesn’t happen the instance is lost and won’t be displayed as part of the campaign item.

Before we can actually use the control we need to register it with uCommerce.

Register Target Configuration UI

To add the target UI to uCommerce we’ll add it to the table called uCommerce_EntityUi. This table holds the mapping between the type, which is to be configured, i.e. our QuantityTarget, and our UI to do the configuration, i.e. our QuantityUi.ascx user control.

Because uCommerce is multilingual we’ll want to add a description of the new UI in the table uCommerce_EntityUiDescription otherwise the target UI will show up blank in the drop down lists.

When the “Add” button is clicked our new target UI is added to the campaign item and the New() method is called on our user control thus creating a new instance of the target we’re configuring.

With that in place our new UI is now available when setting up new campaign items and we can create new quantity targets, so we’re ready to move on to dealing with existing targets.

Feeding Marketing Foundation with Targets using TargetAggregator

With the previous steps complete we need to deal with existing targets so Marketing Foundation can find them and evaluate them for customers entering the site: Enter the TargetAggregator.

TargetAggregator is responsible for finding targets for any given campaign item configured in Marketing Foundation.

TargetAggregator relies on individual TargetResolvers to find targets for a campaign item, e.g. uCommerce has a single target resolver called DefaultTargetResolver, which handles the built-in targets.

We’ll build a custom target resolver by implemeting the ITargetResolver. It will handle our Quantity target and any other future targets.

Thus our QuantityTargetResolver ends up looking like this:

Register Custom Target Resolver with TargetAggregator

At this point uCommerce doesn’t know about our custom target resolver yet so we’ll have to tell it about it. This is done using the Marketing configuration file found in /ucommerce/configuration/Marketing.config.

We’ll have to register a new component and add it to the target aggregator registration.

First the new component

And finally grab the id from the component and add it to the target aggregator registration in the same file.

That’s it. Our new target is good to go and will act exactly as the built-in targets, which ship with uCommerce.

In Summary

This article showed you how to add custom targeting logic to uCommerce, the user interface to configure it, and how to handle data access for it as well. When you think about it each target is a mini-application hosted inside uCommerce dealing with all the usual concerns of a full-blown app.

Some of the concerns like the resolver need only be implemented once while others like the UI and the target itself are highly specific to the task they’re trying to accomplish and require a new implementation for each new type you need.

Marketing and particularly discounting are areas, which often come with very specific business rules highly different dependent on the individual business. uCommerce ships with a bunch of useful targets, but having the ability to add your own ensures that you can accommodate any targeting scenario.

Marketing Foundation introduced with uCommerce 2.0 adds rich marketing capabilities, which can be used to stimulate customers to buy. It’s built based on three simple principles: Advertise, Act, and Award.

Advertise

One of the common issues with discounts is that customers are never told about them thus a discount does not work its full effect. Basically the customer is only made aware of the discount once they actually trigger it, which is akin to throwing marketing dollars out the window as the customer was likely to buy anyway.

That’s why we built each campaign item in uCommerce to include the “Advertise” component so marketers actively have to decide whether to advertise or not; at the end of the day why wouldn’t you?

When doing advertisements in uCommerce you will select a number of targets, which are to be satisfied in order for the campaign item to be displayed. You can think of them in terms of, “Customer is viewing this category”, “Customer is viewing this page”, “Customer is in this particular store or catalog”.

If multiple targets are configured in the “Advertise” section the campaign item will be displayed if any of the targets are satisfied.

Once a campaign item is targeted for the current customer its contents can be displayed, which includes rich text, video, HTML, and even the actual targets and awards inside the campaign item. What this boils down to is that you can display banners, which feature video, sound, or HTML content and you can take this a step further by actually telling the customer what she needs to do in order to receive a particular discount.

Say you have a campaign item set up called “Free shipping for orders over 400€”. The intent is clear enough, but what if you could actually tell the customer how close she is to get that discount? It just so happens that you can.

Using the information produced by Marketing Foundation you can tell the customer exactly what she must do to trigger the discount.

Say she’s got items in the cart with a total value of 350€. You’d pop up a message telling her that by buying for 50€ more she’d get free shipping; oh and by the way here are some products which 50€ or more making it easy for the customer to take the action we want her to.

Act

The act section of a campaign item is the thing we want the customer to do to trigger a discount. When you think about it a discount is actually composed of two things: The thing we want the customer to do; the act part, and the thing the customer gets; the award part.

Think of “Act” as “The customer must buy this particular product”, “The customer must buy for more than x amount”, “The customer must buy something from this particular store, catalog, or category”, etc.

Targets can be combined to form even more powerful campaign items such as a product bundle or kit depending on which side of the pond you’re on.

If multiple targets are set up in the “Act” section of the campaign item they must all be satisfied in order to trigger the discount. Say you want to the customer to buy two products to get a discount. You’ll set up two targets: One for each of the products in involved. uCommerce will look for these products in the cart of they are both found will trigger the discount.

Award

The final piece of the puzzle is the “Award”, i.e. the thing the customer gets. The award is completely separate from the rest of the campaign item and thus can be reused for many different types of discounts, e.g. “Buy for more than 400€ and get free shipping ” could also be “Enter this promo code and get free shipping”. The only difference is that the “Buy for more than 400€” act section is substituted with “Enter this promo code”. The award remains the same.

Types of awards include “Get amount of unit price”, “Get amount off order total”, “Get amount off order lines total”, “Get percentage off shipping”. Awards can be combined like targets and effectively gives you a discount for each of the awards configured.

It’s important to distinguish between order discounts and order line discounts. The difference being that order level discounts are typically applied only once per order, e.g. “Get amount off order total” will only add a single discount to the order as you’d expect.

Order line discounts on the other hand can involve multiple order lines as in the case of the bundle or kit. Here two or more order lines are involved in the discount thus each of lines will have the order line discount applied, e.g. “Get 10% off unit price” will produce two discounts; one for each order line satisfied by the Act section.

Campaign Items

The campaign item ties together our “Advertise”, “Act”, and “Award” sections and is the unit, which can be thought of as a “Discount”. However, the campaign item does more than just set up a discount, it serves as the content for the advertisement as well.

A campaign item is assigned a “definition” when it’s created. The definition determines the content that the marketer can add to the advertisement. So this is basically where you’d add all the rich content we discussed in the beginning of the article.

You can read more about definitions in Catalog Foundation Explained: Product Definitions. The basic concept of the definition is the same for campaign items as for products although obviously a campaign item definition does not deal with variants.

Because the campaign items are configured using definitions you can add your own properties and multilingual properties effectively giving you multilingual marketing campaigns right there. No need to configure the same campaign item twice if you want to target different languages, just add the relevant multilingual properties and you’re done!

Multiple Discounts Per Order, Or No

In some cases you don’t want the customer to receive multiple discounts. That’s where the configuration of the campaign item comes in. Of course you can disable individual campaign items that you don’t customer to receive at all by removing the checkmark in the “Enabled” checkbox.

More interestingly you can configure a campaign item to not allow additional discounts if the “Act” section of current campaign item is satisfied. Combine this with the priority of individual campaign items and you can effectively control which discounts the customer is awarded based on your business rules.

You can prioritize campaign items by right-clicking the campaign and choosing “Prioritize campaign items” in the tree menu.

Campaigns

Finally we come to the top-most level of Marketing Foundation: The campaigns. A marketing campaign is a collection of campaign items grouped together under a name so each campaign will effectively hold all the planned marketing activities for a given period of time.

A marketing campaign is assigned an interval for which it is active. uCommerce will automatically activate campaign items within in the campaign once the activation period is reached and disabled them again once the activation period is done.

In Summary

uCommerce Marketing Foundation is a highly flexible way to set up marketing messages and discounts in your online store. Combined targets and awards make for interesting possibilities when it comes to different discount types and best of all you can let your customers know exactly what they need to do to get a discount, which is the way it should be.

More importantly Marketing Foundation is built-in from the ground up using our Framework First approach, which means that new targets and awards can easily be added. You can even go so far as to change the inner workings on Marketing Foundation. What this means for your online store is that marketing can be tailored to meet your needs exactly.

Summary

Managing multiple items as one in the basket is handy when working with complex product options like we did for the MacBook Air just now. At all times should customers be certain as to what they’re buying and managing the items should be as straightforward as for “simple items”.

Combining multiple items into one visually is a matter of adding a bit of extra information to tie the items together and doing a clever presentation of the items.

All the internal calculations and stock management stay the same behind the scenes so you just have to worry about doing a nice presentation of the basket.

Variants is a great way to offer up products which have varying properties, but sometimes they are just not enough or it’s too cumbersome to maintain each and every variant combination you want.

In this article you’ll discover how to build an Apple-style product configurator with uCommerce.

There are two pieces to doing a highly flexible product configurator: The configurator itself and the subsequent presentation of the basket.

We’ll cover the configurator itself in this article and do a separate article for the basket itself.

Step 1: Product Definition for the Main Product

First we’ll need a main product which is the one that we want to configure. For the sake of concreteness let’s build a product configurator for an Apple MacBook Air.

We’ll build a definition to hold main products. Let’s call it “Configurable”. The product definition will hold information to present the main product unique selling proposition like what you see on the main product page on Apple.com.

We won’t be doing any variants for this product definition as the options will come from somewhere else.

Before we move on let’s create the MacBook Air in the product catalog.

Step 2: Add Options to the Catalog

For a MacBook Air we’ll need to be able to configure the CPU, the amount of storage, and a couple of add-ons like an external optical drive and display.

We’ll do the options as individual products, which incidentally they typically are anyway with their own inventory.

Let’s add a couple more product definition for the various types of options: CPU, Flash Storage, and Display.

We’ll do variants for the product options as they will become the actual choices the customer has to choose from when configuring the final product.

Here are the product options configured in a separate category for good measure. Note that each option has a number of variants configured.

I did go ahead and create a definition for each type of add-on, but that’s not a strict requirement. I’m just being a smartass and showing off some other features of uCommerce :)

Step 3: Configure Available Options

Now we’ve got a catalog of products and main products and now for the good stuff: Configuring the available options for each main product. Customers will be able to select CPU, Flash Storage, and optional optical drive or Display for our MacBook Air.

uCommerce supports related products, which is a handy way of building up a list of available options for a given product. So let’s see if we can make that work for our configurator.

First let’s set up a new relationship kind called “Option” to help us find available options later on.

And now let’s actually add the options to our MacBook Air.

Step 4: Build the Configurator

With the previous steps concluded we’ve got the required information set up in the catalog and now we’re ready to present the options to our rabid following; sorry, loyal customers :)

Enter Razor. Enter the code!

First we’ll load up the product that we wish to configure. Of course it would typically come from a listing, but we’ll just grab it directly to get to the point.

Finally we’ll grab the “Option” relations and present them in a list. Here’s what the Razor code in Umbraco will look like.

And here’s what the product configurator looks like when the customer sees it in Umbraco. Add some CSS and images to the HTML and you’ve got your product configurator.

Summary

Creating and maintaining highly configurable products in uCommerce is a perfect way to offer up nice customization opportunities for customers.

By using the out of the box capabilities like product definitions, relationship kinds, and relationships combined with the API you can build a rich product configurator, which will present product options dynamically based on the options attached to any given product.

Also doing configurable products like this is a great way to manage inventory of individual components instead of complete product configurations. This means that less inventory is required because any given option might be part of multiple different product configurations thus inventory will seem higher with this approach.

In this article you saw how we can use uCommerce to build an Apple-style configurator, but this technique can be further extended to present even more complex decision trees if required.

Imagine building the options themselves with sub-options by doing deeper relationships. This way you can support some very complex scenarios and have complete decision trees for product with very different options, e.g. triple-play service providers of TV, phone, and internet services, which require very different configuration for each option.

When working with an e-commerce transaction system in an online store typically the information stored on the orders and order lines will come from the products themselves in the catalog system.

However, in some cases you might want to add custom information such as a personalized message, an indication whether gift wrapping is required, serial numbers, measurements, or something else entirely.

Enter Dynamic Order Properties

For this specific scenario uCommerce supports dynamic order properties, which is a way to add information to basket, orders, and individual order lines.

You can add as many as you want and you don’t have to stick with the same number of properties or even the same names across orders.

For individual order lines you’ll refer to the index of the order line to target a specific one. That the first parameter. The index values will be part of the order XML produced by CommerceLibrary:GetBasket().

Once set the dynamic order property will be outputted as part of the XML produced by GetBasket() or GetPurchaseOrder() in the orderProperties element under the order itself or under individual order lines.

Admin

Dynamic order properties will be displayed in uCommerce Admin as part of the order overview.

Summary

Dynamic order properties is a great way to add custom information to orders during checkout or indeed later in the order process if required. It can be used to capture customer choice for later use such as custom messages, newsletter sign up flags, and more.

Because they are automatically picked up by the order management interface in the backend they are useful for information store managers need to know during the order management process.

More often than not you will leverage uCommerce in a web context either via the Commerce Library XSLT extensions or through .NET directly.

In some cases though you might need to leverage the API outside a web context for automated integration between systems, for custom web services, or integration of uCommerce functionality directly in other custom applications such as point of sale- or kiosk apps.

This article outlines the steps required to get the API going.

Reference uCommerce Assemblies

First you need to reference the uCommerce assemblies and their dependencies in your project.

You’ll need to add references to:

UCommerce.dll

UCommerce.Infrastructure.dll

UCommerce.Umbraco.dll

businesslogic.dll (Umbraco)

Castle.Core.dll

Castle.Windsor.dll

FluentNhibernate.dll

NHibernate.dll

Nhibernate.ByteCode.Castle.dll

Modify App.Config

uCommerce needs some configuration to run. You’ll find examples of the relevant groups in web.config in your Umbraco installation. You’ll want to copy the commerce sectionGroup, connectionStrings, and commerce sections.

Add Configs to Application Folder

Components.config holds information about all the various subsystems in uCommerce. Copy Components.config and Marketing.config from the website folder you installed Umbraco and uCommerce in, e.g. c:\inetpub\Umbraco\uCommerce\Configuration and copy them to your app folder.

Modify Components.config to Work Outside Web Context

The configuration files assume a web context so we’ll have to update them to work in a non web environment. Open up Components.config in your favorite editor and modify any life cycle with a value of “PerWebRequest” to “Thread”.

This tells uCommerce to create an instance of the object once per thread as opposed to once per request, which oviously doesn’t make sense for what we’re trying to do.

Do the same for Marketing.config if you intend to use that in your application.

Remove Includes in Components.config

Be sure to remove includes in components.config, which refer to Presenters.config and XmlRenderings.config.

Summary

Leveraging uCommerce outside a web site makes for some interesting use cases. Foremost is automated integration with other systems, but you could use this method to establish an offline Point of Sale or Kiosk-type system with a completely different frontend done in Windows Presentation Foundation for a rich in store experience.

When we first conceived of uCommerce years ago there was no uCommerce HQ and no real plan for what uCommerce should become. When time came to choose a data access layer we went the RAD route and chose Subsonic for its productivity benefits. Since then Subsonic has been a blessing and a course.

A blessing because it got us off the ground rapidly as intended and it introduced some pretty cool concepts to the uCommerce API such as LINQ based Active Record.

What really hurt was the complete lack of options for tuning queries for optimum performance. Subsonic is great for throwing together custom queries, but is rather lacking in projecting the needed result into an existing model. Basically this means lots of lots of lazy loading, which hurts performance badly due to the many tiny SQL queries being issued to the database.

Thus we decided to switch to a more full featured ORM and the natural choice at the time was NHibernate.

NHibernate has been present in uCommerce since the very early days. In fact it was introduced in uCommerce 1.0.2 to improve performance when querying the catalog via the XSLT API. We’ve slowly migrated bits and pieces of uCommerce to NHibernate where it made sense over the years.

uCommerce 2.0

During the past two years we’ve kept uCommerce backwards compatible with previous versions to make it simple to upgrade to new versions of uCommerce. With version 2.0 we didn’t really have that option anymore as we reached the end of what was possible to achieve internally so we decided to migrate the final uCommerce .NET APIs to EntitiesV2 and NHibernate.

What this means for you and existing code written against UCommerce.Entities, UCommerce.Runtime, and UCommerce.Pipelines will have to be migrated to UCommerce.EntitiesV2.

The following article describes changes required to make your code run against the new API. Completing the migration will give you several benefits:

A clearer API to work with

Less code to write

Better performance

Caching support

Single programming model for everything

Ids vs Entities

One of the common patterns you see in Subsonic is the use of id properties to tie object together. This is not possible in NHibernate, which has a more entity focused approach.

NHibernate moves the responsibility of handling the association to the “aggregate root” or in other words to the more logical owner of the child object, e.g. the order handles order line.

// Notice the RemoveOrderLine patterns. Use it whenever you can to delete.

purchaseOrder.RemoveOrderLine(orderLine);

purchaseOrder.Save();

As you can see the order is still responsible for handling the delete of the order line. You simply remove the order line from the order with the RemoveOrderLine() method and it will get deleted automatically when the order is saved. Because the operations are not actually carried out until the Save is issued you get the benefit of bulk operations because they will be batched together once you save.

If you don’t use the method, but go the orderLine.Delete() route instead, you’ll often see the following error message, “deleted object would be re-saved by cascade (remove deleted object from associations)[UCommerce.EntitiesV2.OrderLine#2] ==> RemoveEntity”. This happens because the loaded order has a reference to the object and would re-save it to the database.

Deep Deletes

In Subsonic the pattern for deleting an object is very straightforward: You simply go order.Delete(). The issue with Subsonic is that it has no knowledge of relationships between objects so in many cases simply deleting an order would cause a SQL error because other data would be related to the order like order lines, properties, customer, shipments, addresses, etc.. So you have to know about these related objects and the order in which to delete them. Not very user friendly.

NHibernate is smart enough to know about the relationships between objects, so it’ll go ahead and delete related objects where it makes sense so you don’t have to think about it. These are called cascades and it’s the same mechanism, which ensured that our order line got saved in the previous example.

One to One Relationships

An interesting design decision with Subsonic is that it doesn’t expression one to one relationships, e.g. PurchaseOrder has one Customer. Instead Subsonic will treat all relationships as many to many, e.g. PurchaseOrder has many Customers, which makes sense from an ORM implementation point of view, but is very confusing for a developer trying to use an API built on this approach.

Of course NHibernate lets us map data exactly the way we want, which makes the API so much cleaner and simple to understand.

Many to Many Relationships

While Subsonic defines everything as a one to many relation it’s not so great a handling many to many relations. Typically these are implemented with a relation table to go between object A and B, like in the case of a category and product relationship where the same product might be present in multiple categories. Subsonic will map the go-between and require more code to handle the relationship.

Subsonic

// Grab a random product and category

var product = Product.All().First();

var category = Category.All().First();

// Create the relationship

var categoryProductRelation = new CategoryProductRelation();

categoryProductRelation.ProductId = product.ProductId;

categoryProductRelation.CategoryId = category.CategoryId;

categoryProductRelation.Save();

NHibernate

// Grab a random category and product

var category = Category.All().First();

var product = Product.All().First();

// Simply add the product to the category and you're done

category.AddProduct(product);

category.Save();

As you can see NHibernate completely eliminates the requirement to create the relation object yourself. It will handle the intricacies of the relationship behind the scenes for you.

LINQ to uCommerce

With the switch to NHibernate LINQ to uCommerce will gain new options as well. The most obvious change is that you can get away with writing less code than today when doing joins. In many cases you can even get rid of the join altogether.

Summary

As you can see there are significant changes between the Entities and EntitiesV2 APIs, but rest assured that migrating to the newer API is very straightforward. uCommerce Admin, which is a pretty significant codebase written entirely against the Entities API was migrated to EntitiesV2 in three days straight including testing. The benefits we’ve seen from the migration are significant. UIs are more responsive, code required to do a certain operation is clearer, and more often than not there’s less of it.