Install and Run

This document shows the steps to run iPLAss on windows environment.
For this guide, Apache Tomcat is required as the application server, and MySQL is used as our DBMS.

iPLAss installer(war)itself is modified to fit with Apache Tomcat, however iPLAss is integrable with other OS/DBMS (require database configuration to fit with iPLAss environment).

This guide was made under the following conditions:

・Windows environment
・JRE 8 installed.

  1. Install Apache Tomcat (abbreviated as Tomcat)

    1. Download the Tomcat installer from Tomcat DownloadSite.

      Download the "32-bit/64-bit Windows Service Installer" from the Core session
    2. Unzip/install the downloaded installer to any folder.

  2. Install MySQL

    1. From MySQL DownloadSite , download MySQL Community Server (5.7 or above) installer.

      Download the "Windows (x86, 32 & 64-bit), MySQL Installer MSI"
    2. Install the downloaded installer to any folder.
      Please choose the following settings while installing.

      Setup Type = Server only
      Type and Networking:ConfigType = Dedicated Machine
    3. Configure MySQL (my.ini or my.cnf)

      Please modify the file referring to the following example.

      There is a my-default.ini file in mysql server’s folder, which is not the one we want to configure about.
      Please find the file that is actually being used for the server.(In the case of Windows, it is by default at C:\ProgramData\MySQL\my.ini).
        [client]
        default-character-set=utf8mb4
      
        [mysql]
        default-character-set=utf8mb4
      
        [mysqld]
        character-set-server=utf8mb4
        max_allowed_packet=100M
        transaction-isolation=READ-COMMITTED
        query_cache_size=0 (1)
        lower_case_table_names=1
        innodb_file_format=Barracuda (2)
        innodb_file_per_table=1
        innodb_large_prefix=1 (2)
        internal_tmp_disk_storage_engine=MyISAM (3)
        default-time-zone='Asia/Tokyo' (4)
      1Not required for MySQL 8.0.1 or higher.
      2Not required for MySQL 5.7.7 or higher.
      3Not required for MySQL 8.0.16 or higher.
      4Required for Connector/J 8.0 or higher.
      Please change the timezone depending on the working system environment.
      It is required to import timezone beforehand. For more details about importing timezone, please refer to Mysql timezone’s DownloadSite .

      Please change other items if necessary for your specific conditions.
      Once the file is modified, restart the MySQL Server.

      Important Notice
      In the case that MySQL binary log is enabled, there could be errors during the process of function generation.
      To deal with it, please enable the log_bin_trust_function_creators.
  3. Install MySQL JDBC driver

    1. Download Connector/J (GA) from MySQL’s DownloadSite .

      Download "Platform Independent (Architecture Independent), ZIP Archive"
    2. Install the downloaded installer to any folder.

    3. Then copy the JDBC driver files from the unzipped folder to Tomcat’s directory which we just installed in previous steps.

      %CATALINA_HOME%\lib

      ※「CATALINA_HOME」is referring to the directory of where the Tomcat was installed.

  4. Preparing the Database
    Since the iPLAss installer will create the database and user information, there is no action needed here.

  5. Configuring the Logs (optional)
    It is possible to configure the logs by placing the setting files for log under the directory of iPLAss.

    Log Setting File

    Place the log setting file for logback. The setting files are loaded in the following order.

    1. Try to locate logback-test.xml file.

    2. If file not found, try to find logback.groovy file.

    3. If file not found, then it will try to get logback.xml file.

    iPLAss Home Directory

    Environment variable「IPLASS_HOME」shell be set to the iPLAss home directory.
    By default the iPLAss directory are in the following position:

    %USERPROFILE%\.iplass
  1. Acquiring the installer (iplass.war)

    If the user does not have the installer files yet, please get the installer via the methods listed below.

    1. Download the installer from our DownloadSite

    2. (in the case of Enterprise Edition)Please find the iplass.war from installer directory within the supplied iPLAss SDK.

  2. Deploy iplass.war into Tomcat

    1. Copy-paste the「iplass.war」into the following directory of Tomcat.

      %CATALINA_HOME%\webapps

      If Tomcat was not started, please start Tomcat after placing the WAR file.
      If Tomcat is running, it will initialize the deployment automatically after placing the WAR file.

  3. Show the setup interface screen.

    1. Input the following URL to web browser to access the setup interface screen.
      The URL for iPLAss setup interface is as follows:

      http://localhost:8080/iplass

      or

      http://<ServerHostName_OR_IPaddress>:8080/iplass

      ※If you have configured the Tomcat’s port number, then use the configured port number.

  4. Executing the setup process of iPLAss

    1. Input the setup information

      1. Input the information to access Database.

        On iPLAss setup interface’s screen, input the information following the essential points listed below.

        Database

        Use 'MySQL'

        DBA User Name

        Enter the username of a user with MySQL’s DBA privilege

        DBA Password

        Enter the password of the above user

        Binary data file store location

        Directory of where the binary data should be stored at.
        For MySQL and PostgreSQL, Binary typed data are supposed to be stored externally respecting the standard. For Oracle and SQLServer, they store the binary data externally only when configured.

        Automatic table creation

        Check when you want the tables to be created automatically
        If the tables have already existed, they will be replaced. So this option should be unchecked in the condition if we want to keep the data, such as reinstalling.
        ※Please have it checked if this is your first time installing the product.

        JDBC URL

        Should be filled automatically hostname and portnumbers (see the rows below) are inputted.
        If you need to manually change the URl, please check the 'Edit'.

        Host Name

        The hostname or ip address of where the MySQL was installed.

        Port Number

        3306 (by default)
        ※If you have manually configured the port number, please use the configured port number

        Schema Name

        mtdb (unchangeable)

        User Name

        Any created mysql username

        Password

        The password for above user.

        DataSource Name

        jdbc/iplass (by default)
        If you need to manually change the URl, please check the 'Edit'.

        DataSource automatic setting

        Check if you want Tomcat to configure the sources for you.
        This row is useless for servers other than Tomcat.

      2. iPLAss Input The Tenant Information.

        Tenant Name

        Any name decided by the developer.(recommended to use half width keyboard input method)

        Administrator User ID

        Any ID decided by the developer

        Administrator Password

        Any acceptable password decided by user
        ※If you need to see the password, check[View Password]
        The 'View Password' option will not be presented if the user is using IE.

        About the Manager ID and password
        UserId should be over 4 characters long and can be composed only by English characters, numbers, and the specific special character of - , @ , _ , .
        Password should be over 6 characters long and only be composed by English characters, numbers, and the following special character: ~!#\\$^&*+;:?/|{}\\.=_,- .

        iPLAss Setup Interface Screen

        01_iPlassSetup_en
    2. Start the setup process
      After inputting the setup information, please click the 'Start setup' button to begin the setup process.
      If the setup finished normally, the message of「please restart the application server」will be presented.

      The Message when Finished Normally

      iplassSetupSuccess
  5. Restarting the application server (Tomcat)

    1. Just restart the application server (Tomcat)

  6. Access the tenant

    1. Input the following URL to web browser in order to access the tenant.

      http://localhost:8080/iplass

      or

      http://<Serverhost_or_IPaddress>:8080/iplass

      ※If you have manually configured the port number of Tomcat, please use the configured port number

    2. Show the tenant login pages
      The page will generate tenant automatically when it was accessed for the first time.
      Once generated, the user will be redirect to the tenant’s login page.

      iPLAss Login Page

      iplassLogin
      Later on (accesses other than generating the tenant), The user will not be redirected. It is recommended to bookmark this page for later accesses.
      If all the steps was followed without custom configurations otherwise, the login page’s URL should be as follows.
      http://<Serverhost_or_IPaddress>:8080/iplass/<TenantName>/gem/
    3. Log in to the tenant
      Please input the manager’s userId and password which was set during the tenant setup process to the input boxes and click the login button.
      After log in, make sure the tenant’s interface page (GEM) are presented normally.
      If the GEM page was displayed normally, the installation is finished completely.

      iPLAss TopPage

      iplassTop

As a demonstration, let’s create a simple application with the standard features.
We will follow the following steps to create a management interface for master data of arbitrary products.

  1. Understand two different types of interfaces.

    1. General pages and AdminConsole
      On the tenant generated by iPLAss, there are two web applications ready to use right at the beginning: The [General pages] and [AdminConsole].

      General pages

      The interfaces meant for end-users
      This is the top page what will be shown to the user after login.
      It is auto-constructed depending on the information defined in the AdminConsole.

      AdminConsole

      The interfaces meant for system manager and developers.
      It is used to define entities, design the interfaces, and control many aspects of the applications. We will explain about it in details later.

    2. start the AdminConsole

      Let’s start the AdminConsole.
      While logged in as the tenant manager, click the「User Admin」in the header, the Menu will show up.
      Clicking AdminConsole on the menu, the AdminConsole interfaces will be initiated.

      Starting AdminConsole

      startAdminConsole

      AdminConsole Top Page

      iplsassAdminConsole
    3. About the AdminConsole

      On the left side of AdminConsole, there are two menu groups:「MetaDataSettings」and「Tools」.
      「MetaDataSettings」will display the metadata defined by tenant in hierarchical trees menus.
      Metadata is representing the setting information of the applications which run on iPLAss.
      The creation and modification of metadata will be done on the tree menus.
      「Tools」 is a tool collection for developers. It will be used a lot during the development phases.

      「MetaDataSettings」and「Tools」

      metadataSetting

      ※There are some predefined metadata created during the generation of tenants.
      They will be used for the preset features provided by iPLAss such as「mtp」and「GEM」.

  2. Creating Metadata: the definition of the Entity

    Entity is the Metadata which is equivalent to the concept of 'table' in RDB.
    As utility features of iPLAss, the searching/editing/aggregation functions of the entities are predefined depending on their definitions.

    1. Creating Entity

      As an example, We will create the 'product category master' entity which serve to manage the product category, and the 'product master' entity which manage the information of products.

      To create Entity, select the「Entity」from MetaDataSettings, and right click on it to open the menu. On the menu, choose the「Create Entity」, and the dialog box to generate Entity will show up.

      「Create Entity」

      CreateEntity01

      Entity Creation

      CreateEntity02

      The Necessary Entries to Create Entity

      Name

      The name of the Entity
      Use "."(a dot) To travel through the file paths.

      Display Name

      The name used when displaying the entity.
      It will be used in various situations such as displaying the data to the end-users on GEM pages.

      Description

      The description to the entity.

      1. Creating necessary Entity

        Pleas input the data as instructed, and click the「Save」button.

        Product Category Master

        CreateCategoryEntity

        Product Master

        CreateProductEntity
      2. Add Property to Entity.

        'Property' is the properties possessed by Entity. As in RDB an Entity is equivalent to a table, a Property is equivalent to a column.

        To add Property to Entity, either double click the target Entity,
        or right click the target Entity to select the 「Open Entity」from the pop up menu.

        「Open the Entity」

        setupEntity

        After the「Open Entity」was selected, the Entity’s settings interface will show up.
        To add Property, click the 「Add」button on the interfaces.

        「Add」Button

        setupProperty

        On the add property dialog of Product Category entity,
        add a reference type property called "parentCategory" referring to ProductCategory itself.

        Add「Parent category」Property

        setupProductCategory01

        Sample Data Entry

        Name

        parentCategory

        Display Name

        Parent Category

        Type

        Reference

        Reference Entity

        ProductCategory

        reference relationship

        normal reference

        The changes on Entity will not reflect to the system until the user press the「Save」button.

        「Save」button

        setupProductCategory02

        Upon finish adding properties to the ProductCategory, we will add properties to Product as well.
        Please add and save the properties to the Product as instructed below. (To prevent confusion with the previous one. The previous one means that the product category is referring to itself, and this one means the product is referring to product category.)

        Adding Property To「Product」

        setupProduct01

        Sample Data Entry

        Name

        productCategory

        Display Name

        Product Category

        Type

        Reference

        Reference Entity

        ProductCategory

        Reference Relation

        Normal Reference

        Adding「Price」Property

        setupProduct02

        Sample Data Entry

        Name

        price

        Display Name

        Price

        Type

        Integer

        Now we are done with adding Properties to both Entities.

  3. Check the result on the GEM pages.

    Let’s confirm that newly added metadata is reflected on the screens.
    On GEM pages, click on the「Home」button to reload. There should be two additional buttons added corresponding to the Metadata we just created.

    Confirm On The GEM Pages

    TopPage

    By clicking on the corresponding button, the user can see the configured Properties to make sure their changes are reflected.

    Confirming the configured Properties.

    prudoctCategoryMaster
    prudoctMaster

    It is possible to use the buttons such as "Add" and "Search" to add/search/edit the products.
    The following are the corresponding actions

    Sample of adding Product Category

    entryProductCategory

    Sample of Adding Product

    entryProduct

    Sample of Searching Product

    searchProduct

For iPLAss beginners, it would be the best to start with the Tutorial to learn iPLAss’s amazing features.