Installing Ektron’s Sample Workflow Template

Prerequisite

Ektron SDK is installed See Also: Using Ektron’s Developer SDK

Ektron provides a C# workflow template sample for a sequential workflow. You can modify this sample or use it to create new workflows. It is based on the Ektron default workflow.

To install Ektron’s sample workflow template, copy and paste the Ektron Ordering Sequential Flow.zip file using the From & To information below.

From:

C:\Program Files\Ektron\CMS400SDK\Commerce\Workflow\Templates\VS2010

To:

C:\Documents and Settings\~user name~\My Documents\
  Visual Studio 2010\Templates\ProjectTemplates\Visual C#\Workflow

NOTE: Make sure you replace ~user name~ in the path with the user name under which Visual Studio project templates are saved.

Extract the .zip file in the To location. Then, you can work with a sample workflow. See Also: Working with the Sample Workflow

Working with the Sample Workflow

Prerequisite

You installed Ektron’s sample workflow template. See Installing Ektron’s Sample Workflow Template.

1. Open Visual Studio.
2. Choose File > New > Project.
3. If you are using C#, expand the Visual C# project type. Otherwise, expand the Visual Basic project type.
4. Click Workflow.
5. From the My Templates area, select Ektron Ordering Sequential Flow.
6. Select a new Name. If necessary, change the Location, Solution and Solution Name.
7. Click OK.
8. If a prior version of the software developer's kit (SDK) is installed, the assemblies in the sample may be older than those in your site. To avoid an issue:
   1. From your project's bin folder, remove Ektron.Cms.Common.dll and Ektron.Workflow.dll.
   2. Copy those files from the bin folder of your Ektron site to the bin folder of the newly-created workflow project.
   3. Re-establish the References to these dlls from the project's bin folder.
9. Open the Workflow.cs file in the Solution Explorer.
   —Image—

   

10. Make any necessary changes to the workflow. For information on Microsoft’s Workflow Activities, see Build Custom Activities To Extend The Reach Of Your Workflows.
11. Debug as needed.
12. Build the workflow. This creates a DLL of the workflow and places it in the project’s bin/debug folder.
13. Navigate to the DLL's folder. For example, C:\Documents and Settings\~user name~\My Documents\Visual Studio 2010\Projects\MyWorkFlow\MyWorkFlow\bin\Debug.
14. Move or copy the new workflow DLL file to your website’s bin folder.

Adding Workflow Activities to Your Toolbox

1. Open or create a Workflow in Visual Studio. See Installing Ektron’s Sample Workflow Template
2. Display the Toolbox (View > Toolbox).
3. Right-click the mouse within the Toolbox and choose Add Tab.
4. Type Ektron Workflow Activities then press Enter.
5. —Image—

   

6. Click the Ektron Workflow Activities tab.
7. Right-click the mouse in the empty area and choose Choose Items. The Choose Toolbox Items dialog appears.
   —Image—

   

8. In Visual Studio 2010, select the .NET Framework Components tab.
9. Browse to webroot\siteroot\bin\Ektron.Workflow.dll file. This file provides access to Ektron’s workflow activities.

   NOTE: Alternatively, you could use the following location: C:\Program Files\Ektron\CMS400vxx\bin. The file is identical in both places. Using the bin folder in your site provides better speed. However, if you use the bin folder in Program Files, you do not have to worry about deleting the .dll file if you change or delete your site.

10. Click OK.

For easier viewing, right-click the workflow activities and select Sort Items Alphabetically.

NOTE: Ektron’s workflow activities appear only when the workflow is opened in design mode.

Inserting Workflow Activities Using Drag and Drop

Because Visual Studio is a visual environment, lines that connect events and activities change as you add or remove them. To add an activity to a workflow:

1. Display the Visual Studio toolbox (View > Toolbox).
2. Click the Ektron Workflow Activities tab. Ektron’s Workflow Activities appear.
   —Image—

   

3. Drag an activity and drop it into the desired location in the Workflow.
4. As desired, modify the activity’s properties using Visual Studio's Properties area.
   —Image—

   

Activities

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.

Email Message

• Bcc (String)—A blind carbon copy of the email is sent to the address entered in this property. If you select OrderId for the EmailArgs property, the Bcc property is dynamically populated with the order’s information.
• Body (String)—Enter the main content of the email. If you select a parameter from the MessageType property, the Body property uses the corresponding content for that message type.
• CC (String)—A carbon copy of the email is sent to the email address entered in this property. If you select OrderId for the EmailArgs property, the CC property is dynamically populated with the order’s information.
• From (String)—The address from which the email is sent. If you select OrderId for the EmailArgs property, the CC property is dynamically populated with the order’s information.
• HtmlBody (Boolean)—Select whether to send the email in HTML or plain text. True (default), use HTML; False, use plain text.
• ReplyTo (String)—Specify the address to which the recipient of the email replies.
• Subject (String)—Enter subject information for the email. If you select a parameter from the MessageType property, the Subject property uses the subject information for that message type.
• To (String)—The email is sent to the address in this property. If you select OrderId for the EmailArgs property, the To property is dynamically populated with the order’s email information.

Email Server

• Port (Integer)—Set this value to the port your system uses access to retrieve email. In most cases, the port is set to 25. If that is not the case, see your System Administrator. The default is 25. If blank, this property uses the ek_SMTPPort value in the site’s web.config file.
• SmtpHost (String)—The address of the server hosting the email system. If blank, this property uses the ek_SMTPServer in the site’s web.config file.

Handlers

• SendingEmail (String)—Event handler to add custom code to the sending email event. This event fires right before the email is sent.
• SentEmail (String)—Event handler to add custom code to the sent email event. This event fires right after the email is sent.

Misc

• EmailArgs—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.
• MessageType—Select the type of message that is sent for this activity. If you select None, the message is sent with the text in the Body property.
  • None (default)—uses the text in the Body property.
  • OrderReceived—Sends the Order Received email defined in the Workarea > Settings > eCommerce > Configuration > Messages screen when an order is received.
  • OrderCancelled—Sends the Order Cancelled email defined in the Workarea > Settings > eCommerce > Configuration > Messages screen when an order is received.
  • OrderShipped—Sends the Order Confirmation email defined in the Workarea > Settings > eCommerce > Configuration > Messages screen when an order is received.

For information on defining the messages, see Configuring eCommerce.

Activities

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.

Email Message

• Bcc (String)—A blind carbon copy of the email is sent to the address entered in this property.
• Body (String)—Enter the main content of the email.
• CC (String)—A carbon copy of the email is sent to the email address entered in this property.
• From (String)—The address from which the email is sent.
• HtmlBody (Boolean)—Select whether to send the email in HTML (True) or plain text (False).
• ReplyTo (String)—Specify the address to which the recipient of the email replies.
• Subject (String)—Enter a brief summary for the email.
• To (String)—The email is sent to the address in this property.

Email Server

• Port (Integer)—Set this value to the port your system access to retrieve email. In most cases, the port is set to 25. If that is not the case, see your System Administrator. The default is 25. If blank, this property uses the ek_SMTPPort value in the site’s web.config file.
• SmtpHost (String)—The address of the server hosting the email system. If blank, this property uses the ek_SMTPServer in the site’s web.config file.

Handlers

• SendingEmail (String)—Event handler to add custom code to the sending email event.
• SentEmail (String)—Event handler to add custom code to the sent email event.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.

Handlers

• MethodInvoking—Select a method to call before the order is captured.

Misc

• Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.

Handlers

• MethodInvoking—Select a method to call before the stock level is checked.

Misc

• orderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.
• ReturnValue (Boolean)
  • True—the quantity of each product ordered is in stock.
  • False (default)—there is not enough product in stock to fulfill the order.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order is canceled.

Misc

• Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order has been captured.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order has been marked as fraud.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order has been processed.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order has been received.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order is shipped.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId. from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.
• Roles—

Handlers

• Invoked (String)—Specify code that executes when the order has been updated.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId. from the list.

Activity

• Name (String)—Enter a name for the Activity.
• Description (String)—Enter a description for the Activity.
• Enabled (Boolean)—True (default), enable the activity; False, disable.

Handlers

• MethodInvoking—Select a method to call before the stock level is checked.

Misc

• OrderId—Select OrderId to dynamically associate this activity with orders in Ektron. Click Browse () and select OrderId. from the list.
• orderStatus
  • Received (default)—marks an order as received
  • InProcess—marks the order as in process
  • Shipped—marks the order as shipped
  • Completed—marks the order as completed
  • Canceled—marks the order as canceled
  • OnHold—puts the order on hold
  • Fraud—marks the order as fraud

The following figure shows the Object Model for Ektron’s Payment Gateway Provider.

The PaymentGatewayProvider is the abstract base class you must extend to implement your own payment gateway. Details and descriptions of the PaymentGatewayProvider API can be found in the Ektron API Reference Manual’s Providers API > PaymentGatewayProvider section.

Creating a Custom Payment Gateway Provider

In addition to the out-of-the-box payment gateways providers shipped with Ektron, you can create your own custom payment providers that connect with any payment gateway you choose. Below are the basic code steps you need to complete when creating a custom gateway provider. Additional code examples used by Ektron to create the PayFlow and Authorize.NET providers are located in: C:\Program Files\Ektron\CMS400SDK\Commerce\Providers\Commerce.Providers\PaymentGateways

The complete C# code sample used in this example is available at the end of this section. See CustomGatewayProvider Code Example

1. Create a class library project in Visual Studio.
2. Add references to these DLLs:
   • Ektron.Cms.Commerce
   • Ektron.Cms.Common
   • Ektron.Cms.ObjectFactory
   • Ektron.Cms.Instrumentation
   • System.Configuration
   • Add these using statements to the code-behind:

     using System;
     using System.Collection;
     using System.Collection.Specialized;
     using Ektron.Cms;
     using Ektron.Cms.Common;
     using Ektron.Cms.Commerce; 

3. Change the namespace to:

   namespace Ektron.Cms.Extensibility.Commerce.Samples

4. Rename your class and inherit as below:

   public class CustomPaymentProvider: 
     Ektron.Cms.Commerce.PaymentGatewayProvider.PaymentGatewayProvider

5. Add the following constructor.

   #region constructor, member variables
   public CustomPaymentProvider() { }
   #endregion

6. Add the methods required by the PaymentGatewayProvider base class. The Initialize method reads configuration information, the others are related to the payments and will be completed later in the example.

   public override void 
     Initialize(string name, 
     System.Collections.Specialized.NameValueCollection config)
   { if (config == null) 
     { throw new ArgumentNullException("config"); 
   // Assign the provider a default name if it doesn't have one 
     if (String.IsNullOrEmpty(name)) name = "CustomPaymentProvider";   
     if (string.IsNullOrEmpty(config["description"])) 
       { config.Remove("description"); 
         config.Add("description", "CustomPaymentProvider"); 
       } 
   // Call the base class's Initialize method 
       base.Initialize(name, config); 
   // Throw an exception if unrecognized attributes remain 
     if (config.Count > 0) 
       { foreach (string key in config.AllKeys) 
         { EkException.WriteToEventLog("Unrecognized Payment Gateway 
           Provider attribute: " + key, 
           System.Diagnostics.EventLogEntryType.Warning); 
         } 
       } 
     }
   }
   public override string Authorize()
   {
   }
   public override string AuthorizeAndCapture()
   {
   }
   public override string CapturePreauthorization(string transactionId)
   {
   }
   public override string VoidPreAuthorization(string transactionId)
   {
   }
   

7. Implement the Authorize method that you added in the previous step. This method is called to authorize a given amount of money when an order is submitted.

   public override string Authorize()
   { if (PaymentMethod.GetType() != typeof(CreditCardPayment)) 
     throw new Ektron.Cms.Commerce.Exceptions
       .AuthorizationException("Invalid Payment Type"); 
     CreditCardPayment creditCard = (CreditCardPayment)this.PaymentMethod; 
     if (creditCard.ExpirationDate.IsExpired()) 
       throw new Ektron.Cms.Commerce.Exceptions.Payment.CreditCard
         .CardExpiredException("Card Is Expired"); 
     IsSubmissionSuccess = true; 
     Authorization.AuthorizedOn = DateTime.Now; 
     Authorization.TransactionId = new Guid().ToString(); 
     return Authorization.TransactionId;
   }

   In this example, the card number and card holder name are not checked. In a real world scenario, there would be additional validation (for example, via checksum) and the authorization may be obtained via a Web service or HTTP post.

   NOTE: If the authorization fails, you can choose to either throw an exception or manually set the failure. For example:
   SubmissionError = "Not enough Funds";IsSubmissionSuccess = false;

8. Implement the AuthorizeAndCapture, CapturePreauthorization and VoidPreAuthorization methods you added earlier.
9. AuthorizeAndCapture requires that Authorization.CapturedOn be set, as the capture occurs at the same time as the Authorization.
10. For CapturePreauthorization and VoidPreAuthorization, set the appropriate dates for these actions, so they are recorded in the system properly.

    public override string AuthorizeAndCapture()
    { IsSubmissionSuccess = true; 
      Authorization.AuthorizedOn = DateTime.Now; 
      Authorization.CapturedOn = DateTime.Now; 
      Authorization.TransactionId = new Guid().ToString(); 
      return Authorization.TransactionId;
    }
    public override string CapturePreauthorization(string transactionId)
    { IsSubmissionSuccess = true; 
      Authorization.CapturedOn = DateTime.Now; 
      return Authorization.TransactionId;
    }
    public override string VoidPreAuthorization(string transactionId)
    { IsSubmissionSuccess = true; 
      Authorization.VoidedOn = DateTime.Now; 
      return Authorization.TransactionId;
    }

11. Save and build the project.
12. Copy your project’s DLL file to your Ektron website’s bin directory.
13. Register the provider in your site’s web.config file. The web.config file provides the facility to manage payment gateway providers within Ektron.
14. To do this, locate the EktronPaymentGateway section and change the defaultProvider parameter to the name of your custom provider. Note that changing this from “Automatic” to the name of your provider overrides the settings in Workarea > Settings > Commerce > Configuration > Payment Gateways. Ektronnow will use the new provider.
15. If you start your search from the top of the file, it is the second instance.

    <EktronPaymentGateway defaultProvider="CustomPaymentProvider">

16. Add your custom payment provider between the EktronPaymentGateway’s <providers> tags. Note that the name defined here must match the defaultProvider from the previous step.

    <providers>
      <add name="CustomPaymentProvider" 
        type="Ektron.Cms.Extensibility.Commerce.Samples.CustomPaymentProvider,
        CustomPaymentProvider" />
    </providers>
    

17. Save the web.config file.
18. Next, add the payment gateway to the Workarea.
    1. Go to Workarea > Commerce > Configuration > Payment Options.
    2. Select New > Payment Gateway.
    3. In the Name drop-down, select customerPaymentProvider.
    4. Check both Cards and Checks checkboxes.
    5. Save these changes. Your custom payment provider is now the default provider. Whenever a payment provider needs to be contacted, the information routes through the new custom provider.

Displaying Your Custom Provider an Option in the Workarea

In the example above, you changed the web.config file’s EktronPaymentGateway defaultProvider parameter to the name of your custom payment provider. This overrides the payment provider settings in the Workarea. To manage all payment providers from the Workarea > Settings > Commerce > Configuration > Payment Gateways screen:

1. In the web.config file, locate the EktronPaymentGateway section and make sure the defaultProvider parameter is set to Automatic.

   <EktronPaymentGateway defaultProvider="Automatic">

2. Save the web.config file.
3. Navigate to the Workarea > Settings > Commerce >Configuration > Payment Gateways screen.
4. Choose New > Payment Gateway.
5. From the Name drop-down list, select the name of the your new custom gateway.
6. Check the Default box if you want this to be the default payment gateway. The default payment gateway is the gateway all payment information is routed through.
7. Enter the User ID for this payment gateway. This ID will identify your account with this gateway provider.
8. Enter the password for your account with this gateway provider.
9. If this gateway provider expects additional parameters when contacting it, click the Expand Custom Values link and enter those values into the Custom 1 and Custom 2 fields.
10. Click Save. The custom gateway provider has been added and can now be managed from the Workarea.

CustomGatewayProvider Code Example

WARNING! Copying, pasting, and using the following code without modification to create a DLL will not result in a working custom payment provider. This code is provided as an outline of what is needed to create an actual custom payment provider.

using System;
using System.Collections;
using System.Collections.Specialized;
using System.Configuration.Provider;
using Ektron.Cms;
using Ektron.Cms.Common;
using Ektron.Cms.Commerce;
namespace Ektron.Cms.Extensibility.Commerce.Samples
  {
  public class CustomPaymentProvider : 
    Ektron.Cms.Commerce.PaymentGatewayProvider
    {
    public CustomPaymentProvider() { }
      public override void Initialize(string name, 
      System.Collections.Specialized.NameValueCollection config)
      {
      if (config == null throw new ArgumentNullException(;
      // Assign the provider a default name if it doesn't have one
      if (String.IsNullOrEmpty(name))
      name = CustomPaymentProvider"
      if string.IsNullOrEmpty(config(["description"])) 
        {
        config.Remove("description");
        config.Add("description", "CustomPaymentProvider";
        }
        // Call the base class's Initialize method
        base.Initialize(name, config);
        // Throw an exception if unrecognized 
          attributes remain
        if (config.Count > 0)
        {
        foreach (string key in config.AllKeys)
          {
          EkException.WriteToEventLog("Unrecognized 
            Payment Gateway Provider attribute:
            " + key, 
            System.Diagnostics.EventLogEntryType.Warning);
          }
        }
      }
    public override string Authorize()
    {
    if (PaymentMethod.GetType() != typeof(CreditCardPayment))
      throw new Ektron.Cms.Commerce.Exceptions.
        AuthorizationException("Invalid Payment Type");
      CreditCardPayment creditCard = (CreditCardPayment)
        this.PaymentMethod;
      if (creditCard.ExpirationDate.IsExpired())
      throw new Ektron.Cms.Commerce.Exceptions.Payment.CreditCard.
        CardExpiredException( "Card Is Expired";
      IsSubmissionSuccess = true;
      Authorization.AuthorizedOn = DateTime.Now;
      Authorization.TransactionId = new Guid().ToString();
      return Authorization.TransactionId;
    }
    public override string AuthorizeAndCapture()
      {
      IsSubmissionSuccess = true;
      Authorization.AuthorizedOn = DateTime.Now;
      Authorization.CapturedOn = DateTime.Now;
      Authorization.TransactionId = new Guid().ToString();
      return Authorization.TransactionId;
      }
    public override
      string CapturePreauthorization(string transactionId)
      {
      IsSubmissionSuccess = true;
      Authorization.CapturedOn = DateTime.Now;
      return Authorization.TransactionId;
      }
    public override string VoidPreAuthorization(string transactionId)
      {
      IsSubmissionSuccess = true;
      Authorization.VoidedOn = DateTime.Now;
      return Authorization.TransactionId;
      }
    }
  }

The following figure shows the Object Model for Ektron’s Shipment Provider.

The ShipmentProvider is the abstract base class you must extend to implement your own Shipping Provider. Details and descriptions of the ShipmentProvider API can be found in the Ektron API Reference Manual’s Providers API > Shipment > Provider > ShipmentProvider.

Creating a Custom Shipment Provider

In addition to the out-of-the-box shipment providers that come with Ektron, you can create a custom provider that connects with any shipping company you choose. Below are the basic code steps you need to complete when creating a custom shipment provider. Additional code examples used by Ektron to create FedEx, Flat Rate and UPS shipment providers are located in:

C:\Program Files\Ektron\CMS400SDK\Commerce\Providers\Commerce.Providers\Shipping

The complete C# code sample used in this example is available at the end of this section. See CustomShipmentProvider Code Example.

1. Create a class library project in Visual Studio.
2. Add references to these DLLs:

   Ektron.Cms.Commerce
   Ektron.Cms.Common
   Ektron.Cms.ObjectFactory
   Ektron.Cms.Instrumentation
   System.Configuration
   

3. Add these using statements to the code-behind:

   using System.Configuration. 
   using Ektron.Cms.Commerce.Shipment.Provider; 
   using Ektron.Cms.Commerce using Ektron.Cms.Instrumentation

4. Change the namespace to:

   namespace Ektron.Cms.Extensibility.Commerce.Samples
   {

5. Rename your class and inherit as below:

   public class CustomShipmentProvider : ShipmentPovider
   {

6. Add the following constructor private variables and properties. The items added to the shippingOptionList are the shipping methods exposed as a service type in the management screen inside the Workarea.

   #region constructor, member variables
   public CustomShipmentProvider()
   { IsTrackingSupported = false; 
     _shippingOptionList = new List<string>(); 
     _shippingOptionList.Add("CustomOption_1"); 
     _shippingOptionList.Add("CustomOption_2");
   }
   private List<string> _shippingOptionList;
   #endregion 

7. Add the following methods required by the ShipmentProvider base class.
   • Initialize—reads configuration information
   • GetServiceTypes—returns a List <string> of the shipping options available
   • GetTrackingUrl—exposes tracking support
   • GetRates—returns a list of shipping rates for the items being shipped. The contents of this method will be added in the next step.

   #region ShipmentProvider Implementation
   public override void 
     Initialize(string name, 
     System.Collections.Specialized.NameValueCollection config)
   { if (config == null) 
     { throw new ArgumentNullException("config"); 
   // Assign the provider a default name if it doesn't have one 
     if (string.IsNullOrEmpty(name)) name = "CustomShipmentProvider"; 
     if (string.IsNullOrEmpty(config["description"])) 
       { config.Remove("description"); config.Add("description", 
         "CustomShipmentProvider Provider"); } 
   // Call the base class's Initialize method 
       base.Initialize(name, config); 
   // Throw an exception if unrecognized attributes remain 
     if (config.Count == 0) throw new 
       ProviderException("Shipment provider attribute missing."); 
     else { 
   //read all config attributes. 
       ServiceUrl = config["serviceUrl"]; 
       Key = config["key"]; 
       Password = config["password"]; 
       AccountNumber = config["accountNumber"]; 
       MeterNumber = config["meterNumber"]; 
       TransactionId = config["transactionId"]; 
           } 
         }
   public override List<string> GetServiceTypes()
     { return _shippingOptionList;
     }
   public override string GetTrackingUrl(string trackingId)
     { return "";
     }
   public override List
     <ShippingOptionData>GetRates(IEnumerable
     <ShippingMethodData> 
     expectedOptions, AddressData origin, AddressData destination, 
     Weight weight, Dimensions dimensions)
     {
    }
   #endregion 

8. Implement the GetRates method. Add this code to public override for GetRates which was added during the previous step. (This example uses flat rates for your shipping methods. In a real world scenario, the shipping methods and their corresponding rates can be obtained via FedEx, UPS, a third party application or a Web service.) When complete, the code should look like this.

   public override List <ShippingOptionData> 
     GetRates(IEnumerable<ShippingMethodData> 
       expectedOptions, AddressData origin, AddressData destination, 
       Weight weight, Dimensions dimensions)
   { List <ShippingOptionData> availableOptions = 
       new List <ShippingOptionData>(); 
     try 
       { foreach (ShippingMethodData expectedOption in expectedOptions) 
         { Log.WriteInfo("Custom Shipping Provider.ExpectedOption:" + 
           expectedOption.Name); 
           switch (expectedOption.ProviderService.ToLower()) 
           { case "customoption_1": ShippingOptionData customOption1 = 
             new ShippingOptionData(); 
             customOption1.Id = expectedOption.Id; 
             customOption1.Name = expectedOption.Name; 
             customOption1.ShippingFee = 25.00M; 
             customOption1.ProviderService = "CustomOption_1"; 
             availableOptions.Add(customOption1); 
             break; 
             case "customoption_2": 
               ShippingOptionData customOption2 = new ShippingOptionData(); 
               customOption2.Id = expectedOption.Id; 
               customOption2.Name = expectedOption.Name;
               customOption2.ShippingFee = 50.00M;
               customOption2.ProviderService = "CustomOption_2"; 
               availableOptions.Add(customOption2); 
               break; 
           } 
         } 
       } 
     catch (Exception e) 
       { Log.WriteError("Custom Shipping Provider: Error retrieving shipping
         rates." + e.Message); throw; 
       } 
     return availableOptions; 
   } 

9. You can use the GetRates method to restrict countries to which you ship. For example, if you want to prevent shipping to all countries except Canada, add these lines of code to the GetRates method.

   if (destination.Country.Id != 124) 
     throw new Ektron.Cms.Commerce.Exceptions.Shipping.InvalidAddressException 
     ("We ship only to Canada.");
   

10. Save and build the project.
11. Copy your project’s DLL file to your Ektron website’s bin directory.
12. Register the provider in your site’s shipment.config file. This file provides the facility to manage shipping providers within Ektron. Locate the shipmentProvider section and change the defaultProvider parameter to the name of your custom provider.

    <shipmentProvider defaultProvider="CustomShipmentProvider"> 

13. Add your custom shipping provider between the shipmentProvider’s <providers> tags. Note that the name defined here needs to match the name defined as the defaultProvider in the previous step.

    <providers>
      <add name="CustomShipmentProvider" 
        type="Ektron.Cms.Extensibility.Commerce.Samples.CustomShipmentProvider,
          CustomShipmentProvider" serviceUrl="" key="" password="" 
          accountNumber="" meterNumber="" 
          transactionId="CustomShipmentProvider based transaction" />
    </providers> 

14. Save the web.config file.
15. Your custom shipping provider is now the default provider. Whenever you need to obtain shipping rate information, the information routes through the new custom provider.
16. Add the shipping methods that are available for your provider in the Workarea > Settings > Commerce -> Shipping > Methods screen.
    1. Select New > Shipping Method.
    2. Enter a name. This is what a customer sees during the checkout process. An example is “Ground” or “Next Day”. For this example, use “Custom1”.
    3. Check the Active checkbox.
    4. Click View Options and select CustomOption_1 from the list.
    5. Click Save).
    6. Repeat this process for the CustomOption2 shipping method type.

The options are now available in the checkout process, and are shown on the shipping method selection screen.

using System.Configuration.Provider;
using Ektron.Cms.Commerce.Shipment.Provider;
using Ektron.Cms.Commerce; 
using Ektron.Cms.Instrumentation;
namespace Ektron.Cms.Extensibility.Commerce.Samples
{
  public class CustomShipmentProvider : ShipmentProvider
  {
    #region constructor, member variables
    public CustomShipmentProvider()
      {
        IsTrackingSupported = false;
        _shippingOptionList = new List<string>();
        _shippingOptionList.Add("CustomOption_1");
        _shippingOptionList.Add("CustomOption_2");
      }
    private List<string> _shippingOptionList;
    #endregion
    #region ShipmentProvider Implementation
    public override void Initialize(string name, 
      System.Collections.Specialized.NameValueCollection config)
    {
      if (config == null)
        throw new ArgumentNullException("config");
        // Assign the provider a default name if it doesn't have one
      if (string.IsNullOrEmpty(name))
        name = "CustomShipmentProvider";
      if (string.IsNullOrEmpty(config["description"]))
      {
        config.Remove("description");
        config.Add("description", "CustomShipmentProvider Provider");
      }
    // Call the base class's Initialize method
    base.Initialize(name, config);
    // Throw an exception if unrecognized attributes remain
    if (config.Count == 0)
      throw new ProviderException("Shipment provider attribute missing.");
    else
      {
        //read all config attributes.
        ServiceUrl = config["serviceUrl"];
        Key = config["key"];
        Password = config["password"];
        AccountNumber = config["accountNumber"];
        MeterNumber = config["meterNumber"];
        TransactionId = config["transactionId"];
      }
    }
    public override List<string> GetServiceTypes()
    {
      return _shippingOptionList;
    }
    public override string GetTrackingUrl(string trackingId)
    {
      return "";
    }
    public override List<ShippingOptionData> 
      GetRates(IEnumerable<ShippingMethodData> 
        expectedOptions, AddressData origin, AddressData destination, 
        Weight weight, Dimensions dimensions)
    {
      List<ShippingOptionData> availableOptions = new List<ShippingOptionData>();
      try
      {
        foreach (ShippingMethodData expectedOption in expectedOptions)
        {
        Log.WriteInfo("Custom Shipping Provider.ExpectedOption:" 
          + expectedOption.Name);
        switch (expectedOption.ProviderService.ToLower())
        {
          case "customoption_1":
            ShippingOptionData customOption1 = new ShippingOptionData();
            customOption1.Id = expectedOption.Id;
            customOption1.Name = expectedOption.Name;
            customOption1.ShippingFee = 25.00M;
            customOption1.ProviderService = "CustomOption_1";
            availableOptions.Add(customOption1);
            break;
          case "customoption_2":
            ShippingOptionData customOption2 = new ShippingOptionData();
            customOption2.Id = expectedOption.Id;
            customOption2.Name = expectedOption.Name;
            customOption2.ShippingFee = 50.00M;
            customOption2.ProviderService = "CustomOption_2";
            availableOptions.Add(customOption2);
            break;
        }
        }
      }
      catch (Exception e)
      {
        Log.WriteError("Custom Shipping Provider: 
          Error retrieving shipping rates." + e.Message);
        throw;
      }
      return availableOptions;
    }
    #endregion
  }
}

The following figure shows the Object Model for Ektron’s Inventory Provider.

The InventoryProvider is the abstract base class you must extend to implement your own Inventory Provider. Details and descriptions of the InventoryProvider API can be found in the Ektron API Reference Manual’s Providers API > Inventory > Provider > InventoryProvider.

Creating a Custom Inventory Provider

In addition to the out-of-the-box inventory provider that comes with Ektron, you can create your own custom provider that connects with an existing inventory system. Below are the basic code steps you need to complete when creating a custom inventory provider. A code example for the inventory provider used by Ektron is located in:

C:\Program Files\Ektron\CMS400SDK\Commerce\Providers\Commerce.Providers\Inventory

The complete C# code sample used in this example is available at the end of this section. See CustomInventoryProvider Code Example.

1. Create a class library project in Visual Studio.
2. Add references to these DLLs:
   • Ektron.Cms.Commerce
   • Ektron.Cms.Common
   • Ektron.Cms.ObjectFactory
   • System.Configuration
3. Add these using statements to the code-behind.

   using Ektron.Cms.Commerce.Inventory.Provider;
   using Ektron.Cms.Commerce.Data; 
   using Ektron.Cms.Commerce; using Ektron.Cms.Common; 
   using Ektron.Cms.Extensibility;
   using Ektron.Cms.Extensibility.Commerce; 

4. Change the namespace to:

   Ektron.Cms.Extensibility.Commerce.Samples { 

5. Rename your class and inherit as below:

   CustomInventoryProvider InventoryPovider 

6. Add the following constructor, private variables and properties.

   Public CustomInventoryProvider() { } private CmsInventory _inventory;
   protected CmsInventory Inventory 
     { get 
       { if (_inventory == null) 
         { _inventory = CmsInventory(RequestInformation); 
         } return_inventory; 
       } 
     } 

7. Override the following methods. These methods area called when the inventory system is queried.
   • GetInventory—returns an InventoryData data class for a given product id.
   • SaveInventory—persists updates to the stock levels inside the inventory system.

     In this example, we trigger Ektron extensibility events, such as OnBeforeInventorySave() and OnAfterInventorySave(). In a real world scenario, your existing inventory system may have its own inventory events that are used.

   public override InventoryData GetInventory (long entryId) 
     { return Inventory.GetInventory(entryId); }
   public override void SaveInventory(InventoryData inventory) 
     { OnBeforeInventorySave(inventory);
       Inventory.SaveInventory(inventory); 
       OnAfterInventorySave(inventory); 
       if (inventory.UnitsInStock < inventory.ReorderLevel) 
         { OnInventoryReorderLevelReached(inventory); } 
     } 

8. Save and build the project.
9. Copy your project’s DLL file to your Ektron website’s bin directory.
10. Register the provider in your site’s web.config file. The web.config file provides the facility to manage inventory providers within Ektron. Locate the InventoryProvider section and change the defaultProvider parameter to the name of your custom provider. If you start your search from the top of the file, it will be the second instance.

    <inventoryProvider defaultProvider="CustomInventoryProvider">

11. Add your custom payment provider between the EktronPaymentGateway’s <providers> tags. Note that the name defined here needs to match the name defined as the defaultProvider in the previous step.

    <providers>
      <add name="CustomInventoryProvider" 
        type="Ektron.Cms.Extensibility.Commerce.Samples.CustomInventoryProvider,
        CustomInventoryProvider"/>
    </providers> 

12. Save the web.config file.

Your custom inventory provider is now the default provider. Whenever the inventory is queried, the call routes through the new custom provider.

using Ektron.Cms.Commerce.Inventory.Provider;
using Ektron.Cms.Commerce.Data;
using Ektron.Cms.Commerce;
using Ektron.Cms.Common;
using Ektron.Cms.Extensibility;
using Ektron.Cms.Extensibility.Commerce;
namespace Ektron.Cms.Extensibility.Commerce.Samples
  {
    public class CustomInventoryProvider : InventoryProvider
    {
      public CustomInventoryProvider() { }private CmsInventory _inventory;
      protected CmsInventory Inventory
      {
        get
        {
          if (_inventory == null)
          {
            _inventory = new CmsInventory(RequestInformation);
          }
        return _inventory;
        }
      }
      public override InventoryData GetInventory(long entryId)
      {
        return Inventory.GetInventory(entryId);
      }
      public override void SaveInventory(InventoryData inventory)
      {
        OnBeforeInventorySave(inventory);
        Inventory.SaveInventory(inventory);
        OnAfterInventorySave(inventory);
        if (inventory.UnitsInStock < inventory.ReorderLevel)
        {
          OnInventoryReorderLevelReached(inventory);
        }
      }
    }
  }    

Creating the Calculator Code

1. Create a class library project in Visual Studio named Commerce.CustomShippingCalculator. You need to import the necessary Ektron namespaces. To do this, add references to:
   • Ektron.Cms.Api
   • Ektron.Cms.Commerce
   • Ektron.Cms.Common
   • Ektron.Cms.Instrumentation
   • Ektron.Cms.ObjectFactory
   • Microsoft.Practices.EnterpriseLibrary.Validation
   • System.Configuration
2. Add the following using statements.

   using System.Collections.Generic; 
   using Microsoft.Practices.EnterpriseLibrary.Validation; 
   using Ektron.Cms; 
   using Ektron.Cms.Common; 
   using Ektron.Cms.Commerce; 
   using Ektron.Cms.Commerce.Shipment.Provider; 
   using Ektron.Cms.Extensibility; 
   using Ektron.Cms.Extensibility.Commerce; 
   using Ektron.Cms.Instrumentation; 
   using Ektron.Cms.Commerce.Exceptions; 
   using Ektron.Cms.Commerce.Exceptions.Shipping; 

3. Change the namespace to Ektron.Cms.Extensibility.Commerce.Samples. Then, rename your class to CustomShippingCalculator and inherit from the ShippingCalculatorStrategy class. See sample code below.

   namespace Ektron.Cms.Extensibility.Commerce.Samples 
     { public class CustomShippingCalculator : ShippingCalculatorStrategy 
     {
   

4. Add a few helper variables, properties, and functions. The function GetFlatPackageList "flattens" the items in the basket, returning 1 for each item quantity. So, if we have 4 widgets, we'll have 4 packages, each with one widgetWidgets are mini-applications that you place on a Web page using PageBuilder; a widget provides either specific functionality (calculators, search, social bars, etc.) or areas into which you can add content (content blocks, list summaries, collections, and so on)..
5. The following logic fits the goods into packages, adding a function to get another warehouse location. (It is hard-coded in this example.)

   namespace Ektron.Cms.Extensibility.Commerce.Samples
   { public class CustomShippingCalculator : ShippingCalculatorStrategy 
     { private EkRequestInformation _requestInfo; 
       private IShippingMethod _shippingService; 
       protected EkRequestInformation RequestInformation 
       { get 
         { if (_requestInfo == null) 
           { _requestInfo = 
             ObjectFactory.GetRequestInfoProvider().GetRequestInformation();
           } 
           return _requestInfo; 
         } 
       }
     } 
     protected IShippingMethod ShippingService 
     { get 
       { if (_shippingService == null) 
         { _shippingService = ObjectFactory.GetShippingMethod(); 
         } 
         return _shippingService; 
       } 
     } 
     protected List<ShippingMethodData> GetActiveShippingMethodList() 
     { Criteria<ShippingMethodProperty> 
       criteria = new Criteria<ShippingMethodProperty> 
         (ShippingMethodProperty.DisplayOrder, 
         EkEnumeration.OrderByDirection.Ascending); 
       criteria.AddFilter(ShippingMethodProperty.IsActive, 
         CriteriaFilterOperator.EqualTo, true); 
       return ShippingService.GetList(criteria); 
     } 
     protected List<ShippingPackageData> 
       GetFlatPackageList(List<AdjustedBasketItem> basketItems) 
     { List<ShippingPackageData> flatList = new List<ShippingPackageData>(); 
       foreach (AdjustedBasketItem item in basketItems) 
       { if (item.IsTangible) 
         { for (int x = 1; x <= item.Quantity; x++) 
           { ShippingPackageData package = 
             new ShippingPackageData(item.Dimensions, item.Weight); 
             package.Items.Add(item);
             flatList.Add(package); 
           } 
         } 
       } 
       return flatList; 
     } 
     private AddressData GetWarehouseAddressData() 
     { AddressData address = new AddressData(); 
       address.Name = "Ektron"; 
       address.AddressLine1 = "542 Amherst St."; 
       address.City = "Nashua"; 
       address.Country = new CountryData();
       address.Country.Id = 840; 
   // USA 
       address.Region = new RegionData();
       address.Region.Id = 31; 
   // NH 
       address.PostalCode = "03063";
       return address;
     }
   } 

6. Override the OnBeforeCalculate method, which is called when shipping is calculated for the basket.

   public override void OnBeforeCalculate(BasketCalculatorData basketData, 
     ShippingMethodData shippingMethod, CancellableEventArgs eventArgs) { }
   

7. In this method, add code to ship items with a tax class id of 4 from another warehouse, versus the default one specified (package.Items[0].TaxClassId == 4 ).

   public override void OnBeforeCalculate(BasketCalculatorData basketData, 
     ShippingMethodData shippingMethod, CancellableEventArgs eventArgs)) 
     { bool hasTangibles = basketData.Basket.HasTangibleItems; 
       List<ShippingMethodData> 
         availableShippingMethods = GetActiveShippingMethodList(); 
       List<ShippingPackageData>
         shippingPackages = GetOrderPackages(basketData.AdjustedItems); 
   //convert list of items into flat list - all 1 quantity. 
     List<ShippingPackageData> 
       shippingPackages = FlattenItemsIntoPackages(basketData.AdjustedItems); 
       if (shippingPackages.Count == 0) 
         { Log.WriteInfo("No packages to calculate shipping for."); 
           return; 
         } 
         Dictionary<string, int> rateCount = new Dictionary<string, int>(); 
   //Get Rate for each package 
     foreach (ShippingPackageData package in shippingPackages) 
       { List<ShippingOptionData> shippingRateList;
         Log.WriteVerbose(string.Format("Shipping package: 
         {0} x {1} x {2} {3}, {4} {5}", package.Dimensions.Height,
         package.Dimensions.Length, package.Dimensions.Width, 
         package.Dimensions.Units.ToString(), package.TotalItemWeight.Amount,
         package.TotalItemWeight.Units.ToString())); 
   //Get rate for each available option and populate the 
   // BasketCalculatorData.ShippingRates list. 
     if (package.Items[0].TaxClassId == 4) shippingRateList =
       ShipmentProviderManager.Provider.GetRates(availableShippingMethods,
       GetWarehouseAddressData(), basketData.ShipTo, package.TotalItemWeight,
       package.Dimensions); 
     else shippingRateList = ShipmentProviderManager.Provider.GetRates 
       (availableShippingMethods, basketData.ShipFrom, basketData.ShipTo, 
       package.TotalItemWeight, package.Dimensions); 
       if (shippingRateList.Count == 0) 
         { EkException.ThrowException(new NoRatesAvailableException 
           ("No shipping rates are available for the supplied item.")); 
         } 
   //add rates to basket.ShippingRates 
     foreach (ShippingOptionData rate in shippingRateList) 
       {
   //if there are multiple packages, we need to total up rates for each 
   //shipping method.
   //NOTE: we can only return rates that are applicable to ALL packages.
   //For example, package 1 has rates for ground, priority, freight
   // package 2 has rates for ground, priority
   //only return rates for ground and priority since freight will only be
   //a partial quote.
   //check if this shipping method has already been added. 
         ShippingOptionData existingMethodRate = 
           basketData.ShippingRates.Find(delegate(ShippingOptionData match) 
           { return match.ProviderService == rate.ProviderService; }); 
         if (existingMethodRate == null) 
           { basketData.ShippingRates.Add(rate); } 
         else 
           { existingMethodRate.ShippingFee += rate.ShippingFee; }
   //need to keep count of how many times this shipping method rate is added
   //to make sure we have a method rate for each package. 
         if(rateCount.ContainsKey(rate.ProviderService))
           { rateCount[rate.ProviderService]++; }
         else 
           { rateCount.Add(rate.ProviderService, 1); } 
       } 
     }
   //default exchange rate 
     ExchangeRateData exchangeRate = new ExchangeRateData(0, 0, 1m, null); 
     if (basketData.ShippingRates.Count > 0 
       && basketData.ShippingRates[0].CurrencyId 
       != RequestInformation.CommerceSettings.CurrencyId) 
       { IExchangeRate rateService = ObjectFactory.GetExchangeRate(); 
         exchangeRate = rateService.GetCurrentExchangeRate(); 
         if (exchangeRate == null) 
           { Log.WriteError(string.Format("No exchange rate found for 
             current currency {0}. Shipping rates could not be converted
             to current currency.", 
             RequestInformation.CommerceSettings.CurrencyId)); 
             EkException.ThrowException(new CmsException(string.Format 
              ("No exchange rate found for current currency {0}. Shipping 
              rates could not be converted to current currency.", 
              RequestInformation.CommerceSettings.CurrencyId))); 
           }
       }
   //go through all shipping methods and remove any that don't have rates 
   //for packages. 
     for(int x = 0; x < basketData.ShippingRates.Count; x++)
       { bool removed = false; 
       if(rateCount[basketData.ShippingRates[x].ProviderService] 
         < shippingPackages.Count)
         { basketData.ShippingRates.RemoveAt(x); x--; 
   //need to decrement loop counter so we don't skip any as we loop through 
           removed = true; 
          } 
          if (!removed) 
            { if (basketData.ShippingRates[x].CurrencyId 
              != RequestInformation.CommerceSettings.CurrencyId) 
              {
   //if shipping rate currency is not current currency, convert it 
                basketData.ShippingRates[x].ShippingFee 
        = exchangeRate.ConvertPrice(basketData.ShippingRates[x].ShippingFee);
              }
   //is this the selected shippingmethod for basket? If so, set shipping cost
   //on basket 
     if (shippingMethod != null 
       && shippingMethod.ProviderService 
       == basketData.ShippingRates[x].ProviderService) 
       { basketData.TotalShippingCost 
         += basketData.ShippingRates[x].ShippingFee; 
       } 
     } 
   } 
   if (basketData.ShippingRates.Count == 0 && hasTangibles) 
     { basketData.ValidationResults.AddResult(new ValidationResult 
       ("No shipping rates are available for the supplied item.", this, 
         "", "", null)); } eventArgs.IsCancelled = true; 
     } 

8. When shipping is calculated for the basket, the above function runs first. Setting the IsCancelled property to true on eventArgs instructs Ektron to stop further execution of the shipping calculations. This, in effect, overrides the shipping functionality.
9. Build the project, and copy the assembly into the Ektron site's bin directory.

Registering the Event with the System

After you create the event assembly and place it inside the bin directory, you need to register the event. Use the objectfactory.config file to register custom events within Ektron. To do that:

1. Open the siteroot/objectfactory.config file.
2. Find the objectStrategies section of the file.
3. Within that section, locate or add this key: name="ShippingCalculator".
4. Add a reference to the class created earlier in the <strategies> key, as shown below.

   <objectStrategies>
     <add name=ShippingCalculator">
   <strategies>
     <add name="CustomShippingCalculator" 
     type="Ektron.Cms.Extensibility.Commerce.Samples.CustomShippingCalculator,
     Commerce.CustomShippingCalculator"/>
   </strategies>
   </add>
   </objectStrategies>