Custom Events

SmithCart > Integration

SmithCart supports the ability to configure Custom Events. This is useful if you need to populate a backend ERP or accounting system with new store orders.  To enable Custom Events settings, navigate to the Custom Events section of the Store Settings.

The following Custom Events are available to be configured in your store:

 

On Checkout Complete Event (Web Service)

This event allows you to call to a custom web service that you program. The web service that is called can be on the same server as the cart or on another server. The event that triggers the web service call is a successful checkout in the cart.

  Download Sample Event Handler VS Project

 

In the BuyNow module store settings if you check "Enable On Checkout Complete Event (Web Service)", a text box will be displayed where you enter the web service URL you want to call as follows:

 

Naming Convention

The following is the naming convention for the Web Service URL:

http://domain.com/DesktopModules/SmithEventHandler/API/Event/OnCheckoutComplete?OrderID=[ORDERID]&OrderDetailIDs=[ORDERDETAILIDS]

Domain Name – The domain name, server name or IP address for your web service

Service Name – The full path to your web service

OrderID=[ORDERID] – Token used by the cart to pass the order id to the web service

OrderDetailIDs=[ORDERDETAILIDS] – Token used by the cart to pass the order detail id's to the web service

On successful order the cart will do an http post with name value pairs (NVP) in the querystring populated by tokens.

Example

In the BuyNow settings in the web service URL field enter the following URL:

http://domain.com/DesktopModules/SmithEventHandler/API/Event/OnCheckoutComplete?OrderID=[ORDERID]&OrderDetailIDs=[ORDERDETAILIDS ]

[ORDERID] – The Order ID from the cart order.

[ORDERDETAILID] - Comma separated list of Order Detail IDs from the cart order.

  1. The customer successfully checks out and purchases three products.
  2. The cart saves the order to the database
    1. OrderID 9 is saved to the Smith_StoreOrders table
    2. OrderDetail IDs 15, 16 and 17 are saved to the StoreOrderDetails table
  3. The cart makes the following web request to your custom web service:

    http://domain.com/DesktopModules/SmithEventHandler/API/Event/OnCheckoutComplete?OrderID=9&OrderDetailIDs=15,16,17

  4. Your custom web service receives the web service call and does the following:
    1. Consumes the parameters passed and executes some business logic based on your requirements (i.e. Query the Smith_StoreOrderDetail table and create license keys).
    2. Generates web response in the following format:

      OrderDetailID1, LicenseKey1, OrderDetailID2, LicenseKey2, OrderDetailID3, LicenseKey3

      For Example: 4, ABC2X55YTR, 5, RTY856PKIL, 6, EWS321BNH

  5. The cart then reads the response from the custom web service and saves the new license key in the Smth_StoreOrderDetail table in a field called "WebServiceData”.  This field can be viewed by the user in the "My Accounts" module and by the admin in the Mange Orders page.

Request and Response

Web Client Request: http://domain.com/DesktopModules/SmithEventHandler/API/Event/OnCheckoutComplete?OrderID=9&OrderDetailIDs=15,16,17

Web Server Response: 4, ABC2X55YTR, 5, RTY856PKIL, 6, EWS321BNH

SmithCart uses the built in Dot Net “DataContractSerializer” class to parse the response from your custom web service. Please see the following c# code as an example of how SmithCart consumes the response from your custom web service.

WebResponse wsRes = wsReq.GetResponse();

DataContractSerializer wsData = new DataContractSerializer(typeof(string));

string info = (string)wsData.ReadObject(wsRes.GetResponseStream());

Please see the following link for more info on the Dot Net “DataContractSerializer” class:

http://msdn.microsoft.com/en-us/library/system.runtime.serialization.datacontractserializer(v=vs.90).aspx

Because SmithCart uses the “DataContractSerializer” class to parse the response, your custom web service should be implemented using the either a “RESTful” web service or Web API.

This is the simplest and most open technique for communicating with a web service and is not tied to any specific platform or technology. Rather than passing all the order information in the querystring the cart passes the unique keys (Order ID and Order Detail IDs) that enables the web service to lookup any or all order information required. The only caveat is that the data returned from your custom web service may not contain any commas in the actual data because the comma is used as a field delimiter for the cart to parse the response.

Additional Notes

  • The order is saved to the database before the web service call
  • The data passed back from the web service is saved to the “Smith_StoreOrderDetail” table in a field titled “WebServiceData”
  • To insert the data returned from the web service to the confirmation email add the token called [WebServiceData] in your email template.  See the Email Templates KB article for more information.
  • The “WebServiceData” field can be viewed by the user in the "My Accounts" module in the order detail section.  See the Smith My Account module KB article for more information
 

On Checkout Complete Event (Stored Procedure)

This event allows you to call a custom SQL stored procedure on checkout complete.  

When you check "Enable On Checkout Complete Event (Stored Procedure)", a text box will be displayed where you can enter the stored procedure you want to call as follows:

Naming Convention

The following is the naming convention for the stored procedure:

DatabaseOwner + ObjectQualifier + ModuleQualifier in front of your stored procedure.

  • DatabaseOwner is usually “dbo”
  • ObjectQualifier – Is assigned when you installed DNN. The objectqualifier in your database could be "dnn" or you may not be using one. If you are not sure you can check by logging into your database using SSMS.
  • ModuleQualifier is “Smith”

For example, a stored procedure titled “TransferOrder” should be named as follows:

“dbo.dnn_Smith_ TransferOrder”

 

Parameters Passed to Stored Procedure

The following two parameters are passed to the OnCheckout Complete Event Stored Procedure:

1. OrderID (String) – SmithCart order id generated for the new order.

2. SCData (String) – Custom parameter that passes the value of a session variable (SCData) to your stored procedure when checkout is complete. The "SCData" parameter allows the cart to integrate with another Asp.Net application or other modules in your portal. Note: SmithCart does not populate the SCData session object, it is only populated by another application or module on your site. If you don’t have a requirement for passing additional data using SCData it will be passed as an empty string.

Note: It is required that the “OrderID” and “SCData” parameters are defined as varchar or nvarchar parameters at the top of your stored procedure.

 


Step 1 Page Events

The event that triggers the Step 1 Page Events to be triggered is a successful completion of the Step 1 page. This is useful if you need to verify customer information before proceeding to the next page of the checkout process.

Parameters Passed to Stored Procedure

The following customer information is passed to the stored procedure as parameters:

  • First Name
  • Last Name
  • Address 1
  • Address 2
  • City
  • Country
  • State
  • Zip
  • Phone 1
  • Phone 2
  • Email
  • IP Address

Your stored procedure should either return a 1 or 0.   Returning "1" indicates success and the user is allowed to complete checkout.  When your stored procedure returns "0" it indicates failure and the user is prevented from continuing