Target Audience

Targeted audience for this document are:

• Users who would like to install and configure RMsis (Requirement Management Extension for JIRA)
• Users who would like to upgrade existing RMsis.

Assumptions

In this document, it is assumed that the readers are aware of JIRA and its basic configuration. For detailed information about JIRA, please refer (JIRA documentation).

Terminology

Following table describes the terms used in this document.

System Requirements

Hardware

RMsis can be installed on any server/machine where JIRA is installed. You would need a server class machine, as suggested by Atlassian for JIRA.

Software

RMsis Application Structure

RMsis 1.3.0 onwards

From version 1.3.0 onwards, it is not required to explicitly download and install RMsis. Administrators can install directly from Plugin Install option provided in the Administration menu. Internally, the plugin still comprises of two parts

• a plugin, which installs alongside JIRA.
• A separate RMsis application with it's own embedded Tomcat server.

RMsis 1.2.1 and older

If required, these versions of RMSis can be downloaded from http://products.optimizory.com/rmsis/download. The compressed downloaded file contains following files:

• rm.war: It is the RMsis web application.
• jira-rmsis-x.x.jar: It is the JIRA plugin, which connects RMsis application with JIRA
• setup.sh: Setup file for Linux/Unix
• setup.bat: Setup file for Windows
• sample-conf directory which contains sample database and mail configuration files
• README.txt: Contains basic README file. This file contains brief installation instructions.

Database Setup

For RMsis 1.3.0 onwards

Embedded H2 Database

From version 1.3.0 onwards, RMsis is shipped with H2 as embedded database. This can be configured during the process of RMsis application deployment.

For all versions of RMsis

MySQL

1. Open a unix terminal or a windows command prompt whichever is relevant to you. And login to MySQL database using the command line client that is shipped with the MySQL. Use "root" (administrator) credentials to login.
2. Create a database to store RMSis data. Use any name for it. Example - "rmsis".
3. Create a database user and assign permissions to this user to access the database created above.
4. Exit MySQL

$ mysql -uroot -ppassword
mysql> create database rmsis;
mysql> grant all on rmsis.* to 'username'@'hostname' identified by 'new_user_password';
mysql> exit;

Microsoft SQL Server 2005 / 2008

1. Create a database for RMsis (e.g. rmsis). Note that the collation type must be case insensitive, e.g.: 'SQL_Latin1_General_CP437_CI_AI' is case insensitive. If it is using your server default, check the collation type of your server.
2. Create a database user which RMsis will connect as (e.g. rmsisuser). Note that rmsisuser should not be the database owner, but should be in the db_owner role.
3. Create an empty 'schema' in the database (e.g. rmsisschema) for the RMsis tables. Please note that a 'schema' in SQL Server 2005 is a distinct namespace used to contain objects, and is different from a traditional database schema. It is not required to create any of RMsis tables, fields or relationships (RMsis will create these objects in empty schema when it starts for the first time). Read more on SQL Server 2008 schemas in the relevant Microsoft Documentation (http:/msdn2.microsoft.com/en-us/library/ms190387.aspx).
4. Ensure that the user has permission to connect to the database, and create and populate tables in the newly-created schema.
5. Ensure that TCP/IP is enabled on SQL Server and listening on the correct port (the port is 1433 for the default instance of SQL Server). Read the Microsoft documentation for information on how to enable a network protocol (TCP/IP) and how to configure SQL server to listen on a specific port.
6. Ensure that SQL Server is operating in the appropriate authentication mode. By default, SQL Server operates in 'Windows Authentication Mode'. However, if user is not associated with a trusted SQL connection, i.e. 'Microsoft SQL Server, Error: 18452' is received during RMsis startup, it is required to change the authentication mode to 'Mixed Authentication Mode'. Read the Microsoft documentation on authentication modes and changing the authentication mode to 'Mixed Authentication Mode'
7. Turn off the SET NOCOUNT option. Open SQL Server Management Studio and navigate to Tools -> Options -> Query Execution -> SQL Server -> Advanced. The following screenshot displays the configuration panel for this setting in MSSQL Server 2005/2008. Ensure that the SET NOCOUNT option is not selected:
8. Copy SQL server driver to application server.
9. Download the SQL Server JDBC driver (v1.2.3) from JTDS.
10. Add the SQL Server JDBC driver jar (jtds-1.2.3.jar) to the <Tomcat install>/lib/ directory.

License Activation

• After installation of RMsis, "RMsis" link will appear on JIRA menu bar.
• Clicking on the same will lead to the following screen

• Users can decide at this stage to go for
  
  • 1 month free trial
  • buy a license of their choice.
• The next steps are shown in the following sections

Generating Trial License

• The screen shows the system code for this RMsis instance.
• To generate license key, click on "RMsis Evaluation License Key"
• The CRM System will prompt you to
  
  • enter login information
  • OR create your login

• Once logged in, the system will seek input on  the number of users desired.
• Enter number of users, check "Terms and Conditions" and "Privicay Policy".

• Click on "Proceed", generates the license.
• Copy the license key from CRM and paste it in the text box given at the RMsis installation screen.

• Click the submit button. It will show license validity.

Buying a License

• To buy a Perpetual License Key, click on "Buy RMsis Production License Key"
• The CRM System will prompt you to
  
  • enter login information
  • OR create your login

• Once logged in, the system will seek input on  your choice of license.

• Select the Type of License, check "Terms and Conditions" and "Privicay Policy".
• Click on "Generate License and Proceed"
• You will get a Quotation for the choice and will be offered a choice of payment options
  • Credit Card / Paypal
  • Wire Transfer
• Pay using your preferred option

• Once you payment is received, the License will be automatically enabled.
• You can access the same by clicking in the Account > Generate License option.

• Select the license, you wish to generate.
• Enter the system code from your installation.
• Press Generate

• Once the license is generated, copy and paste into your installation.
• Pressing Submit, enables the new license

RMsis version upgrade is essentially in three steps

1. Save the base configuration and prepare for installation.
2. Install RMsis
   1. RMsis plugin can be installed through JIRA Universal Plugin Manager.
3. Upgrade RMsis
   1. Login as administrator in JIRA and then click on RMsis menu.
   2. You will be automatically redirected to Upgrade RMsis screen.

The entire sequence of upgrade process is elaborated below for different base (existing) versions.

Upgrading from V.1.3.0 and later

Prepare for upgrade

In order to upgrade existing RMsis with new version, please follow the steps mentioned below:

1. Take backup of existing database.

   • MySQL

     $ mysqldump -uroot -ppassword rmsis_database_name > backup_file.sql

     Note : For Microsoft SQL server 2005/2008 please refer http://msdn.microsoft.com/en-us/library/ms187048.aspx

Install the new version using JIRA Universal Plugin Manager

• Login as JIRA administrator and select Plugin > Plugin > Install
• Get the URL for the desired version of RMsis from http://products.optimizory.com/rmsis/download
• Click on Upload Plugin and enter the URL when prompted.

Upgrade

• After clicking on RMsis menu, the upgrade screen will appear.
• click on UPGRADE to proceed. You will be redirected to RMsis deployment step.

Deploy RMsis

Upgrading V.1.2.1 and older to V.1.3.0 and beyond

Prepare for upgrade

In order to upgrade existing RMsis with new version, please follow the steps mentioned below:

1. Stop JIRA and Tomcat.
2. Undeploy your rm.war from Tomcat Server
3. Take backup of existing database.

   • MySQL

     $ mysqldump -uroot -ppassword rmsis_database_name > backup_file.sql

     Note : For Microsoft SQL server 2005/2008 please refer http://msdn.microsoft.com/en-us/library/ms187048.aspx

4. Save your rm.war and jira-rmsis-x.x.x.jar, just in case you need to revert back to the old setup.

Install the new version using JIRA Universal Plugin Manager

• Login as JIRA administrator and select Plugin > Plugin > Install
• Get the URL for the desired version of RMsis from http://products.optimizory.com/rmsis/download
• Click on Upload Plugin and enter the URL when prompted.

Upgrade RMsis

• Enter your old RMsis home directory path in the above screen and then click on UPDATE RMSIS HOME button.
•  After clicking, RMsis will configure RMsis home directory inside JIRA home directory with using previous RMsis database and mail configuration.
• The following screen will appear:

 

Deploy RMsis

Upgrade License

Trouble Shooting and FAQ's

FAQ

What is RMsis base url?

If http://www.example.com is host, & tomcat server is running on port 8080 of this host; then RMsis base url(i.e. host ID) will be http://example.com:8080/rm/. RMsis base url may be different according to your deployment scenario.

Where are the log files located?

If you get an error, which log files should you share with us?

Logs files that you need to share in case of error are:-

• *Application Server Logs:*These logs files are generally located in logs folder of your application server. e.g. In case of Apache Tomcat, it is located in <CATALINA_HOME>/logs/ folder.
• JIRA Logs: These are located at <JIRA_HOME>/logs/ folder.
• RMsis Logs: These are located at <RMSIS_HOME>/logs/ folder.

Is the system code for RMsis same as the one for JIRA?

No, they are different.

Common Issues

I have JIRA installed on a different server and I have installation problems !

I have JIRA running on another server and I am getting one of the following errors:

• Unable to interpret JIRA response
• Invalid Base URL
• The log files contain one or more of the following errors, apart from the above
  • HttpClient error
  • Jira - RMsis not connected

One of the following may be the cause of error, please check if

• Firewall / Proxy is interfering with JIRA-RMsis communication.
• Port number is correctly specified in the base URL.

If your system reaches this state, then you will need to

• if you get an error database is in inconsistent state, drop the database
• fix the identified issue
• restart JIRA
• reinstall RMsis

Caution: If your system is already in use, please backup the database before trying out any fix.

I have upgraded RMsis, but now I cannot see any data !

Please clear the Tomcat Cache. This can be done by deleting the TOMCAT_HOME/work/Catalina/<HOST_NAME>/rm folder.

Listener Error

I am getting the following error while operating on issues java.lang.RuntimeException:com.atlassian.jira.event.ListenerException: Could not find class:com.optimizory.plugins.listener.RMsisListener

May be you have wrong listener configuration. To resolve this issue: -

• Open JIRA in your browser and login with administrator account
• Now go to Administration Menu and click on Listeners link under the system category
• If any listener shows up with name (RMsis Listener, com.optimizory.plugins.listener.RMsisListener) then delete this listener by clicking on the delete link corresponding to that listener

JIRA top navigation bar is showing multiple RMsis menus

You may have multiple JIRA plugins installed in the system. To resolve this issue : -

• Shutdown JIRA and remove previous versions of jira-rmsis plugin from JIRA_HOME/plugins/installed-plugins/ directory
• Restart JIRA again

RMsis is already connected to JIRA

I am getting the following error after clicking on RMsis. Error : RMsis is already connected to JIRA instance "XXXX-XXXX-XXXX-XXXX".

Detailed error in this case is as below: -
Error : RMsis is already connected to JIRA instance "XXXX-XXXX-XXXX-XXXX". It cannot be connected to this JIRA instance "YYYY-YYYY-YYYY-YYYY".
Please note that here "XXXX-XXXX-XXXX-XXXX" and "YYYY-YYYY-YYYY-YYYY" represent two different JIRA server IDs.
Typically this error is due to the fact that RMsis can be connected with only one JIRA instance. If one instance of JIRA is already connected and there is need to connect to another JIRA instance then please specify different database configuration for RMsis (in jdbc.properties file) and restart application server.

In order to use RMsis for both JIRA instances simultaneously, different RMsis instance and license keys would be required.

There is no log file in <RMSIS_HOME>/logs/ folder

This is because RMsis may not have permission to create / write a file in RMsis logs directory. You need to provide write permission to <RMSIS_HOME>/logs/ and will have to restart RMsis.

The RMsis initialization time is very high!

This problem has been fixed in Version 0.70 of RMsis. Please upgrade, if you are facing performance problems with each user login.

jar:command not found

I am getting the following error during setup; jar:command not found / 'jar' is not recognized as an internal or external command

Please check that you have JDK installed (Java development kit). If you have not installed JDK then install it and set the JDK path as follows:

• For linux/unix, run the command: export PATH=$PATH:path_to_your_jdk/bin/
• For windows, Please set the jdk (Java development kit)'s bin directory path in the environment variable "PATH"

Support

For any queries or unresolved issues, you can reach out to our support team support@optimizory.com and we will ensure a prompt response to your problem.