Installation

Launching Installer

The first screen when you launch the application will be this:

Launch the installer in different Operating Systems

• Unzip the OIM installer folder to find the executable(.exe) file.

• The steps to launch the installer in different Operating Systems (OS) are given below. Follow the steps given for the OS that you are using.

Windows

Linux

* Double click the executable .exe file given in the application folder (It is advisable to run .exe file by right-clicking Run as administrator where * is replaced with the application version). If one instance of this release is already installed, then the user will be notified. * Click yes to continue with the installation. It will then display the uninstallation key for the current installation.

Before Installation * Extract the zip file. Make sure user who will run installer owns the files and has full access to extracted files. * Create empty directory with full access(it should not be inside installation directory) and export it's path to OPSHUB_TEMP_DATA variable as shown in below example: export OPSHUB_TEMP_DATA=/home/setup/temp * If you are doing a silent installation, make sure you have provided the same path for OPSHUB_TEMP_DATA as provided during Silent Registration for Linux. * If Linux has NFS (Network File System) based file system, please add the following line in OIM user's '.bashrc' file: In /home/{OIM user}/.bashrc file, add the following line at the end: export JAVA_OPTS="$JAVA_OPTS -XX:+StartAttachListener" Without the Java option, the server start up will fail. The error details are available here. * See minimal access required to install OpsHub Integration Manager here, when you do not have root access. To Run sh file * Open terminal window and go to the folder containing the install.sh file. * Execute the following command: sudo -E sh install.sh. * To run the sh File, you need to have access to Linux UI. This is because the installation process requires user inputs through UI. Installation won't get completed through remote terminal connection (i.e. Putty). To Run sh File from External File (Silent Installation) To install OpsHub Integration Manager through terminal connection (i.e. Putty), follow the steps given below: * Complete user registration as described here. * Download and modify OpsHubAutoInstall.xml file as per your requirement by click here. * Make sure, you will transfer the modified file on the instance where you want to install OpsHub Integration Manager. * Set an environment variable OPSHUB_AUTO_INSTALL on the installation instance, the value of variable is the path to the OpsHubAutoInstall.xml file. File name can be different. For example, export OPSHUB_AUTO_INSTALL=/home/Downloads/OpsHubAutoInstall.xml. * After setting environment variable, run the installer with command sudo -E sh install.sh. * Please refer Possible Error section for trouble shooting error(s) occurred during Installation.

Recommended Installation Path for OpsHub Integration Manager Installer for Linux

• It is recommended to install or perform migration of the OpsHub Integration Manager in the /opt folder or /user/local folder.

  • For OpsHub Integration Manager migration, if the OpsHub Integration Manager is not installed at the above places, then follow the steps mentioned here.

  • Reason: SELinux prevents Linux users from running a OpsHub Integration Manager service in the user's home directory. Hence, the user needs to avoid installing OpsHub Integration Manager in the home directory.

Minimal access required to run linux installer using external file

• OpsHub Integration Manager Installation Directory should be owned by user who run installer/migrator and has following permissions.

Here are the required permissions:

Permission	Directory
--x	/usr
--x	/proc
r-x	/usr/bin
r-x	/usr/bin/*
--x	/usr/lib64
r-x	/usr/lib64/*
--x	/usr/share (if user edits file using nano)
r-x	/usr/share/*
rw-	/etc/systemd/system (if user needs OpsHub Integration Manager as a service for Ubuntu)

• Note: For HSQLDB, root access is required when user needs to install/migrate OpsHub Integration Manager.

Possible error during Silent Installation/Upgradation

[ Starting automated installation ]

[Timestamp] java.util.prefs.FileSystemPreferences$2 run

INFO: Created system preferences directory in java.home.

com.izforge.izpack.installer.InstallerException: Validating data for panel UserInputPanel.EmailIdVerificationForExistingCode was not successfull

com.izforge.izpack.installer.InstallerException: Validating data for panel UserInputPanel.EmailIdVerificationForExistingCode was not successfull

at com.izforge.izpack.installer.AutomatedInstaller.validatePanel(Unknown Source)

at com.izforge.izpack.installer.AutomatedInstaller.installPanel(Unknown Source)

at com.izforge.izpack.installer.AutomatedInstaller.doInstall(Unknown Source)

at com.izforge.izpack.installer.Installer.main(Unknown Source)

[ Automated installation FAILED! ]

Solution

Make sure you have performed the following steps correctly:

• You have registered as described Registration - Silent Registration for Linux before Installation/Upgradation.

• You have registered using the same path for which you install/upgrade OpsHub Integration Manager.

• You have used the correct verification code.

  • Verification Code is unique for each machine and installation path. The code generated on a different machine and for different path won't work.

• You have export same value for OPSHUB_TEMP_DATA during Registration and Installation/Upgradation.

License Information

On launching the installer, you will see the license agreement window that contains all license-related terms and conditions.

If you agree with the license details, then only you can move to the next step i.e. Installation.

License Information window has the details of the trial license and the contact information to purchase the license.

Possible exceptions

While uploading the license from license management tab, OpsHub Integration Manager throws exceptions as below:

• Unable to install license com.opshub.license.exception.LicenseException: Failed to get license content because of If you are accessing OpsHub from different machine then change localhost to ip address of the machine where OpsHub installed.

• The filename, directory name, or volume label syntax is incorrect

com.opshub.license.install.OpsHubLicenseManager.getLicenseContent(OpsHubLicenseManager.java:60) at com.opshub.license.install.OpsHubLicenseOperationManager.getLicenseContent(OpsHubLicenseOperationManager.java:34) at com.opshub.license.install.LicenseInstaller.getOHLicenseContent(LicenseInstaller.java:128) at com.opshub.license.install.LicenseInstaller.installLicense(LicenseInstaller.java:57) at com.opshub.license.install.LicenseInstaller.installLicense(LicenseInstaller.java:51) at com.opshub.license.server.LicenseBO.validateAndInstallLicense(LicenseBO.java:329) at com.opshub.license.server.LicenseServer.validateAndInstallLicense(LicenseServer.java:96) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:483) at com.metaparadigm.jsonrpc.JSONRPCBridge.call(JSONRPCBridge.java:1122) at com.opshub.JSON.JSONRPCServlet.service(JSONRPCServlet.java:349) at javax.servlet.http.HttpServlet.service(HttpServlet.java:729) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:230) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.catalina.filters.HttpHeaderSecurityFilter.doFilter(HttpHeaderSecurityFilter.java:120) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at com.opshub.JSON.CacheControlFilter.doFilter(CacheControlFilter.java:27) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:192) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:165) at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:199) at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:96) at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:474) at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:140) at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:79) at org.apache.catalina.valves.AbstractAccessLogValve.invoke(AbstractAccessLogValve.java:624) at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:87) at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:349) at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:495) at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:66) at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:767) at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1347) at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61) at java.lang.Thread.run(Thread.java:745) Caused by: java.io.FileNotFoundException: If you are accessing OpsHub from different machine then change localhost to ip address of the machine where OpsHub installed.

• The filename, directory name, or volume label syntax is incorrect

at java.io.FileInputStream.open(Native Method) at java.io.FileInputStream.(FileInputStream.java:138) at de.schlichtherle.license.LicenseManager.loadLicenseKey(LicenseManager.java:741) at com.opshub.license.install.OpsHubLicenseManager.getLicenseContent(OpsHubLicenseManager.java:55)

Installation

Here is a video on how to install OpsHub Integration Manager on the Windows machine:

Select Installation Path

• You now have to select the installation directory. Before you select a directory, make sure the directory is empty. All the log files, configuration files, and servers are placed in this directory. If the directory is not available, you can create a directory as per your own specifications.

Registration

• Each installation must be registered with OpsHub. Registration can be done either in Online or Offline mode. Please refer Registration section for more details.

Database Selection# Advance Installation

• Go through this section if you want to configure Advance Installation. Else, proceed to the Installation Progress section.

Let's now learn about the steps for advance installation.

Connection Mode Configuration

• Select the type of connection protocol you want to use for running the server. If HTTPS is selected, you need to follow one more step SSL Certificate Configuration for advance installation.

OpsHub Database Custom Configuration

• If you want to create databases manually, mark the checkbox "Check this if you will be creating databases manually". The instructions to create databases have been mentioned in the section Manual creation of databases.

• If the checkbox "check this if you are creating databases manually" is unchecked then enter the names of the databases that you want to configure and according to the database selection in the previous stage (MySql, MS SQL/Azure SQL, PostgreSQL or Oracle) databases/schemas will get created.

• Database name can contain $, _, #, alphabets, and numbers without any space.

• If there are more than one database, give different names for each one.

Install OpsHub server as a service

• If the application is installed as a service, the server will automatically start on system boot. You need not to start and stop the server explicitly. In case, you want to stop the services, you can go to Services, find the service and stop it manually from there.

Data Encryption Configuration

• Advanced Data Encryption: Enables user to generate a secret key and store it in a secured location, or select an existing secret key if available. This configuration also allows the user to select the desired encryption algorithm for ensuring security of the application.

a) Configuration for secret key location User can select either of two options:

• Generate a secret key: With this option, a secret key would be automatically generated, and user needs to select location, where he/she desires to store this key.

• Use the existing secret key: If user already has secret key available,then user should select this option. User needs to select path where "opshub.key" file is available to use that key.

b) Configuration for algorithm to encrypt data User can select his desired algorithm from the available list to ensure security of data in application.

Installation Progress

The image below shows the overall progress of installation.

• Setup Shortcuts: It will add the application to the Windows program list if the operating system is Windows and will add the application to the Linux program list if the operating system is Linux. It will also create the OpsHub Integration Manager launcher.

Installation Success

The image below shows a successful installation.

Once you have installed the application, click Get Started With the Application to see how to get started.

Appendix

SSL Certificate Configuration

It is advisable to enter the server-host name in the given field, it might create problem with IP address in some cases. Alias of the certificate should be unique.

• Enter the name of your Organizational unit.

• Enter the Organization name.

• Enter the current City or Locality.

• Enter the current Country Code. It should be alphabetic code. For e.g., "IN" for India, "US" for America, "AU" for Australia, etc.

• Select the number of days till when the certificate should be valid.

Note : Please note with the above steps OpsHub Integration Manager will be installed with SSL configuration. But the corresponding SSL certificate imported will be self-signed. In case you want to install certificate signed by your CA authority then follow the steps given in this section How To Import a Certificate in appendix.

Manual creation of databases

For manual creation of databases, you can use the following queries:

Queries for MySQL database

Let's name the database as db1:

DROP DATABASE IF EXISTS db1;
CREATE DATABASE db1 CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

Let's name the reports database as reportsdb:

DROP DATABASE IF EXISTS reportsdb;
CREATE DATABASE reportsdb CHARACTER SET latin1 COLLATE latin1_general_cs; 

Queries for MS SQL/Azure SQL Database

Collation Considerations

• For Multiple Language Systems:

  • If your end systems support multiple language characters, it's essential to choose a collation that supports UTF characters.

  • To enable UTF character support in OpsHub Integration Manager, install it on Microsoft SQL Server 2019 or above.

  • Select a collation with a UTF postfix, for example: Latin1_General_100_CS_AS_SC_UTF8

• For Single Language Systems:

  • If your end systems utilize a single language and your selected collation includes all the necessary characters and is supported in SQL Server versions below 2019, you can proceed with the installation on SQL Server version below 2019. Select an appropriate collation that suits your end systems [which are going to be configured in OpsHub Integration Manager].

  • Select an appropriate collation that suits your end systems (which will be configured in OpsHub Integration Manager).

  • Here is guide that may help you decide the right collation for your database.

Note: We need 1 database and 2 schemas to be created manually, out of which The database and schema name must be the same for the OpsHub database, and another schema should be created for reportsdb.

drop database IF EXISTS db1
db1 database: create database db1 COLLATE Latin1_General_CS_AS;
db1 schema: create schema db1;
Reports schema: create schema reportsdb;

Queries for Oracle Database

Note: Replace <<SERVER_PASSWORD>> with the actual password.

Let's name the database as db1:

drop user db1 CASCADE;
CREATE USER db1 IDENTIFIED BY <<SERVER_PASSWORD>> DEFAULT TABLESPACE users QUOTA 500M ON users TEMPORARY TABLESPACE temp PROFILE DEFAULT ACCOUNT UNLOCK

Let's name the reports database as reportsdb:

drop user reportsdb CASCADE;
CREATE USER reportsdb IDENTIFIED BY <<SERVER_PASSWORD>> DEFAULT TABLESPACE users QUOTA 2048M ON users TEMPORARY TABLESPACE temp PROFILE DEFAULT ACCOUNT UNLOCK

Note: Ensure both db1 and reportsdb users have the required privileges. For system and object privileges, refer to Database Prerequisites.

• Note, in case of manual database creation with Oracle database, OpsHub database user ("db1") and OpsHub reports database user ("reportsdb") shall be created on the same server. At the time of installation, you need to provide the username and password for the database server.

• In case of Oracle database, passwords for the database users ("db1" and "reportsdb") shall be the same as the password of the server on which they are created.

• If you want to change the tablespace quota for OpsHub database "db1", following query can be used:

ALTER USER db1 QUOTA <size_of_tablespace> ON users;

Note: "db1" and "reportsdb" are the database/schema/database user names used in the above queries. You can name them differently as per your requirements.

Queries for PostgreSQL Database

• In case of manual database creation for PostgreSQL Server database, database and schema should be in lowercase only.

  • We need 1 database and 2 schemas to be created manually, out of which database and schema's names must be same for opshub database. The other schema will be created for reportsdb.

Let's say the name of the database is db1:

drop database IF EXISTS db1
db1 database: CREATE DATABASE db1
WITH
ENCODING = 'UTF8'
LC_COLLATE = 'en_US.UTF-8'
LC_CTYPE = 'en_US.UTF-8'
TEMPLATE = template0;

Note: The above query will create database with Collate United States, UTF-8. For creating database with desired collate, update LC_COLLATE and LC_CTYPE as per the requirement.

db1 schema: create schema db1;
Reports schema: create schema <schema_name>;

Here <schema_name> will be the schema name of reportsdb.

Collation change of MS SQL/Azure SQL Databases

If the user needs to change the collation of OpsHub Integration Manager's database, follow the below-mentioned steps:

Important Note

• When changing the collation, compare the code pages of the old and new collations to ensure that character representations are consistent and prevent data conversion issues. For example, changing Turkish_CS_AS collation to Latin1_General_CS_AS will convert "ı"(dott-less i) to "i".

• When considering a collation change, it's important to be aware about variations in character encoding and sorting rules between the old and new collation settings. Character conversion will occur during the process of collation change as mentioned in the above example. This conversion can lead to the irreversible loss of the original data.

Procedure:

1. Stop the OpsHub Integration Manager Server: Ensure the OpsHub Integration Manager server is not running.

2. Database Backup: Take a backup of the database.

3. Download Scripts: Download the provided script by clicking here.

4. SQL Editor: Open the SQL editor.

5. Changing the columns collation: Open the Migration Script file and replace YOUR_COLLATION_NAME with the collation name you would like to migrate to as the new collation. Execute the Migration Script and copy the generated SQL statements. Open a new window in SQL editor, paste those statements and execute them.

6. Database collation change: Open the Database Collation Change Script file and replace YOUR_COLLATION_NAME with the collation name you would like to migrate to as the new collation. Also, replace YOUR_DATABASE_NAME with the name of the database on which OpsHub Integration Manager is installed. Execute the script file.

7. Start OpsHub Integration Manager Server: Restart the OpsHub Integration Manager server.