Install the Visual Modeler using the SDK

To install the Visual Modeler, perform the following steps:

1. Locate the release Sterling.jar file for this release (called something like IBM_VisualModeler-0.1-OC001-<date>-<build>.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:
   • 

     ./sdk.bat install <sterlingjar>
     

   • 

     ./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 following command from the <sdk_home> directory:
   • 

     ./sdk.bat generateIndexFile
     

   • 

     ./sdk.sh generateIndexFile
     

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 Visual Modeler from this JAR file by following the instructions for installing the reference 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. 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"