Skip to content

Installation Guide

Jump to bottom
Janis Rumnieks edited this page Jan 28, 2021 · 16 revisions

This guide shows you how to install ChitChat. It will require you to have administrator access to OBIEE as well as access to the physical machine on which the server resides. When you download the installer, the installation directory should not be modified at all. For convenience, move the directory to a convenient access location, such as a home directory or the desktop.

Installation

Setting Up the Database

The installer has the ability to build the database tables required, without specifying a new username. If the correct permissions are provided, the installer will create a new user RMREP, and create tables required for the application to operate correctly. The SQL scripts being executed can be found in the SQLScripts directory in the default installation directory. Please feel free to read those files (the installer replaces placeholders at runtime, so some syntax may not make perfect sense). For Oracle 12c databases, identify a pluggable database for the application to install to (The SID should be preceded by a /, rather than a : in the JDBC Connection String).

Go to the location of SocializeInstaller.jar, and execute the following command:

java -jar SocializeInstaller.jar -Method:BuildDatabase -DatabasePath:/app/oracle/oradata/ORCL/ -JDBC:"jdbc:oracle:thin:@localhost:1521:ORCL" -DatabaseUser:”sys as sysdba” -DatabasePassword:password -NewDBUserPassword:password1

If "sys as sysdba" is not recognised as a single value, try single quotes instead of the double.

The above command requires the following parameters:

  • -Method - Tells the installer what process in the installation you wish to carry out, followed by a colon and the process name. In this case, building the database (buildDatabase).
  • -DatabasePath - Tells the installer where to place the datafiles for ChitChat in your database server.
  • -JDBC - Tells the installer what JDBC driver to use, followed by a colon and then the JDBC string.
  • -DatabaseUser - Specifies the user to access the database with and create the tables required by ChitChat.
  • -DatabasePassword - Specifies the password for the user previously given.
  • -NewDBUserPassword - Indicates the password for the new database user (RMREP) being created.

Adding a WebLogic Data Source

Use WLST to run the create-ds.py script found in the ChitChatInstaller/jndiInstaller directory.

To use this script, modify the ds.properties file using the method of your choosing. Several lines must be modified in this file to reflect your installation. The most commonly changed lines include:

  • domain.name
  • admin.url
  • admin.userName
  • admin.password
  • datasource.target
  • datasource.url
  • datasource.password

An example configuration for 12c can be found below:

#server connection info
domain.name=bi
admin.url=t3://localhost:9500
admin.userName=weblogic
admin.password=password1
 
#server target info
#Used if the target is a managed server
datasource.target=Servers/bi_server1
#Used if the target is a cluster
#datasource.target=Clusters/bi_cluster
 
#database connection info
datasource.driver.class=oracle.jdbc.OracleDriver
datasource.url=jdbc:oracle:thin:@localhost:1521/orcl
 
#database user info. ONLY change the password
datasource.username=RMREP
datasource.password=password1
 
#shouldn't change these
datasource.name=jdbc/rmrep_datasource
datasource.jndiname=jdbc/rmrep_datasource
datasource.initialCapacity=1
datasource.maxCapacity=10
#datasource.shrinkPeriodMinutes=
datasource.test.query=SQL SELECT * FROM DUAL

All other lines in this properties file should remain the same. Once properly configured, execute the create-ds.py script using WLST. In 12c, the standard path to this tool is <BI>/oracle_common/common/bin/wlst.sh, and in 11g the standard path is <WL_HOME>/server/bin/wlst.sh.

Execute the script by running the following command, providing appropriate paths where required:

<BI>/oracle_common/common/bin/wlst.sh ./create-ds.py

If the script fails, please verify all input variables in the properties file. You might also have to delete the partially created JNDI Data Source from the WebLogic Console, before trying to run the script again.

Once the script completes successfully, verify through the WebLogic Console that the appropriate JNDI Data Source has been instantiated. The Data Source name will be jdbc/rmrep_datasource.

Deploying the Application on WebLogic Server

Use WLST to run the deploySocialize.py script found in the ChitChatInstaller directory.

To use this script updated the connect command with username, password and url to connect to your Weblogic Server instance. You must also update the second parameter in deploy command to reflect your ChitChat access location.

An example can be found below:

connect('weblogic', 'Admin123', 't3://localhost:9500')
edit()
startEdit()
deploy('Socialize', '/app/oracle/ChitChatInstaller/war/Socialize.war', targets='bi_server1')
save()
activate()
exit()

Execute the script by running the following command, providing appropriate paths where required:

<BI>/oracle_common/common/bin/wlst.sh ./deploySocialize.py

After executing this command, the Socialize deployment should be visible in the list of deployments, and it should be in an Active or Running status. Please go to the WebLogic Console to verify the deployment is both installed and running. If the deployment is not running, start the deployment. If the deployment fails to start, please look in the log located at <FMW_HOME>/user_projects/domains/bifoundation_domain/socialize.log. The WebLogic Data Source connection may not be set up correctly (exception will read unable to resolve jdbc.rmrep_datasource).

Activating Security

The application integrates tightly with the BI Server, to the point of requiring users to be logged in to be able to add annotations, and only allowing owners of annotations to edit the given annotation. To allow the application to utilize these features, it requires visibility of the OBIEE generated cookie, which holds the identifier for the user's session. The application calls the OBIEE web services to authenticate users with the provided cookie.

To allow the commentary tool to view this cookie, the OBIEE cookie path must be set to the root path. This will allow the cookie to still be visible where required, but also allow the application to receive the cookie from OBIEE.

Steps:

  1. Open the instanceconfig.xml file. (Default 11g path: <MW_HOME>\instances\instance1\config\OracleBIPresentationServicesComponent\coreapplication_obips1\instanceconfig.xml, Default 12c path: <MW_HOME>\user_projects\domains\bi\config\fmwconfig\biconfig\OBIPS\instanceconfig.xml)
  2. Find the <Security> block and insert the following code inside it: 
    <CookiePath>/</CookiePath>
  3. Save the changes to this file and restart the BI Server.

NOTE: Please be aware that by changing the Cookie Path of OBIEE, the session cookie that browsers use to communicate with the analytics server will now be visible to all deployments hosted on WebLogic. This means that if a malicious deployment is hosted on the WebLogic server, the harmful application will have access to OBIEE user sessions. If only trusted applications are deployed on the WebLogic server, then there is no security risk in performing this action.

NOTE: The application, by default, authenticates users using OBIEE's SOAP web services. The above steps are required in order for this authentication to take place. If modification of the instanceconfig.xml to open the cookie availability is undesired, then there is an option to opt out of enforced authentication. WARNING: this will allow the application to be vulnerable to attacks where users can forge personal credentials to pose as other users. Without authenticating against OBIEE, there is no way to avoid this. To do this, please refer to the application constants section below.

Configuration

ChitChat requires several configuration parameters to be set up in the database. To configure the application you must log in to the database schema as the RMREP user, and insert the values manually into the APPLICATION_CONSTANT table.

The current columns in the table are id, version, key, value, and encrypted. The version and encrypted fields should be left as 0. The identifier should be incremented as required. The key and value pairs are described below.

Required Parameters

Administrators

This parameter allows administrators special functions, such as deleting annotations or documents when necessary.

They key for this variable is admin, and should be set to a string containing usernames who are desired to be administrators, delimited by the character of your choosing. The minimum value should be weblogic.

Server Port

This parameter informs the application of which port to access for web services to authenticate. If the users will not be authenticated with cookies, then this variable can be left absent. However, if the users are to be authenticated using their web session, then this variable must be set to the correct port.

The key for this variable is serverport, and the value is simply the port number. Please keep in mind, this is the Analytics port, not the WebLogic port.

Protocol

The key for this variable is protocol, and the value is the protocol (http, or https).

User Profiles

User Profiles require a directory to store profile images in. The application constant to assign for this feature is named uploadpath.

The uploadpath option must contain a valid directory path on the file system. For example, C:\Program Files\rm\ or /var/rm/. Please verify the correct directory exists, has applicable permissions (666), and that the path provided to the application indicates a directory (it must end with \ or /).

Email Sharing

ChitChat provides sharing of comments and annotations through Email ( via SMTP). The settings to share these emails are required, and must be set. If email sharing functionality is not desired, then the following parameters must be set to dummy values. The key values are smtp_server, smtp_sender, and smtp_password.

The smtp_server value must be set to a valid SMTP server. The smtp_sender value must be set to the email address to be logged in as. The final required parameter, smtp_password, must be set to the password of the user.

Before testing this integration, be sure to verify all fields are correct. If they are not correct, then the integration will fail.

Please note that some SMTP servers, she utilized this way, will send these emails to the spam folders of recipients. Please ensure this folder is checked, and appropriate emails are marked as "Not spam".

Optional Parameters

Opt out of OBIEE Authentication

This parameter, when set, allows the application to "opt out" of OBIEE authentication. This application constant is titled security.

WARNING: this will allow the application to be vulnerable to attacks where users can forge personal credentials to pose as other users. Without authenticating against OBIEE, there is no way to avoid this.

The security option must be set to n in order for this to take effect.

Slack

Slack configuration requires two application constants to be set: hasslack and slacktoken.

The hasslack option, if Slack is to be configured, should be y.

The slacktoken option must contain the Slack API key provided by Slack's integration portal.

JIRA/Confluence

Jira/Confluence configuration requires three application constants to be set: hasjira, jirahost, and jiralogin.

The hasjira option, if Jira/Confluence is to be configured, should be y.

The jirahost option must contain the JIRA URL instance.

The jiralogin option must contain the login username and password to access the JIRA instance, separated by a colon.

Salesforce Chatter

Chatter configuration requires a handful of application constants to be set. Many of these are required because Chatter tokens expire within several hours. In order to automatically refresh the token, these several parameters are required.

The haschatter option, if Chatter is to be configured, should be y.

The chatterurl option should be set to the path of the Chatter instance.

The chatter_client_id option should be set to the client identifier provided by the Chatter Integration App on the Salesforce instance.

The chatter_client_secret option should be set should be set to the client secret provided by the Chatter Integration App on the Salesforce instance.

The chatter_username option should be set to the login information of the integration user.

The chatter_pw option should be the concatenation result of the user's login password, and the provided Salesforce security token.

During execution of the chatter integrations, another environment variable, chattertoken, will be created. This is normal behavior for the application, and this option should never be modified.

Enabling the Application

In order to use the application, you must add a small block of code on any given dashboard where you desire to have the application active. Follow the steps below to accomplish this:

  1. Go to the desired dashboard where you desire to have the application.
  2. Go to "Edit Dashboard".
  3. Add a new Column on the right-side of the dashboard.
  4. Add a Text Object inside the Column object you just created.
  5. Copy and Paste the following code into this text field and check the Contains HTML Markup box at the top. Click OK. 
    <rm id="socializePageParams"
user="@{biServer.variables['NQ_SESSION.USER']}"
tab="@{dashboard.currentPage.name}"
page="@{dashboard.name}"
context1 = "@{pYear}">
</rm>
<script src="/Socialize/js/dashboard.js"></script>

This code block should remain largely unchanged, however the one customizable field is the context attribute. In the example above, we have an attribute context1 set to equal the presentation variable pYear. This will filter all the comments on the page by year (e.g. when the pYear presentation variables is changed via a dropdown, all comments will be filtered by the year they were created on. Comments made in the context of 2011 will not show up in the context of 2012). If you wish to add additional contexts, add another attribute on the line BEFORE context1, named context2, and set it's value to another presentation variable using the same syntax.

If you wish to remove context1, simple remove everything in the line where it is EXCEPT the > symbol.

Now save and run the dashboard. A grey rectangle with an arrow should appear on the right side of the dashboard. Click this button to activate the commentary tool.

With Oracle Analytics Server (OAS, tested with version 5.5.0) you may have to enable HTML content in dashboards. Go to http://YOUR_OAS_HOST_NAME:9502/analytics/systemsettings/ and make sure the Allow HTML Content option is ticked. You will have to restart the bi_server presentation service after that, which you can do directly from the System Settings screen.

Congratulations! You have successfully installed ChitChat. To use the tool to its fullest capabilities, please refer to the User Guide.

Clone this wiki locally