Oracle Retail Customer Engagement Cloud Service (Relate ... · Relate 11.1 Relate Installation Guide - Installer 6 Who Should Use This Guide This guide is intended for anyone responsible

Oracle® Retail Customer Engagement Cloud Service (Relate)Installation Guide - InstallerRelease 11.1E79518-01Revision 2

September 2016

Oracle® Retail Customer Engagement Cloud Service (Relate), Installation Guide - Installer, Release 11.1

Copyright © 2016, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are “commercial computer software” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Chapter 1: Introduction ................................................... 5Who Should Use This Guide................................................................................... 6

Related Documents .............................................................................................. 6

Supported Platforms ............................................................................................. 7Application Server Operating System...................................................................... 7

Database Server Software .................................................................................... 7

Required Materials ................................................................................................ 7

Installing Java Development Kit (JDK) Version 1.7.x ............................................ 8Modifying the Environment Variables (Windows) .................................................... 10

Modifying the Environment Variables (Linux) ......................................................... 12

Chapter 2: Installation ................................................... 13Overview ............................................................................................................. 13

Assumptions ........................................................................................................ 14Installation Process ............................................................................................. 14

Database Installation .......................................................................................... 15

SQL Server Installation....................................................................................... 15

Oracle Installation.............................................................................................. 24

Create the New Database ................................................................................... 33

SQL Server .................................................................................................. 33

Oracle ........................................................................................................ 34

Upgrade the Database........................................................................................ 35

SQL Server .................................................................................................. 35

Oracle ......................................................................................................... 35

Relate Installation ............................................................................................... 36Initial Configuration ........................................................................................... 48

Chapter 3: Initial Configuration ..................................... 49Overview ............................................................................................................. 49

C O N T E N T S

Table of Contents 3

Relate Installation Guide - Installer Relate 11.1

Segment Management Query Templates ............................................................. 50Start Relate Services ........................................................................................... 50

Log In .................................................................................................................. 51Perform Initial Configuration .............................................................................. 52Import Users and User Configurations (New Installation) ................................... 52

Import New Franchisee CSV File .......................................................................... 54

Import User CSV File.......................................................................................... 56

Import Roles CSV File......................................................................................... 58

Import Franchisee Assignment CSV File ................................................................ 59

Appendix A: Start/Stop Relate Services ......................... 61Overview ............................................................................................................. 61

Windows ............................................................................................................. 61

Service............................................................................................................. 61

Start ........................................................................................................... 61

Stop ........................................................................................................... 62

Non-Service ...................................................................................................... 62

Start ........................................................................................................... 62

Stop ........................................................................................................... 62

Linux ................................................................................................................... 63Start ................................................................................................................ 63

Stop ................................................................................................................ 63

Appendix B: Secure Sockets Layer (SSL) ........................ 64Overview ............................................................................................................. 64

Create the SSL Certificate .................................................................................... 65Enable SSL for Relate .......................................................................................... 67

Appendix C: Revision History ......................................... 71

4 Table of Contents

Introduction

The Relate Installation Guide - Installer provides the procedures and instructions necessary to perform either a full installation/configuration of the Relate application and its associated database, or an upgrade to Oracle Relate™ 11.1.

This document is intended only as a guide for a typical implementation. Since implementations will differ from customer-to-customer, it is up to the person performing the implementation to know when and how to deviate from this guide.

Refer to the following chapters for the information you need to get started:

Chapter 2, “Installation” on page 13, describes the installation and configuration of Relate Services and the database using an installer that will guide you through the entire installation process.

Chapter 3, “Initial Configuration” on page 49, provides instructions for configuring Relate Services after it has been installed.

Appendix A: “Start/Stop Relate Services” on page 61, provides instructions for starting and stopping Relate in Windows and Linux.

Appendix B: “Secure Sockets Layer (SSL)” on page 64 provides procedures for creating SSL certificates and enabling SSL in Relate.

C H A P T E R

The rebranding for the latest version of this documentation set is in development as part of post MICROS acquisition activities. References to former MICROS product names may exist throughout this existing documentation set.

If you are upgrading from a previous version of Relate earlier than version 11.0, please contact your project manager for more information.

5

Relate 11.1 Relate Installation Guide - Installer

Who Should Use This GuideThis guide is intended for anyone responsible for the installation and configuration of, or the upgrade to, Relate 11.1, including Operations Technical Support and Customer Technical Support.

Anyone using this guide should have a working knowledge of XML, the network system being used and, depending upon the environment and system you are using, SQL Server or Oracle database, and the Windows or the Linux operating system.

Related DocumentsThe following documents are part of the Relate CRM documentation suite and may be helpful when configuring/validating the Relate application. These documents can be found on the Relate 11.1 Installation CD-ROM in the /documentation directory.

Relate User Guide - The Relate User Guide provides the end user with instructions/details on how to use the Web Interface to the CRM Server. It aids the user by describing information required to perform an operation, what the information is used for (if necessary), and how different pieces of information interact with each other (if necessary).

Batch Processing & Web Services Guide - Provides users with information, examples, and guidelines needed to compose SOAP-based and XML messages for the Relate application (through batch file processing and the web interface), and how to integrate applications with Relate through WSDL interfaces.

Relate Database Dictionary - The Relate Database Dictionary provides users with a description of the Relate database tables, fields, relationship diagrams, and default data.

Relate Configuration Guide - The Relate Configuration Guide provides a description of the Relate configuration tool as well as instructions, requirements, and information concerning the configuration of the Relate application and database. The settings include both those set at the time of installation and those that may be changed at a later date.

6


Supported PlatformsThe following list describes the minimum requirements necessary to install and run Relate 11.1 and its associated database.

Application Server Operating System Windows Server 2008 R2 SP1 running a 64-bit Java Virtual Machine

OpenSuse version 12.3

At least 8 GB of RAM is required on the application server.

Database Server Software MS SQL Server 2012 SP1 (running on Windows Server 2008 R2 SP1)

Oracle 11gR2 - Release 11.2.0.2 (running on Windows Server 2012)

Required MaterialsThe following materials are required to complete the installation and configuration of the Relate application and the associated database.

Relate 11.1.xx Installation CD-ROM

Operating System (Installed)

Database Server (Installed)

Java™ SE Development Kit 7 (JDK version 1.7) (Installed)

For instructions on installing JDK 1.7, see “Installing Java Development Kit (JDK) Version 1.7.x” on page 8.

“Installed” means that the item must be installed before the Relate installation can begin.

Supported Platforms 7


Installing Java Development Kit (JDK) Version 1.7.xOracle’s Java Development Kit (JDK) is used for running Java applets and applications. The latest version of the kit can be downloaded from:http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

1. Check to see if there is an existing version of Java on the server by entering the following command:

C:\> java -version

2. The system will present the version number if there is an existing Java version. Note the version number of the Java version installed.

If nothing is returned, continue with next step.

If an older version exists (e.g. Java 1.6.x_xx) continue with next step.

If the command returns Java 1.7.x_xx, skip to “Modifying the Environment Variables (Windows)” on page 10.

3. Download and run the jdk-7uXX-windows-vvvv.exe application, where:

XX is the revision number.

vvvv is either i586 or x64, depending upon the system on which the installation is being performed.

The Java installer opens.

Figure 1-1: Java Installer

Similar steps will need to be performed in Linux to install the Java Development Kit (JDK) Version 1.7.x.

Installing Java Development Kit (JDK) Version 1.7.x 8


4. Click Next to continue.

The Choose Program Features step opens.

Figure 1-2: Choose Program Features

5. Click Next to perform the installation.

While performing the setup, accept all of the defaults.

The program installs Java SDK 7, which includes JDK 1.7, the Java FX SDK, the Java Runtime Environment (JRE), and the Java plug-in on the web server.

6. Click Finish to complete the JDK installation.

Figure 1-3: Finish Installation

Once the JDK has been installed, add an Environment Variable for Java and add the Java directories to the web server's path.



Modifying the Environment Variables (Windows)Update the server's Environment Variables and path by performing the following:

1. In the Start menu, select Control Panel.

2. If Control Panel is organized by category, click to open System and Security.

3. Click System.

4. Click the Advanced system settings link on the left side of the window.

The System Properties window opens on the Advanced tab.

5. Click the Environment Variables button.

The Environment Variables window opens.

6. Check to see if the JAVA_HOME variable already exists.

If the variable does not exist, continue with the next step.

If the variable does exist, check whether its value is c:\Program Files\Java\jdk1.7.0_XX (where XX is the revision number).Note: The short name cannot be used here.

If the variable exists, but the value is not correct, continue with step 12.

If the value is correct, continue with step 15.

7. In the System Variables pane, click New to open the New System Variable dialog box.

Figure 1-4: Add New System Variable

The path may differ if you installed the JDK to a directory other than the default.



8. Enter JAVA_HOME in the Variable name field. Ensure that the variable name is all upper case.

9. Enter c:\Program Files\Java\jdk1.7.0_XX, where XX is the revision number. If the JDK has been installed somewhere other than in c:\Program Files, enter the absolute path to the \jdk1.7.0_XX directory.

10. Click OK to save the system variable information.

Continue with step 15.

11. If the JAVA_HOME variable exists, but is not set to the correct value, click the JAVA_HOME variable in the System Variables list to select it.

12. Click Edit.

The Edit System Variable window opens.

Figure 1-5: Edit Java Home

13. In the Variable value field, enter c:\Program Files\Java\jdk1.7.0_XX, where XX is the revision number. If the JDK has been installed somewhere other than in c:\Program Files, enter the absolute path to the jdk1.7.0_XX directory.

14. Click OK to save the system variable information.

Continue with the next step.



15. While in the Environment Variables window, from the System Variables pane, click to highlight the Path system variable, then click Edit.

Figure 1-6: Edit Path

16. Check whether the value %JAVA_HOME%\bin already exists. If it does, you are finished with this procedure.

Otherwise, continue with the next step.

17. In the Edit System Variable dialog box, click to place the cursor in the Variable value field, then press the [End] key. This places the cursor at the end of the path.

18. Append the following to the end of the value in the Variable value field:

;%JAVA_HOME%\bin

19. Click OK to save the System Variables.

20. In the Environment Variables window, click OK to save the Environment Variable information.

21. Exit the Control Panel.

Modifying the Environment Variables (Linux)Several commands must be run to prepare Java for Relate. However, the commands required for setting environment variables in Linux will depend upon the Linux distribution used, the shell used, and the installation directory for Java. Therefore, you will need to determine the commands required to perform the following tasks.

1. Check whether the $JAVA_HOME variable is set to the jdk1.7.0_XX directory. If it is not, set $JAVA_HOME to the absolute path to the jdk1.7.0_XX directory.

2. Check whether the $PATH variable includes the $JAVA_HOME\bin value. If it does not, add $JAVA_HOME\bin to the $PATH variable.


InstallationOverviewThis chapter describes:

The installation procedure for Relate 11.1.

The upgrade procedure for Relate 11.1 from an earlier version.

C H A P T E R

This installation will not completely configure Relate, it will only configure the system settings. The rest of the settings must be configured before Relate can be used. See Chapter 3, “Initial Configuration” on page 49 and the Relate Configuration Guide for more information.

Overview 13


AssumptionsThis chapter assumes the following:

The host computer has a server Operating System (OS) installed (see “Application Server Operating System” on page 7).

Java Development Kit (JDK) 1.7.x has been installed.

The database software (see “Database Server Software” on page 7) has been installed.

Information such as Organization ID, database name, database username/password, etc. is available.

An SSL certificate is available for Relate (“Create the SSL Certificate” on page 65).

Installation ProcessThe installation process consists of the following steps:

1. Run the database installer for your database.

If you are installing an SQL Server database, see “SQL Server Installation” on page 15.

If you are installing an Oracle database, see “Oracle Installation” on page 24.

2. Create or upgrade the database.

If you are creating a SQL Server database, see “SQL Server” on page 33.

If you are creating an Oracle database, see “Oracle” on page 34.

If you are upgrading a SQL Server database, see “Upgrade the Database” on page 35.

3. Run the Relate installer (see “Relate Installation” on page 36).

4. Configure the software (see Chapter 3, “Initial Configuration” on page 49).

New installations of Relate require an SSL certificate. Upgrades do not require an SSL certificate.

Assumptions 14


Database Installation

SQL Server Installation

Use the following procedure to install a SQL Server database:

1. Insert the Database Installation CD into the CD-ROM drive.

Figure 2-1: Welcome Screen

If the Installer does not automatically start:

a. Open a browser and navigate to the CD drive.

b. Double-click the Relate-db-11.1.00.xx.exe file.

The Welcome screen will be displayed.

c. Click Next to move to the next step.

At any time during the installation process, click Cancel to exit the process without saving any settings that may have been entered.

A SQL Server database installation can only be performed by the Windows installer. The Linux database installer does not include the option to install a SQL Server database.

A SQL Server database server should not be used with a Linux application server. This configuration is not supported and may result in unpredictable behavior in Relate.

Database Installation 15


2. If necessary, change the Installation Directory. Click Next to move to the next step.

Figure 2-2: Installation Directory

To browse for a directory, do the following:

a. Select the folder icon next to the entry field. A Browse for Folder window opens.

Figure 2-3: Browse for Folder

b. Navigate through the directory structure to locate the proper folder.

c. Click on the folder to select it, then click OK.

The full path of the folder appears in the entry box.

If the entered directory exists, the installation program will display a warning message that the existing directory will be renamed. Click OK to confirm the message and continue.



3. Click the checkbox for the database and installation type you are performing. Click Next to move to the next step.

Figure 2-4: Select Components

a. If this is a new installation for SQL Server:

1) Check SQL Server - New Install.

2) Click Next, then continue with step 5.

b. If this is an upgrade installation for SQL Server:

1) Check SQL Server - Upgrade.

2) Click Next, then continue with the next step.

Select one, and only one, database component.



4. Enter the name of the Relate database. Click Next to continue with step 9 on page 22.

Figure 2-5: Database Information

5. Enter the following information for your organization:

Figure 2-6: Organization Info

a. Organization ID (Numeric) - The 3-digit identification number assigned to your organization.

b. Three Letter Company ID - This 3-character company ID is also assigned to your organization.



When you are finished, click Next to move to the next step.

6. Define the database information.

Figure 2-7: Database Information (New Install)

a. Enter the Relate Database Name.

b. Select the Database Recovery Model: Full or Simple.

c. Select whether you are performing a Simple or Advanced database file configuration, then click Next to continue with the next step.

Simple - All database files are placed in a single specified directory.

Advanced - Different database files are placed in separate directories that are specified individually.

d. Click Next to continue.

If you selected Simple database file, continue with the next step.

If you selected Advanced database file configuration, continue with step 8.



7. Select the location of the database files, then click Next to continue with step 9.

Figure 2-8: Database File Locations - Simple







d. Click Next to continue with step 9.



8. If you selected Advanced database file configuration in step c:

Figure 2-10: Database File Locations (SQL Server)

a. Select the locations for the database files.


1) Select the folder icon next to the entry field. A Browse for Folder window opens.


2) Navigate through the directory structure to locate the proper folder.

3) Click on the folder to select it, then click OK.


b. Enter the database owner credentials:



1) Relate Database Username - This will be used by Relate to connect to the database.

2) Relate Database Password - Password for the username.

3) Confirm Password - If this does not match the password already entered, a dialog box is displayed with a warning. Click OK to return to the Relate User Credentials screen.

When you are finished, click Next to continue.

9. Click Next to begin the installation. When the installation is complete, the Finish screen is displayed.

Figure 2-12: Ready to Install



10. Click Finish to close the Installation Wizard.

Figure 2-13: Installation Complete



Oracle Installation

Use the following procedure to install an Oracle database:

1. Insert the Database Installation CD into the CD-ROM drive.




b. Run the installation program for your operating system:

Windows - Double-click the Relate-db-11.1.00.xx.exe file.

Linux - Double-click the Relate-db-11.1.00.xx.run file.

The Welcome screen will be displayed.


At any time during the installation process, click Cancel to exit the process without saving any settings that may have been entered.

The look and feel of the installer and installation paths entered will be different if you are installing in a Linux environment; however, the steps will mostly be the same.



2. If necessary, change the Installation Directory. Click Next to continue with the next step.








If the entered directory exists, the installation program will display a warning message. Click OK to confirm the message and continue.



3. Click the checkbox for the database and installation type you are performing. Click Next to move to the next step.

Figure 2-17: Select Components

a. If this is a new installation:

1) Check Oracle - New Install.


b. If this is an upgrade installation for Oracle:

1) Check Oracle - Upgrade.


Select one, and only one, database platform.

The Linux database installer will only provide the “Oracle” options.



4. Complete the following information for your organization:

Figure 2-18: Organization Info

a. Organization ID - The 3-digit identification number assigned to your organization.

b. Three Letter Company ID - This 3-character company ID is also assigned to your organization.

When you are finished, click Next to move to the next step.



5. Select whether you are performing a Simple or Advanced database file configuration, then click Next to continue.

Figure 2-19: Simple or Advanced Database File Locations

Simple - All database files are placed in a single specified directory.

After selecting Simple, click Next to continue with the next step.

Advanced - Different sets of database files are placed in separate directories that are specified individually.

After selecting Advanced, click Next to continue with step 7.



6. Select the location of the database files, then click Next to continue with step 8.

Figure 2-20: Database File Locations - Simple

a. Select the locations for the database file.







b. Enter the login credentials for the user RELATE:

1) Relate Database Password - Password for the RELATE username.



2) Confirm Password - If this does not match the password already entered, a dialog box is displayed with a warning.

c. Enter the login credentials for the user RELATE_USER:

1) Relate User Database Password - Password for RELATE_USER username.


When you are finished, click Next to continue with step 8.

7. Select the locations of the database files.

Figure 2-22: Database File Locations - Advanced

a. Select the locations for the database file.









b. Enter the login credentials for the user RELATE:

1) Relate Database Password - Password for the RELATE username.


c. Enter the login credentials for the user RELATE_USER:

1) Relate User Database Password - Password for RELATE_USER username.


When you are finished, click Next to continue with the next step.



8. Click Next to begin the installation. When the installation is complete, the Finish screen is displayed.


9. Click Finish to close the Installation Wizard.

Figure 2-25: Installation Complete



Create the New Database

This process will create a new Relate database. This sample database contains tables, fields, etc. for Relate to use.

SQL Server

1. Locate the database creation files. These files are located in the sqlserver directory within the directory specified in step 2 of the “Database Installation” on page 15 procedure.

2. Open the file 01CreateDB.sql using your database interface software (e.g. SQL Server Management Studio).

3. Execute the script 01CreateDB.sql.

The database is created.

4. Open and execute the script 02CreateUser.sql.

Usernames and passwords for the database are created.

5. Open and execute the script 03CreateRelate.sql.

Database tables are created.

6. Open and execute the script 04LoadData.sql.

Sample data is loaded into the Relate database.

7. Open and execute the script 05OrgID.sql.

Organization information is set in the Relate database.

8. Open and execute the script 06InsertReports.sql.

Reports are created for Relate.

If you selected an Upgrade installation option in the Relate Database Setup Wizard, do NOT perform the procedures in this section. Proceed to “Upgrade the Database” on page 35.

Look for errors after running each of the following scripts. If any errors occur, contact your product representative for assistance.



Oracle

1. Locate the database creation files. These files are located in the oracle directory within the directory specified in step 2 of the “Database Installation” on page 15 procedure.

2. Open the file 01CreateTBS.sql using your database interface software (e.g. sqlplus).

3. Execute the script 01CreateTBS.sql.

The tablespaces are created.

4. Open and execute the script 02CreateUsers.sql.

Usernames and passwords for the database are created.

5. Open and execute the script 03CreateRELATE.sql.

Database tables are created.

6. Open and execute the script 04LoadQRTZRS.sql.

Quartz locks are set.

7. Open and execute the script 05OrgID.sql.

Organization information is set in the Relate database.

8. Open and execute the script 06InsertReports.sql.

Reports are created for Relate.

9. As the sysdba user, run the following command in Oracle:

GRANT EXECUTE on sys.dbms_crypto to public;

Look for errors in the log files after running each of the following scripts. If any errors occur, contact your product representative for assistance.

The name of the log file is similar to the name of the script, though without a number at the beginning, and with a file extension of .log. For example, the log file for 01CreateTBS.sql is CreateTBS.log.

The script 05OrgID.sql does not create a log file.

The script 06InsertReports.sql does not create a log file.



Upgrade the Database

In this section you will run database scripts that will upgrade the existing database.

SQL Server

1. Locate the database creation files. These files are located in the sqlserver directory within the directory specified in step 2 of the “Database Installation” on page 15 procedure.

2. Open the file db-updates.sql using your database interface software (e.g. SQL Server Management Studio).

3. Execute the script db-updates.sql.

The database schema is updated for Relate 11.1.

Oracle

1. Locate the database creation files. These files are located in the oracle directory within the directory specified in step 2 of the “Database Installation” on page 15 procedure.

2. Open the file db-updates.sql using your database interface software (e.g. sqlplus).

3. Execute the script db-updates.sql.

The database schema is updated for Relate 11.1.

If you selected a New Installation option in the Relate Database Setup Wizard, do NOT perform the procedure in this section. Go to “Create the New Database” on page 33, or proceed to “Relate Installation” on page 36 if you have already created the database.



Upgrades on Oracle will only succeed if the current version of Relate was installed by the 11.0 installer.

The upgrade scripts should be run by Oracle’s Relate user.



Relate InstallationThis procedure will install the Relate software.

1. Insert the Application Installation CD into the CD-ROM drive.




b. Run the installation program for your operating system:

Windows - Double-click the Relate-11.1.00.xx.exe file.

Linux - Double-click the Relate-11.1.00.xx.run file.


A SQL Server database server should not be used with a Linux application server. This configuration is not supported and may result in unpredictable behavior by Relate.

Relate Installation 36


2. If necessary, change the Installation Directory from the default. If you are performing an upgrade, this directory must be set to the path in which Relate is currently installed.


Click Next to continue:

If Relate is already installed on your system, continue with the next step.

If you are installing Relate on a Windows system, and Relate is not installed on your system, continue with step 4.

If you are installing Relate on a Linux system, and Relate is not installed on your system, continue with step 6.

If this is an upgrade, the path should be set to the directory where Relate is currently installed.

If you change the installation directory, the path cannot contain any spaces. If the path contains spaces, the installation will fail.



3. If the Installer detects another instance of Relate, the screen shown below will be displayed.

If this screen does not appear, and you are not performing an upgrade, continue with step 4 (Windows) or step 6 (Linux).

Figure 2-28: Previous Version Detected

a. If the previous version is Relate 11.0 and you wish to continue, click Next. The Installer will do the following:

Stop Relate if it is currently running (Windows Only).

Delete the services (Windows Only).

Rename the existing <install_directory> to <install_directory>.preupg.

Continue with step 4.

b. If the previous version is not Relate 11.0:

1) Contact your project manager for assistance.

2) Click Cancel and then OK when asked if you want to stop.

c. If you do not wish to continue, click Cancel, then click OK when asked if you want to stop.



4. Enter the following information (Windows Only):

Figure 2-29: Service Username and Password

a. Service Username - Enter the Windows Username under which the Relate service will run (Administrator, SYSTEM (recommended), Root, etc.).

The user name must be in the form DOMAIN\USERNAME.

b. Service Password - Enter the Password for the Username in the Service Password text box.

c. Confirm Service Password - Enter the Password a second time in the Confirm Service Password text box.

If this does not match the password already entered, a dialog box is displayed with a warning. Click OK to return to the Service Logon Information screen.

d. Click Next to move to the next step:

If this is a new installation, continue with the next step.

If this is an upgrade installation, continue with step 10.

If the account is local, the DOMAIN portion is the name of the local machine.



5. Enter the SSL configuration information:

Figure 2-30: Service Logon Information

a. Enter the full path for the Java Keystore File (see “Create the SSL Certificate” on page 65 for more information).

b. Enter the SSL Key Alias. This is the alias used by Relate.

c. Enter the Keystore Password used to access the keystore.

d. Re-enter the password in the Confirm Keystore Password file.

e. Click Next to continue with the next step.

If you place the keystore file with the filename relate.keystore in the same directory as the installer program, this field will be populated automatically. The installer will then place the keystore file in the ssl directory of the Installation Directory (see step 2).

This will value will depend upon the configuration of your system.

In the line commands given in the procedure “Create the SSL Certificate” on page 65 in Appendix B: “Secure Sockets Layer (SSL)”, the alias is tomcat.



6. Select the database you will be using. Click Next to move to the next step.

Figure 2-31: Database Engine

If you selected Oracle, continue with the next step.

If you selected Microsoft SQL Server, continue with step 8.

A SQL Server database server should not be used with a Linux application server. This configuration is not supported and may result in unpredictable behavior.



7. If you selected Oracle as your database, enter the database information:

Figure 2-32: Database Information (Oracle)

a. Database Server Hostname - Name of the server.

b. TCP Port on the Database Server - This is typically “1521”, but if you are going to use another port, enter the number here.

c. Oracle SID - The SID for Oracle.

d. Database Password - Used by Relate to connect to the relate_user database account.

e. Confirm Password - If this does not match the password already entered, a dialog box is displayed with a warning. Click OK to return to the Database Credentials screen.

When you are finished, click Next to continue with step 9.



8. If you selected Microsoft SQL Server as your database, enter the database information:

Figure 2-33: Database Information (SQL Server)

a. Database Server Hostname - Name of the server.

b. TCP Port on Database Server - This is typically “1433”, but if you are going to use another port, enter the number here.

c. SQL Server Instance - SQL Server Instance to use. If necessary, leave this field blank.

d. Database Name - This must agree with the database name you used when installing the database.

e. Database Username- This will be used by Relate to connect to the Relate database.

f. Database Password - Used by Relate to connect to the Relate database.

g. Confirm Password - If this does not match the password already entered, a dialog box is displayed with a warning. Click OK to return to the Database Credentials screen.

When you are finished, click Next to continue with the next step.



9. Enter the Organization Information:

Figure 2-34: Organization Information

a. Organization ID - This is the identification number assigned to your organization. This must match the Organization ID you provided in the Database Installer.

b. Descriptor - This is the 3-Letter company code assigned to your organization. This must match the Company ID you provided in the Database Installer.

c. Enter the necessary information for the superuser. Click Next to move to the next step.

1) User ID - The username to use when logging into the system as the superuser.

2) Password - The password to use when logging into the system as the superuser.

3) Confirm - Confirm the password for the superuser.

If this does not match the password already entered, a dialog box is displayed with a warning. Click OK to return to the Relate Super User Credentials screen.

4) E-Mail Address - The e-mail address to which Relate will send all messages to be delivered to the superuser.

5) Click Next to move to the next step.

When Relate 11.1 runs for the first time, this will be the only user who can log into the system.



10. Configure Relate services. Click Next to continue with the next step.

a. If necessary, update the memory allocations for Relate services.

b. If necessary, click to enter a checkmark ( ) in the Start Relate Services checkbox to start Relate services when installation is finished.

When you are finished, click Next to continue:

New Installation - Continue with step 12.

Upgrade Installation - Continue with the next step.

Figure 2-35: Relate Services Memory Allocation (Windows and Linux New

Installation)

Figure 2-36: Relate Services Memory Allocation (Linux Upgrade)

Speak with your product representative to determine the proper values to enter in these fields.



11. If you are performing an upgrade installation, confirm the upgrade by clicking Next to continue with the next step.

Figure 2-37: Upgrade Confirmation

12. Click Next to start the installation process. This process will install the files necessary to run Relate and configure the system settings.




13. After the installation is complete, if you selected the option to start services in step 10, the Installer alerts you that the services will take some time to start. Click Next to complete the Relate installation.

Figure 2-39: Installation Finished

14. Click Finish to complete the Relate setup.

Figure 2-40: Complete Relate Setup Wizard



Initial ConfigurationRefer to Chapter 3, “Initial Configuration” on page 49 for instructions on the initial configuration of Relate.


Initial ConfigurationOverviewThis procedure describes the initial configuration of Relate following installation.

The following tasks need to be performed in order to configure Relate:

“Start Relate Services” on page 50

“Log In” on page 51

“Perform Initial Configuration” on page 52

C H A P T E R

If Relate 11.1 has not been installed, configuration cannot be performed. Perform the installation procedure inChapter 2, “Installation” on page 13 before performing the actions in this chapter.

Overview 49


Segment Management Query TemplatesQuery templates for Segment Management are now in a different location and use a different format than previous versions of Relate. If you are upgrading from Relate 11.0 and you have customized Segment Management query templates, these customizations must be migrated properly to be available in Relate 11.1.

The values in the current query template file(s) must be configured in the file(s)

\srv\relate-services-deploy\apache-tomcat\webapps\relateui#ORG\qry_resource_XX.js

where ORG is the Organization ID and XX is the two-letter ISO language code (upper-case) for the properties being set.

Start Relate ServicesIf Relate Services is not running, start the application or service. See Appendix A: “Start/Stop Relate Services” on page 61 for more information.

Speak with your product representative before attempting to move these configurations to Relate 11.1 from a previous version.

Each Organization on the server has a separate directory for these configurations. The universal configuration used in earlier versions of Relate must now be configured for each Organization.

After configuring the new file(s), back up the new file(s) in a safe location. These directories will be overwritten if you redeploy the .WAR files.

Segment Management Query Templates 50


Log InUse the following procedure to log into the Relate application:

1. Use a Web Browser to navigate to the URL provided at the time of installation (similar to: http://<hostname>:<port_number>/relateui/<ORG_ID>/).

The Relate login page is displayed.

Figure 3-1: Relate Login

2. Enter your username in the Username field.

3. Enter password in the Password field.

4. Click the Login button, or press the [Enter] key.

The Relate main page opens.

Figure 3-2: Relate Main Page

Log In 51


Perform Initial ConfigurationInitial configuration will need to be performed before Relate is ready for use. This configuration includes such requirements as adding organizations, adding and configuring users, creating Role Groups, and making additional configuration changes to Relate. These configuration changes are described in the Relate Configuration Guide.

See also: The Relate Configuration Guide for a full description of configuration procedures and the configuration options available.

Import Users and User Configurations (New Installation)If the Relate installation is a new installation, User data may be imported through comma-separated values (CSV) files. These files can be created programmatically from an existing database, allowing Users to be easily moved to Relate.

To import Users into Relate, do the following:

1. Import Franchisees into Relate (if Relate is configured to use Franchisees):

a. Create the Franchisees CSV file:

The Create Franchisees CSV file will have the following line format for each new Franchisee:

FRANCHISEE_ORG_NAME,FRANCHISEE_ORG_DESCRIPTION

where:

FRANCHISEE_ORG_NAME - Is the name of the Franchisee.

FRANCHISEE_ORG_DESCRIPTION - Is a description of the Franchisee.

b. Import the Franchisee CSV file. See “Import New Franchisee CSV File” on page 54 for a description of the procedure.

2. Import Users into Relate:

a. Create the Users CSV file.

The Users CSV file will have the following line format for each new User:

USR_EMAIL,USR_LNAME,USR_FNAME,USR_LANGCODE,USR_ID,USER_LOCATION_ID,COUNTRY_CODE

where:

The first line in a Create Franchisees CSV file must define the Location ID for a user. The next lines will then be used to add as many Franchisee IDs as desired.

Perform Initial Configuration 52


USR_EMAIL - User email address.

USR_LNAME - User last name.

USR_FNAME - User first name.

USR_LANGCODE - ISO language code for the User’s default language.

USR_ID - Unique ID for the User.

USER_LOCATION_ID - Unique ID for the User’s Location.

COUNTRY_CODE - ISO country code for the User’s country.

b. Import the User CSV file. See “Import User CSV File” on page 56.

3. Import Roles into Relate:

a. Create the Roles CSV file.

The Roles CSV file will have the following line format for each Role assigned to a User:

ROL_EMAIL,ROL_ROLENAME,ROL_USR_ID

where:

ROL_EMAIL - Email address of the User being assigned the Role.

ROL_ROLENAME - Name of the Role.

ROL_USR_ID - ID of the User being assigned the Role.

b. Import the Roles CSV. See “Import Roles CSV File” on page 58.

4. Import the Franchisee Assignments in Relate:

a. Create the Franchisee Assignment CSV file.

The Franchisee Assignment CSV file will have the following line format for each Franchisee assignment:

FRANCHISEE_EMAIL,FRANCHISE_ORGNAME,FRANCHISE_LOCFLAG,FRANCHISEE_USR_ID

where:

FRANCHISEE_EMAIL - Email address of the User being assigned to the Franchisee.

FRANCHISE_ORGNAME - Name of the Franchisee, or the ID of the Location to which the User is assigned. The value in this field depends upon the value of the FRANCHISE_LOCFLAG.

FRANCHISE_LOCFLAG - This flag indicates the information included in the FRANCHISE_ORGNAME field.

TRUE - The FRANCHISE_ORGNAME contains the ID of the Location to which the User will be assigned.

The Roles Relate_SystemAdmin and Relate_UserAdmin cannot be assigned to a User through the import process.

Import Users and User Configurations (New Installation) 53


FALSE - The FRANCHISE_ORGNAME contains the name of the Franchisee to which the User will be assigned.

FRANCHISEE_USR_ID - ID of the User being assigned to the Franchisee.

5. Import the Franchisee Assignment CSV file. See “Import Franchisee Assignment CSV File” on page 59.

Import New Franchisee CSV File

Use the following procedure to import a Franchisee comma-separated values (CSV) file:

1. In the System menu for Relate, click Franchisees.

Figure 3-3: System Menu

Only perform this procedure if Franchises are enabled in Relate.

Users must be assigned the Relate_SystemAdmin role or the Relate_UserAdmin role to perform this procedure.



The Franchisees page opens.

Figure 3-4: Franchisees Page

2. In the ACTIONS menu, click IMPORT FRANCHISEE CSV FILE.

Figure 3-5: Import Franchisee CSV File

3. A Choose a CSV File window opens.

Figure 3-6: Choose a CSV File Window

4. Click the Browse... button.

The file selection process for an upload file begins. The procedure for selecting a file depend upon the operating system and browser being used. See the documentation for the operating system and browser for more information about selecting a file for upload.

5. Click the Import button.



The data is imported into Relate. When the data has been imported, confirmation of the successful import is displayed.

Figure 3-7: Import Success Confirmation

6. Click the X ( ) to close the window.

Import User CSV FileUse the following procedure to import a User-related comma-separated values (CSV) file:

1. In the System menu for Relate, click Import Users CSV File.


You must be assigned the Relate_SystemAdmin role or the Relate_UserAdmin role to perform this procedure.



The Import User CSV File page opens.

Figure 3-9: Import Users CSV File Page



3. After selecting a file, click the Import button.



4. Click the red X ( ) to close the tab.



Import Roles CSV FileUse the following procedure to import the user roles in a comma-separated values (CSV) file:














Import Franchisee Assignment CSV FileUse the following procedure to import the franchisee assignments in a comma-separated values (CSV) file:















Start/Stop Relate ServicesOverviewThis chapter describes the procedures for starting and stopping Relate Services.

How you start and stop Relate Services depends on whether you are running it as a Windows service, as a Windows non-service application, or as a Linux application.

Windows

Service

StartUse the following procedure to start Relate Services where Relate is a Windows service:

1. In the Start menu, open the Control Panel.


3. Open Administrative Tools.

4. Double-click Services to open the Services window.

5. Click to select the RelateServices service.

6. Click the Start Service button ( ).

or

1. Open a command prompt.

2. Run the following command to start Relate Services:

net start relateservices

3. Wait 5-15 minutes to give the processes time to fully start.

A P P E N D I X

Overview 61

APPENDIX A: Start/Stop Relate Services Relate 11.1

StopUse the following procedure to stop Relate Services where Relate is a Windows service:

1. In the Start menu, open the Control Panel.


3. Open Administrative Tools.

4. Double-click Services to open the Services window.

5. Click to select the RelateServices service.

6. Click Stop Service button ( ).

7. Wait 1-5 minutes to give the process time to fully shut down.

or


2. Run the following command to stop Relate Services:

net stop relateservices


Non-Service

StartUse the following procedure to start Relate Services where Relate is not a Windows service:


2. Change the working directory to Tomcat’s bin directory.

cd \srv\relate-services-deploy\apache-tomcat\bin\

3. Start Relate Services by running:

.\startup.bat


StopUse the following procedure to stop Relate Services where Relate is not a Windows service:



cd \srv\relate-services-deploy\apache-tomcat\bin\

3. Stop Relate Services by running:

.\shutdown.bat


62 Windows


Linux

StartUse the following procedure to start Relate Services:



cd /srv/relate-services-deploy/apache-tomcat/bin/

3. Start Relate Services by running:

./startup.sh


StopUse the following procedure to stop Relate Services:



cd /srv/relate-services-deploy/apache-tomcat/bin/

3. Shut down Relate Services by running:

./shutdown.sh

4. Wait 1-5 minutes to give the processes time to fully shut down.

Linux 63

Secure Sockets Layer (SSL)OverviewSecure Sockets Layer (SSL) is a protocol that uses public key encryption to protect sensitive information in communications over the internet.

This chapter provides instructions for enabling SSL for use with Relate. The person(s) performing this procedure should be familiar with internet protocols, SSL, and how SSL is used on the internet.

A P P E N D I X

Relate supports alternate ports for SSL and non-SSL connections.

Overview 64

APPENDIX B: Secure Sockets Layer (SSL) Relate 11.1

Create the SSL CertificateThe following procedure to create an SSL certificate will create a file named relate.keystore in the directory where the commands are

To create an SSL certificate for Relate in Windows, do the following:


2. Change to the directory where the keystore file should be located.

3. Create a new, self-signed certificate:

a. Run the following command:

keytool -genkey -alias tomcat -keyalg RSA -dname “cn=[hostname]”-validity [duration]

where:

[hostname] is the system name (localhost may not work on some systems).

[duration] is the number of days for which the certificate will be valid.

b. When prompted, enter a password for the keystore. You may use any password of your choosing.

It is recommended that you locate the file in the same directory where the Relate installer is/will be located. See step 5 on page 40 of the Relate Installation procedure.

You can override the default keystore location by adding a -keystore parameter to the command. If you do change the default location, make sure it agrees with the configuration setting.

The command-line options are the following:

genkey - Tells the keytool application to generate a new public/private key pair.

alias - The name used to refer to the Relate Services keys.

keyalg - Specifies the algorithm to use when generating the keys.

dname - Distinguished name.

validity - Specifies the number of days for which the key is valid. The key being created will only last for 90 days unless you use the “-validity xxx” switch to extend this length of time. At the end of this period, the key will need to be renewed.

65 Create the SSL Certificate


c. Press Enter to use the same password for the alias.

Figure B-1: Create Keystore (Windows)

4. Extract the newly created self-signed certificate from the keystore to a local file:

a. Run the command to export the certificate:

Windows

keytool -export -alias tomcat -file [path]\relate.keystore

Linux

keytool -export -alias tomcat -file [path]/relate.keystore

where:

[path] is the full destination path for the certificate file.

b. When prompted for the keystore password, enter the password you entered in the previous step.

Figure B-2: Export Certificate (Windows)

5. Import the certificate into the Java cacerts file:

a. Run the command to import the certificate:

Windows

keytool -import -alias relate -file [path]\relate.keystore -keystore [java_path]/cacerts

Linux

keytool -import -alias relate -file [path]/relate.keystore -keystore [java_path]/cacerts

It is recommended that you put the relate.keystore file in the same directory as the Relate Installer. This will allow the installer to automatically locate the file (see step 5 on page 40 of the Relate Installation procedure).

You can put this file anywhere you would like by specifying the appropriate path. It is important to remember the file location and the file name.

Create the SSL Certificate 66


where:

[path] is the full destination path for the certificate file.

[java_path] is the full destination path for the Java cacerts file.

b. Enter the keystore password when prompted.

c. Press the [y] key, then press the [Enter] key to confirm that you trust the certificate.

The certificate is now installed.

Enable SSL for RelateUse the following procedure to enable SSL for Relate Services:

1. Create the SSL Certificate.

2. Configure the Relate Services SSL Keystore File, Relate Services SSL Password, and Relate Services SSL Connector Port settings in Conflate:

a. Open a file browser and navigate to c:\srv\conflate (Windows) or /srv/conflate (Linux).

b. Double-click the conflate.jar file.

The Conflate Main window opens.

Figure B-3: Conflate Main Window

67 Enable SSL for Relate


c. Click Edit Configs.

The Edit Configs window opens.

Figure B-4: Edit Configuration Window

d. Make sure the “General” tab is selected.

e. Open the System/Relate Services category and select Relate Services SSL KeyStore File.

f. Type in the File URI for, or use the browser button to navigate to, the directory where the keystore file is located.

If you choose to type in the File URI; it must start with “File:/”, each space in the path must be replaced with “%20”, and backslashes cannot be used.

Figure B-5: Relate Services SSL Keystore File Setting

Enable SSL for Relate 68


g. If you choose to use a password for your Keystore file other than the default (“changeit”), perform the following steps:

Figure B-6: Relate Services SSL Keystore Password Setting

1) Select Relate Services SSL Keystore Password.

2) Type in the password.

h. If you choose to use a network port for SSL web service requests other than the default (8443), do the following:

Figure B-7: Relate Services SSL Connector Port Setting

1) Select Relate Services SSL Connector Port.

2) Enter the new network port number.

i. Click Save.

j. Click Close.

k. Click Deploy.

Click Yes when asked “Configure Relate with the current settings?”.

l. Click Close to close the Conflate Main window.

3. Restart Relate Services (see Appendix A: “Start/Stop Relate Services” on page 61).

69 Enable SSL for Relate


4. Verify the Relate Services key:

a. Open a browser and go to the following address: https://localhost:NNNN/xmlapi/xxx where “NNNN” is the Relate Services SSL connector port number ([DEFAULT] 8443) and “xxx” is 3-character company code used when installing Relate. You should be notified that there is a problem with the certificate (Internet Explorer) or the certificate is from an unknown authority (FireFox).

b. Continue to the website (Internet Explorer) or accept the certificate (FireFox). You organization’s ID Number should be displayed (see right).

c. Close the browser.

Depending on the browser you use, the message you receive may differ from the ones cited below.

Enable SSL for Relate 70

Revision History

A P P E N D I X

RELATE VERSION

DATE DESCRIPTION OF CHANGE

11.1 Oct 2014 In the “Installation” chapter, “Relate Installation” section, removed Licensed Feature Selection and License Key Entry steps.

11.0 Aug 2014 In the “Installation” chapter, changed the screenshots to reflect the new design in the installer windows.

In the “Installation” chapter, “Relate Installation” section, added Licensed Feature Selection and License Key Entry steps.

In the “Installation” chapter, changed the “Relate Installation” steps and ordering to reflect reorganization of the installation procedure.

In “Initial Configuration” chapter, added Franchisees, removed User Organizations.

In the “Initial Configuration” chapter, added the franchisees CSV import file, updated the format of the users CSV import file, and added the franchise assignment CSV file. Removed the user organizations CSV import file, and removed the user organizations assignment CSV file.

10.8Doc Ver 5

May 2014 In the Secure Sockets Layer (SSL) appendix, added missing information describing how to import the generated SSL certificate into Java.

10.8Doc Ver 4

Feb 2014 In the Secure Sockets Layer (SSL) appendix, corrected description of the -dname command line option to read “Distinguished name”.

71

APPENDIX C: Revision History Relate 11.1

10.8Doc Ver 3

Jan 2014 Removed OpenSSL installation information.

10.8Doc Ver 2

Jan 2014 In the Secure Sockets Layer (SSL) appendix, corrected broken link and removed incorrect information.

10.8 Jan 2014 In the “Installation” chapter, added SSL Configuration step to the “Relate Installation” section.

Changed the name of the “Enable Secure Sockets Layer (SSL)” chapter to “Secure Sockets Layer (SSL)”.

In the chapter “Secure Sockets Layer (SSL)”, split the procedure “Enabling SSL for Relate” into “Create the SSL Certificate” and “Enable SSL for Relate”.

10.5 Sept 2013 In the “Installation” chapter, “Database Installation” section, removed all XBR steps from both the “SQL Server Installation” and “Oracle Installation” procedures.

In the “Installation” chapter, “Create Database” section, removed the 05CreateXBRADMIN.sql and 06LoadXBRADMIN.sql files from the “Oracle” database creation procedure, and changed the numbers for the Org ID and Insert Reports files.

Updates to installation screenshots.

10.0 May 2013 In the “Introduction” chapter, updated Java installation procedure to reflect upgrade to Java version 1.7.

In the “Installation” chapter, updated images to match installer.

Separated information about enabling SSL into the “Enable Secure Sockets Layer (SSL)”.

General cleanup and proofreading.

9.7 Sep 2012 In “Import Users (New Installation)” section of “Initial Configuration” chapter, added COUNTRY_CODE to fields in Users CSV file.


9.6 Jun 2012 Removed section “Prepare Java JRE 1.6 for Relate (Windows)” from “Introduction” chapter.

Updated screen captures throughout document.


RELATE VERSION


72


9.5 Mar 2012 Installation Chapter:

Removed upgrade prerequisites from Relate 9.0.

Removed report installation script from database upgrade procedures.

Initial Configuration Chapter:

Updated Log In procedure to a non-specific username and password.


9.0 Sept 2011 Entire reworking of the Installation Guide, including the following information:

Reorganized information in the chapters.

Moved “Add New Organization” and “Users and Roles” chapters to the Relate Configuration Guide.

Update document to new format.


RELATE VERSION


73