Install the Sterling Configurator Visual Modeler using the SDK

About this task

This topic describes how to use the SDK to install the Sterling Configurator Visual Modeler on either a Windows 2000/2008 or a UNIX operating system. Successful installation creates a Sterling.war file on your SDK machine.

Note: Install your servlet container before attempting to install the Sterling Configurator Visual Modeler.
Note: If you are using Windows Server Edition, 64-bit, or Windows 7, 64-bit, you might encounter the following issues when running SDK targets:
  • The system cannot resolve env.COMERGENT_SDK_HOME. To avoid this issue, explicitly specify the COMERGENT_SDK_HOME path in sdk.xml. For example: <property name="sdk.base.dir" value="C:/SDK"/>
  • You encounter a java.io.IOException: Cannot run program "command.com" error. You can ignore the exception, or upgrade to Ant 1.7 (or later).

Procedure

To install the Sterling Configurator Visual Modeler, perform the following steps:

  1. Locate the release Sterling.jar file for this release (called something like Sterling-9_5-RC2.jar) and copy it to a temporary location on your system.
  2. At the command line, navigate to the <sdk_home> directory.
  3. Edit the <sdk_home>/my_sdk.properties file to specify the value of the container.home and app.name properties. The SDK uses these properties to determine the values of other properties as follows:
    • deploy.home is set to container.home/apps.dir. The deploy.home property is used to specify the servlet container deployment directory.
    • The app.name is the name of the Web application. The app.name is usually the same as the Web application's directory under the deployment directory. In this guide, we assume that the value of this property is “Sterling”. If you want to change the name of the Web application (for example, to change the name of the generated WAR file), modify the app.name entry in the my_sdk.properties file.
    • debs.home takes the value container.home/apps.dir/app.name.

      The project.name property defined in the sdk-settings.properties file is used to specify the name of the project directory in the SDK. In general, this is not the same as the app.name property.

      Note:
      • If you are running the SDK on UNIX, you may have to add execute permission to the <sdk_home>/sdk.sh file: 
        chmod +x <sdk_home>/sdk.sh
      • After you run the merge target, you may have to modify the permissions on the <sdk_home>/workspaces/project/OracleCreateSchema.sh file.
  4. If you are running the SDK on Windows 2008, you must perform the following tasks to ensure that the environment variables are picked up correctly:
    • Edit the sdk.bat file located in the <sdk_home> directory by adding the -Denv.COMERGENT_SDK_HOME=%COMERGENT_SDK_HOME% argument. For example:

      "%JAVA_HOME%/bin/java" -Xmx256m -classpath %CP% -Denv.COMERGENT_SDK_HOME=%COMERGENT_SDK_HOME% org.apache.tools.ant.Main -emacs -buildfile %COMERGENT_SDK_HOME%\sdk.xml %ARGS%

    • Edit the sdk.xml file located in the <sdk_home> directory by commenting the property environment statement. For example: 
      
<<-- <property environment="env"/> -->
  5. Run the following command from the <sdk_home> directory:
    • Windows
      ./sdk.cmd install <sterlingjar>
    • UNIXLINUX
      ./sdk.sh install <sterlingjar>
    where <sterlingjar> refers to the location of the Sterling.jar file as located in step1.
  6. After you install, set the version number on the SDK Index HTML page by running the generateIndexFile target.
  7. Run the newproject target, specifying a project name for this installation. For example: 
    
./sdk.sh newproject matrix (for UNIX)
sdk newproject matrix (for Windows)

    This target can take a few minutes to run.

  8. Edit the <SDK_HOME>/projects/matrix/matrix_dev.properties and add the database information.
  9. You can also set other properties such as the logging level. Values you set here are automatically merged into the prefs.xml configuration files under the <sdk_home>/builds/project/ directory. See the topic ''Email Addresses'' for information about the email addresses set in the properties files.
  10. Database targets:
    1. If you plan to run the Knowledgebase on Oracle, run the installOracle target, specifying the location of the Oracle JDBC JAR file, to copy the Oracle JDBC drivers JAR file to the project files. The name and location of the JAR file will vary from installation to installation. For example: 
      
C:\oracle\product\10.2.0\client_1\jdbc\lib\ojdbc14.jar

      or
      /opt/oracle/product/10.2.0/client_1/jdbc/lib/ojdbc14.zip

      For example:

      ./sdk.sh installOracle /tmp/Oracle_jdbc.jar (for UNIX)

      sdk installOracle /tmp/Oracle_jdbc.jar (for Windows)

      This copies the JAR file to the WEB-INF/lib/ directory in the release directory. It also renames the file to oraclejdbc.jar.

    2. If you plan to run the Knowledgebase on DB2, run the installDB2 target, specifying the location of the DB2 JDBC JAR file, to copy the DB2 JDBC drivers JAR file to the project files. The name and location of the JAR file will vary from installation to installation. For example: 
      
C:\DB2\SQLLIB\java\db2jcc.jar

      or
      /opt/db2/sqllib/java/db2jcc.jar

      For example:

      ./sdk.sh installDB2 <location of db2jdbc.jar file> (for UNIX)

      sdk installDB2 (location of db2jdbc.jar file> (for Windows)

      This copies the JAR file to the WEB-INF/lib/ directory in the release directory. It also renames the file to db2jdbc.jar.

      Note: You must manually copy the DB2 license JAR, db2jcc_license_cu.jar, to the WEB-INF/lib/ directory in the release directory.
  11. Run the env.setDBType target to set the appropriate database type.

    For Oracle: 

    
./sdk.sh env.setDBType Oracle (for UNIX)
sdk env.setDBType Oracle (for Windows)

    For DB2: 

    
./sdk.sh env.setDBType DB2 (for UNIX)
sdk env.setDBType DB2 (for Windows)
  12. If you plan to support locales other than the default U.S. English (en_US) locale, perform the localization installation and customization steps.
  13. Run the merge target to create your first build in the builds/ directory. 
    
./sdk.sh merge (for UNIX)
sdk merge (for Windows)

    This target can take a few minutes to run. The sdk merge target copies the Web application files from the releases directory and merges in the files and properties currently in your project directory. If the target fails with a message relating to the JDBC driver, check that you have run the database install targets appropriately:

    • If you are creating an Oracle-based project, then check that you have run the installOracle target, and ensure that the oraclejdbc.jar file is now in the <sdk_home>/releases/debs-Aries/overlay/WEB-INF/lib/ directory.
  14. Run the distWar target to create the WAR file that you will deploy. For example: 
    
./sdk.sh distWar (for UNIX)
sdk distWar (for Windows)

    This target can take a few minutes to run. The generated WAR file is in
    <sdk_home>/dist/. Its name is determined by the app.name and deploy.environment properties and a timestamp. You can rename the WAR file to Sterling.war.

  15. Alternatively, you can run the dist target. This creates a JAR file that contains the WAR file along with JAR files that provide the SQL scripts and XML data files. You can install the Sterling Configurator Visual Modeler from this JAR file by following the instructions for installing the reference Sterling Configurator Visual Modeler. Note that you can skip the steps to set the database properties information because your prefs.xml file already has this information.
  16. In the <sdk_home>/dist/time_stamp/ directory, rename the generated prefs_dev.xml file to prefs.xml file. This is the basic configuration file that must be copied under the home directory of the user running the servlet container.
  17. Run the createDB target to create the Knowledgebase schema. 
    
      ./sdk.sh createDB (for UNIX)
      sdk createDB (for Windows)

    Check the results of the createDB target by looking at log files in the <sdk_home>/logs/projects/project_name directory.

  18. Run either the loadDB target (to load the minimal data set) or the loadMatrixDB target (to load the full Matrix reference data set) into the Knowledgebase. 
    
./sdk.sh loadDB (for UNIX)
sdk loadDB (for Windows)

    or

    
./sdk.sh loadMatrixDB (for UNIX)
sdk loadMatrixDB (for Windows)

    Check the results of the loadDB or loadMatrixDB targets by looking at the <sdk_home>/workspaces/project_name/debs.log file.

    Check for an error similar to the following:

    
File: WEB-INF/xmldata/Minimal/Partner:
[CMGT_LOOKUP_CACHE_ENTRY_DOESNT_EXIST] error: 
"No Lookup Cache entry for locale en_ Lookup
 Category PartnerStatus Lookup Code 10."
com.comergent.api.dataservices.NoLookEntryExistForSourceException:
 [CMGT_LOOKUP_CACHE_ENTRY_DOESNT_EXIST] error: 
" No Lookup Cache entry for locale en_ Lookup 
Category PartnerStatus Lookup Code(or Lookup Description) 10."
This error is caused by an invalid locale specification in your
 system environment. On UNIX, check whether the LANG environment variable
 has a country or region setting. It should look like this:
LANG=en_US.UTF-8
  19. (Optional) To set the database password to be encrypted:
    1. Encrypt the database password string: 
      
      ./sdk.sh encryptVal <password> (for UNIX)
      sdk encryptVal <password> (for Windows)

      The result is an encrypted version of the password.

    2. Edit the encrypted password string into the <SDK_HOME>/projects/matrix/matrix_dev.properties properties file as the relevant password property. For example: 
      
      ORACLE_PASSWORD=<encrypted_password>

      The encrypted form of the password is entered into the schema creation scripts that are used by the createDB target, so you must run the createDB target before you encrypt the password.

    3. Run the sdk merge target to add the database properties in prefs.xml file. Use the same information as mentioned in step 13
    4. Edit the prefs.xml file to add the Encrypted attribute as a child to Comergent/DataServices/DataSource/ENTERPRISE node. For example, 
      <DataServices transientState="true">
    <DataSource transientState="true">
      <ENTERPRISE transientState="true">
        <SrvcSubType ChangeOnlyAtBootTime="true" controlType="text" defaultChoice="DB2" displayQuestion="Database type" help="Enter the database type (ORACLE, MS, DB2)." runtimeDisplayed="true" visible="true" boxsize="45">DB2</SrvcSubType>
        <DataService ChangeOnlyAtBootTime="true" controlType="text" defaultChoice="JdbcService" displayQuestion="ENTERPRISE Data Service" help="Enter the name of the Data Service to use (JdbcService, LocalDataService)." runtimeDisplayed="true" visible="true" boxsize="45">JdbcService</DataService>
        <UserId ChangeOnlyAtBootTime="true" controlType="text" defaultChoice="cmgtuser" displayQuestion="Database UserId" help="Enter the database user id." runtimeDisplayed="true" visible="true" boxsize="45">db2admin</UserId>
        <Encrypted>true</Encrypted>
        <ConnectString ChangeOnlyAtBootTime="true" controlType="text" defaultChoice="jdbc:db2://localhost:50000" displayQuestion="Database Connection String" help="Enter the database connection string." runtimeDisplayed="true" visible="true" boxsize="45">jdbc:db2://localhost:50000/VMSDK</ConnectString>
        <Password ChangeOnlyAtBootTime="true" controlType="text" defaultChoice="cmgtpassword" displayQuestion="Database Password" help="Enter the database password." runtimeDisplayed="true" visible="true" boxsize="45">IDES:L4gwopcvSxHN+dVMK1/HLg==</Password>
      </ENTERPRISE>
  20. Rebuild the Sterling.war file using the SDK distWar target and redeploy it. Use the same information as mentioned in step 14
    After deployment, if you get an error similar to the following, then redeploy the Sterling.war file in exploded mode.
    [CMGT_E_SERVER_NOT_INITIALIZED]error:"Server awaiting initiation"