Table of Contents Previous Next Index

CHAPTER 1 Introduction : Overview

Overview

The SDK provides:

A framework of Ant targets that enable you to install the Sterling Multi-Channel Selling Suite and manage your customizations to the system. Customizations can be as simple as setting the connection information for the Knowledgebase database server or as complex as changing the look‑and‑feel of the end-user pages or adding new functionality to the Sterling Multi-Channel Selling Suite.

A comprehensive suite of documentation that includes an HTML version of this guide, a complete set of the product documentation, a tutorial designed to walk you through using the SDK, Javadoc for the public APIs supported, and an integrated SDK index to the complete set of message types, JSP pages, and data objects used by the Sterling Multi-Channel Selling Suite.

Use the SDK to install and customize your implementation of the Sterling Multi-Channel Selling Suite. The following diagram summarizes the process of creating a customized implementation of the Sterling Multi-Channel Selling Suite:

FIGURE 1. SDK Process to Create Customized Implementations

The steps are as follows:

1. Install a release of the Sterling Multi-Channel Selling Suite into the sdk_home/releases/ directory using the install target.

2. Create a project for your implementation using the newproject target. A project directory is created: sdk_home/projects/project/ and a copy of the release is copied to the sdk_home/builds/project/ directory.

3. Set configuration properties and create customizations in the sdk_home/projects/project/ directory.

4. Merge your customizations into your project using the merge target. The merge target builds your customizations over to the sdk_home/builds/project/ directory. At the same time, the data bean classes are generated and the configuration properties merged in to the configuration files.

5. Create a new version of the Sterling.war Web application file using the dist target. The Sterling.war file is created in the sdk_home/dist/ directory.

6. Deploy the new Sterling.war file to your servlet container.

Releases, Projects, and Builds

Releases

Each release of the Sterling Multi-Channel Selling Suite can be installed into the SDK under the sdk_home/releases/ directory. For example, Release 8.0 is installed into sdk_home/releases/debs-8.0/. You install a release by running the sdk install target.

For Release 6.3.1 and earlier, the application and product documentation are installed together using one execution of the install target.

For Release 6.4.1 and later, the application and product documentation are installed by executing the install target twice: once to install the application and once to install the documentation.

Projects

When you work on an implementation of the Sterling Multi-Channel Selling Suite, you are essentially working on a customization of a release of the Sterling Multi-Channel Selling Suite. Your customization might be as simple as setting the database connection information specific to your implementation, or it might be as complex as adding a new functional component to the system. In either case, the changes you want to make are maintained in a project: the set of files and directories you maintain to capture all the changes you want to make to the release of the Sterling Multi-Channel Selling Suite.

Each project consists of a set of directories and files in a project directory in sdk_home/projects/. All the changes that you need to make to the Sterling Multi-Channel Selling Suite must be made here: do not make changes in the sdk_home/releases/ directory. You can make the following types of customizations:

configuration parameters: using the properties files, set the relevant values for properties such as database type and connection information, logging levels, and so on.

changes to existing files: make changes to JSP pages and controllers by copying the file from the release to your project and changing the file in the project location. Use the customize target to copy the files from their location in the release to the corresponding location in the project directory.

new files: you can create new data objects, new Java classes by creating the corresponding files in the appropriate locations under the project directory.

Builds

After you finish making your customizations in the project directory, build your customized release of the Sterling Multi-Channel Selling Suite by merging the customizations with the release on which the customizations are made. When you build your implementation, it is created under the sdk_home/builds/ directory. See Building and Merging for what happens during the build process.

You can build your project as many times as you like, but each build overwrites the previous one. Typically, as you build your project, you can watch to see that the data objects are generated and compiled successfully and that other Java classes that you have created compile successfully. The build terminates if a compilation error occurs.

Building and Merging

The SDK provides a framework within which you can maintain different releases of the Sterling Multi-Channel Selling Suite and different customization projects. At any one time, the SDK has one active project and environment, and the debs.version property in the corresponding project_env.properties file determines the active release for the project.

Environments

When you work on a project, you may need to maintain different versions of the configuration parameters so that you can deploy the customized implementation into different locations. For example, you may need to work with a local development installation first, then test the customizations in a QA environment, before moving the customized implementation into the production environment. You may want to connect to different databases for these deployments or set different logging levels.

To help this process, we provide the ability to work with different environments in the same project: dev, local, qa, and prod. At any one time, the deploy.environment property of the sdk-settings.properties file indicates which one is active. When you run the merge target, the properties from the corresponding project_env.properties file are merged with the configuration files, and these are the ones set in the configuration files you find in the sdk_home/builds/project/ directories.

Building Process

When you build your implementation, the files from the active project are merged with the active release as follows:

1. When you first create the project using the newproject target, a new directory is created in the sdk_home/builds/ directory: this is essentially a copy of the active release. A project directory for the new project is created under the sdk_home/projects/ directory.

2. To start customizing your project, install the appropriate database connection files: use the installDB2, installODBC (Release 6.x-7.0), installMSSQLJDBC (Release 7.1.1 and later), or installOracle target to do this.

3. You must specify the database type using the env.setDBType target.

4. You create customizations in the project directory, sdk_home/projects/project/. The customize target helps you to move files from the release to the project directory.

5. After you have created your customizations in your project directory, you run the merge target. This merges the changes from your project directory by copying the new files from the project directory into the build directory. In the process, newer versions of files from the sdk_home/projects/project/ directory overwrite existing files that were copied from the sdk_home/releases/ directory in Step 1, so that changes made in your project overwrite the original release file in the build directory, not in the releases directory.

a. In Release 6.0 through Release 6.7, properties defined in the project_env.properties files are used to substitute placeholder tokens in configuration files. For each property in a configuration file, if a token value is found, such as @SMTP_SENDER@, then if a corresponding value is specified in the properties file, it is replaced with the specified value:

		SMTP_SENDER=sales@matrix.com

b. In Release 7.0 and later releases, properties defined in the project_env.properties files are used to populate the prefs.xml configuration files.

6. Once you run the merge target, you can run the schema creation and data loading targets: createDB and loadDB respectively. These targets use the database connection information that was copied form the project properties file to the script and schema files in the sdk_home/workspaces/project/ directories.

7. Run the dist target. This creates a new Web application file that is ready to deploy to the servlet container.

8. By running the switchenv target, you can change the active environment used to build the project: this enables you to set different values of the configuration parameters; for example, to point to a different database.

Building and Deploying

Keep in mind that when you are working in the SDK, you are building your customized implementation of the Sterling Multi-Channel Selling Suite. Once you have completed the customization process, you deploy the resulting Sterling.war Web application file to the servlet container. In general, the machine(s) on which you run the SDK can be completely separate from the machine(s) on which you run the Sterling Multi-Channel Selling Suite.

TABLE 2. SDK and Deployment 

 

SDK

Servlet Container

Machine

Usually your desktop machine

Usually a server-strength machine

Software requirements

You must have a JDK installed

You must have a servlet container installed

Database connections

Must be able to connect to the Knowledgebase to create schema and load data

Must be able to connect to the Knowledgebase to run the Sterling Multi-Channel Selling Suite

Purpose

To build your implementation of the Sterling Multi-Channel Selling Suite

To run the Sterling Multi-Channel Selling Suite Web application

In general, each servlet container provides a specific deployment mechanism and we suggest that you use this to deploy your customized Web application from the SDK to the servlet container. If you use the servlet container deployment tool, then this looks after any configuration or registration steps that the servlet container must perform to use the Web application. You should also consult the Sterling Multi-Channel Selling Suite Implementation Guide for any specific steps required to deploy the Sterling Multi-Channel Selling Suite Web application.

FIGURE 2. Logical Separation of Machines

Usually, the database server that holds the Knowledgebase is a separate machine from both the machine on which you run the SDK and the machine running the servlet container. By running the createDB and the loadDB (or loadMatrixDB) targets, you can create and populate the Knowledgebase schema from the SDK machine. When you run the merge target, the database connection information is set in the data source configuration files under the sdk_home/builds/project/ directory. When you deploy the Web application to the servlet container, then the database connection information is used to provide runtime access between the Sterling Multi-Channel Selling Suite and the database server.

Deploy Targets

If you run the SDK and servlet container on the same machine, then it is possible to deploy the customized Web application using SDK targets. However, these targets are shortcuts useful for early testing: they should probably not be used to perform the final deployment of the implementation to your QA and production servlet containers. See List of Targets for more information about the deploy targets.

Upgrading Releases and Projects

The SDK is designed to support you through the process of implementing the Sterling Multi-Channel Selling Suite at your site and to provide a means to maintain your customizations as you update the implementation over time. If a new release of the Sterling Multi-Channel Selling Suite is produced, then you may need or want to upgrade to the new release either to add additional functionality or to enhance existing functionality.

The SDK supports this process by enabling you to use the SDK to upgrade from one release (the source) to another (the target) and then to upgrade your project from the source release to the target release. In this process, the SDK helps you to identify what changes have been made in the new release and how they intersect with customizations that you have made.

The following files are created as part of the upgrade process:

conflictingfiles.log: this lists all files that exist in the target release and the project, but not in the source release. It also lists Java classes whose source file exists in the project, and whose class file is in the target release.

filestobedeleted.log: this lists all files that exist in the project and the source release, but which have been deleted in the target release.

filestobeupgraded.log: this lists all files that exist in both the source and target releases and in the project.

SDK Properties

When you run SDK targets, the targets use properties that you have specified in the properties files. Bear in mind that properties can be specified in one or more files and so you must understand the order in which the properties files are read.

When you run an Ant target, the property files are read by the target in the following order. Once a property is read in from one property file, it is ignored in any files that are read after that. Consequently, the file in which you define a property is important: if the same property is defined in a file that is read before the intended file, then your intended value will not be used.

1. sdk-settings.properties: the SDK uses this file to track what environment, project, and release are currently in use. You should not manually edit this file: use the corresponding targets: switchenv, switchproject, and switchdebs respectively.

2. project_env.properties: use this file to set properties specific to the project and the stage of the project

3. project.properties: use this file for properties that are common to all stages of your project.

4. my_sdk.properties: use this file for properties that you use in all your SDK projects. This file is not overwritten when you perform an upgrade to your SDK and so you can use it to preserve properties that would otherwise be lost if you put them in sdk-settings.properties or default_sdk.properties. This file is created when you run the setup target.

5. default_sdk.properties: sets default values for anything not set in higher precedent files.

Note that leaving an entry blank is interpreted by Ant as an empty string, and not that the property is not defined. Thus the following will cause the container.name property to be set to ““ in any SDK target that is run:

container.name=