home Product Docs Support About us Demos Downloads Live Sites Forum

Configuration FAQ

How do I change the Date Format in the KonaKart application?
How does Internationalization work in KonaKart?
How do I translate the KonaKart Admin App?
How do I add a Payment Module ?
How do I add a Shipping Module ?
How do I configure Free Shipping ?
How do I configure the Zones Shipping Module ?
How do I add an Order Total Module ?
How do I modify the eMail templates ?
How can I make something happen when a product needs to be reordered ?
How can I make something happen when an order is received or the state of an order is changed ?
How can I configure KonaKart to use HTTPS / SSL ?
How do I edit the KonaKart configuration files ?
How can I change the editable file list in the admin app ?
How can I activate a promotion ?
How can I display the coupon entry field in the UI ?
How can I enable / disable One Page Checkout ?
How can I configure Search Engine Optimization (SEO) features ?
How can I configure Digital Downloads ?
How can I create a new Admin App user ?
How can I create new Roles ?
How does auditing work in KonaKart ?
How do I set-up Email in KonaKart ?
How can I change a skin for the KonaKart application ?
How can I use Customer Groups ?
How can I store and display multiple prices for a product ?
How can I set the default sort order for products retrieved using the client API ?
How can I implement Single Sign On ?
How can I connect to an LDAP directory ?
How can I implement my own credential encryption algorithm ?
How do I configure bundle products ?
What are product tags and how can I use them ?
How can I refund a credit card ?
How can I add custom functionality to the admin app ?
What is a default customer ?

How do I change the Date Format in the KonaKart application ?

This has to be changed in two places:

In WEB-INF/validation.xml it must be set in this section towards the top of the file. This is used to validate any dates that are input through the UI.

                   <constant>
                             <constant-name>DATE_PATTERN</constant-name>
                             <constant-value>dd/MM/yyyy</constant-value>
                   </constant>

In the WEB-INF/classes/Messages.properties file it must be changed under the date.format key.
i.e.  date.format=dd/MM/yyyy

How does Internationalization work in KonaKart ?

KonaKart is completely multilingual both at the database level and at the UI level.

The data within the database such as product descriptions and category names etc. may exist in different languages. The database contains a languages table that contains information about each of the supported languages. When a new product is added to the database through the administration tool, it is possible to enter a description in multiple languages.

There is also a message catalog for each language. These can be found in the WEB-INF/classes directory of the application server. The default message catalog is called Messages.properties. This is defined as the default catalog in the struts-config.xml file in the WEB-INF directory using the following syntax:

<message-resources parameter="Messages" null="false"/>

In order to change a language, the following steps must be taken (An example can be seen in the class SetLocaleAction.java):

Struts must be informed of the new language by calling the method setLocale() from within the Struts action. If Struts is passed a locale of en_GB, it looks for a message catalog called Messages_en_GB.properties. If it can’t find that, it looks for Messages_en.properties. If it cannot find that, it defaults to Messages.properties which was set as the default in the struts-config.xml file.

The KonaKart client engine must be informed of the new locale by calling the setLocale() method on it. This call configures the engine so that all subsequent calls will retrieve data from the KonaKart database in the appropriate language.

How do I translate the KonaKart Admin App ?

The KonaKart Administration Application can be completely translated simply by creating two message catalogues for your chosen language.

Whichever language you use this is also a handy way to re-label  the "custom" fields that appear on many of the important objects within KonaKart to reflect the meaning in your particular system.

Your new message catalogs must be called:

AdminMessages_<language-code>.properties                       // contains all the strings except the help page text
AdminHelpMessages_<language-code>.properties                 // contains just the text on the help pages

For <language_code> you should use the 2-character language code that you have set up in the languages section of the admin application.   For example, you might have "fr" for French, "zh" for Chinese, "de" for German, "ja" for Japanese etc.

You should place your completed message catalogs in this directory:

webapps/konakartadmin/WEB-INF/classes

Since there are quite a large number of messages to translate, you might choose to do this over a period of time.   A recommended approach is to start your new message catalogs with copies of the default (English) catalogs (called AdminMessages.properties and AdminHelpMessages.properties) then translate the messages that are most important to you first and complete the rest as time permits.

There are also a number of strings in the database that need to be translated.   These are used by the Admin App to label some of the configuration parameters and provide helpful comments.   If you issue a:
                             "SELECT configuration_title, configuration_description FROM configuration;"
SQL query, you will see the values that you can update.

Also, you may wish to include translations for the velocity templates (eg. EmailNewPassword, OrderDetails, OrderInvoice, OrderPackingList and OrderStatusChange).

Once you have completed the message catalogs, velocity templates and a sql update script for your language, please contribute these to the KonaKart Community by posting them to the contributions section of our forum for the benefit of other users.

how do i add a payment module ?

Payment modules shipped with KonaKart are installed and configured through the Administration Application.

If you wish to add a new payment gateway and are not a programmer, please contact us. If you are a Java programmer, it is possible for you to add your own module by following the examples we provide in the package. There is a detailed guide in the Customization FAQ .

The best approach is to learn by example. We supply all of our supported modules in source code format. They can be found under the examples directory.  All payment modules should extend com.konakart.bl.modules.payment.BasePaymentModule and implement com.konakart.bl.modules.payment.PaymentInterface.  

In order to determine which Payment Modules are installed, the KonaKart engine reads the "MODULE_PAYMENT_INSTALLED" configuration property which should contain a semicolon delimited list of payment modules installed. In the case of a current osCommerce database, the property will contain a list of PHP modules (i.e. cc.php;cod.php). KonaKart ignores the extension. Let's say that you introduce a new module called "MyModule". In this case, KonaKart will look for a class called MyModule.class in the package "com.konakart.bl.modules.payment.mymodule". Note that the package name is always the class name converted to lower case.

The interface that the payment module implements is relatively simple . The main method is called getPaymentDetails(Order order, PaymentInfo info) . The module is passed in the Order object and a PaymentInfo object . The PaymentInfo object contains details on zone information so that the module can be disabled if the delivery address isn't within a zone. It also contains details used mainly for IPN (Instant Payment Notification) such as the host and port details for the return notification and a secret key that can be used to validate the return notification. The order object contains all details about the order, some of which, may be required. In the case of the PayPal example, the final piece of the puzzle is contained in a Struts action class called com.konakart.actions.ipn.PayPalAction. This action is called by PayPal in order to return the status of the payment. When received, the action class may change the state of the order as well as updating the inventory.

How do I add a shipping module ?

Shipping modules shipped with KonaKart are installed and configured through the Administration Application.

If you wish to add a new shipping module and are not a programmer, please contact us. If you are a Java programmer, it is possible for you to add your own module by following the examples we provide in the package.
The best approach is to learn by example. We supply a few examples in source code format:

• com.konakart.bl.modules.shipping.flat.Flat.java - Flat rate
• com.konakart.bl.modules.shipping.item.Item.java - Rate per item
• com.konakart.bl.modules.shipping.table.Table.java - Rate based on weight or order amount
• com.konakart.bl.modules.shipping.zones.Zones.java - Rate based on weight and zone

In order to determine which Shipping Modules are installed, the KonaKart engine reads the "MODULE_SHIPPING_INSTALLED" configuration property which should contain a semicolon delimited list of shipping modules installed. In the case of a current osCommerce database, the property will contain a list of PHP modules (i.e. flat.php;item.php;table.php). KonaKart ignores the extension. Let's say that you introduce a new module called "MyModule". In this case, KonaKart will look for a class called MyModule.class in the package "com.konakart.bl.modules.shipping.mymodule". Note that the package name is always the class name converted to lower case.

The interface that the shipping module implements is relatively simple . The main method is called getQuote(Order order, ShippingInfo info) . The module is passed in the Order object and a ShippingInfo object . The ShippingInfo object contains details on zone information so that the module can be disabled if the delivery address isn't within a zone. It also contains information about the number of packages and their weight etc so that the shipping cost can be calculated . The order object contains all details about the order, some of which, may be required.

An alternative approach is to contact us with details of the Shipping Module that you would like to integrate with KonaKart so that we can create the module for you.

How do I configure free shipping ?

From version 2.2.3.0, free shipping can be set on a product by product basis. To set free shipping for a product, you must navigate to the Details tab of the Edit Product panel in the Admin App. There you must change the product type to "Physical Product - Free Shipping".  In order for this mechanism to function correctly, you must install the Shipping Module called "FreeProduct". This module will return a shipping quote of zero if it detects that the physical products within the order all have free shipping.

Free shipping for all products can be configured in the Administration Application in the section Modules>>Order Totals by selecting the Shipping Module.

You may allow free shipping by setting the Allow Free Shipping value to "true" . In order to not show the  shipping cost of zero on the order you must set Display Shipping to "false". Free shipping can be made conditional for orders over a certain amount or just for a combination of national / international orders.

The text that you display on the screen in the area that you would normally select a shipping method, is defined in WEB-INF\classes\com\konakart\bl\modules\shipping\Shipping_xx.properties. This can be set to e.g. "Free shipping for orders over $50", "Free Shipping", "No Shipping" etc.

Note that in order to completely remove shipping from the checkout process, you will need to make modifications to the checkout process (i.e. JSPs, Struts Actions and GWT code in the case of one page checkout).

how do i configure the Zones Shipping Module ?

The Zones Shipping Module allows you implement shipping rates based on the weight of the shipment, for different countries. The module can be installed and configured through the Admin App.  The number of different shipping zones has to be decided before running the Admin App. It is set in the properties file:

    /webapps/konakartadmin/WEB-INF/classes/com/konakartadmin/modules/shipping/zones/Zones.properties

by editing the section:

    # Set this to the number of zones you require.
    MODULE_SHIPPING_ZONES_NUMBER_OF_ZONES=1

The Admin App uses the above information to create a number of entry fields called "Zone 1 Countries", "

how do i add an order total module ?

Order Total modules shipped with KonaKart are installed and configured through the Administration Application.

If you wish to add a new order total module and are not a programmer, please contact us. If you are a Java programmer, it is possible for you to add your own module by following the examples we provide in the package.

The best approach is to learn by example. We supply a few examples in source code format:

• com.konakart.bl.modules.ordertotal.shipping.Shipping.java 
• com.konakart.bl.modules.ordertotal.subtotal.Subtotal.java
• com.konakart.bl.modules.ordertotal.tax.Tax.java
• com.konakart.bl.modules.ordertotal.total.Total.java

In order to determine which Order Total Modules are installed, the KonaKart engine reads the "MODULE_ORDER_TOTAL_INSTALLED" configuration property which should contain a semicolon delimited list of order total modules installed. In the case of a current osCommerce database, the property will contain a list of PHP modules (i.e. ot_subtotal.php;ot_tax.php;ot_shipping.php). KonaKart ignores the extension. Let's say that you introduce a new module called "MyModule". In this case, KonaKart will look for a class called MyModule.class in the package "com.konakart.bl.modules.ordertotal.mymodule". Note that the package name is always the class name converted to lower case.

The interface that the order total module implements is relatively simple . The main method is called getOrderTotal(Order order, boolean dispPriceWithTax, Locale locale)  . The module is passed in the Order object which contains all details about the order, some of which, may be required.

An alternative approach is to contact us with details of the Order Total Module that you would like to integrate with KonaKart so that we can create the module for you.

how do i modify the email templates ?

If configured to do so, KonaKart will send out emails after registration, to confirm orders and to distribute new passwords. The emails are generated using Velocity templates which can be found in the /WEB-INF/classes directory of both the App and the Admin App. The current templates are all files following the pattern *.vm. Note that the file name must end with an underscore followed by a two letter country code (i.e. OrderConfirmation_en.vm).

When the state of an order is changed through the Admin App, an eMail may be sent to the customer based on the template called OrderStatusChange_xx.vm where xx is the two letter country code. A different template may be defined for each order state where the naming convention is OrderStatusChange_stateId_xx.vm. For example if the order changes state from state 1 to state 2, it will use the template called OrderStatusChange_2_xx.vm if it exists. If it doesn't exist,  KonaKart will use the default OrderStatusChange_xx.vm template.

how can i make something happen when a product needs to be reordered ?

When the number of products in stock hits the reorder level defined by the configuration property STOCK_REORDER_LEVEL, KonaKart instantiates a class defined by the property STOCK_REORDER_CLASS. If this property isn't set, the class that is instantiated is com.konakart.bl.ReorderMgr. If you write a custom class it must implement the interface com.konakart.bl.ReorderMgrInterface which contains only one method:

    public void reorder(int productId, int currentQuantity) throws Exception;

After the class is instantiated, the reorder method is called and information regarding the productId and current product quantity is passed to the method so that it can use this information to trigger an event. This mechanism is a useful generic way  to interface KonaKart to external systems since the custom class could write data to a database, call a web service or write data to a file etc.

If the configuration variable STOCK_REORDER_EMAIL is set, then KonaKart will also send an eMail alert .

All of the configuration variables can be edited in the Configuration>>Stock and Orders section of the Admin App.

how can i make something happen when an order is received or the state of an order is changed ?

When an order is saved in the database or the status of an order is changed (i.e. through the callback of a payment gateway), KonaKart instantiates a class defined by the property ORDER_INTEGRATION_CLASS. If this property isn't set, the class that is instantiated is com.konakart.bl.OrderIntegrationMgr. If you write a custom class it must implement the interface com.konakart.bl.OrderIntegrationMgrInterface which contains two methods:

    public void saveOrder(OrderIf order);
    public void changeOrderStatus(int orderId, int currentStatus, int newStatus); 

When an order is saved, the class is instantiated and the saveOrder() method is called with the order passed in as a parameter. The changeOrderStatus() method is called when the status is changed. The parameters supplied to the method are the orderId, the current status and the new status.

The state of an order may be changed manually through the Admin App. In this case KonaKart instantiates a class defined by the property ADMIN_ORDER_INTEGRATION_CLASS. If this property isn't set, the class that is instantiated is com.konakartadmin.bl.AdminOrderIntegrationMgr. If you write a custom class it must implement the interface com.konakartadmin.bl.AdminOrderIntegrationMgrInterface which contains the method:

    public void changeOrderStatus(int orderId, int currentStatus, int newStatus);

This mechanism is a useful generic way  to interface KonaKart to external systems since the custom classes could write data to a database, call a web service or write data to a file etc.

The ORDER_INTEGRATION_CLASS and ADMIN_ORDER_INTEGRATION_CLASS properties can be edited in the Configuration>>Stock and Orders section of the Admin App.

how can I configure KonaKart to use HTTPS / SSL ?

SSL can be enabled and configured in the Configuration>>HTTP/HTTPS section of the Admin App. When SSL is enabled and the port numbers are correctly defined, KonaKart will automatically switch between HTTP and HTTPS depending on whether the customer is logged in or not. Whenever the customer is logged in, a session id is passed back and forth, so the protocol is set to HTTPS. Whenever the customer isn't logged in, the protocol is set to HTTP.

How do i edit the konakart configuration files ?

The configuration files can be found underneath your KonaKart installation directory at:

webapps\konakart\WEB-INF\classes\konakart.properties
and
webapps\konakartadmin\WEB-INF\classes\konakartadmin.properties

They can be edited using any text editor. Alternatively, they can be edited from the Configuration>>Configuration Files section of the Admin Tool. Note that most changes will not take effect until KonaKart is restarted.

How can I change the editable file list in the admin app ?

In the "Configuration Files" section of the Admin Tool a list of files is shown that can be edited.   By default these are the main KonaKart properties and logging files.

You can add any files you like to that list so long as they are accessible to the KonaKart server - wherever that's running in your configuration.

There's a simple XML file (called konakart_config_files.xml) where the files that are shown are defined.  It looks like this:

---

<?xml version="1.0" encoding="ISO-8859-1"?>

<konakart-config-files>
  <file>
    <displayName>KonaKart Properties File</displayName>
    <fileName>../webapps/konakart/WEB-INF/classes/konakart.properties</fileName>
  </file>

  <file>
    <displayName>KonaKart Admin Properties File</displayName>
    <fileName>../webapps/konakartadmin/WEB-INF/classes/konakartadmin.properties</fileName>
  </file>

  <file>
    <displayName>KonaKart Logging Properties File</displayName>
    <fileName>../webapps/konakart/WEB-INF/classes/konakart-logging.properties</fileName>
  </file>

  <file>
    <displayName>KonaKart Admin Logging Properties File</displayName>
    <fileName>../webapps/konakartadmin/WEB-INF/classes/konakart-logging.properties</fileName>
  </file>
</konakart-config-files>

---

You'll find this file under webapps/konakartadmin/WEB-INF/classes.  In the default installation on Windows that is: C:\Program Files\KonaKart\webapps\konakartadmin\WEB-INF\classes\konakart_config_files.xml.

You'll see that you define a path to the file and a "display name" which is the name you see in the list in the Admin Tool.

A point to note if no files are listed:

Depending on your configuration (eg. if you are not using the default tomcat container supplied in the download kit) you may find that the default definitions of the relative paths in the supplied konakart_config_files.xml will not work - you will have to amend these to suit your environment.

How can I activate a promotion ?

You must follow these steps :

• Ensure that the promotion module that you want to use, is installed. All promotion modules can be found in the Modules>>Order Total section of the Admin App.
• Create a new promotion in the Products>>Promotions section of the Admin App. The online help provides extra information and most attributes have floatover text with a more detailed description. When creating the promotion, you must select which promotion module to use from the Promotion Type drop list. The configuration data required, depends on the  promotion type. Once the promotion has been saved, it is immediately active as long as the Active check box was ticked and the current date lies between the promotion start and end dates.
• Rules may be added to the promotion by clicking on the Rules button.  When a rule is selected, a pop-up window opens where the rule can be configured (e.g. Activate promotion for products belonging to a certain category). When the pop-up window is closed, the rule is saved and the Promotion Rules window shows a summary of the rules that have been set.
• If the promotion needs to be activated through a coupon, you can create a coupon by clicking the Coupons button. The coupon must be given a name and a code (the text entered by the customer to activate the coupon). The coupon may also be programmed so that it can only be used a defined number of times. The final step is to enable the coupon entry field in the UI during checkout. To do this you must set the "Display Coupon Entry Field" to true in the Configuration>>My Store section of the Admin App.

How can I display the coupon entry field in the UI ?

You must set the "Display Coupon Entry Field" to true in the Configuration>>My Store section of the Admin App.

How can I enable / disable One Page Checkout ?

In the Configuration>>My Store section of the Admin App there are two configuration variables that control "One Page Checkout".  When the Enable variable is set to true, the application automatically uses One Page Checkout. When set to false, the original shipping, payment and checkout screens are used.

There is another variable for enabling checkout without registration. If One Page Checkout is enabled and this variable is also set to true, then a customer doesn't have to complete a separate registration process before checking out. He can just enter the shipping address during the checkout process.

How can i configure search engine optimization (SEO) features ?

The SEO features can be configured through the message catalogs with the attributes beginning with "seo." (e.g seo.default.meta.description or seo.meta.keywords.template). The catalogs contain multi-lingual templates in order to write product information (name, model, manufacturer, category) into:

• The URL
• The window title
• The meta description
• The meta keywords

The templates may contain the following placeholders : $category, $manufacturer, $name, $model which are substituted by real data depending on what is being viewed at the time. Each attribute within the message catalog has a description which explains how it is used.
 

How can i configure digital downloads ?

KonaKart supports digital downloads which can be downloaded from the KonaKart on line store, as soon as payment is received for the products.  A new section appears on the customer's Account page, with a link for each downloadable product in the order.

To configure KonaKart for selling digital downloads, the following steps must be taken :

1. Using the Admin App, ensure that the "Product Type" attribute of all downloadable products is set to "Digital Download". You must also enter the "File Path" and the "Content Type" .
1. File Path : The File Path will be concatenated to the "Base Path" defined by a configuration variable. For example, if the Base Path is set to "C:/images/" and the File Path is set to "cities/london.jpg", then the downloaded file will be C:/images/cities/london.jpg . If the Base Path is left empty (default value) then the File Path must be set to the full name, i.e. C:/images/cities/london.jpg .  Note that if the Base Path ends with a "/" then the file path should not start with a "/" because the two strings are concatenated to create the full path for the digital product.
2. Content Type :  The Content Type describes the content of the file. Examples are "image/jpeg" or "application/pdf". A list of Content Types may be found here.
2. Using the Admin App in the section Configuration>>Configure Digital Downloads you may configure some parameters regarding the digital download functionality. These are:
1. Base Path : The base path of the downloadable files as explained above.
2. Max Number of Downloads : The maximum number of times that the file can be downloaded. -1 for an unlimited number of downloads.
3. Number of days link is valid : The number of days that the download link is valid for. -1 for an unlimited number of days.
4. Delete record on expiration : When the download link expires, the database table record defining the link will be automatically deleted. Setting this to true avoids having to do manual cleanup of the database.
5. Download as an attachment : When set to true, the digital download is downloaded as an attached file that can be saved on disk. When set to false, the browser attempts to display or run the file.
3. The digital downloads shipping module must be installed in the Modules>>Shipping section of the Admin App. This shipping module activates automatically when the whole of the order consists of digital downloads and displays a $0 shipping cost. Any other shipping module should not return a shipping quote in the case of a digital download order.

How can i create a new admin app user ?

New Admin App users can be created and configured using the Admin App, if you are logged in as a user with the required privileges.

Each KonaKart user can be assigned one or more roles in order to define the functionality available to that user.  The first step is to create a new user in the Customers>>Customers section of the Admin App. The user type must be set to "Admin User".

Once the user has been created, roles may be assigned in the Customers>>Assign Roles section of the Admin App. The role assignment becomes active the next time the user logs in.

How can i create new roles ?

The default KonaKart database already contains a number of roles. New roles may be created (and existing roles may be edited) in the Customers>>Maintain Roles section of the Admin App.  

Each role is mapped to a number of panels with a set of privileges. Each role to panel association may have a combination of read / insert / edit / delete privileges.  

API call security may also be enabled in the Configuration>>Security and Auditing section of the Admin App. When enabled, this allows you to map roles to API calls and is useful for enforcing security through the SOAP Web Service interface of the Admin App.

Precise instructions on how to create new roles, can be found in the on-line help.

 

How does auditing work in konakart ?

Auditing can be enabled on the Admin App API in order to keep track of when API calls are made and by whom. All audit data is written to the KonaKart database and can be viewed in the Audit Data>>Audit Data section of the Admin App.

Auditing can be configured in the Configuration>>Configure Auditing section of the Admin App. It can be configured independently for Reads / Edits / Inserts and Deletes. The level may be set to "summary" or "detailed" :

• Summary :  The name of the API call, the type of Action (read , write etc.) , the id of the object being edited, inserted etc. (where applicable) and the time stamp are saved.
• Detailed :  Where possible, the objects being deleted, edited etc. are also saved in a serialized form . Note that enabling detailed auditing can have a detrimental affect on performance and may save a large amount of data.

How DO I SET UP EMAIL in konakart ?

In most cases email can be configured completely within the KonaKart Admin App in the  Configuration>>Email Optionssection (see image below).   Here you can set up your SMTP server host, your SMTP username, SMTP password and whether or not the SMTP server requires authentication:



As with all fields in the Admin App, use the floatover text on each label to find out more about each configuration option.

For more advanced users there is a konakart_mail.properties file in which you can define additional mail properties.  (In fact, you can rename this file if you wish and change its location - so long as you define the filename holding these values in the Admin App - see "KonaKart mail properties filename in the image above)).   A common example of the use of this konakart_mail.properties file is for setting up access to the Google Mail SMTPS server (this uses a non-standard port (465), requires authentication and uses encryption.   An example of the parameters to set to use the Google SMTPS mail gateway is provided in the default konakart_mail.properties file.
 

How can I change a skin for the KonaKart application ?

Version 2.2.1.0 is the first version that includes JSPs which can support multiple skins and so this FAQ refers to versions from 2.2.1.0 onwards.

The style sheets for the KonaKart application are in the konakart/styles directory. stylesheet.css is used by the "old style" JSPs which are in the WEB-INF/jsp_osc directory. Note that if you want to continue using these JSPs, then you must copy them to the WEB-INF/jsp directory after deleting the contents of this directory.

The "new style" JSPs are in the WEB-INF/jsp directory and they use the stylesheet called skin_style.css . This style sheet contains information that is common to all skins that we ship. The unique information for each skin is in a separate style sheet called  tile1.css, tile2.css etc. which is imported by skin_style.css. In order to change the skin, you must edit skin_style.css to import a different skin. For example you could change :