How To Complete a Single Instance Cantara Installation on Tomcat

Required components

The following components are required to complete this installation. It is assumed that you have a patch Windows 2016 Server instance available with sufficient privileges to install and configure the required components.

Deploying the Cantara JDE Objects to Your JD Edwards Server

To deploy the Cantara JDE objects

In this example installation, only the minimum required components will be deployed. To utilise Rinami Cantara mobile applications you will be required to install additional JD Edwards components from the Cantara Portal. Please refer to your implementation partner as to which components should be deployed. The same method can be utilised for each module.

It is assumed that the person completing the Cantara JD Edwards Components installation has experience working within the JD Edwards Object Management Workbench and is familiar with the process of defining, building and deploying JD Edwards packages.

The steps required to deploy the Cantara JD Edwards Components to your Oracle JD Edwards EnterpriseOne system are:

1. Create an OMW project and promote it so that new objects can be created within the project. The project can be named as per your corporate naming standard. If there is no preferred standard then the project can be named as per the PAR file, so for example, the core components projects would be named CNTR_CORE. The most common configuration would be to promote the project to status 21 and create the objects within the DV environment.

2. Within OMW, select the new project and click the Restore action.
   

3. Select Yes to use a ZIP file and then choose the Cantara JD Edwards Components file from your download location. An example of the file name would be PRJ_CNTR_CORE_E920_5.0.5.par

4. Ensure that all of the objects within the project are checked in.

5. Complete a Full package build and deployment to any enterprise servers that will be connected to Cantara for each environment required.

6. Once the package is deployed, go back into OMW and generate the tables included in the project

7. You can promote and deploy the objects to each required path code using the normal JD Edwards OMW and deployment server process.

Refer to the JD Edwards Objects and Configuration topic for more details.

Configuring the JD Edwards Enterprise Server

To ensure the correct operation of the Cantara Integration Platform you must ensure that all relevant kernels and components on the target Oracle JD Edwards EnterpriseOne Enterprise servers are configured correctly. This should be completed using Server Manager but can also be done via direct edit of the JDE.INI if that is standard policy. Updates to the Enterprise servers should only be completed by an experienced JD Edwards System Administrator that understands Configurable Network Computing (CNC) activities.

Specific configuration elements to be reviewed/updated are:

List Retrieval Engine

The Output Location is where temporary query results are written prior to being returned the Cantara via the XMLList engine. You should check that this path is correct, the defined folder exists and that the user that the JD Edwards server kernels are running as have read and write permissions to it. It is recommended that this folder be monitored and any expired query results that have not been automatically removed are deleted. 

The Repository Size is the percentage of free disk space that the list engine will allocate to temporary results. If this limit is exceeded then the list engine will fail to return results to the Cantara. It is important to ensure that the location selected output location has sufficient free disk space to handle both the maximum size of expected queries but also takes into account the likely number of concurrent queries being executed by users. This setting only takes effect if disk monitoring is enabled.

Use Disk Monitor enables disk monitoring. It is recommended that this enabled to ensure that query activities to do not directly impact the operation of the JD Edwards enterprise server.

XML Lookup

Generally the XML List settings do not need to be updated from the default except for the last setting which is XML Kernel Reply 7. This must be set to 1 (enabled) to ensure that UBE submission through Cantara operates correctly.

Kernel Definitions

There are a number of kernels required to enable integration to JD Edwards. Changes kernel definitions can significantly impact the performance and operation of the JD Edwards Enterprise server and therefore should be only made after consideration for all of the factors involved.

The Call Object Kernel is central to the operation of the enterprise servers. Generally this will not require changes however if you are expecting a high number of concurrent users to be accessing JD Edwards through the Cantara platform then it may be necessary to increase the maximum number of kernels allowed to support the increased load.

The XML List Kernel will process query requests from Cantara. These kernels are not multi-threaded and are shared by concurrent users and therefore sufficient resources should be provided to prevent queuing of query requests.

The XML Service Kernel is responsible for receiving and routing service requests from Cantara. If you experience timeouts of execution of functions then it may be that there are insufficient XML Service kernels available to process the volume of requests.

Further details of the elements to be modified are available at JD Edwards Objects and Configuration under JDE.INI settings.

These changes must be done to each JD Edwards Enterprise or Batch server that will be integrated to via Cantara. To apply any changes made to the enterprise server configuration, the relevant services will need to be restarted.

Creating the required installation folders

This is an example configuration for a full local install of the Cantara Integration Platform with all components installed under a single parent directory of C:\Cantara. Please refer to your internal guidelines with regards to installation paths and folders and adjust as necessary.

The following folders should be created:

Install Oracle Java SE JDK 1.8.0

Execute the Oracle Java installer.

The only required component is the Development Tools. These are to be installed in C:\Cantara\Java\jdk1.8.0.

Install and Configure Oracle MySQL Server

Execute the Oracle MySQL installer.

Select the Custom install option so that you can determine the required components and installation path.

Select the MySQL Server 5.7.22 - X64 edition. You can optionally install the MySQL Workbench if you wish to administer the server directly from within the host machine.

Define the installation and data directories as per your prior setup.

Once the installation is completed you can configure the MySQL server for Cantara. Select Standalone MySQL Server.

Set the Config Type to Server Computer. You can leave the other settings as per their defaults. If you wish to access the database server remotely and have Windows Firewall enable then make sure to check the option Open Windows Firewall port for network access.

Set a root password for database administration. If you wish to connect to the database from a remote host you will also need to create a User Account with administration rights that is able to connect remotely.

If you want MySQL to run as a service (recommended) then you can configure the requirements for the service. Default options are suitable for Cantara.

Database Creation

As we will be installing two farms you will need to define at least two databases as the data for each farm is defined at database level. You can optionally install a database per component and per farm which is the configuration described below. The benefit of separating the databases is that you can then relocate each component to different database servers (eg production and non-production) as required. The following databases will be created:

The SQL script to create a Cantara database user and the above databases would be:

CREATE USER 'cantara'@'localhost' IDENTIFIED BY 'PASSWORD';

CREATE SCHEMA `cntr_access_test` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_access_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_assur_test` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_assur_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_admin_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;

GRANT ALL ON `cntr_access_test`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_access_prod`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_assur_test`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_assur_prod`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_admin_prod`.* TO 'cantara'@'localhost';

Once the database schemas have been created you can then run the appropriate installation script again each as required.

Install and Configure MongoDB Server (Optional)

Execute the MondoDB installer and select Custom Setup.

Select the required components and set the installation path. Please refer to the MongoDB documentation regarding the installation requirements. You may choose to install the additional components if required for you deployment.

Configure the service information so that the MongoDB service starts as a service within Windows.

Install Apache Tomcat 9.0 servers

This documentation provides an example installation of Apache Tomcat 9.0 on a Windows 2016 Server system. Please refer to the Apache Tomcat documentation relevant to your operating environment for further details and options with regards to the installation and configuration of the Apache Tomcat server.

As we are running both a production and test farm on the same Windows machine, we will require two instances of Apache Tomcat to be installed.

Extract the Apache Tomcat archive to C:\Cantara\Test\apache-tomcat-9.0 and to C:\Cantara\Prod\apache-tomcat-9.0

Set the JAVA_HOME environment variable within Windows. This should be configured as a System variable and set to C:\Cantara\Java\jdk1.8.0

Before performing and configuration, run the startup script to initialise the default server folders. This can be found at $CATALINA_HOME\bin\startup.bat (where $CATALINA_HOME is the base install path of the Apache Tomcat server) and will launch a new console window showing the status of the startup. Check that no errors exist on initialisation.

Extract the MySQL Java Connector archive and copy the jdbc driver JAR into the $CATALINA_HOME\lib folder. The file will be named mysql-connector-java-8.0.11.jar. Also copy the javax.mail.jar file into the same Apache Tomcat library folder.

Once each of the web applications have been deployed you can complete the configuration of the Apache Tomcat instances.

Deploy the Cantara Assur Servers

To deploy the Test Farm Cantara Assur Server

1. Extract the Assur application archive file into the folder C:\Cantara\Test\Assur\assur.war. 

2. Copy the context.xml from within the C:\Cantara\Test\Assur\assur.war\META-INF folder into the C:\Cantara\Test\apache-tomcat-9.0\conf\Catalina\localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be assur.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the test Assur instance.

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="C:\Cantara\Test\Assur\assur.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/TestAssur"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_assur_test"
               username="cantara"/>
   </Context>
   

To deploy the Prod Farm Cantara Assur Server

1. Extract the Assur application archive file into the folder C:\Cantara\Prod\Assur\assur.war. 

2. Copy the context.xml from within the  C:\Cantara\Prod\Assur\assur.war\META-INF folder into the C:\Cantara\Prod\apache-tomcat-9.0\conf\Catalina\localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be assur.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Assur instance.

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="C:\Cantara\Prod\Assur\assur.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/ProdAssur"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_assur_prod"
               username="cantara"/>
   </Context>
   

Deploying the Cantara Access Servers

To deploy the Test Farm Cantara Access Server

1. Extract the Access application archive file into the folder C:\Cantara\Test\Worker\worker.war. 

2. Copy the context.xml from within the C:\Cantara\Test\Worker\worker.war\META-INF folder into the C:\Cantara\Test\apache-tomcat-9.0\conf\Catalina\localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be cantara.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the test Access instance.

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="C:\Cantara\Test\Worker\worker.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/TestWorker"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_access_test"
               username="cantara"/>
       <Resource auth="Container"
               mail.debug="false" 
               mail.smtp.auth="false" 
               mail.smtp.host="smtp.rinami.com"
               mail.transport.protocol="smtp" 
               name="mail/Rinami"
               global="mail/Rinami"
               type="javax.mail.Session"/>
   </Context>
   

   You can optionally include a definition for an SMTP mail server. This will enable the Cantara Integration Platform to send email messages either via REST service calls or as part of the Advanced Job Scheduler functionality.

4. Copy the required Oracle JD Edwards Connector library files into the folder C:\Cantara\Test\Worker\worker.war\WEB-INF\lib

5. Extract the contents of the AIS_Client_Java_API archive and copy the AIS_Client_2.0.jar file into the folder C:\Cantara\Test\Worker\worker.war\WEB-INF\lib.

   AIS Version

   If your tools release is older than 9.2.2.0 then you should use the AIS_Client.jar file. If you do not wish to deploy AIS support then you do not need the client jar.

To deploy the Prod Farm Cantara Access Server

1. Extract the Access application archive file into the folder C:\Cantara\Prod\Worker\worker.war. 

2. Copy the context.xml from within the C:\Cantara\Prod\Worker\worker.war\META-INF folder into the C:\Cantara\Prod\apache-tomcat-9.0\conf\Catalina\localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be cantara.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Access instance.

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="C:\Cantara\Prod\Worker\worker.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/ProdWorker"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_access_prod"
               username="cantara"/>
       <Resource auth="Container"
               mail.debug="false" 
               mail.smtp.auth="false" 
               mail.smtp.host="smtp.rinami.com"
               mail.transport.protocol="smtp" 
               name="mail/Rinami"
               global="mail/Rinami"
               type="javax.mail.Session"/>
   </Context>
   

   You can optionally include a definition for an SMTP mail server. This will enable the Cantara Integration Platform to send email messages either via REST service calls or as part of the Advanced Job Scheduler functionality.

4. Copy the required Oracle JD Edwards Connector library files into the folder C:\Cantara\Prod\Worker\worker.war\WEB-INF\lib

5. Extract the contents of the AIS_Client_Java_API archive and copy the AIS_Client_2.0.jar file into the folder C:\Cantara\Prod\Worker\worker.war\WEB-INF\lib.

   AIS Version

   If your tools release is older than 9.2.2.0 then you should use the AIS_Client.jar file. If you do not wish to deploy AIS support then you do not need the client jar.

Deploying the Cantara Administration Console

To deploy the Cantara Administration Console Server

1. Extract the Console application archive file into the folder C:\Cantara\Console\console.war. 

2. Copy the context.xml from within the  C:\Cantara\Console\console.war\META-INF folder into the C:\Cantara\Prod\apache-tomcat-9.0\conf\Catalina\localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be console.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Assur instance.

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="C:\Cantara\Console\console.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/Console"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_admin_prod"
               username="cantara"/>
   </Context>
   
   
   
   

Configuring the Apache Tomcat 9.0 Test Farm Server

Install Apache Tomcat as a windows service by running the command

C:\Cantara\Test\apache-tomcat-9.0\bin\service.bat install Test

This will create a Windows service named Apache Tomcat 9.0 Cantara. If you are using Windows SMB shares for JD Edwards Media Object storage, the service account for this Windows service should be changed to a domain account that has read/write access to the media object queue folders. The service should also be set to delayed autostart so that it launches after the pre-requisite database services have started.

Configure the Apache Tomcat server using the tomcat9w.exe configuration tool

C:\Cantara\Test\apache-tomcat-9.0\bin\tomcat9w.exe //ES//Test

-Dcantara.worker.etc=C:\Cantara\Test\Worker\etc
-Dcantara.assur.etc=C:\Cantara\Test\Assur\etc

As there will be two instances of Apache Tomcat running on a single host, you must reconfigure one instance to use different ports. The following changes should be made to the C:\Cantara\Test\apache-tomcat-9.0\conf\server.xml file:

<Server port="8005" shutdown="SHUTDOWN">
changed to
<Server port="8105" shutdown="SHUTDOWN">


<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
changed to
<Connector port="8180" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8543" />


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
changed to
<Connector port="8109" protocol="AJP/1.3" redirectPort="8443" />

Configuring the Apache Tomcat 9.0 Production Farm Server

Install Apache Tomcat as a windows service by running the command

C:\Cantara\Prod\apache-tomcat-9.0\bin\service.bat install Prod

This will create a Windows service named Apache Tomcat 9.0 Cantara. If you are using Windows SMB shares for JD Edwards Media Object storage, the service account for this Windows service should be changed to a domain account that has read/write access to the media object queue folders. The service should also be set to delayed autostart so that it launches after the pre-requisite database services have started.

Configure the Apache Tomcat server using the tomcat9w.exe configuration tool

C:\Cantara\Prod\apache-tomcat-9.0\bin\tomcat9w.exe //ES//Prod

-Dcantara.worker.etc=C:\Cantara\Prod\Worker\etc
-Dcantara.assur.etc=C:\Cantara\Prod\Assur\etc
-Dcantara.console.etc=C:\Cantara\Console\etc

Verify Service Installation

Start the Test and Prod Apache Tomcat services through the Windows Service Management Console. The services should start cleanly and logs should be clear of errors. Check the following log files for errors:

1. C:\Cantara\Prod\apache-tomcat-9.0\logs\catalina.yyyy-mm-dd.log

2. C:\Cantara\Test\apache-tomcat-9.0\logs\catalina.yyyy-mm-dd.log

Verify Landing Pages and Update Server Tokens

To control administration access between components, credentials must be set on each of the access server and assur server components. This is accessed through the Change Server Token link in the top right of each component landing page. The default credentials are admin/admin.

Configuring the Cantara Administration Console

When you launch the Cantara Administration Console you will be greeted with a login prompt. The default username and password are admin/admin.

Initial configuration must be completed in the following order.

Base Administration Console Configuration

Go to the Administration page and set your Tenant ID and Database JNDI name. Your tenant ID is available from the Cantara Portal at https://portal.cantara.cloud. 

Define the Test Farm

Go to the Farm page and enter the first farm details.

Define the Assur Instance

Configure the Assur Instance details.

Define the Test Farm Worker Instance

Define the Production Farm

Go to the Farm page and then to the Farms tab to add a new Farm. Follow the same process as the test farm but ensuring the URL endpoints and JNDI entries are correct for Production.

Enter your Enterprise Licence information

You can access your licence information from the Cantara Portal at https://portal.cantara.cloud