User and Developer Guide

This is version of the KonaKart User Guide

This User Guide can be downloaded in PDF format from

Legal Notices

(c) 2006-2018 DS Data Systems UK Ltd, All rights reserved.

DS Data Systems and KonaKart and their respective logos, are trademarks of DS Data Systems UK Ltd. All rights reserved.

The information in this document is free; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

Table of Contents

1. Introduction
What is KonaKart ?
Who is the software intended for?
Solution Provider / System Integrator / OEM
Important changes from v.
2. KonaKart Information
Community, Business and Enterprise Editions
Community Edition
Enterprise Edition
Business Edition
Support and Professional Services
Is KonaKart Open Source?
Is the full source code available?
3. KonaKart Features
General Functionality
JSR 286 Liferay Portlet
ERP Integration
Content Management System Integration
Basic Content Management
Customer Functionality
Customer Groups - Wholesale/Retail
B2B Features
Call Center Functionality
Social Login
One page checkout
Checkout without registration
Digital Downloads
Bookable Products
Product Stock Reservation
Product Bundles
Gift Certificates
Product Recommendations
Reward Points
Indexed Search
Suggested Search
Product Tags and Tag Groups (Faceted Search)
Marketing - Customer Tags and Expressions
Advanced Search Engine Optimization (SEO)
Payment Functionality
Recurring Billing
Shipping Functionality
Tax Functionality
Order management
PDF Invoices
Java Message Queue Integration
Customer Events
Exchange Rate Updates
KonaKart and KonaKartAdmin Tiles
Facebook Messenger Bot.
Export for Google Merchant Center / Google Retail
4. Architecture
Software Architecture
Deployment Architecture
5. Installation
Before You Begin
Platforms Supported
Install Java
Create a Database
Upgrading the Database between releases of KonaKart
Install KonaKart
Installing KonaKart on Windows
Installing KonaKart on Unix/Linux
Silent Mode Installations
Graphical Installation Wizard
Manual Installation
Starting Up and Shutting Down KonaKart
Starting up KonaKart
Shutting down KonaKart
Setting up KonaKart as a Windows Service
KonaKart as a Service - option 1
KonaKart as a Service - option 2
Default Admin App Credentials
Admin Password Validation
Super User
Installation Notes for Databases
Defining the Database Parameters
Encrypting the Database Parameters
Defining the Database Parameters - Using JNDI
Notes for DB2 and Oracle
Notes for Postgresql
Notes for MySQL
Notes for Microsoft SQL Server
6. Installation of KonaKart Business and Enterprise Editions
Before You Begin
Create a Database
Installing Enterprise Extensions
Installing KonaKart Enterprise Extensions on Windows
Installing KonaKart Enterprise Extensions on Unix/Linux
Silent Mode Installations
Graphical Installation Wizard
Business Edition Installation
Installing KonaKart Business Edition on Windows
Installing KonaKart Business Edition on Unix/Linux
Silent Mode Installation of the Business Edition
Manual Installation of the Enterprise Extensions
Users created by the Enterprise Extensions Installation
Single Store Mode
Multi-Store Multiple DB Mode
Multi-Store Single DB Mode with Shared Customers
Multi-Store Single DB Mode NON-Shared Customers
7. Installation of KonaKart on other Application Servers
General Notes on Installing KonaKart on Application Servers
Edit Config Files - Admin Application Functionality
Email Properties File
Reporting Port Numbers and Report Location
Configuring Parameters for Images
Setting the Optimum Memory Values
Installing KonaKart on BEA's WebLogic Application Server
Installing KonaKart on JBoss or Wildfly
Installing KonaKart on IBM's WebSphere Application Server
Installing KonaKart on IBM's WebSphere Application Server Community Edition
Installing KonaKart on GlassFish
Installing KonaKart on JOnAS with Tomcat
Installing KonaKart on JOnAS with Jetty
8. Upgrading
Recommended Upgrade Steps
Installation of the new Version
Database Upgrade
Test new Installation against Upgraded Database
Re-build Custom Code
Upgrade the Struts Storefront
Assess Changes to WebApp Configuration files
Assess Changes to Tomcat Configuration files
KonaKart Directory Structure Changes
KonaKart Message Changes
Documentation and javadoc Changes
Admin App Changes
9. Administration and Configuration
KonaKart Administration Application
Main Features
Reporting - BIRT Viewer Security
Role-based Security and Configuration
Initial Locked-Down Configuration
File-based Configuration
Launching the Admin App
Configuring KonaKart for HTTPS / SSL
Editing the KonaKart Configuration Files
Changing the Editable File List in the Admin App
KonaKart Properties Files
Configuration of Messages
Switching to Database Messages
KKMessages Utility
Log4j2 Logging
Internationalization of KonaKart
Translating the KonaKart Application
Translating the country names
Translating the KonaKart Admin Application
Changing the Logo on the KonaKart Admin Application
Changing the Date Format in the KonaKart Application
Formatting of Addresses
Email Configuration
Modifying the Email Templates
Receiving Notification Emails of Exceptions
Adding Custom Business Objects for use in Velocity Templates
Using an External Email Delivery Service
Using a email barcode generator
Using Google reCAPTCHA Service
Search Engine Optimization (SEO) Features
Sitemap Generation
Adding Custom Functionality to the Admin App
Adding Panels
Adding Custom Configuration Panel
Adding Buttons
Adding A Custom Application - Insert Product Wizard
Searching with wildcards
Case In-Sensitive Searching
Making something happen when a product needs to be reordered
Making something happen when the state of an order changes
PDF Invoices
Activating a Promotion
Testing a Promotion
Applying Promotions to Products
Displaying Coupon Entry Fields in your Store
Configuring Digital Downloads
Configuring Bookable Products
Import/Export of KonaKart Data
Export of Orders using exportOrder
Import/Export of KonaKart Data using XML_IO
Custom Imports Using the Importer Panel
Reset Database Tool
Multiple Prices for Products
Future Product Prices
Sale Price
Variant Pricing
Tier Pricing
Dynamic product prices
Tax Configuration
Tax algorithm and numeric precision
Validation of Order Totals
Multiple Quantities for Products
Default Sort Order for Products
Bundle Configuration
Product Options
Product Tags
Managing Product Reviews
Using CLOBs for Product Descriptions
Credit Card Refunds
Saving and Editing of Credit Card details
Configuration of Admin Application
Configuration of Store Front Application
Edit Order Number and Custom Fields
Shippers and Shipments
Wish Lists
Gift Registries
Gift Certificates
Enable Gift Certificates
Creating a Gift Certificate
Creating a new Admin App User
Creating New Roles
Default Customer Configuration
Making Customers Invisible
Customer Groups
Forgotten Password
Set User Password
Authentication with Username or Telephone
Double Opt-In for Registration and Newsletter
Customer Registration
Newsletter Subscription
Custom Credential Checking
Custom Credential Checking - LDAP
Multi-Store Configuration and Administration
Configuring KonaKart to function in Multi-Store Mode
Multi-Store Configuration
Product Synchronization
Scheduling in KonaKart
Configuring Quartz to execute KonaKart jobs
Customizing the KonaKart jobs
Deletion of Expired Data
Data Integrity
Executing the Data Integrity Checker from a Script
Configuring KonaKart to use Analytics Tools
Configuring KonaKart to use Google Analytics
Configuring KonaKart to use Other Analytics Tools
Setting up RMI Services
Step by Step Guide to setting Up KonaKart to use RMI
Integrating a Java Message Queue
Setting Up The Java Message Queue
Monitoring The Java Message Queue
Transactional Message Processing
kkCmd - Command line tool
Changing the standard password encryption algorithm
10. KonaKart Content
Content Overview
Text Content
Banner Content
Content Expressions
Content Caching
Content Access
11. Marketing - Customer Tags and Expressions
What are Customer Tags?
What are Expressions?
Tutorial for creating an expression using the standard customer tags
How to set Customer Tag Values in Java code
Mailing Lists
12. Using Artificial Intelligence to derive Product Recommendations
Steps Required
Steps Required - Zucchetti AI service
Steps Required - Internal KonaKart service
Custom Fields
13. Reward Points
Configuration of Reward Points
Technical Details
14. Solr Search Engine
Configuring KonaKart to use Solr
Customization of Solr
Forcing Solr Usage
Suggested Search
Suggested Search using Solr terms
Suggested Spelling
Catalog Support for Suggested Search and Spelling
Faceted Searching
Prices, Manufacturers and Categories
Custom Faceted Search
Multi-Valued Facets
15. Payment, Shipping and OrderTotal Modules
Module Types
Payment Modules
Shipping Modules
Order Total Modules
Other Modules
How to Create a Payment Module
Study the "KonaPay" APIs
Choose which Interface Type you want for your users
Sign up for a Test Account with "KonaPay"
Determine which of the existing payment modules is the closest match
Copy the files of the closest match as the starting point
Define the configuration parameters
Understanding the Configuration Options
Add the "KonaPay" gateway to the Admin App
Implement the PaymentInterface
NameValue[] Parameters
Implement the Action code
Save IPN details
Save the gateway response to a file
Send payment confirmation email
Struts mapping
Build, Deploy and Test
How to Create a Promotion Module
Determine which of the existing Promotion modules is the closest match
Copy the files of the closest match as the starting point
Define the configuration parameters
Add the new promotion module to the Admin App
Build, Deploy and Test
16. Recurring Billing
Payment Schedule
Using a Payment Gateway that supports Recurring Billing
Insert a subscription
Update a subscription
Read the status of a subscription
Manual Subscription Management
Managing Recurring Billing through KonaKart
17. Multi-Vendor Functionality
Setting up a Main Store
Setting up a Vendor Store
Customer View of the Order
Vendor View of the Order
Administrator view of the Order
Order State Change
Order Payment
18. Product Stock Reservation
API Calls
Storefront Application
Order Integration Manager
Reservations for Bookable Products
Batch Removal of Expired Stock Records
19. Order Management
Order Creation
Order Lifecycle Management
Order Modification
API Calls for Archived Orders
20. KonaKart B2B features
Customer Hierarchy
Catalog / Contract Prices
Customer Tags
B2B Customer Administrator
Company Administrator Security
21. KonaKart ERP Integration
File Transport
XML Message Structure
Messages from ERP to KonaKart
Update Product
Update Product Prices
Update Order
Export Invoice
Export Customer to KonaKart
Match Customer to KonaKart
Payment Capture
Messages from KonaKart to ERP
Export Customer to ERP
Match Customer to ERP
Order Export to ERP
Update Object
Installation and Configuration
Incoming Message Processor
Apache ActiveMQ
ERP Integration - Configuration Parameters
ERP Integration - OrderIntegrationMgr
ERP Integration - Logging
22. Custom Validation
Custom Validation for the Store-Front
Configuring validation on data entered through the UI
Custom Validation for the Admin Application file
Fields Supported by Custom Validation
CustomValidaton Using a Custom Engine
23. Custom Product Attributes and Miscellaneous Items
Using Custom Product Attributes
What types of Custom Attributes can be added to a product?
Creating a Custom Attribute Definition and adding it to a Template
Entering Template based Custom Attribute data for a Product
Displaying the custom data in the storefront Application
Miscellaneous Items
Product Description Custom Fields
24. Programming Guide
Using the Java APIs
Using the SOAP Web Service APIs
Using the JAX Web Service Storefront APIs
Enable the JAX Web Storefront Services
Using the JAX Web Service Admin APIs
Enable the JAX Web Admin Services
Step-by-step guide to using the JAXWS SOAP APIs:
Using the RMI APIs
Using the JSON APIs
Using the JSON APIs to build a JavaScript client
HTML character escaping
Running Your Own SQL
Database Layer Changes from v7.2.0.0
Table and Column Name Changes
KonaKart/Torque Programming Changes
Customizable Source Code
Source Code Location
Building the Customizable Source
Developing the storefront in Eclipse
Developing the Product Creation Wizard in Eclipse
Customization of the KonaKart Engines
KonaKart Customization Framework
Adding a New API call
Modifying an Existing API call
Enabling Engine Customizations
Building with Maven
Pluggable Managers
25. Reporting
KonaKart Reporting from the Admin App
Modifying the Reports
Adding New Reports
Defining a Chart to appear on the Status Page of the Admin App
Reports Configuration
Defining the Set of Reports Shown in the Admin App
Accessing the Database in the Reports
Customer Events
Creating Customer Events
26. Liferay Portal Integration
Creation of portlet WAR files
27. Social Login
Google Sign-In
PayPal Login
All Modules
28. TaxCloud Integration
How does the integration work?
Points to Note
29. Thomson Reuters Integration
How does the integration work?
Auditing of Order Transactions
Points to Note
30. PunchOut
Customization of the PunchOut message
Application PunchOut Code