table of contents - sap · table of contents chapter 1: getting ... user administration,...
TRANSCRIPT
Table of Contents
Chapter 1: Getting Started with SAP Roambi 1 Roambi ES product overview 1
Roambi Analytics 2 Roambi Flow 2
Getting help 3
Chapter 2: Configuration and Customization 5 Configuring Roambicast 5
Editing SMTP settings for Roambi 5 Testing the SMTP server 6 Sending a Roambicast 6
Constructing a Roambicast link to add portals to a mobile device 6 Constructing a Roambicast link to add an account to a mobile device 7
Enabling and disabling compression 8
Modifying the display language for Roambi 8
Installing language support on Windows 9 Installing language support on Linux (RedHat Fedora) 9 Installing language support on Linux (Ubuntu) 9 Enabling Japanese characters for Linux 9
Changing your organization's logo 9 Logo size specifications 10 Uploading logos to the Roambi server 10
Installing a custom Roambi theme 11
Uploading a custom theme to the Roambi server 11 Defining a custom download URL for the Roambi client app 13
Chapter 3: Portal Management 16
Adding and deleting portals 16
Adding portals 16
Deleting portals 18 Modifying general portal details 18 Customizing the server maintenance message for a portal 20
Configuring server details for a portal 22
Accessing the server configuration 23 SAP BOE 26 IBM Cognos 27 Microsoft Reporting Services 28 Liferay 28 Microsoft SharePoint 28 Microsoft Analysis Services 29
Specifying a root folder for client devices 29
Configuring Auto-synchronization for folders 33
Enabling Auto-synchronization for folders 33 Synchronizing folder names 37
Roambi support for refreshed data in native report results 40
Folder synchronization support 40 Specifying a working directory (Roambi Flow only) 41
Enabling a portal as a primary login option 43 Enabling or disabling a portal 48
Chapter 4: User Accounts 52 Finding users 52
Creating and deleting users 54
Creating users 54 Deleting users 55
Granting and revoking administrator privileges 56 Setting a temporary password 58 Manually setting a user password 61 Locking the Roambi client application 63 Blocking and wiping a device 66
Managing portal accounts 67
Attaching a portal to an account 69 Detaching a portal from an account 70
Chapter 5: Security 71 User Administration, Authentication and Authorizations 71
Session Security Protection __________ 72 Network and Communication Security 79
Data Storage Security 82 Data Protection and Privacy_______________ 82
Introduction _________________________________ 82 Glossary ____________________ 82
User Consent ________________________________________________ 83
Read Access Logging ______________________________ 83 Information Report ___________________ 83
Deletion of Personal Data ___________________ 83 Change Log ______ 84
Chapter 6: Maintenance 85 Viewing system details 85 Running the system diagnostic check 86
Migrating to a new Roambi ES release 89
Chapter 7: Load Balancing 90 Load balancing and failover 90 Using a BIG-IP Local Traffic Management appliance for load balancing 91
Basic network for Roambi with a BIG-IP appliance 91 Creating an HTTP health monitor for a BIG-IP appliance 92 Defining a Roambi server pool 92 Creating an HTTP profile 93 Creating a TCP profile (optional) 93 Creating a virtual server 93
Using a Cisco ACE load balancer with Roambi 94
Chapter 8: Firewall Placement 95 Roambi behind a firewall and client VPN 95 Roambi behind a firewall and reverse proxy 96
Reverse proxy architecture 96
Setting up a reverse proxy for Microsoft IIS 97 Setting up a reverse proxy for Apache 98 Setting up a reverse proxy for Citrix Netscaler 99 Setting up a reverse proxy and SSL rewrite for Apache HTTPD mod_proxy 99
Demilitarized Zone (DMZ) 99 DMZ with load balancing 100
Using Threat Management Gateway (or Internet Security and Application Server) with Roambi 101
TMG integration with Roambi 101 Setting up TMG for Roambi 102 Creating a firewall policy in TMG for the Roambi client 102 Enabling HMTL form authentication for iOS devices (optional) 103 Configuring Tomcat, TMG, and Kerberos 105 Enabling TMG for client devices 108
Chapter 9: SSL 110 Preparing Tomcat to use SSL 110
SSL requirements for Roambi and Tomcat 110 Enabling the Tomcat HTTPS connector 111
Installing SSL to Tomcat using OpenSSL 111
Downloading and installing the OpenSSL utility 111
Extracting the root CA of a server 112 Using OpenSSL to view the contents of a PEM file 113 Specifying that OpenSSL s_client should use a trusted certificate 114 Verifying the certificate files 115
SSL task reference 115
Adding a trusted certificate authority (CA) to an iOS device 116 Connecting to the Roambi server via SSL and troubleshooting connections 116 Creating a keystore for Tomcat 116
Creating a Certification Sign Request (CSR) for Tomcat 117 Importing a certificate file to Tomcat 117 Verifying SSL certificates via SSL Checker 117 Viewing certificate details from a web browser 117 Listing the certificates in a keystore 117 Validating the SSL requirements using OpenSSL 118 Verifying the server connection using OpenSSL 118 Checking the certificate chain using OpenSSL 118
Verifying SSL certificates using OpenSSL 119 Verifying the Tomcat connector settings 119
Installing SSL to a reverse proxy server 119
Configuring Tomcat for SSL offloading 119 Configuring Tomcat behind a reverse proxy 120 SSL and BIG-IP appliances 121
Installing SSL to IIS 121
Downloading and installing the ARR extension for IIS 121
Installing the certificate files 121 Installing the intermediate certificates from the Certificate Authority (CA) to IIS 122
Chapter 10: Single Sign-on (SSO) 125 Using SSO with Roambi 126
HTTP requests between mobile device and SSO solution 127
HTTP requests between the SSO solution and Roambi server 127 Requests between the Roambi server and BI system 128
SSO architecture and HTTP request process 128
HTTP requests between mobile device and SSO solution 128 HTTP requests between the SSO solution and Roambi server 129 Requests between the Roambi server and BI system 129
Configuring SSO for Roambi 130 Specifying an SSO solution for Roambi 131
Configuring Roambi for use with SiteMinder 131
Installing Web Agents for SiteMinder and Roambi 132 General SiteMinder configuration tips 132 Tips for integrating SiteMinder with Roambi and Cognos 132 Integrating SiteMinder with Roambi and SAP BOE 133
Configuring Roambi for Trusted Auth 134
Configuring Roambi for Trusted Authentication with BOE 136 Configuring Roambi for SiteMinder and Trusted Authentication with BOE 138
Configuring Roambi ES for Quest Single Sign-on for Java 140
Installation Guidelines 140 Configuring Quest Single-Sign on for Java 141
Chapter 11: Batch Processes 142 Determining the source data and folder IDs for batch processes 142
Running Roambi batch processes 144
Executing the batch process command 144 Batch process syntax 144
Setting up a batch command when the source report resides in a different portal than the RBI 146 Defining a locale for the batch utility 146
Batch process command examples 146
Updating and replacing an RBI with new source data on the same portal 146 Copying an RBI to a new portal folder on the same portal 147
Creating a new RBI on a different portal 147 Creating a new RBI on the same portal with a new name and source parameters 164 Using the batch utility to create a template RBI when the source report has parameters 148
Using a text file as the parameter source for a batch process 148
Text file format for batch processes 148 Running a batch process with arguments stored in a text file 148
Using batch processes in SiteMinder-protected environments 149
Chapter 12: Application Service API 151 Obtaining the report URL 151
Obtaining the report URL from Roambi Publisher 151 Obtaining the report URL from a Roambicast email 159
Editing the report URL 160 Launching the report 160
Returning to the third-party application 160 Linking to a specific Cardex card 161
Chapter 13: Troubleshooting 162 Isolating issues 162
Using log files to troubleshoot issues with Roambi 163
Enabling logging for Roambi on the server 163 Accessing log files on client devices 164 Recovering crash logs for mobile devices 165
Roambi Flow Issues 165
Roambi Flow publishing and PDF issues 165 SSL issues with Roambi Flow on Linux 166 SSL issues with Roambi Flow on Windows 166 Screen capture issues for Roambi Flow 166
Timeout errors 167
Download timeouts 167 Tomcat session timeouts 167
MS Excel import errors and OpenOffice errors 168
File import failed for MS Excel file 168 MS Excel file import fails after a long wait 168 OpenOffice index out of range error on import of Excel 168
Missing entry for connStringInstance 1 in roambi-settings.properties 169 java.lang.NoClassDefFoundError: com/sun/star/frame/XModel 169 Missing or corrupt files 169 Application has failed to start 170
Roambicast issues 170
Roambicast does not successfully send emails 170 File upload issues 170
MS Excel files do not upload 170 File size is too large 170
Client device errors 171
Users cannot download or refresh Roambi analytics reports on their mobile devices 171 Error: "Download failed" 171
Network configuration issues 172
HTTP 404 error after deployment of Roambi war file to Tomcat 172 Troubleshooting the network configuration 172
Roambi Publisher issues 174
Publisher displaying "sqlite library not found" messages 174 Post Too Large 174 HTTP Request Error 174
Batch Process Issues 174
[main] INFO com.mellmo.roambi.UpdateRoambi - reponse
body:<errors><error>Failed to update parameter values. Parameters table does
not contain parameter: My Prompt:</error></errors> 176
[main] INFO com.mellmo.roambi.UpdateRoambi - reponse
body:<errors><error>Failed to update parameter values. XML document structures must start and end within the same entity.</error></errors> 176
Error: “Server could not complete the request” when requesting a new parameter set on a batch Roambi. 176
General portal issues 176
Portal does not appear in Roambi Publisher 177 SAP Business Objects Enterprise (SAP BOE) issues 177
Enabling JCE verbose logging for SAP BOE 177
User cannot log in to SAP BOE portal 177
INCORRECT PORTAL CREDENTIALS: The username-password combination you have used for this location are either invalid or incorrect 178 Server returned an HTTP error upon attempted login 178 Cannot import a webi document 178
Cognos Issues 178
Generating the Cognos logs 178
Verifying the Cognos configuration 179
INCORRECT PORTAL CREDENTIALS: The username-password combination you have used for this location are either invalid or incorrect. 179
Your Roambi installation is missing required library files. Please contact your administrator. 179
SSRS Issues 180
Non-functional parameters appear on the Roambi login screen 180 Cannot login: user id or password invalid 180 Roambi analytics reports are not correctly displaying 180 Config Manager webservice_url 181 HTTP 500 or 401 Not Authorized 181 Cannot publish in SSRS 181
Microsoft Analysis Services Issues 181
Blink View does not display cubes in the database folder 181
Blink View displays error ”Not authorized” on login 181 Cannot login. Get error “SSRS has authentication to Navigate” 182
Liferay Issues 182
Incorrectly formatted Web Service URL 182 User cannot publish view in Liferay 182 Users and content are missing when Liferay starts 183
Roambi batch process is successful, but the View does not update using
Community Liferay Server 183 User cannot log in to Roambi ES with new Liferay account 183
SSL Issues 183
Issue: Web browser hangs when attempting to access SSL URL 183 Issue: Intermediate certificates are missing on HTTP server 183 Error message: "Cannot recover key" 184
Error message: "Your credentials could not be verified because the server could
not be reached (-1206)” when using mod_ssl on apache" 184 Validation error: "verify error:num=19:self signed certificate in certificate chain" 184 Validation error: verify error:num=20:unable to get local issuer certificate 184
Reverse proxy issues 184
Checking if reverse proxy is working properly 185 Troubleshooting reverse proxy issues with Tomcat 185
Kerberos Issues 185
Enabling Kerberos debug logging 185
Checking the Kerberos configuration 185 Listing SPNs 186 Verifying that a Kerberos ticket can be issued 186 Checking if a tgt ticket has been created and cached on the client 186 [Krb5LoginModule] authentication failed 186
Client not found in Kerberos database (6) 186
Chapter 14: Roambi ESX 187
About Public Portals 187 Adding a Public Portal 188 Adding Authentication Credentials to a Public Portal 189 Configuring a Public Portal 190 Enabling a Public Portal 193
Publishing Roambi Files to Public Portals 193
Chapter 1: Getting Started with
SAP Roambi The SAP Roambi ES Administration Guide contains instructions and suggestions for
configuring and administrating the Roambi Enterprise Server (ES). If you have not already installed the Roambi server, see the SAP Roambi ES Installation
Guide for step-by-step instructions for installing the server and its prerequisite software. This guide includes the following chapters:
Configuration and Customization: Information about how to configure and customize the
appearance of Roambi
Portal Management: Adding, deleting, and modifying Roambi BI portals
User Accounts: Managing Roambi user accounts
Security : Adding or changing server, Publisher, or mobile device security options
Maintenance: Basic Roambi server maintenance tasks
Load Balancing: Benefits of load balancing and instructions for setting up a BIG-IP load
balancing appliance
Firewall Placement: Various options for firewall placement, including the pros and cons of
each configuration
SSL: Configuring SSL for the Roambi server
Single Sign-on (SSO): SSO architecture and configuration instructions
Batch Processes: Configuring and running Roambi batch processes
Application Service API: Using the Application Service API to allow third-party applications
to launch a specific Roambi analytics report.
Troubleshooting : Common problems and solutions for the Roambi server
SAP Roambi ES product overview
The Roambi Enterprise Server (ES) is a secure and scalable server solution that enables you to
transform your critical business reports and data into interactive dashboards and reports for mobile
devices.
The data sources for Roambi ES can range from single spreadsheets to sophisticated
Business Intelligence (BI) systems. Roambi ES is designed to meet and exceed the unique requirements for an enterprise-grade
mobile application, including:
-1 –
Broad connectivity to diverse data sources and BI systems
Enterprise-ready user interface and tools
Security and administrative capabilities required by enterprise IT
Regardless of the size of your organization, Roambi ES enables your mobile workers to have
convenient, up-to-the-minute business information for on-the-go-analysis, impromptu
presentations, and smarter decision-making. In addition to the Roambi server, Roambi ES includes the Roambi Analytics Publisher application
and optionally the Roambi Flow Publisher application. Each Publisher application works with your
data to create the dashboards and reports that are viewable on your mobile devices. In addition to the Roambi server, Roambi ES includes the Roambi Analytics Publisher
application. The Publisher applications work with your data to create the dashboards and
reports that are viewable on your mobile devices.
SAP Roambi Analytics
Roambi Analytics reports are interactive mobile dashboards that can be instantly delivered to
any iPhone, iPad, or iPod Touch. Several types of reports, called Views, are available so that
you can tailor your analysis to the source data that you are working with. Roambi ES includes
the following views:
Blink
Cardex
CataList
Elements
Layers
PieView
Pulse
Squares
SuperList
Trends
Card
SAP Roambi Flow SAP Roambi Flow is an information publishing platform that is available for purchase with the
Roambi Enterprise Server. Roambi Flow enables users to easily create dynamic reports that embed
Roambi analytics and that can be shared on the iPad. If your Roambi license agreement includes a
Roambi Flow license, Roambi Flow will be automatically installed with the Roambi server, and you
will only need to perform a few additional configuration steps to set up Roambi Flow for your
organization's users.
- 2 -
Getting help
Roambi Flow requires that each Flow user has a separate account; SAP highly recommends
that users not share accounts to prevent two users from simultaneously editing the same
document.
Getting help If you are having any issues with the Roambi server, please review the Troubleshooting
chapter of this guide and the sections of the ES5 Installation Guide that are relevant to your
configuration before contacting Roambi technical support. If you are having any issues with the Roambi server, please review the Troubleshooting
chapter of this guide before contacting Roambi technical support.
- 3 -
Chapter 2: Configuration and
Customization
You have several options provides several configuration options to customize your Roambi
server for your organization. This chapter discusses available configuration options and how
to use these options:
Configuring Roambicast
Enabling and disabling compression
Modifying the display language for Roambi
Additionally, your organization has several options for customizing the look and feel of the
Roambi server and client application. Note that some types of customization, such as
creating a theme, require the involvement of your Roambi technical representative.
This chapter contains basic instructions for the following types of customization:
Changing your organization's logo
Installing a custom Roambi theme
Note: Configuration changes that should be made as part of the initial Roambi installation
and set up process are discussed in the ES5 Installation Guide.
Configuring Roambicast
The Roambicast feature allows Roambi Publisher users to automatically email Roambi
Analytics reports to fellow portal users. A Roambi system administrator must configure
Roambicast before users can use the automated version of this feature.
Editing SMTP settings for Roambi
Before you can configure your SMTP settings for Roambi, you will need to set up the SMTP
mail server to be used by Roambi. See the documentation for your mail server for instructions
on setting up an SMTP server.
To configure Roambicast:
-4-
Chapter 2: Configuration and Customization
In the upper-right of the Administrator's Console, click the System
tab. The System tab options display on the left pane of the screen.
From the list of System tab options, click the SMTP Settings tab to display the current
SMTP settings.
Enter the information for your SMTP server: In the Host field, type the name or DNS domain named host for the SMTP host server.
In the Port field, type the port number used by the SMTP server.
Press the Return key.
Roambi validates the Host and Port values by attempting to connect to the SMTP
server. If Roambi cannot connect to the SMTP server, the screen prompts you to
check your settings and retry.
After connecting to the SMTP server, the Administrator's Console displays fields
for additional SMTP settings with default values already filled in with information
from the SMTP server.
- 5 -
Configuring Roambicast
Verify that the default values are correct for your SMTP server, or make the necessary
changes for the server. Depending on your email server configuration, these settings
might include the following fields: Domain Host: SMTP server domain name.
From Email: Email address displayed in the From field of a sent email.
URL Host for Emails: Host value used to construct links for emails. If your
Roambi server is behind a reverse proxy, this host name must be the reverse
proxy machine name. To determine the value for this field, start a browser
session using Roambi FQDN; this field should suggest the browser URL.
Click the Save Settings button.
Roambi saves the settings and the Administrator's Console displays buttons giving you the
options to send a test email (see Testing the SMTP server) or edit your settings.
Testing the SMTP server
After you have added your SMTP server information to the Administrator's Console, you can
verify that the server is working as expected by sending a test email. To validate the SMTP settings by sending a test email:
1. On the SMTP Settings tab, click the Send Test Email button to display a Send Test
Email prompt.
2. In the Email field, enter a valid email address.
3. Click the Send button. Within a few moments, you should receive an email at the Send Test Email address,
which confirms that your SMTP settings are correct. Users should now be able to send Roambi Analytics reports using Roambicast.
Sending a Roambicast You can send a Roambicast of a Roambi Analytics report using two different methods: If you have configured your SMTP settings, when you create an analytics report in Roambi
Publisher, you will have the option to Roambicast that report at the end of the publishing
process.
You can manually construct a Roambicast link to automatically add portals or accounts to a
device. (See Constructing a Roambicast link to add portals to a mobile device and
Constructing a Roambicast link to add an account to a mobile device.)
Constructing a Roambicast link to add portals to a mobile
device
To manually construct a Roambicast link that automatically adds a portal to a user's mobile device, use
the following link format in your email, depending on how you installed the Roambi server:
- 6 -
Chapter 2: Configuration and Customization
• When you installed the Roambi server, if you renamed the Roambi .war file "ROOT",
use the following link format:
For HTTP:
roambi-http://[RoambiServer]/SourceManager/[PortalID] For
HTTPS:
roambi://https://[RoambiServer]/SourceManager/[PortalID]
• When you installed the Roambi server, if you renamed the Roambi .war file something
other than "ROOT", use the following link format:
For HTTP:
roambi-http://[RoambiServer]/roambi/SourceManager/[PortalID] For
HTTPS:
roambi://https://[RoambiServer]/roambi/SourceManager/[PortalID]
Note: If you changed the name of the Roambi .war file to something other than "roambi" or
"root", the directory under the RoambiServer directory should have the same name as
your .war file. For example, if you renamed the Roambi .war file to "myapp.war", your
HTTP URL would be roambi-http://[RoambiServer]/myapp/SourceManager/[PortalID].
The URL contains the following parameters:
RoambiServer is the address for the server where the Roambi server is installed.
PortalID is the ID for the portal where you created the Roambi analytics report that you
want to send via Roambicast.
Constructing a Roambicast link to add an account to a
mobile device To manually construct a Roambicast link that adds an account to a user's mobile device, use
the following link format in your email:
• To use HTTP:
roambi-http:/[RoambiServer]
• To use HTTPS:
roambi://[RoambiServer]
The RoambiServer parameter should contain the URL used to access the Roambi server.
- 7 -
Enabling and disabling
compression
Enabling and disabling compression Roambi analytics files (RBI files) that contain large amounts of data or that have certain features
enabled, such as summary charts or different charts in each view, can grow to be quite large in
size. These large files can take a long time to download to mobile devices. Additionally, if users
are downloading files via a 3G network, large data files can result in increased data charges. To decrease the size of RBI files while still retaining all of your data and features, you can
enable file compression on the Roambi server (by default, file compression is disabled). Note: If file compression is disabled, the server will not be able to open compressed RBI files.
To enable file compression on the Roambi server:
• In the directory where your application server is installed, navigate to the following folder:
[application_server]/webapps/[roambi]/WEB-INF/
• Open the web.xml file in a text editor.
• Scroll or use CTRL+F to find the following piece of XML code:
<init-param>
<description>Enable RBI compression</description>
<param-name>EnableCompression</param-name> <param-
value>false</param-value>
</init-param>
• Change the value of the param-value element from false to true to
enable compression. • Save your changes and restart the application server.
Modifying the display language for Roambi
Roambi applications and file formats are UTF-8 encoded so that you can change your
language on your machine, and the application and data will display in the new language. Because some Roambi report elements, such as the title bar on the Cardex report, are
generated on the server, if most users will be using a language other than English, you will
need to install support for that language on the server where the Roambi server is installed. Note: Roambi retains the date and number format from the original source report
regardless of what language the server uses.
When using the Roambi web application, language settings are determined by the OS
that is running the browser.
For Mac, you can change the OS language in the System Preferences.
For Windows, see the documentation for the version of Windows that you are using.
- 8 -
Chapter 2: Configuration and Customization
Installing language support on Windows To install language support on Windows XP or Windows 2003:
• From the Windows Control Panel, select the Regional and Language option.
• Click the Keyboards and Languages tab.
• Under Display Language, click Install/uninstall languages.
• Follow the prompts to install the necessary language files for your language.
Installing language support on Linux (RedHat Fedora) To install language support on RedHat Fedora:
1. Install the font packages required for your language, such as fonts-korean sazanami,
fonts-gothic sazanami, fonts-mincho, and fonts-chinese.
2. In the jre/lib folder, create a fontconfig.properties file describing which
fonts should be used.
Use fontconfig.RedHat.properties.src as a template for this file.
Installing language support on Linux (Ubuntu)
To install language support on Ubuntu, type the following command: $ 1) sudo apt-get install ttf-unfonts
Enabling Japanese characters for Linux If your mobile device users will be accessing the version of the Roambi Visualizer client app that has
been translated to Japanese, you will need to enable Japanese characters on your Linux server. To enable Japanese characters for Linux:
Create a $JAVA/jre/lib/fonts/fallback directory:
$ sudo mkdir -p $JAVA/jre/lib/fonts/fallback
Copy the Japanese true type font to the /fallback folder:
$ sudo ln -s /usr/share/fonts/truetype/ttf-japanese-
gothic.ttf $JAVA/jre/lib/fonts/fallback/
Changing your organization's logo
You can upload a custom logo to the Roambi server so that when users connect to their
mobile devices, they see your organization's logo rather than the Organization Name as
the link to their portals.
- 9 -
Changing your
organization's logo
Logo size specifications If you have users connecting to the Roambi server via both phone and tablet devices, you will
need both a small and large version of your logo so that the logo displays properly:
The small logo should be a PNG file that is 220 pixels wide by 40 pixels tall.
The large logo should be a PNG file that is 440 pixels wide by 80 pixels tall.
Uploading logos to the Roambi server To add a custom logo for your organization to your devices portals, you need to upload the
logo files to the Roambi server:
In the upper-right portion of the Administrator's Console, click the System tab to
display the list of system options on the left side of the screen.
From the list of system options on the left side of the screen, click Appearance to
display the Roambi appearance options:
Select a Small Logo: Under Organization Logos, in the Small Logo box, click the Select button to
open a Select File window.
The Select File window lists all small logo files that have been uploaded to the
server and also allows you to upload or delete files on the server.
- 10 -
Chapter 2: Configuration and Customization
If you see that the logo file you want was previously uploaded, select that file and
click the Save button.
If you need to upload your logo file, click the + sign at the lower-left of the list of
files. Clicking the + button opens a File Upload dialogue.
Browse to your logo file and click Save.
If you need to delete a file on the server, select the file and click the - button.
Repeat the previous steps for the Large Logo.
Restart the Roambi application on your mobile device. Once you confirm that you can see
the new logos, instruct your users to restart the application on their mobile devices.
If users have already created a portal with the previous logo (or no logo) on their
mobile devices, they might need to exit the application, kill the application in the
background, the relaunch the Roambi application to see the new logo.
Installing a custom Roambi theme
Roambi themes are packaged as ZIP files and contain graphics and information about the look
and feel of the Roambi user interface. Contact your Roambi technical representative to start the
process of building a theme if you would like a custom look for your Roambi UI.
Uploading a custom theme to the Roambi server
To install a custom Roambi theme:
- 11 -
Installing a custom
Roambi theme
In the upper-right portion of the Administrator's Console, click the System tab to display
the list of system options on the left side of the screen.
From the list of system options on the left side of the screen, click Appearance to display
the Roambi appearance options:
Under Custom Theme Settings, in the Install Theme box, click the Select button to
open a Select File window.
This window lists any ZIP theme files that have already been uploaded to the Roambi server.
If you do not have your theme file already uploaded, in the lower-left corner of the
window, click the + sign to open a File Upload dialogue.
Browse to the theme ZIP file provided by your Roambi technical representative.
Click Save.
- 12 -
Chapter 2: Configuration and Customization
Restart the Roambi application on your mobile device. Instruct your users to kill the
application in the background, then restart the Roambi application on the device.
Defining a custom download URL for
the Roambi client app If you would like your users to download the Roambi client app for their mobile devices from a
URL other than the Apple App Store, you can specify a custom download URL. By default, when users are prompted to download the Roambi client via a Roambicast email, the
email will contain a link to the Roambi version that can be downloaded from the Apple App Store.
When you specify a custom download URL, you can direct users to a different download location.
Use a custom download URL if your organization uses a custom application or a secure
application loader. To define a custom download URL for the Roambi client app:
Click the System tab in the upper-right part of the Administrator's Console to access
system-related functionality.
Click the General tab to view general system details:
Scroll down to see the Applications section:
- 13 -
Defining a custom download URL for the Roambi
client app
Under Applications, toggle the Show Custom URLs switch to ON:
The custom URL fields for Roambi Analytics and Roambi Flow become visible.
- 14 -
Chapter 2: Configuration and Customization
The custom URL field for Roambi Analytics becomes visible.
In the Roambi Analytics URL field, specify the URL where users will download the
Roambi Analytics Visualizer client app. If your organization uses Roambi Flow, in the Roambi Flow URL field, specify the URL
where users will download the Roambi Flow client app.
- 15 -
Chapter 3: Portal Management
This chapter contains information on adding, deleting, and modifying BI portals for SAP Roambi:
Adding and deleting portals
Modifying general portal details
Configuring server details for a portal
Customizing the server maintenance message for a portal
Specifying a root folder for client devices
Configuring Auto-synchronization for folders
Specifying a working directory (Roambi Flow only)
Enabling a portal as a primary login option
Enabling or disabling a portal
Adding and deleting portals
At least one Roambi portal should have been created for you when your Roambi server was
initially set up. If you have at least one portal already created or imported for the Roambi
server, you can add more portals or delete a portal from the Roambi Administrator's Console.
Adding portals
To add a portal to the Roambi server:
Click the Add Portal button in the lower left corner of the dashboard:
An Add Portal window opens:
- 16 -
Chapter 3: Portal Management
- 17 -
Modifying general
portal details
From the Portal Source drop-down list, select the BI tool that will be used as the data
source for the portal. Depending on which portal you choose, the portal may also be
used to store RBI files. In the Name text box, type a unique name for the portal.
Click Add.
Configure the portal using the Administrator's Console.
Each portal type has different configuration requirements. See the individual section for the portal
type in the ES5 Installation Guide to learn about the configuration parameters for that portal.
Deleting portals You can delete a portal by selecting it in the left pane then clicking the Delete Portal button
in the lower right corner of the dashboard:
Modifying general portal details After you add a portal to Roambi, you can still edit some of the general details related to the portal.
To edit the general details for a portal:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work with.
- 18 -
Chapter 3: Portal Management
The Console displays the Portal Details:
- 19 -
Modifying general portal details Chapter 3: Portal Management
The Portal Details section contains the following fields:
Type: Value is set during portal creation and cannot be changed.
Name: Name of the portal as appears to users of the Roambi Administrator's
Console and Publisher.
ID: Unique identifier for the portal that was assigned when the portal was
created; cannot be changed.
ID Alias: Human-readable ID for the portal; This ID is used for migration
when upgrading from previous versions of the Roambi server.
Description: Short description for the portal.
Support Message: Message to display to users when the server is taken down
for maintenance (see Customizing the server maintenance message for a
portal).
Customizing the server
maintenance message for a portal If you need to take the Roambi server offline for maintenance, you can configure a custom
message that displays when a user tries to connect to an affected portal.
-20 -
Customizing the server maintenance message for a portal
The custom message also displays if an Administrator has disabled the portal from the Roambi
server. Custom messages enable you to communicate to users when and why they cannot
connect to the server. To set a custom maintenance message for a portal:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 21 -
Click inside the Support Message box. The
Support Message is enabled for editing.
Type a new Support Message describing the details of the maintenance or other
information that you want to communicate to users who connect to the portal. Click Save to save your changes.
The new message will now be displayed to users who try to connect to the portal while the
server is offline or the portal has been disabled.
Configuring server details for a portal
The information required to configure server details for a portal varies by portal type. This
topic explains how to navigate to the page where you can edit server details and what
details are required for each portal type.
- 22 -
Chapter 3: Portal Management
Accessing the server configuration To access the server configuration details that can be edited:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 23-
Chapter 3: Portal Management
Click the Configuration tab to view the server configuration.
Note that options on this screen vary by portal type:
- 24 -
Configuring server details for a
portal
- 25 -
Chapter 3: Portal Management
For any type of portal, you can enable or disable the portal from this tab (see Enabling or
disabling a portal). To learn more about the available fields under Portal Parameters, see the
section that follows that corresponds to your portal type.
SAP BOE
SAP BOE has the following available Portal Parameters:
Authentication:Type of BOE authentication to be used by Roambi. Valid values are
secEnterprise, secLDAP, secWinAD, and secSAPR3. If you are using SiteMinder
and/or Kerberos for authentication, set this value to secWinAD. If you are using
TrustedAuth for SSO authentication, set this value to secEnterprise. If you are using both
CA SiteMinder and TrustedAuth, set this value to secEnterprise.
- 26 -
Configuring server details for a
portal
Server Name: Name of the server where the Content Management System (CMS) is
deployed.
Web Service Url (SAP BOE v4 only): URL to the BOE web services deployment. This
URL will likely use the format http://[Server]/dswsbobje/services.
IBM Cognos
Cognos has the following available Portal Parameters:
Dispatcher URL: URL for the Cognos server that handles the Dispatcher.
Gateway URL: URL assigned to the portal by the web server. For example, if you use IIS
with a gateway named Cognos8, the gateway points to http://[server_name]/Cognos8/cgi-
bin/cognos.cgi. (For ISAPI, replace "cognos.cgi" with "cognosisapi.dll".)
Namespace: Name Space ID for the Authentication provider that is configured in
the Security section of Cognos.
Note: If you are using Cognos v7 "Access Manager" as your namespace, do not specify
Access Manager as your namespace in the Roambi Namespace field. Instead,
specify the nampespace default, which is the CAMID in Cognos.
Version: Cognos version. Valid values are 83 (Cognos8.3), 84 (Cognos 8.4), C10
(Cognos 10.x), C11 (Cognos 11.x).
- 27 -
Chapter 3: Portal Management
Microsoft Reporting Services
Microsoft Reporting Services has the following available Portal Parameters:
Windows NT Domain: Windows domain that you use to log into Windows. If you do not
specify this domain, you can log into any Windows domain, but you will need to manually
enter the Windows domain on the Roambi Publisher login screen.
Time Zone: Time zone used by the server. Use standard Time Zone format for this value:
http://www.timeanddate.com/library/abbreviations/timezones/
Web Service URL: Web Service URL specifed in the Report Services Configuration Manager. If
the report server instance has a name other than ReportServer, add the instance name at the
end of the URL. For example: http://[server_name]:[port]/[instance_name].
Liferay
Liferay has the following available Portal Parameter: Web Service URL: URL for the Liferay portal. For example: http://liferay.[company_domain].com.
- 27 -
Configuring server details for a
por-tal
Microsoft SharePoint
Microsoft SharePoint has the following available Portal Parameters:
Context Path: Path to the web site that Roambi will access. The path should start with a
"/". To determine the correct context path:
Navigate to the target SharePoint site.
Go to Site Actions > Site Settings.
The context path will be in the following place in the site
URL: http://[SharePointURL]:[port]/[context_path]
Windows NT Domain: Default Windows NT domain for authentication. This parameter
allows users who belong to this domain to skip typing the domain as part of their
User ID. Users who do not belong to the domain will need to use the format
[domain]/[user_name] when typing their User IDs.
Web Service URL: SharePoint server URL without the context path. This URL should
not end with a "/".
- 28 -
Chapter 3: Portal Management
Microsoft Analysis Services
Microsoft SQL Server Analysis Services has the following available Portal Parameters:
Windows NT Domain: Default Windows NT domain for authentication (optional).
Server Type: Analysis Services OLAP source. This parameter should contain "SSAS".
Server URL: URL where the Microsoft Multidimenstional Pump application is installed.
For example, http://[IIS_Server]/[OLAP]/msmdpump.dll.
Specifying a root folder for client devices
Setting a root folder for client devices ensures which folders users will see as a top-level
folder for navigation when they connect to a portal from their mobile devices. Any user with Administrator rights can specify a root folder for client devices.
To specify that a folder should display as a root folder:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 28 -
Specifying a root folder for
client devices
- 29 -
Above the Portal Details, click the Folders tab.
The Console displays the Portal Folders:
- 30 -
Chapter 3: Portal Management
From this tab, you can set a root folder and specify Sync Folders. Sync Folders automatically
synchronize the content on users' mobile devices with the content on the Roambi server. Under Root Folders, click the Add Folder
button. An Add Root Folder window opens.
- 31 -
Specifying a root folder for
client devices
From the folder list, browse to and select the folder that you want to set as a root folder.
Click the Add Root Folder button. The folder now appears in the list of root folders under Portal Folders:
Users will need to restart the Roambi Visualizer application on their mobile devices before the
root folder will be visible. When users then connect to the portal, the root folder will display as
one of the top-level folders in their folder list. Note that the root folder designation only applies
to mobile devices and not to the Roambi server.
- 32 -
Chapter 3: Portal Management
Configuring Auto-synchronization for folders
Auto-synchronization automatically updates the content of folders with this feature enabled on
client devices. Auto-synchronized folders (called Sync Folders) ensure that users always
access the most recent data on their mobile devices when they connect to a portal. After you enable auto-synchronization for a folder, users' mobile devices initiate the download.
Once a device finds the sync folder, the download request initiates. When users open the auto-synchronized folder on their devices, the devices show the content
of the synced folder on the device. The screen will appear empty if no RBI files have been
downloaded. Additionally, the Roambi Visualizer application for mobile devices has a
parameter in Settings that defines the maximum file size that can be downloaded by auto-
synchronization. By default, the size limit is 5MB, but users can increase the size limit on their
devices to enable the download of larger files. If you set the File Expiration option for an RBI, auto-synchronization works slightly differently. For
files with expirations set, auto-synchronization will only sync the report link and not the report
itself. Synching only the link prevents users' devices from having download, delete, and re-
download unread reports. Any user with Administrator rights can enable auto-synchronization for a folder.
Enabling Auto-synchronization for folders To enable auto-synchronization for a folder:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the General tab for the portal:
- 33 -
Configuring Auto-synchronization for
folders
- 34 -
Above the Portal Details section, click the Folders tab.
The Console displays the Portal Folders section:
From this tab, you can set a root folder and specify folders to be auto-synchronized.
- 35 -
Chapter 3: Portal Management
Under Sync Folders, click the Add Folder button.
An Add Sync Folder window opens.
From the folder list, browse to and select the folder that you want to auto-synchronize.
If you want to automatically delete Roambi files from the device after they are deleted from
the server, check the Auto Delete box.
When an RBI file is deleted from the server portal, that RBI file will be deleted from both the
folder in the Connect tab and from the Library (if it was previously downloaded) on users'
mobile devices. As soon as users tap Refresh on their devices, the RBI file will be removed.
Click the Add Sync Folder button. The folder now appears in the list of auto-synchronized folders under Portal Folders:
- 36 -
Configuring Auto-synchronization for
folders
This folder will now automatically contain updated content when users connect to the portal
after restarting the Roambi application from their mobile devices. However, note that if a user
has already downloaded an RBI file, the data for that file will not be updated even if the data
has changed. Additionally, if an RBI was deleted from the Roambi library, that RBI will not
download again. Only RBIs that were republished with the same name in the same location
will automatically download upon sync.
Synchronizing folder names You can manually sync the folder names from the server using the Administrator's Console.
For example, if you change the name of a folder on a portal, use the folder sync feature to
update the folder name on the Roambi server. To synch the folder names on the server:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 37 -
Chapter 3: Portal Management
- 38 -
Chapter 3: Portal Management
Above the Portal Details, click the Folders tab.
The Console displays the Portal Folders:
Click the Sync Folder Names button to the right of the Portal Folders heading:
- 39 -
Configuring Auto-synchronization for
folders
The folder names are updated to those that are on the portal.
SAP Roambi support for refreshed data in native
report results
Depending on which BI tool you are using, Roambi's support for refreshing rendered,
saved, or scheduled native report results varies. The following table summarizes
Roambi's support for refreshed report results:
BI Tool SAP BOE Crystal Reports SAP BOE WebI
IBM Cognos
Microsoft SSRS
Refreshed native report support
Roambi supports scheduled report instances.
Roambi supports scheduled report instances. Roambi does not support saved report outputs due
to inadequate metadata for the reports. Roambi supports snapshot reports.
Folder synchronization support With most iPad and iPhone configurations, folders will synchronize as expected when
using the sync feature. The following table explains Roambi support for folder
synchronization for various iPad and iPhone configurations:
- 40 -
Chapter 3: Portal Management
Configuration Steps
Refresh
Comments folders?
Default setup
Default iPad setup
Device with
passcode
iPad with passcode
iPad with
autolock disabled
iPad with cover
lock/unlock disabled,
autolock enabled
after 2 minutes iPad with cover
lock/unlock disabled,
autolock enabled
Press lock
button, then
unlock
device Close Smart
Cover, then
open Press lock
button, then
unlock
device Close Smart
Cover, then
open Close Smart
Cover, then
open
Close Smart
Cover, then
open Close Smart
Cover, then
open
Y
Y
Y
Y
Application is sent into the background when Smart Cover is on, regardless of lock
Y
settings, because of the default Smart Cover settings.
Y
Refresh runs after the application returns from the background or resumes from a
"lock".
Specifying a working directory (Roambi
Flow only) If your organization will be using Roambi Flow, you will need to set up a working directory for each
portal after you have created and configured the portal. Roambi uses the working directory to store
temporary files for Roambi Flow documents. You may have set up a working directory for a portal
during the Roambi installation process, but if you ever add a new portal, you will need to set up a
working directory for that portal if Roambi Flow will be accessing portal data. Any user with Administrator rights can create the working directory for a portal. To create a working directory for a portal for Roambi Flow:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen.
- 41 -
Specifying a working directory (Roambi
Flow only)
From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 42 -
Chapter 3: Portal Management Above the Portal Details, click the Folders tab.
The Console displays the Portal Folders:
-
Specifying a working directory (Roambi
Flow only)
Under Roambi Flow Working Directory, click the Select Folder button.
An Add Working Directory window opens:
- 44 -
Chapter 3: Portal Management
Browse to the folder that you want to use as a working directory and click Select
Folder. The selected folder is now listed as the working directory:
In the BI tool that is associated with the portal, you will need to give Roambi Flow users read
and write access to this folder on the network. One way to do this would be to set up a
Roambi Flow users group within the BI tool, assign Roambi Flow users to that group, and
then give the group read and write access to the folder on the network.
Enabling a portal as a primary login option
The primary login portal is the BI portal that authenticates users to the Roambi server. The
primary login portal should be a portal that actually stores content. Do not use Microsoft
Analysis Services portal as primary login portals. The primary login portal is the portal that authenticates users to the Roambi server. The primary
login portal should be a portal that actually stores content.
- 45 -
Enabling a portal as a primary
login option
If you have multiple portals on the Roambi server, only one of these portals should be
enabled as the primary login portal. If you are using a Single Sign-on (SSO) solution with one of your portals, this is the
portal that should be enabled for primary login. To enable a portal as a primary login option:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
Enabling a portal as a primary
login option
Click the Security tab to display security options for the portal:
Under Login Options, toggle the Enable Primary Login switch to
ON. This portal has now been enabled as a primary login option for users.
- 47 -
Chapter 3: Portal Management
Enabling or disabling a portal
After you have created and configured a portal with the Roambi Administrator's Console, you
will need to enable the portal before users can access it. Conversely, if you need to block
access to a portal for any reason, you can disable that portal without having to delete it. To enable a portal:
On the Administrator's Console, click the Portals tab to display the list of available portals
on the left side of the screen. From the list of portals, select the portal that you want to work
with. The Console displays the Portal Details:
- 48 -
Chapter 3: Portal Management
Click the Configuration tab to display portal configuration options.
- 49 -
Enabling or disabling a
portal
- 50 -
Chapter 3: Portal Management
To enable the portal, under Portal Status, toggle the Enable Portal switch to ON. (To
disable the portal, toggle the Enable Portal switch to OFF.)
- 51 -
Chapter 4: User Accounts
Users create their own accounts in Roambi Publisher, but as an Administrator, you will be
able to modify their accounts in such ways as granting or revoking administrative privileges
and controlling access to the mobile devices that are associated with an account. This chapter contains instructions for the following tasks related to Roambi user accounts:
Finding users
Creating and deleting users
Granting and revoking administrator privileges
Setting a temporary password
Manually setting a user password
Locking Roambi client applications
Blocking and wiping a device
Managing portal accounts
Finding users
You can use the Administrator's Console to browse user accounts and make changes to
individual accounts.
To find a user in the Administrator's Console:
In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users:
- 52 -
Chapter 4: User Accounts
Scroll through the list of users or use the Search field at the top of the list to find the
user that you are looking for. Select the user that you want to view or edit.
- 53 -
Creating and
deleting users
The General tab displays basic details about the user.
Creating and deleting users
You can delete but not create users from the Administrator's Console.
Creating users You do not have the ability to create users from the Administrator's Console. Users create their
own Roambi accounts by logging into Roambi Publisher with the same credentials that they use to
access their BI tool accounts. For example, if a user has an SAP BOE account and logs into that
account with the username JDOE and password 1234, they can log into the SAP BOE portal in
Roambi using these credentials. Roambi automatically creates their account the first time that they
log into the portal. As the Administrator, you have the ability to manage these accounts, and can
perform tasks such as locking user devices and blocking and wiping devices. You do not have the ability to create users from the Administrator's Console. Users create their
own Roambi accounts by logging into Roambi Publisher with the same credentials that they use to
access their BI tool accounts. Roambi automatically creates their account the first time that they
log into the portal. As the Administrator, you have the ability to manage these accounts, and can
perform tasks such as locking user devices and blocking and wiping devices.
- 54 -
Chapter 4: User Accounts
You do not have the ability to create users from the Administrator's Console. Users create their own
Roambi accounts by logging into Roambi Publisher with the same credentials that they use to access
their BI tool accounts. Roambi automatically creates their account the first time that they log into the
portal. As the Administrator, you have the ability to manage these accounts, and can perform tasks
such as locking user devices and blocking and wiping devices.
Deleting users To delete a user account from the Roambi server:
In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users:
Scroll through the list of users or use the Search field at the top of the list to find the user
that you are looking for. Select the user that you want to delete:
- 55 -
Granting and revoking administrator
priv-ileges
The General tab displays basic details about the user.
In the lower-right corner of the Administrator's Console, click the Delete User button:
the Roambi server deletes the user account.
Granting and revoking
administrator privileges If you have Administrator privileges for your Roambi account, you can grant and
revoke Administrator privileges to other Roambi users. To grant or revoke Administrator privileges to a Roambi user:
1. In the upper-right part of the Administrator's Console, click the Users tab to display the
list of users in the left part of the screen. 2. Browse the list of users and select the user whose rights you want to edit.
- 56 -
Chapter 4: User Accounts
3. The General tab displays basic information about the user.
4. Click the Security tab to display privilege and password options for the user:
- 57 -
Setting a temporary
password
5. In the Administrator Privileges box, toggle the ON or OFF button to grant or
revoke Administrator privileges to the user.
Setting a temporary password
If users create new accounts or forget their passwords, you can manually set a temporary
password for them from the Administrator's Console. Roambi then emails the temporary
password to the users, and they will be prompted to select a new password the next time that
they log into Roambi. To set a temporary password: In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users in the left part of the screen. Browse the list of users and select the user whose password you want to set.
- 58 -
Chapter 4: User Accounts
The General tab displays basic information about the user.
Click the Security tab to display privilege and password settings for the user:
- 59 -
Setting a temporary
password
Under System Password Settings, in the Reset to Temporary Password box, click the
Reset Password button to open a Reset Password window:
Click the Reset Password button. The user's password is now changed for their Roambi account. Roambi will email the new
password to the user. The next time that the user logs into Roambi, the user will need to
click the Users tab, select his or her user account, and manually set a new password.
- 60 -
Chapter 4: User Accounts
Manually setting a user password
If users forget their passwords, you can manually set them from the Administrator's Console.
This feature is also helpful if you are setting up a shared account for a group. To manually set a user password:
In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users in the left part of the screen. Browse the list of users and select the user whose password you want to set.
The General tab displays basic information about the user.
Click the Security tab to display privilege and password options for the user:
- 61 -
Manually setting a user
password
Under System Password Settings, in the Manually Set New Password box, click the
Set Password button to open a Set Password window:
- 62 -
Chapter 4: User Accounts
In the New Password text box, type the new password for the user.
In the Confirm New Password text box, re-type the same password to confirm the
password change.
Click the Set Password button. The user's password is now changed for their Roambi account. The user receives an
email notification that the account password changed. Note that if a user has Administrator rights and manually sets his or her own password, the
user will not receive an email notification.
Locking the SAP Roambi client application
As a security measure, the SAP Roambi server provides a way for you to remotely lock the
Roambi client application and data on a user's mobile device. This feature can be useful if
users temporarily misplace their phones or iPads and blocks anyone who finds the device from
accessing Roambi analytics until the device is returned to the user. If a user has left the company or knows that they will not recover their device, the block-and-
wipe feature (see Blocking and wiping a device) provides a more stringent way to restrict
Roambi access than locking the Roambi application. To lock the Roambi application on a user's mobile device:
In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users in the left part of the screen. Browse the list of users and select the user.
- 63 -
Locking the Roambi client
application
The General tab displays basic information about the user.
Click the Devices tab to view the user's mobile devices:
- 64 -
Chapter 4: User Accounts
From the Device Name drop-down list, select the device that you want to lock. Click the Application Lockdown
button. A warning prompt displays:
Click Lockdown to disable the Roambi application on the specified device.
- 65 -
Blocking and wiping
a device
Blocking and wiping a device
The Administrator's Console gives you the ability to block and wipe all Roambi accounts and
data from a user's mobile device. Blocking a device blocks all access to the Roambi server,
and wiping the device deletes all accounts and reports from that device. This feature is very useful if users leave the company and take their devices with them, or if a
user's device is stolen. Because blocking and wiping a device is permanent, if you only temporarily need to block access
to a device, such as if a user has lost their device and is still searching for it, use Application
Lockdown instead of blocking the device. See Locking the Roambi client application. To block and wipe a user's mobile device:
In the upper-right part of the Administrator's Console, click the Users tab to display the list
of users in the left part of the screen. Browse the list of users and select the user.
The General tab displays basic information about the user.
Click the Devices tab to view the user's mobile devices:
- 66 -
Chapter 4: User Accounts
From the Device Name drop-down list, select the device that you want to block and wipe. Click the Block and Wipe button.
A warning prompt displays:
Click the Block and Wipe button to complete the process.
- 67 -
Managing
portal accounts
The Device Details now show that this device has been blocked:
If you need to unblock the device, you can select the device again and click the
Unblock Device button.
Managing portal accounts
Users with Roambi Publisher accounts can manage their own portal accounts for the
Roambi server. The Account tab is visible in the upper-right corner of the web interface. Click the Account tab to view portal account options: Click the Account tab to view portal account options.
- 68 -
Chapter 4: User Accounts
The Portal Accounts tab lists all portals that are available for this Roambi server, even if the
current active user does not have access to them. Users initially create their Roambi accounts by selecting a portal on the Publisher login page,
then logging in with their credentials for that BI tool. If a user wishes to use Publisher with
other portals, they will need to manually attach those portals to their Roambi accounts.
Attaching a portal to an account
Portals that are available on the server but that the user cannot yet access are grayed out.
To attach an available portal to a Roambi account:
From the list of portals under Manage Accounts, select the portal that you want to attach
to the active account.
Type your username and password for the BI tool associated with the portal, and click Save. The portal is now displayed in color and is no longer grayed out.
- 69 -
Managing
portal accounts
Detaching a portal from an account If you need to remove a portal from an account, you can also do that from the Portal
Accounts tab. To detach a portal from a Roambi account:
From the list of portals under Manage Accounts, select the portal that you want to
detach from the account.
Click the Remove Account button to remove the portal from the account. The portal is no longer associated with the Roambi account. If you need to add the portal back, you can
do so at any time by entering user credentials for the BI tool that is associated with the portal.
- 70 -
Chapter 5: Security
The Security tab of the SAP Roambi Administrator's Console provides several options for
adding security to the Roambi server:
Requiring a passcode for mobile devices
Limiting access to Roambi Publisher to Administrators
Specifying a Single Sign-on (SSO) type for user logins (see Specifying an SSO solution for
Roambi)
Modifying Server Encryption Secrets
This chapter describes how to perform the security-related tasks available from the Security tab
of the Administrator's Console. Additionally, you can perform security functions that are tied to an individual user's account, such
as locking a mobile device, from the Users tab of the Administrator's Console. For security
considerations relating to user administration, authentication and authorizations, see User
accounts.
User Administration, Authentication, and
Authorizations
General rules for Roambi server
authentication
While most of this chapter concentrates on configuring Roambi security options using the
Security tab of the Administrator's Console, keep in mind the following general rules for Roambi
server authentication:
All Roambi portals use the standard OAuth-2 authentication protocol for all authentication
requests and user authentication between the BI tool and Roambi server.
Users' mobile devices communicate with the Roambi server using a 128-bit encrypted
access token via the OAuth-2 protocol. This access token identifies which user is
accessing the server. The server decrypts the access token and looks up the user
credentials, session, and login information that is required by the BI system. Roambi
stores identifying information in the Roambi database and not on the mobile device.
The access token for the user is stored in the mobile device keychain. If your configuration
uses SSL the access token cannot be intercepted while the device and server are
communicating. Once the device receives the access token and stores the token in the
keychain, the token cannot be obtained elsewhere.
Chapter 5: Security
A server encryption key encrypts the user access tokens. The Roambi server administrator
can modify the key at any time via the Administrator's Console. (See Modifying Server
Encryption Secrets.)
By default, access tokens expire after one hour; however, users do not need to re-enter
their credentials when the token expires.
Because access tokens are encrypted, potential hackers cannot modify them to impersonate
a different Roambi user. If a hacker does obtain an access token, the token can be used to
access the Roambi server by a different client/request, but can only access information
that the token's original user had access to and can only access the server for the time
that the token is valid. Because the token only represents the original user, the user's
credentials are never at risk of being exposed. The hacker will not be able to access any
underlying BI system outside of the context of the Roambi server.
Controlling Roambi Publisher access
You can restrict access to Roambi Publisher so that only users with Administrator privileges
can use Publisher.
To restrict Roambi Publisher access:
In the upper-right of the Administrator's Console, click the System tab.
The list of System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
- 72 -
Blocking user access to Roambi
Under Publisher Access, toggle the Administrators Only switch to ON to restrict
Publisher access to Administrators.
Blocking user access to SAP Roambi
If you need to temporarily block all new users from accessing your Roambi server from their
mobile devices, you can do so through the the Roambi server Administrator's Console by
enabling auto block. Typically, you would only enable auto block when you are setting up the
Roambi server for the first time. By default, auto block is disabled for the Roambi server. Auto block only blocks mobile device access for new users who have never logged into
Roambi before. If a user has previously connected to the Roambi server, enabling auto
block will have no effect on that user.
Enabling auto block
To block all user access to the Roambi server:
In the upper-right of the Administrator's Console, click the System
tab. The System tab options display on the left pane of the screen.
- 73 -
Chapter 5: Security
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
Under Device Settings, toggle the Auto block switch to ON to block user device access
to the Roambi server.
If users try to access the Roambi server while Auto block is enabled, they will receive a "login
error" when they attempt to connect to Roambi from their mobile devices.
Disabling auto block To unblock users after having enabled auto block:
- 74 -
Enabling and disabling screen shot
cap-ture
In the upper-right of the Administrator's Console, click the System tab.
The list of System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
Under Device Settings, toggle the Auto block switch to OFF to disable auto block.
Disabling auto block does not automatically unblock devices; you will need to go to
each user's account and manually unblock their devices.
Click the Users tab at the top of the Administrator's Console, and select a user whose
device is blocked.
Click the Device tab for the selected user.
Manually unblock the appropriate device(s) for the user.
Enabling and disabling screen shot capture Using the Administrator's Console, you can enable and disable the ability of users to take screen
captures of the currently open Roambi report. Screen shot capture is enabled by default. To enable screenshot capture on users' mobile devices:
- 75 -
Chapter 5: Security
In the upper-right of the Administrator's Console, click the System tab.
The list of System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
Under Device Settings, toggle the Screenshot switch to ON to give users the ability
to capture a screen shot of the currently active Roambi report.
To disable screenshot capture, toggle the Screenshot switch to OFF.
- 76 -
Modifying device passcode
set-tings
Modifying device passcode settings
Device passcode settings control user access to the Roambi server from a mobile device. If
you enable a device passcode for Roambi users, users will be required to enter a passcode
before they can access the Roambi application on their mobile devices. A Roambi
administrator can specify whether users will only need to enter the passcode when their
devices are in offline mode and the required length of a passcode.
Enabling a device passcode To enable passcodes for mobile devices running the Roambi application:
In the upper-right of the Administrator's Console, click the System
tab. The System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
Under Device Passcode Settings, toggle the Device Passcode switch to ON to
enable passcodes for mobile devices.
- 77 -
Chapter 5: Security
When Device Passcodes are enabled, the Administrator's Console displays additional
options for offline mode and passcode length.
Specifying whether the passcode will only be required in
offline-only mode Enabling Offline Only mode means that users will only be prompted to enter passcodes for
their mobile devices when their devices are in offline mode. To enable Offline Only mode:
Enable device passcodes as described in Enabling a device
passcode. The Offline Only option becomes visible:
Toggle the Offline Only switch to On to enable Offline Only mode.
Modifying the minimum length of the device passcode The default minimum passcode length is 4 characters. When Roambi prompts users to create
and enter a passcode, the prompt will include the number of characters required for the
passcode. You can modify this length under Device Passcode Settings in the
Administrator's Console. Valid lengths are 4-10 characters. To modify the length of the device passcode:
Enable device passcodes as described in Enabling a device
passcode. The Offline Only option becomes visible:
- 78 -
Modifying Server Encryption Secrets
To the right of the Min Passcode Size field, click the button corresponding to the
new minimum passcode length.
Network and Communication Security Modifying Server Encryption Secrets
Roambi uses Server Encryption Secrets to secure communication between various parts of
the Roambi application, such as browser cookies, mobile device client tokens, and Cross Site
Request Forgery (XSRF) protection inputs. Security algorithms use the values for the Server
Encryption Secrets to generate encrypted keys that are used in communication between the
Roambi server, client application, and database. The Roambi server decrypts the keys to look
up the appropriate information in the Roambi database as needed. You can modify the Server Encryption Secrets to any value at any time, either as part of a
regular server maintenance schedule or if you believe that the Roambi server may have
been compromised. The following Server Encryption Secrets are available for modification:
Cookie Secret: Hashes web browser cookies
Token Secret: Encrypts user token values
Portal Secret: Encrypts session data for a Roambi portal
After you change the Server Encryption Secrets, users will be prompted for passwords on
their mobile devices the next time that they log in. To modify the Server Encryption Secrets:
In the upper-right of the Administrator's Console, click the System
tab. The System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
- 79 -
Chapter 5: Security
Under Server Encryption Secrets, toggle the Show Keys switch to ON to
enable passcodes for mobile devices.
The current Server Encryption Secrets values display:
As you hover over a Secret, an Edit button becomes visible.
- 80 -
Encrypting Server Keys for added
security
Click the Edit button to change the value of that secret.
The Secret is highlighted and random, cancel, and save buttons become visible:
Click the random button to generate a new random value for the secret, or manually type
a new value for the secret.
Click the save button to save your changes.
Encrypting Server Keys for added security
By defaylt, the encryption keys are stored in the Roambi Database. To increase the
lev-level of security you can add an encryption key that resides in your local file
system. With this option the final keys used by the Roambi Server will be a combination
of both keys: the one stored in the db plus the one provided in File System.
Tospecify the additional encryption key, locate and edit the config.json file in the
.roa-mbi folder where the license key is stored and add the db_secret argument with
the desired encryption key:
{"roambi-data":"0.2.0","db":"mysql://dbserverurl/db_name?user=us-
ername&password=password","db_secret=secretcode","setup_complete":true}
Where secretcode is any string combination with letters and numbers.
Port Configuration
When setting up your Roambi architecture, use non-standard ports to confuse and delay
potential hackers. Using non-standard ports requires any hacker to scan for all available open
ports rather than hacking known default ports. If you decide to use default ports, a potential
hacker not only knows which port to use in an attack, but can often tell the application that is
listening on the port and then knows which methods to use to attack.
- 81 -
Encrypting Server Keys for added
security
Data Storage Security
Data Protection and Privacy Introduction
Data protection is associated with numerous legal requirements and privacy concerns. In addition to compliance with general data privacy acts, it is necessary to consider compliance with industry-specific legislation in different countries. This section describes the specific features and functions that SAP provides to support compliance with the relevant legal requirements and data privacy. This section and any other sections in this Security Guide do not give any advice on whether these features and functions are the best method to support company, industry, regional or country-specific requirements. Furthermore, this guide does not give any advice or recommendations with regard to additional features that would be required in a particular environment; decisions related to data protection must be made on a case-by-case basis and under consideration of the given system landscape and the applicable legal requirements. Note In the majority of cases, compliance with data privacy laws is not a product feature. SAP software supports data privacy by providing security features and specific data-protection-relevant functions. SAP does not provide legal advice in any form. The definitions and other terms used in this guide are not taken from any given legal source.
Glossary
Glossary Term Definition
Personal data Information about an identified or identifiable natural person.
Business purpose A legal, contractual, or in other form justified reason for the processing of personal data. The assumption is that any purpose has an end that is usually already defined when the purpose starts.
Blocking A method of restricting access to data for which the primary business purpose has ended.
Deletion Deletion of personal data so that the data is no longer usable.
Retention period The time period during which data must be available.
End of purpose (EoP) A method of identifying the point in time for a data set when the processing of personal data is no longer required for the primary business purpose. After the EoP has been reached, the data is blocked and can only be accessed by users with special authorization.
- 82 -
User Consent SAP applications ask for user consent before collecting any personal data. SAP Roambi ES provides functionality that allows data subjects to give and withdraw consent to collect and process their personal data. SAP assumes that the user, for example an SAP customer collecting data, has consent from its data subject (a natural person such as a customer, contact, or account), to collect or transfer data to the solution.
Read Access Logging
Read Access Logging (RAL) is used to monitor and log read access to sensitive data. This
data may be categorized as sensitive by law, by external company policy, or by internal
company policy. These common questions might be of interest for an application that uses
Read Access Logging:
• Who accessed the data of a given business entity, for example a bank account?
• Who accessed personal data, for example of a business partner?
• Which employee accessed personal information, for example religion?
• Which accounts or business partners were accessed by which users?
These questions can be answered using information about who accessed particular data
within a specified time frame. Technically, this means that all remote API and UI
infostructures (that access the data) must be enabled for logging.
Information Report
Each person has the right to obtain confirmation as to whether or not personal data
concerning him or her are being processed. In SAP Roambi ES it is possible to display all
information stored about a certain data subject.
Deletion of Personal Data
• Simplified Blocking and Deletion: In addition to compliance with the general data
protection law, it is necessary to consider compliance with industry-specific legislation
in different countries. A typical potential scenario in certain countries is that personal
data shall be deleted after the specified, explicit, and legitimate purpose for the
processing of personal data has ended, but only as long as no other retention periods
are defined in legislation, for example, retention periods for financial documents.
Legal requirements in certain scenarios or countries also often require blocking of
data in cases where the specified, explicit, and legitimate purposes for the processing
of this data has ended, but the data has to be retained in the database due to other
legally defined retention periods. In some scenarios, personal data also includes
referenced data.
Therefore, the challenge for deletion and blocking is to first handle referenced data
and finally other data, such as business partner data.
• Deletion of personal data: The handling of personal data is subject to applicable laws
related to the deletion of such data at the end of purpose (EoP). If there is no longer a
legitimate purpose that requires the use of personal data, it must be deleted. When
deleting data in a data set, all referenced objects related to that data set must be
deleted as well. It is also necessary to consider industry-specific legislation in different
countries in addition to general data protection laws. After the expiration of the longest
retention period, the data must be deleted.
Change Log
Change Log <SAP product name> processes personal data of business partners that are
involved in change requests and activities. If any changes are made regarding the business
partner, the system logs the following information on personal data per change request and
activity:
• User who has changed data
• Data and time of the change
• The change type (update, insert, deletion, single field documentation)
• The identifying keys and their values of the data records
• The heading name for the attribute that has been changed
You can define the fields to be logged.
- 84 -
Chapter 6: Maintenance
You can perform basic system maintenance and diagnostics tasks from the
SAP Roambi Administrator's Console. This chapter describes how to perform these tasks:
Viewing system details
Running the system diagnostic check
Migrating to a new Roambi ES release
If you need to troubleshoot an issue with the Roambi server, see Troubleshooting.
Viewing system details
Click the System tab in the upper-right part of the Administrator's Console to access
system-related functionality.
Click the General tab to view general system details, such as Roambi version and build:
- 85 -
Chapter 6: Maintenance
From this tab, you can also run the system diagnostic check as described in Running the
system diagnostic check.
Running the system diagnostic check
The Roambi server provides a system diagnostic utility to check that everything on the server
is configured correctly and to provide basic information about the system. This utility can be a
helpful starting point for troubleshooting. To run the system diagnostic check:
In the upper-right portion of the Administrator's Console, click the System tab to display the
list of system options on the left side of the screen.
From the list of system options on the left side of the screen, click General to display the System Status options:
- 86 -
Running the system
diagnostic check
In the System Status box, click the Run Diagnostic button.
Roambi runs the quick system check and displays the results in the System
Diagnostic Results window:
- 87 -
Chapter 6: Maintenance
The following table lists the checks that the diagnostic utility performs. If the diagnostic check
finds a problem read the Solution column to help resolve the problem.
Check Description Solution
Active Portals
Portal Integrity Check and Repair
Primary Login Option
License Key
License Key
SMTP Configured
Upload Folder
Server Headless Mode
Roambi Flow Thumbnails
JAI Status
OpenOffice
Font Rendering
Checks that at least one portal
is active and configured.
Validates all portal
configurations.
Determines if at least one
portal is configured as a
primary login option.
Validates the Roambi ES
license key.
Validates the Roambi
server license key. The SMTP Server settings
required for Roambicast
have been configured. Verifies that the Roambi
server can write to the
directory for file uploads.
Checks that the server is
running in headless mode.
Checks that the system is
configured for Roambi
Flow thumbnails. Checks that JAI is
correctly configured. Verifies that OpenOffice is
properly configured and running.
Displays how the server will
render the system font.
Check that you can connect to the
portal outside of Roambi, then
check that the portal is enabled in
Roambi. If you can connect to the
portal, check that the portal was
configured properly. Checks that all portals have
valid configurations. Check that Enable Primary Login
is turned on for at least one portal. Check the Roambi ES5
Installation Guide for instructions
to install the License Key. Contact Roambi support to
troubleshoot your license key.
Follow the instructions in
Configuring Roambicast to
configure the SMTP settings. Check that the upload folder on the
server machine has write
permissions set. Use the Java Memory Settings to
instruct the server to run in
headless mode. Validates that Roambi Flow will
correctly be able to render
thumbnail images.
Displays sample of JAI rendering.
Check the Roambi ES5
Installation Guide for instructions
on configuring OpenOffice. Make sure that the correct fonts are
on the server. See Modifying the
display language for Roambi if you
need help with language support.
- 88 -
Migrating to a new Roambi
ES release
Migrating to a new SAP Roambi ES release For most new releases, upgrading to a new Roambi ES release should be as easy as backing up
the Roambi MySQL database and installing the new Roambi application. However, occasionally,
you might need to perform additional installation steps. Each release of Roambi ES includes a
Migration Guide with instructions on how to migrate from previous versions to the current release.
Refer to this guide for details on migrating to the current release of Roambi ES.
- 89 -
Chapter 7: Load Balancing
Load balancing helps to improve SAP Roambi performance and reliability by using a set
up that has redundant Roambi servers and an appliance that controls traffic to these
servers. Using a load balancing appliance as part of your Roambi system configuration provides
three significant benefits:
High availability: If one Roambi server fails, requests are routed to the other available
servers as part of health monitoring, if supported by your load balancing appliance.
Transparency of maintenance: Taking a Roambi server offline to perform maintenance
is nearly transparent to end users of the Roambi application.
Performance scaling: You can upgrade one server while other servers in the cluster
serve requests with the same externally available URL.
Two load balancing appliance options are the BIG-IP Local Traffic Management (LTM)
appliance and the Cisco ACE load balancer.
Load balancing and failover
The high availability option for SAP Roambi ES eliminates having a single point of failure in
the server configuration and helps reduce failure risk throughout the configuration. To ensure
high availability, SAP recommends hosting Roambi ES in a load balanced and redundant
environment.This environment should have the following characteristics:
Two or more application servers with Roambi should be running behind a single
load balancer.
The environment should maintain session affinity for Roambi Publisher requests.
One configuration might use two Apache HTTP servers to take incoming HTTP requests and
balance them across a dynamic pool of application servers via the Apache Tomcat Connector AJP.
This architecture is an example of Tomcat clustering. In this case, the load balancer detects when
an application server is unavailable and stops sending traffic to that server. Both the load balancer
and individual application servers can be swapped out in the event of a failure. Note: If you are using a load balancing appliance, you must set sessions to be sticky on the
load balancer.
- 90 -
Chapter 7: Load Balancing
Using a BIG-IP Local Traffic Management
appliance for load balancing One way of performing load balancing with SAP Roambi is to use a BIG-IP Local Traffic
Management (LTM) appliance. This section discusses the specifics of setting up and using this
type of appliance for Roambi servers.
Basic network for Roambi with a BIG-IP appliance The following network diagram shows a basic system with two Roambi servers that
communicate with redundant BI systems. The Roambi servers are connected to the BIG-IP
LTM appliance, which resides behind the corporate firewall. Roambi users communicate with
their mobile devices from outside of the firewall.
The following topics in this section discuss how to set up and use a BIG-IP appliance with Roambi:
Creating an HTTP Health Monitor for a BIG-IP appliance
Defining a Roambi server pool
Creating an HTTP profile
Creating a TCP profile (optional)
Creating a virtual server Note: This section does not discuss setting up the BIG-IP appliance itself. See the
documentation for your appliance for specific instructions.
- 91 -
Creating an HTTP health monitor for a BIG-IP
appliance
Creating an HTTP health monitor for a
BIG-IP appliance Create an HTTP health monitor to periodically check if Tomcat is up and to display health
status to the BIG-IP management console. Health monitoring is crucial to BIG-IP's capability
to route traffic only to Roambi servers that are available for requests. To create an HTTP health monitor:
Log in to the management console for your BIG-IP appliance.
From the Local Traffic menu, select Monitors > Create.
Under General Properties, set Type to HTTP.
Under Configuration, set the Interval and Timeout. Timeout should be 3x the value
of Interval. For example, if you set Interval to 60, set Timeout to 180.
In the Send String text box, type GET /\r\n.
In the Receive String text box, type <!--.
Save the health monitor.
Defining a Roambi server pool After creating the HTTP health monitor for Roambi, you will need to define a destination server
pool for the load balanced Tomcat servers running Roambi. BIG-IP will route requests to the
servers in this pool using the specified load balancing method. The following instructions assume
a pool that contains two or more Roambi destination servers running on port 886. To create a Roambi server pool:
Log in to the management console for your BIG-IP appliance.
From the Local Traffic menu, select Pools > Create.
From the Configuration list, select Advanced.
In the Active Monitor section, specify the HTTP health monitor that you just created.
For the Slow Ramp Time text box, determine the number of allowed requests per second to
BIG-IP divided by the number of servers in the pool. SAP recommends initially setting this
value to 30, but you can change it later if you need more or less throughput.
From the Load Balancing Method list, choose a load balancing method. The
default method is Round Robin.
In the Address text box, type the IP address for each Tomcat server running Roambi.
In the Service Port text box, type the port for the Tomcat connector. For example, 886.
Save the server pool.
- 92 -
Chapter 7: Load Balancing
Creating an HTTP profile
After defining the pool for your Roambi servers, you will need to create an HTTP profile that
will be used by the server pool. To create an HTTP profile to be used by the Roambi server pool:
Log in to the management console for your BIG-IP appliance.
From the Local Traffic menu, select Profile > Create.
From the Parent Profile drop-down list, select http.
Under Settings, from the Redirect Rewrite drop-down list, select All.
Save the profile. Enabling Redirect Rewrite for the HTTP profile ensures that trailing forward slashes ("/") are
present at the end of all URIs, which are lost when they are rewritten. These slashes are
necessary for Roambi to properly resolve URIs.
Creating a TCP profile (optional)
You have the option of creating a TCP profile for your system, or you can use a preconfigured
profile. Any TCP profile should have Redirect Rewrite enabled.
Creating a virtual server
The final task for setting up a BIG-IP appliance to load balance Roambi servers to create a
virtual server. This virtual server is defined by and references the Roambi server pool and the
profiles that you previously created. The virtual server listens for a request to Roambi ES and,
after performing any processing defined in the HTTP profile, forwards the request to one of
the Tomcat servers referenced in the Roambi Pool. To create a virtual server for BIG-IP to use with Roambi:
Log in to the management console for your BIG-IP appliance.
From the Local Traffic menu, select Virtual Servers > Create.
Under General Properties, set the Service Port number and type to 443 and HTTPS.
From the Configuration list, select Advanced.
Choose the following configuration options for the virtual server: From the Type drop-down list, select Standard. From the Protocol drop-down list, select TCP.
From the HTTP Profile drop-down list, select the HTTP profile with Redirect
Rewrite enabled that you created.
From the SSL Profile (Client) drop-down list, select the SSL profile that you are using.
- 93 -
Using a Cisco ACE load balancer with Roambi
Under Load Balancing, choose the following options: From the Default Pool drop-down list, select the Roambi pool that you
previously defined. From the Default Persistence Profile drop-down list, select cookie.
Click the Resources tab of the virtual server, and unselect the default httpclass profile.
Save the virtual server.
Using a Cisco ACE load balancer
with Roambi If you are using a Cisco ACE load balancer with Roambi, set up your configuration as
described in the Cisco product documentation. In your configuration file, add the following line to set up SSL redirect:
action-list type modify http urlrewrite
ssl url rewrite location "www\.cisco\.com"
- 94 -
Chapter 8: Firewall Placement
As you plan your security configuration for the SAP Roambi server, keep in mind that the
server needs to be accessible by end users' mobile devices. For many configurations, the
mobile devices will be external to the corporate network. Most organizations use one of three
possible locations for their Roambi server:
Behind the corporate firewall; users access the server via VPN.
Behind the corporate firewall with a reverse proxy.
Behind a Demilitarized Zone (DMZ).
Behind a DMZ with a load balancing appliance.
The sections in this chapter discuss each of these options as well as the pros and cons
to their implementations.
SAP Roambi behind a firewall and client VPN
The most basic security option for Roambi is to place the Roambi server behind a corporate
firewall, and to have users connect to the server via VPN. Client devices use VPN to connect
to the Roambi server just as they would to any other network resource. The following diagram
shows an example of this type of deployment:
- 95 -
Chapter 8: Firewall Placement
VPN options for the iPhone provide additional flexibility. See the Apple web site for
documentation about setting up VPN: http://support.apple.com/kb/HT1424 The firewall-VPN-based deployment type of configuration has two main benefits:
Implementation for Roambi ES is simple.
You can use the existing infrastructure for network access outside of the firewall.
This type of configuration also has two major drawbacks:
Users need two passwords to access the Roambi server: one password for VPN and a
second password for the Roambi portal.
This configuration does not use a two-factor authentication approach.
Additionally, if you choose to use a VPN-based deployment, SAP recommends using HTTPS for
data encryption.
SAP Roambi behind a firewall and reverse proxy
You can use a reverse proxy to allow outside access to Roambi users without requiring
additional passwords and still obfuscate the network infrastructure behind the firewall. This
section gives an overview of an architecture that uses a reverse proxy with Roambi and reverse
proxy commands for three popular proxy solutions.
Reverse proxy architecture The following diagram shows an example of this configuration:
A reverse proxy configuration provides two main benefits:
The configuration has a single point of access and control.
Reverse proxy allows secure outside access.
- 96 -
Roambi behind a firewall and
reverse proxy
Reverse proxy has two primary drawbacks:
If the reverse proxy is compromised, the attacker could gain insight into the HTTP
server infrastructure.
If the system does not use a load balancing appliance, this configuration could have a
single point of failure.
Although you can run Roambi on an application server running either HTTP or HTTPS, SAP
recommends using HTTPS for additional security.
Setting up a reverse proxy for Microsoft IIS
To set up a reverse proxy for IIS:
From the Windows Start menu, start the Internet Information Services (IIS) Manager.
The IIS Manager starts, displaying a server tree in the left pane and management
functions in the right pane.
Create a server farm for Roambi: Expand the server tree in the left pane to view the available Server Farms. Right-
click the Server Farm entry, and select Create Server Farm... from the context
menu. A Create Server Farm window opens.
In the Server Farm name text box, type a unique, descriptive name for the
server farm, such as "Roambi". Click Next.
The Add Server screen displays.
In the Server Address field of the Add Server screen, enter the server address
for the first internal web server that you want to add.
Expand Advanced Settings and set the httpPort to 8080 to match the port used
by the internal server.
Click the Add button to add the server to the farm.
Repeat the steps to add a server for each server that you want to add to the farm.
When you have finished adding all of your servers for the farm, click the Finish button.
When prompted, click Yes to add the URL rewrite rules.
Repeat the previous set of steps for each server farm that you want to create. The
IIS Manager adds each server farm as it is created to the tree on the left pane.
Set up the URL rewrite rules for the first server farm: On the left pane of the IIS Manager, select the server farm. On the right pane,
double-click URL Rewrite to display URL rewrite options. From the Actions menu at the far right, select Add under
conditions. An Add Condition window opens.
- 97 -
Chapter 8: Firewall Placement
On the Add Condition window, use the following settings: In the Condition input field, enter {HTTP_HOST}.
From the Check if input string drop-down list, select Matches the Pattern.
In the Pattern field, type the Fully Qualified Domain Name (FQDN) that
corresponds to the server farm. The pattern should end with an asterisk (*).
For example, roambi.myserver.com*.
Check the Ignore case box.
Click OK.
From the Actions menu at the far right, select Add under conditions to add a second
condition. On the Add Condition window, use the following settings:
In the Condition input field, enter {URL}.
From the Check if input string drop-down list, select Matches the Pattern.
In the Pattern field, type either */roambi/* or simply * if all IIS traffic is
dedicated to Roambi.
Check the Ignore case box.
Click OK.
Repeat the set of steps to set up the URL rewrite rules for each server farm that will be using
reverse proxy. After configuring the reverse proxy for IIS, install the IIS Application Request Routing (ARR)
extension and security certificates to IIS as described in Installing SSL certificates to IIS.
Setting up a reverse proxy for Apache To set up a reverse proxy for an Apache web server:
Navigate to the Tomcat server.xml file:
[TomcatDirectory][version]\conf\server.xml
Open the server.xml file in a text editor.
Add the following element to enable the Apache JServ Protocol (AJP) connector:
<Connector port=”8009” protocol=”AJP/1.3” redirectPort=”8443”/>
Open the Apache httpd.conf file in a text editor.
Append the following two lines to the httpd.conf file:
ProxyPass /roambi ajp://localhost:8009/roambi
ProxyPassReverse /roambi ajp://localhost:8009/roambi
This configuration routes all incoming /roambi traffic to Tomcat using the AJP protocol with the
port 8009 that you configured for Tomcat. Apache also performs a URL rewrite on the response,
meaning that Apache performs a global search-and-replace for localhost:8009 to Apache's
name and port.
- 98 -
Demilitarized
Zone (DMZ)
Setting up a reverse proxy for Citrix Netscaler
Use the following commands to rewrite the HTTP response to HTTPS as part of the
rewrite method:
add rewrite action replace_https replace_all
'HTTP.RES.BODY(100)' '"https://"' -pattern http:// add rewrite policy replace_http_pol TRUE replace_https NOREWRITE bind lb vserver <VSERVER_NAME> -policyname replace_http_pol -priority 1 -type RES_DEFAULT
Setting up a reverse proxy and SSL rewrite for
Apache HTTPD mod_proxy See the Apache documentation for complete information about mod_proxy.
To modify the Apache HTTPD mod_proxy configuration for reverse proxy and to set up the
SSL re-write:
In a text editor, open the proxy.conf file that is referenced by httpd.conf.
Add the following lines of code:
Forwarding using mod_proxy
RewriteEngine On
ProxyPass /server-error-page/ ! ProxyPass / http://[RoambiAppServer]:[Port]/
ProxyPassReverse / http://[RoambiAppServer]:[Port]/
Force to ssl
RewriteEngine On ReWriteCond %{HTTPS} !=on RewriteRule .* https://%{HTTP_HOST}:443%{REQUEST_URI
[QSA,R=permanent,L]
Replace the values for the [RoambiAppServer]:[Port] with the correct server URL
and Port for your Roambi server.
Demilitarized Zone (DMZ)
A Demilitarized Zone (DMZ) deployment for Roambi places a web server inside of the DMZ.
The web server then forwards requests to the Roambi application server. A typical DMZ
deployment has an inner firewall and an outer firewall, with the web server between the two
firewalls. The Internet, or in the case of Roambi, a mobile device is outside of the outer
firewall and only communicates with the web server. The Roambi server and BI system are
behind the inner firewall, and also only communicate with the web server. With a DMZ
configuration, you only need to open the necessary ports on the firewalls. The following
diagram shows an example of this arrangement:
- 99 -
Chapter 8: Firewall Placement
If you have redundant Roambi servers, you can increase security by setting up a host-based
firewall for each server. This arrangement increases protection if one of the web servers in the
DMZ is compromised. An even more secure option would be to set up a two-part DMZ where
you add a third firewall between the Roambi server and the BI system.
DMZ with load balancing
One of the most complex available deployment options is to use a load balancing appliance
inside of a DMZ. In this scenario, the load balancing appliance sits between two firewalls and
handles incoming and outgoing requests. When a client mobile device makes a request, the
following series of events occurs:
The load balancing appliance in the DMZ sends the incoming request to a web farm behind
the inner firewall.
One of the web servers in the web farm then forwards the request to the cluster of
application servers hosting Roambi.
The Roambi server that takes the request forwards the request on to the clustered BI system. Outgoing requests travel the same chain, but in reverse order. The following diagram
shows an example of this configuration:
- 100 -
Using Threat Management Gateway (or Internet Security and Application Server) with Roambi
For this type of configuration, sessions are attached to individual requests and servers via a
"sticky session". With a "sticky session", incoming requests from the Roambi app on mobile
devices go to the same server that was accessed in the initial request. The section Using a BIG-IP Local Traffic Management appliance for load balancing discusses
how to set up the load balancing part of this configuration for one specific type of appliance.
Using Threat Management Gateway (or
Internet Security and Application
Server) with Roambi Another firewall option for Roambi is to use Microsoft Forefront Threat Management Gateway
(TMG), which can act like a reverse proxy. The older equivalent of TMG is called Microsoft
Internet Security and Application Server (ISA), which Roambi also supports as a firewall solution.
TMG integration with Roambi A Roambi ES configuration that is integrated with TMG should usually look like the
following diagram:
This Roambi/TMG configuration would typically use the following workflow:
- 101 -
Chapter 8: Firewall Placement
The Roambi client app attempts to hit the TMG server.
The TMG server responds with a Basic or Form-based Authorization challenge.
The Roambi client app presents the UI to the user.
The user supplies credentials that are passed to TMG.
TMG passes the request/response to the Roambi server using either a Basic or
Kerberos authentication challenge/response (depending on the TMG configuration).
The Roambi server internally converts the Basic or Kerberos authentication into a
Kerberos context for the user.
The Roambi server passes the Kerberos context to the BI system.
The Roambi server replies to the Roambi client.
Setting up TMG for Roambi
To set up TMG with Roambi:
Follow the instructions in the SAP Roambi ES Installation Guide to install and configure
Roambi ES for your BI system using Kerberos. Make sure to follow the instructions in
the Kerberos-related sections.
Create a pass-through firewall policy in TMG. Use the pass-through firewall to make sure that
you are using the correct server name and settings so that traffic is passing through TMG and
being directed to the correct server. Once you are sure that the server name, port, and other
settings are correct, change the firewall policy to a policy that includes client authentication.
Enable HMTL form-based authentication for iOS devices (optional).
Configure application server authentication for TMG and the Roambi server.
Creating a firewall policy in TMG for the Roambi client
To configure TMG for the Roambi client:
In TMG, open the Microsoft Forefront TMG Management console tree,
Set the firewall policy for the server: In the left pane, click Firewall Policy to view firewall policy options. In the right pane, select the policy for the server.
Set the listener:
Click the Listener tab. Select the appropriate listener.
Set up authentication:
Click the Authentication tab. From the Client Authentication Method drop-down list, select HTML Form
Authentication to use the TMG default, which sends a Basic Authentication challenge.
- 102 -
Using Threat Management Gateway (or Internet Security and Application Server) with Roambi
Enabling HMTL form authentication for iOS
devices (optional) TMG uses the User-Agent header sent by the client to determine which authentication
method to use. By default, if the client is a web browser, TMG will use form-based
authentication. If the client is not a browser, TMG will use HTTP Basic authentication. If you want to customize this setting to use form-based authentication, follow the instructions
on the Microsoft web site: http://technet.microsoft.com/library/bb794715.aspx#CreatinganewUserAgentmapping For a customized setting, make sure that the User-Agent for Roambi contains the string "Roambi". If you plan to use form-based authentication, you will need to enable that authentication
type on users' iOS devices. The ListUserAgentMappings Visual Basic script controls
user agent mappings. To enable HTML form-based authentication on users iOS devices, execute the
ListUserAgentMappings with the arguments specified in the following procedure:
To view the current TMG user agent mapping, type the following command:
C:\> cscript ListUserAgentMappings.vbs
The script lists the current user agent mappings:
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights reserved.
No. User-Agent headers Authentication type Enabled/disabled
1 *Blazer* XHTML-MP forms Enabled
2 *DoCoMo* cHTML forms Enabled
3 *Windows CE* XHTML-MP forms Enabled
4 *Symbian OS* XHTML-MP forms Enabled
5 *SonyEricsson* XHTML-MP forms Enabled
6 *Frontpage* Basic authentication Enabled
7 *MSOffice* Basic authentication Enabled
8 *Mozilla* HTML 4.01 forms Enabled
9 *Opera* HTML 4.01 forms Enabled
10 *MSRPC* Basic authentication Enabled
11 * Basic authentication Enabled
Type the following command to add the *Roambi* pattern to the list:
C:\> cscript AddUserAgentMapping.vbs *Roambi* HTML4
The script displays a confirmation message:
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights
reserved. Done!
- 103 -
Chapter 8: Firewall Placement
Verify that the *Roambi* pattern was added correctly:
C:\> cscript ListUserAgentMappings.vbs
The script output shows that *Roambi* has been added to the bottom of the list:
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights reserved.
No. User-Agent headers Authentication type Enabled/disabled
1 *Blazer* XHTML-MP forms Enabled
2 *DoCoMo* cHTML forms Enabled
3 *Windows CE* XHTML-MP forms Enabled
4 *Symbian OS* XHTML-MP forms Enabled
5 *SonyEricsson* XHTML-MP forms Enabled
6 *Frontpage* Basic authentication Enabled
7 *MSOffice* Basic authentication Enabled
8 *Mozilla* HTML 4.01 forms Enabled
9 *Opera* HTML 4.01 forms Enabled
10 *MSRPC* Basic authentication Enabled
11 * Basic authentication Enabled
12 *Roambi* HTML 4.01 forms Enabled
Re-order the rules so that *Roambi* appears after the * entry:
C:\> cscript ListUserAgentMappings.vbs up 12
The script displays a confirmation message:
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights
reserved. Moving the User-Agent mapping specified up...
Done!
Verify the result:
C:\> cscript ListUserAgentMappings.vbs
The script output shows that *Roambi* has been moved to number 11 on the list:
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation. All rights reserved.
No. User-Agent headers Authentication type Enabled/disabled
1 *Blazer* XHTML-MP forms Enabled
2 *DoCoMo* cHTML forms Enabled
3 *Windows CE* XHTML-MP forms Enabled
4 *Symbian OS* XHTML-MP forms Enabled
5 *SonyEricsson* XHTML-MP forms Enabled
6 *Frontpage* Basic authentication Enabled
7 *MSOffice* Basic authentication Enabled
8 *Mozilla* HTML 4.01 forms Enabled
9 *Opera* HTML 4.01 forms Enabled
- 104 -
Using Threat Management Gateway (or Internet Security and Application Server) with Roambi
10 *MSRPC* Basic authentication Enabled
11 *Roambi* HTML 4.01 forms Enabled
12 * Basic authentication Enabled
Configuring Tomcat, TMG, and Kerberos
To configure the Tomcat application server for TMG:
Open the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-
INF/web.xml file in a text editor.
Change the value of the status-overide.enabled context parameter to true:
<context-param> <param-name>status-
override.enabled</param-name> <param-
value>true</param-value>
</context-param>
Uncomment the block related to the SpnegoAuthFilter. (If your version of the web.xml
file does not contain this block, copy and paste the block into the file.)
<filter> <filter-
name>SpnegoAuthFilter</filter-name>
<filter-
class>com.mellmo.roambi.servlet.filter.SpnegoAuthFilter</filter-
class> <init-param>
<description><![CDATA[the 'application name' in Java
logic.conf file.]]></description>
<param-name>app_name</param-name> <param-
value>com.sun.security.jgss.accept</param-value>
</init-param>
<init-param>
<description><![CDATA[ if specified, used as the server account to
authenticate user. the account needs to be one associated with
the SPN.]]></description>
<param-name>server.user_name</param-
name> <param-value>account</param-value>
</init-param>
<init-param>
<description><![CDATA[ if specified, used as the server
account password]]></description>
<param-name>server.password</param-name>
<param-value>password</param-value>
</init-param>
<init-param>
<description><![CDATA[if specified, the server will challenge
with BASIC authentication as well.]]></description>
<param-name>enable_basic</param-name>
<param-value>true</param-value>
</init-param>
- 105 -
Chapter 8: Firewall Placement
<init-param>
<description><![CDATA[ specifies the interval of time between a
force authentication. Typically, once authenticated, the client
will preemptively add Authentication header. When set, we will
force an authentication. Value in seconds.]]></description>
<param-name>force_auth_interval</param-
name> <param-value>120</param-value>
</init-param>
</filter>
<filter-mapping> <filter-name>SpnegoAuthFilter</filter-
name> <url-pattern>/*</url-pattern>
</filter-mapping>
Verify that the enable-basic parameter is set to true, and restart Tomcat. Verify that the Romabi server can use your credentials and issue a valid Kerberos ticket:
With your web browser, navigate to the URL for Roambi ES.
Your browser prompts you for your username and password.
Use your credentials to log in.
If you can successfully log in, Roambi was able to validate your credentials and
issue a valid Kerberos ticket.
Change the single sign-on (SSO) option for Roambi to Kerberos:
In the Roambi Administrator's console, click the System tab at the top, and then
click Security in the left pane. From the Single Sign-on Type drop-down list, select Kerberos:
Navigate to your BI portal and on the Security tab for the portal, enable the Single Sign-on
option for that portal. You can also (optionally) enable the primary login option for the
- 106 -
Using Threat Management Gateway (or Internet Security
and Application Server) with Roambi
portal:
Log out of the Roambi web application.
The login page displays a confirmation message:
- 107 -
Chapter 8: Firewall Placement
In the TMG Management Console, change the Authentication method for the firewall
policy to Basic Authentication. Use the setspn utility that ships with Windows to configure Kerberos and create a keytab
file. (See the Microsoft web site to learn more about setspn:
http://support.microsoft.com/kb/929650.) Type the following command to set up the Service Principal Name (SPN):
C:\> setspn -F -S HTTP/[FullyQualifiedServerName]
[DomainUserAccount]
For example:
C:\> setspn -F -S HTTP/tmg10.myserver.lan TomcatNew
Note that the domain user account must have "Trust this user for delegation to
any service (Kerberos only) enabled.
Type the following command to create the keytab file:
C:\> setspn -F -S HTTP/ServerNameDomainUserAccount
C:\> ktpass /princ HTTP/[Username]@ServerName /pass Passord
/ptype KRB5_NT_SRV_INST /crypto AES256-SHA1 /out
DomainUserAccount.keytab /mapuser DomainUserAccount
For example:
C:\> setspn -F -S HTTP/tmg TomcatNew
- 108 -
Using Threat Management Gateway (or Internet Security and Application Server) with Roambi
C:\> ktpass /princ HTTP/[email protected] /pass
Pass1234 /ptype KRB5_NT_SRV_INST /crypto AES256-SHA1 /out TomcatNew.keytab /mapuser TomcatNew
In your login.conf file, set your app_name parameter.
For example, if your app_name is com.mellmo.security.jgss.accept, the
corresponding block in your login.conf file should look similar to the following example:
com.mellmo.security.jgss.accept {
com.sun.security.auth.module.Krb5LoginModule required
isInitiator=false debug=true useKeyTab=true
keyTab="file://C:/Program Files/Apache Software
Foundation/Tomcat 6.0/tomcat_new.keytab"
principal=tomcat_ne
w storeKey=true;
};
Enabling TMG for client devices Some TMG features might require users to update their version of Roambi Visualizer on
their mobile devices. If users receive a 403 error on their devices, ask them to update the
Roambi Visualizer client app to the latest version.
- 109 -
Chapter 9: SSL
Because all communication between the SAP Roambi server and client mobile devices
uses HTTP requests, SAP recommends configuring SSL to ensure secure
communication when necessary. After you configure SSL for the application server, users will access Roambi via HTTPS instead of
HTTP. Of the many security features provided by HTTPS, the most important feature is that it
ensures that the client is communicating with the correct server, using the following steps:
The client contacts the server.
The server returns a certificate containing the name of the server.
If the certificate is signed by a trusted source, the client verifies that the certificate
is trustworthy. You have two choices for where to install SSL with regards to your Roambi configuration:
Preparing Tomcat to use SSL: Use this option when your Roambi configuration has
the Tomcat server in a DMZ (see Demilitarized Zone (DMZ)).
Installing SSL to a reverse proxy server: Use this option when your Roambi
configuration uses a reverse proxy (see Roambi behind a firewall and reverse proxy).
Preparing Tomcat to use SSL
If your Roambi configuration places your Tomcat server behind a Demilitarized Zone (see
Demilitarized Zone (DMZ)), install the SSL certificates directly to the Tomcat server. You will
need to install SSL to each instance of Tomcat being used by Roambi.
SSL requirements for SAP Roambi and Tomcat
Because of the many variables involved, troubleshooting SSL configuration issues can be difficult.
For SSL to work properly, your Tomcat configuration must meet the following conditions:
The server must be properly handling HTTPS traffic.
You must have a valid private key that matches the valid cert for the server.
A chain of certificates should tie the trusted certificate authority to the server certificate.
The same trusted certificate authority needs to be deployed on both the server and client.
- 110 -
Chapter 9: SSL
The client must be able to reach the server.
The host name of the server URL must match the Common Name (CN) of the certificate.
Enabling the Tomcat HTTPS connector To enable the HTTPS connector for Tomcat:
In the directory where Tomcat is installed, navigate to the /conf directory and open
the server.xml file in a text editor.
Locate and uncomment the <Connector> element that has the scheme="https"
attribute. For example:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" keyAlias="tomcat" keystoreFile="/Users/root/apache-
tomcat-7.0.21/conf/tomcat.keystore" keystorePass="password" />
Modify this <Connector>element as necessary for your configuration. A complete list
of attributes for this element is available in the Tomcat documentation:
http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html Once you have enabled the Tomcat HTTPS connector, install SSL to Tomcat using the
OpenSSL utility as described in Installing SSL to Tomcat using OpenSSL.
Installing SSL to Tomcat using OpenSSL
Tomcat should be using a trusted root Certificate Authority (CA) for SSL communication. You
can set up the trusted root CA for Tomcat by performing the following tasks:
Download and install the OpenSSL utility (see Downloading and installing the
OpenSSL utility).
Extract the root CA of the server (see Extracting the root CA of a server).
Use OpenSSL to check the contents of the PEM file (see Using OpenSSL to view the
contents of a PEM file).
Specify that the OpenSSL s_client should use a trusted certificate (see Specifying
that OpenSSL s_client should use a trusted certificate).
Verify the certificate files (see Verifying the certificate files).
Downloading and installing the OpenSSL utility The OpenSSL utility is free and available to download from the openssl.org web site: http://www.openssl.org/ Follow the instructions from the OpenSSL web site to download and install this utility to the
machine where you installed Tomcat.
- 111 -
Installing SSL to Tomcat using OpenSSL
Extracting the root CA of a server To extract the root CA of a server:
Use the showcerts argument for the openssl command to list all of the certificates for
a server:
$ openssl s_client -connect [ServerURL]:[Port] -showcerts
This command returns the following sample output:
CONNECTED(00000003)
depth=3 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY,
CN = TEST Root CA, emailAddress = [email protected]
verify error:num=19:self signed certificate in certificate
chain verify return:0
--- Certificate chain 0 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST
ONLY/CN=patcheng.local i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST
ONLY/CN=TEST SubCAUK 1/[email protected]
-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- 1 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST
SubCAUK 1/[email protected]
i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root
CA UK/[email protected]
-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- 2 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root
CA UK/[email protected]
i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST
Root CA/[email protected]
-----BEGIN CERTIFICATE-----
... -----END CERTIFICATE----- 3 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST
Root CA/[email protected]
i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST
Root CA/[email protected]
-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ---
In the command output, each block of text including ----BEGIN CERTIFICATE----
and ---END CERTIFICATE---- is an X509 certificate in PEM format.
- 112 -
Chapter 9: SSL
Find the last certificate in the certificate chain section. For example:
-----BEGIN CERTIFICATE-----
MIIC4jCCAkugAwIBAgIJAPImW4KOYI6bMA0GCSqGSIb3DQEBBQUAMIGJMQswCQYDVQQGEw JHQjEOMAwGA1UECAwFSGVydHMxFzAVBgNVBAoMDlRNVUsgVEVTVCBPTkxZMRcwFQYDVQQL DA5UTVVLIFRFU1QgT05MWTEVMBMGA1UEAwwMVEVTVCBSb290IENBMSEwHwYJKoZIhvcNAQ kBFhJwYXRyaWNrQG1lbGxtby5jb20wHhcNMTEwOTI2MjE0MzI2WhcNMTQwOTI1MjE0MzI2 WjCBiTELMAkGA1UEBhMCR0IxDjAMBgNVBAgMBUhlcnRzMRcwFQYDVQQKDA5UTVLIFRFU1Q gT05MWTEXMBUGA1UECwwOVE1VSyBURVNUIE9OTFkxFTATBgNVBAMMDRFU1gUm9vdCBDQTE hMB8GCSqGSIb3DQEJARYScGF0cmlja0BtZWxsbW8uY29tMIGMA0GCSqGSIb3DQEBAQUAA4 GNADCBiQKBgQDSXptRw1D07tMZD14wIKz1NaIZVNRI18B9+dUHpJASe5CTWv6wW8fFtLM obmmoveEkU9k+HZsezp9qavFWvArHHbIsQv+lEfSbuZRWOt/cWlYjTbDLyL3uzGtD7QNk GOuB7bGJqbp7lwtNIQejSphELCwaUqjP6gB+TOOJwIDAQABo1AwTjAdBgNVHQ4EFgQUTem 5P27Y8bTHLXUatRKxvlEYbPEwHwYDVR0jBBgwFoAUTem5P27Y8bTHLXUatRKxvlEYbPEwD AYDVR0UAwEB/zANBgkqhQFAOBgQDR0Rh0vbm9D39MQuTpzFlcl0IG1gTf4dTq3r -----END CERTIFICATE-----
Create a file named cert.pem, and copy and paste this last certificate to the file.
You can use OpenSSL to view the contents of this file.
Using OpenSSL to view the contents of a PEM file To use OpenSSL to view the contents of a Privacy Enhanced Mail (PEM) file, type the
following command: $ openssl x509 -in cert.pem -text
This command returns the following sample output:
- 113 -
Installing SSL to Tomcat using OpenSSL
Specifying that OpenSSL s_client should use a trusted
certificate Once you have the trusted root CA for the server, you must instruct OpenSSL s_client to
use that certificate. To instruct s_client to trust the certificate, type the following command: $ openssl s_client -connect [ServerURL]:[Port] -CAfile cert.pem
This command returns the following sample output:
- 114 -
Chapter 9: SSL
CONNECTED(00000003) depth=3 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN =
TEST Root CA, emailAddress = [email protected]
verify return:1 depth=2 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN =
TEST Root CA UK, emailAddress = [email protected]
verify return:1 depth=1 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN =
TEST SubCAUK 1, emailAddress = [email protected]
verify return:1 depth=0 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN
= myserver.local
verify return:1 --- ...
Verifying the certificate files
To verify the certificate files, type the following command: openssl verify -CAfile [TrustedCACert] [CertToVerify]
For example: openssl verify -CAfile ../rootCA/demoCA/cacert.pem chain.pem
This command returns the following sample output: chain.pem: OK
This output means that chain.pem is verified, all of the certificates are valid, and the
certificates can be tied to a trusted root CA. If you need to perform additional check or investigation for SSL, the SSL task reference
provides some useful commands.
SSL task reference
This section describes how to perform many common tasks related to SSL configuration
and troubleshooting when you have installed SSL directly to Tomcat.
Adding a trusted certificate authority (CA) to an iOS device If the certificate was purchased from a trusted Certificate Authority (CA) like Verisign or GoDaddy,
the root certificate should already be on the mobile device. The complete list of available trusted
root certificates for new releases of iOS is available on the Apple support web site.
If the certificate was not signed by a trusted CA, for example, the certificate is self-signed, you
will need to explicitly configure all of the client mobile devices to trust the root certificate by
adding the cer-tificate to the device.
To add a trusted certificate authority to an iOS mobile device:
- 115 -
SSL task reference
Create a configuration profile using the iPhone Configuration Utility: Download the iPhone Configuration utility (available from the Apple Support web
site) on your Windows or Mac computer. From the left pane, click the Configuration Profiles tab.
In the upper-left part of the pane, click the Add new item to library button.
On the General screen, enter the appropriate information as prompted.
On the left, select Credentials, then click Configure.
Add the CA cert. Click the + sign button to add any additional certs as necessary.
Install the configuration profile to the mobile device:
Connect the target mobile device to your computer using your sync cable.
The device should appear in the left pane of the iPhone Configuration Utility.
On the left pane, select your device, and click the Configuration Profiles tab.
Verify that the mobile device is unlocked, and click the Install button on the right
to go to the Install Profile screen on your device.
On the Install Profile screen, tap Install, then tap Install Now as prompted.
When the green checkmark appears, tap Done.
Connecting to the Roambi server via SSL and
troubleshooting connections Make sure that you are able to actually connect to the Roambi server via SSL. To connect
to the server, type the following command: $ openssl s_client -connect [ServerURL]:[Port]
For example: $ openssl s_client -connect mycompany.com/roambi:443
To troubleshoot an SSL connection, type the following command: $ openssl s_client -state -nbio -connect [ServerURL]:[Port] 2>&1 |
grep "^SSL" For example: $ openssl s_client -state -nbio -connect mycompany.com/roambi:443 2>&1 |
grep "^SSL"
Creating a keystore for Tomcat The following command creates a key-pair for the Tomcat application server by creating a
keystore named tomcat.keystore in the folder where you run the command: $ keytool -genkey -alias tomcat -keyalg RSA -keystore tomcat.keystore
- 116 -
Chapter 9: SSL
This command initiates a series of prompts. Try to provide as much information as possible
in the prompts. The "first and last name" specified in the prompts should be the fully-qualified hostname for the URL.
Creating a Certification Sign Request (CSR) for Tomcat
To create a Certification Sign Request (CSR) for Tomcat, type the following command: $ keytool -certreq -keyalg RSA -alias tomcat -file [ServerURL].csr -keystore tomcat.keystore
Importing a certificate file to Tomcat
To import the certificate file to Tomcat:
Type the following command to convert the .cert file from PEM format to Distinguished
Encoding Rules (DER) format, which is the format required by the Java keytool:
$ openssl x509 -in [ServerURL].cert -inform PEM -out [ServerURL].der
- outform DER
Type the following command to import the DER file to the Tomcat keystore:
$ keytool -import -alias tomcat -trustcacerts -file [ServerURL].der
Verifying SSL certificates via SSL Checker If the Roambi server is accessible via the internet, you can use the SSL Checker tool provided by
SSL Shopper to verify the SSL certificates for the server: http://www.sslshopper.com/ssl-checker.html
Viewing certificate details from a web browser
You can view details for a certificate using a recent version of the Firefox or Chrome browsers.
Click the icon at the left of the address bar to view certificate details.
View the certificate.
Verify that the Common Name (CN) matches the exact domain name of the Roambi
server and any other certificate details of interest.
Listing the certificates in a keystore If Tomcat or Java is handling SSL termination, the Java keystore will contain the certificates for
SSL. You can view these certificates using the Keytool utility. To list the certificates in a Java keystore, type the following command: $ keytool -list -v -keystore [KeystoreName]
- 117 -
SSL task reference
Validating the SSL requirements using OpenSSL If you have the OpenSSL toolkit installed, the OpenSSL command can validate most
SSL requirements. The following command connects to the to [ServerURL]:[Port] using HTTPS and retrieves
the server certificate: $ openssl s_client -connect [ServerURL]:[Port]
For example: $ openssl s_client -connect mycompany.com/roambi:443
This command returns the following sample output:
CONNECTED(00000003) depth=0 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN
= myserver.local
verify error:num=20:unable to get local issuer
certificate verify return:1
depth=0 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN
= myserver.local
verify error:num=27:certificate not
trusted verify return:1
depth=0 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN
= myserver.local
verify error:num=21:unable to verify the first
certificate verify return:1
--- Certificate chain 0 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=myserver.local
i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST SubCAUK
--- Server certificate -----BEGIN CERTIFICATE----- ... The next sections describe how to use the output from this command to verify the requirements.
Verifying the server connection using OpenSSL
To verify that OpenSSL was able to connect to the server, check the first line of the output: CONNECTED(00000003)
In this case, CONNECTED means that s_client was able to successfully connect.
Checking the certificate chain using OpenSSL
The certificate chain is returned after the connection and status lines. The following example
is the certificate chain from the sample output:
- 118 -
Chapter 9: SSL
--- Certificate chain 0 s:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=myserver.local
i:/C=GB/ST=Herts/O=TMUK TEST ONLY/OU=TMUK TEST ONLY/CN=TEST SubCAUK
---
In this output, s: indicates the subject, and i: indicates the issuer for the certificate. Verify that
the server listed for the Common Name (the value for CN=) is the same as the server name
used for the request. You might have multiple certificates in your output. If you see multiple certificates, the
certificates should form a chain where the issuer of the first certificate is the subject of the next
certificate. The issuer of the second certificate should then be the subject of the third certificate,
and so on. If the certificate was purchased from a certificate authority (CA), the end of the chain
should belong to that CA. If you did not purchase the certificate from a CA, the end certificate
should be a self-signed certificate. If the certificates are not forming a chain, see Issue:
Intermediate certificates are missing on HTTP server.
Verifying SSL certificates using OpenSSL Additionally, you can verify certificates by typing the following command: $ openssl verify –CApath [CertsPath] –purpose sslserver [d.cerPath]
For example: $ openssl verify -CApath /etc/ssl/certs -purpose sslserver /etc/ssl/d.cer
Verifying the Tomcat connector settings To verify that the Tomcat connector settings are correct:
In the directory where Tomcat is installed, navigate to the /conf directory and open
the server.xml file in a text editor.
Locate the <Connector> element for the port used by Roambi.
Verify that the value of the protocol attribute is correct. In most cases, the value should be
HTTP/1.1. Verify that the value of the keystoreFile attribute points to the correct path where you
set up the keystore file. Verify that the value of the keystorePass attribute is correct.
The following example shows a <Connector> element with SSL configured: <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" keystoreFile="[TomcatDirectory]\ke- ystore\key.keystore" keystorePass="pass" clientAuth="false" sslProtocol="TLS" />
- 119 -
Installing SSL to a reverse
proxy server
Installing SSL to a reverse proxy server If your Roambi configuration uses a reverse proxy (see Roambi behind a firewall and
reverse proxy), install SSL to the reverse proxy server and not to Tomcat. Commonly used
reverse proxy servers for Roambi include Microsoft IIS, BIG-IP, and Apache. The benefit of
the reverse proxy configuration is that you only need to install SSL to the reverse proxy
server and not to each instance of Tomcat. Regardless of which reverse proxy server you are using, you will need to configure
Tomcat to offload SSL.
Configuring Tomcat for SSL offloading
You will need to modify the server.xml file for your Tomcat application server to offload
SSL. The modified configuration enables Tomcat to not only run the SSL protocol, but to
proxy requests in a secure format using HTTP protocol. This configuration allows you to
install SSL only once and not on each instance of Tomcat in the server cluster. To modify the Tomcat server.xml file for SSL offloading:
Navigate to the server.xml file:
[TomcatDirectory][version]\conf\server.xml
Open the server.xml file in a text editor.
Locate the <Connector> element, which should look the same or similar to the
following example after you installed and configured Roambi:
<Connector URIEncoding="UTF-8" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
enableLookups="false" maxHttpHeaderSize="8192" maxPostSize="8388608"
maxSpareThreads="75" maxThreads="150" minSpareThreads="25"
port="8080" redirectPort="8443"/>
Change the value of the port attribute to "886".
Change the value of maxPostSize to "-1".
Add the attributes, scheme="https", secure="true",
keystoreFile=PathToFile, keystorePass=KeystorePassword, and
proxyPort="443. The keystoreFile contains the path to the file, and
the keystorePass contains the keystore password. The modified <Connector> element should be similar to the following example
(changes shown in bold):
<Connector URIEncoding="UTF-8" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
enableLookups="false" maxHttpHeaderSize="8192" maxPostSize="-1"
maxSpareThreads="75" maxThreads="150" minSpareThreads="25" port="886"
redirectPort="8443" scheme="https" secure="true" keystoreFile="myFile"
- 120 -
Chapter 9: SSL
keystorePass="password" proxyPort="443"/>
Save your changes, and restart the application server. This configuration for the Tomcat connector will proxy any requests to Tomcat port 80 to port 443 on
the server managing traffic. Port 443 then redirects to port 886 for Tomcat HTTP. Because Tomcat is
not running SSL, this traffic should be defined as secure (secure="true") . Users will not be able
to access Tomcat without first going through the server that manages traffic. (You can add a second
<Connector> element with a different port to test directly accessing Tomcat via HTTP.) Once you have Tomcat configured to offload SSL, see SSL and BIG-IP appliances or Installing
SSL certificates to IIS to install SSL to your reverse proxy server, depending on which server
you are using.
Configuring Tomcat behind a reverse proxy You will need to modify the server.xml file to run Tomcat behind a reverse proxy. Your
modification will create a new connector with a different port so that you will have a dedicated
port for troubleshooting behind the proxy. To modify the Tomcat server.xml file to run Tomcat behind a reverse proxy:
Navigate to the server.xml file:
[TomcatDirectory][version]\conf\server.xml
Open the server.xml file in a text editor.
Locate the <Connector> element, which should look the same or similar to the
following example after you have installed and configured Roambi: <Connector URIEncoding="UTF-8" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
enableLookups="false" maxHttpHeaderSize="8192" maxPostSize="8388608"
maxSpareThreads="75" maxThreads="150" minSpareThreads="25"
port="8080" redirectPort="8443"/>
Copy and paste this <Connector> element into the file to create a duplicate element.
Remove the redirectPort="8443" attribute from the new <Connector> element.
Determine if the proxy performs SSL. If the proxy uses SSL, add the following attributes to the new <Connector> element:
scheme="https" secure="true" proxyPort="443" proxyName="proxy FQDN"
Note that the proxyPort can change, but should usually be 443.
If the proxy does not use SSL, add the following attributes to the new
<Connector> element:
proxyPort="80" proxyName="proxy FQDN"
Note that the proxyPort can change, but usually should be 80.
Save your changes, and restart the application server.
- 121 -
Installing SSL to IIS
SSL and BIG-IP appliances A BIG-IP appliance can not only load balance Roambi servers, but can also offload SSL from
a Tomcat application server. SSL offloading facilitates the management of SSL certificates and
reduces the overall cost of managing SSL. A BIG-IP appliance centralizes SSL to one location
so that every server using SSL no longer needs to have SSL certificates installed or run
HTTPS. If your BIG-IP appliance has SSL Acceleration installed, it can also handle many more
SSL requests, which cost more resources than standard HTTP requests. For instructions on configuring SSL for a BIG-IP appliance, see Creating a virtual server
in the section of this guide that discusses configuring a BIG-IP appliance.
Installing SSL to IIS
If you are using a Microsoft IIS web server and plan to use SSL security, you will need to
install the SSL certificates to IIS.
Downloading and installing the ARR extension for IIS
Before you install the SSL certificates, you need to install the Application Request Routing
(ARR) exension for IIS. To install the ARR extension for IIS:
Download the ARR extension by signing in to Microsoft.com as prompted and clicking
the Install Now button on the following web page:
http://www.microsoft.com/web/gallery/install.aspx?appid=ARRv2_5
Save and then double-click the downloaded .exe file to start the installation
process. The IIS extension Installation Wizard starts.
Follow the Installation Wizard prompts to accept the license agreement and install
the extension to your IIS server.
Installing the certificate files Once you have installed the ARR extension to IIS, you can install the files for the SSL certificates.
To install the SSL certificate files to IIS:
From the Windows Start menu, start the Internet Information Services (IIS) Manager.
The IIS Manager starts, displaying a server tree in the left pane and management
functions in the right pane.
Import the SSL certificates: From the left pane of the IIS Manager, select the server. On the right pane,
double-click Server Certificates.
- 122 -
Chapter 9: SSL
On the left, the IIS Manager displays a list of certificates, and on the right, displays the Actions menu.
From the Actions menu, select Import...
An Import Certificate prompt displays.
From the Import Certificate prompt, browse to the certificate file (.pfx file) that you
want to import, and enter the password for the certificate. Click OK to import the certificate.
If the certificate file did not contain the intermediate certificates from the CA, manually
install them using the instructions in Installing the intermediate certificates from the
Certificate Authority (CA).
Bind the certificates: On the left pane of the IIS Manager, select the default web site, and then select
Edit Bindings from the Actions menu at the right of the screen.
A Site Bindings window opens.
On the Site Bindings window, click the Add...
button. An Add Site Binding window opens.
On the Add Site Binding window, use the following settings: From the Type drop-down list, select https.
From the IP address drop-down list, select All Unassigned.
In the Port text box, type 443.
From the SSL certificate drop-down list, select the certificate that you
just imported.
If no certificates are listed, the certificate was not installed correctly.
Click OK.
If the intermediate certificates for this file were not installed correctly, an error
prompt displays. See Installing the intermediate certificates from the Certificate
Authority (CA) to fix the issue.
The Site Bindings window displays the new site bindings.
Click Close to complete the process. If you are using a reverse proxy as part of your security architecture, you can set up this
configuration now. See Setting up a reverse proxy for Microsoft IIS .
Installing the intermediate certificates from the Certificate
Authority (CA) to IIS If any of the SSL certificate files that you installed to IIS did not contain the intermediate
certificates from the CA, you will need to manually install them to IIS.
- 123 -
Installing SSL to IIS
To manually install the intermediate certificates:
Go to the web site for the CA and manually download the missing intermediate
certificates. Save these files to the computer where IIS is installed.
Right-click the downloaded certificate and select Install Certificate from the context
menu. The Certificate Import Wizard opens.
On the first screen of the Certificate Import Wizard, click
Next. The Certificate Store screen displays.
On the Certificate Store screen, choose the Automatically select the certificate store
based on the type of certificate option, and click Next.
The Completing the Certificate Import Wizard screen displays.
Click Finish to complete the import.
At the prompt, click OK to complete the process.
- 124 -
Chapter 10: Single Sign-
on (SSO) Single Sign-on (SSO) allows SAP Roambi users to log in only once to a system and have
access to both Roambi and the integrated BI tools that are part of the system configuration.
Roambi ES5 supports CA SiteMinder or Trusted Auth as SSO solutions. Single Sign-on (SSO) allows Roambi users to log in only once to a system and have access to
both Roambi and the integrated BI tools that are part of the system configuration. Roambi ES5
supports using CA SiteMinder as an SSO solution.
The SSO solution sits between the web browser and the web application on the server.
When a user attempts to connect to Web App1, the SSO solution will authenticate that
user. Once authenticated, that same user will also be able to connect to Web App2 without
having to go through the authentication process again.
- 125 -
Chapter 10: Single Sign-on (SSO)
This chapter discusses Roambi system architecture with a SSO solution at a high level and
then describes how to integrate the supported SSO options with Roambi.
Using SSO with SAP Roambi
Using Roambi with an SSO solution adds another layer of complexity beyond simply placing the
SSO solution between the web browser and web application. SSO solutions intercept HTTP traffic and add authentication and session management on top of
what has already been implemented on the web server. Roambi supports the use of a login form
to help facilitate SSO. Roambi supports the use of a SSO solution with the following BI portals:
SAP BOE (SiteMinder or Trusted Auth)
Cognos (SiteMinder)
SharePoint (SiteMinder)
SiteMinder provides SSO by using cookies to store session information. (Trusted Auth
works by storing the value of the X-Roambi-User-ID HTTP header.) Roambi supports the use of SiteMinder as an SSO solution. SiteMinder provides SSO by
using cookies to store session information. The following process describes how SSO works with cookie-based SSO solutions:
A client first connects to the system and does not have the proper cookie yet.
The SSO solution then starts the authentication process.
Once the client is authenticated, the SSO solution sends a cookie to the client. The scope
for the cookie typically includes the IP domain (myserver.com).
If a client connects to a different application, the SSO solution intercepts the request
and checks the cookie value. The following diagram shows the placement of the SSO solution for a system using Roambi ES:
- 126 -
Using SSO with Roambi
In this diagram, the SSO layer sits in front of the Roambi server. Both SiteMinder and OAM
integrate with the Apache HTTP server and IIS, so you will need to install one of these web
servers to use SSO with Roambi. In this diagram, the SSO layer sits in front of the Roambi server. SiteMinder integrates with
the Apache HTTP server and IIS, so you will need to install one of these web servers to use
SSO with Roambi.
HTTP requests between mobile device and SSO solution When the Roambi application on a user's mobile device sends an HTTP request to the Roambi
server where an SSO solution is configured for the system, the following events occur:
The Roambi application on the mobile device sends a workflow request to the SSO solution.
The SSO solution then returns HTTP status code 302 (Found) to an HTML page.
The Roambi application on the mobile device displays the HTML page until the request
is redirected back to the original request.
The SSO solution allows the request to pass through and drops cookies to the device.
The device stores the cookies so that credentials are not stored on the device.
HTTP requests between the SSO solution and Roambi
server Depending on which SSO solution (SiteMinder or Trusted Auth) you are using, the HTTP
request from the SSO solution to the Roambi server is handled differently:
- 127 -
Chapter 10: Single Sign-on (SSO)
With SiteMinder, the SMSESSION cookie from the request is passed to the BI
connector, which in turn passes it to the BI system. The next section describes how
the SSO solution interacts with a BI system.
With Trusted Auth, the value of the HTTP header X-Roambi-User-ID is used to
authenticate the user to the BI system.
With SiteMinder, the SMSESSION cookie from the request is passed to the BI connector,
which in turn passes it to the BI system. The next section describes how the SSO solution
interacts with a BI system.
Requests between the Roambi server and BI system
The behavior of the request processing between the Roambi server and your BI system
depends on which SSO solution and which BI system you are using:
If you are using SAP BOE with SiteMinder, SiteMinder passes the SMSESSION cookie to
the BOE login process.
If you are using SAP BOE with Trusted Auth, the HTTP header X-Roambi-User-ID
authenticates the user to the BI system.
If you are using Cognos with SiteMinder, SMSESSION is passed to the dispatcher to
retrieve the cam_passport, which uniquely identifies the session.
SSO architecture and HTTP request process
SSO solutions intercept HTTP traffic and add authentication and session management on top of
what has already been implemented on the web server. Roambi supports the use of a login form
to help facilitate SSO. Roambi supports the use of a SSO solution with the following BI portals:
SAP BOE (SiteMinder or Trusted Auth)
Cognos (SiteMinder)
Because the Roambi Visualizer application on mobile devices and the Roambi server
communicate using an HTTP-based protocol, an SSO for Roambi should be configured to sit
between the mobile device and the server:
HTTP requests between mobile device and SSO solution When the Roambi application on a user's mobile device sends an HTTP request to the Roambi
server where an SSO solution is configured for the system, the following events occur:
- 128 -
Configuring SSO for Roambi
The Roambi application on the mobile device sends a workflow request to the SSO solution.
The SSO solution then returns HTTP status code 302 (Found) to an HTML page.
The Roambi application on the mobile device displays the HTML page until the request
is redirected back to the original request.
The SSO solution allows the request to pass through and drops cookies to the device.
The device stores the cookies so that credentials are not stored on the device.
HTTP requests between the SSO solution and Roambi
server Depending on which SSO solution (SiteMinder or Trusted Auth) you are using, the HTTP
request from the SSO solution to the Roambi server is handled differently:
With SiteMinder, the SMSESSION cookie from the request is passed to the BI
connector, which in turn passes it to the BI system. The next section describes how
the SSO solution interacts with a BI system.
With Trusted Auth, the value of the HTTP header X-Roambi-User-ID is used to
authenticate the user to the BI system.
Requests between the Roambi server and BI system
The behavior of the request processing between the Roambi server and your BI system
depends on which SSO solution and which BI system you are using:
If you are using SAP BOE with SiteMinder, SiteMinder passes the SMSESSION cookie
to the BOE login process.
If you are using SAP BOE with Trusted Auth, the HTTP header X-Roambi-User-ID
authenticates the user to the BI system.
If you are using Cognos with SiteMinder, SMSESSION is passed to the dispatcher
to retrieve the cam_passport, which uniquely identifies the session.
Configuring SSO for Roambi
The following procedure describes how to configure SSO for Roambi:
Install the integration piece for your SSO solution to Apache or IIS.
Configure Apache or ISS as the reverse proxy to the Tomcat server that is hosting
Roambi. Make sure that the Tomcat server is running. See Roambi behind a firewall
and reverse proxy for reverse proxy instructions.
Check that Apache or IIS is running and is configured to forward traffic to Roambi.
Configure the SSO solution to present the appropriate login prompt to a client.
Verify that the BI system is working behind the SSO solution.
- 129 -
Chapter 10: Single Sign-on (SSO)
Check that SSO is working with Roambi: Connect to the SAP Roambi ES Administrator Console via the SSO
solution. The SSO solution will prompt you for your login credentials.
Log in to Roambi as the Administrator.
Configure your portal(s) as described in the Roambi ES5 Installation Guide.
Try logging in to Roambi again; you should not need to reenter your credentials if
SSO is working. The rest of this chapter gives specific instructions for various aspects of configuring different components
of a Roambi system that uses SSO. Only use the instructions that apply to your system.
Specifying an SSO solution for SAP Roambi
Use the Administrator's Console to specify which SSO solution you are using.
Note: The SAP Roambi ES Installation Guide contains detailed instructions on configuring
Tomcat to work with SSO and the supported BI portals. Follow these instructions
before configuring SSO in the Administrator's Console.
To specify your SSO type:
In the upper-right of the Administrator's Console, click the System
tab. The System tab options display on the left pane of the screen.
From the list of System tab options, click the Security tab to display security options for
the Roambi server:
- 130 -
Configuring Roambi for use with SiteMinder
From the Single Sign-On drop-down list, select your SSO solution:
SiteMinder is compatible with SAP BOE and Cognos BI EE portals.
Trusted Auth is compatible with SAP BOE portals only.
Custom SSO is compatible with cookie-based SSO solutions and
allows Administrators to specify cookie names.
Kerberos is compatible with SPNEGO-based Kerberos constrained delegation with
Single Sign-on for Java from Quest Software.
From the Single Sign-On drop-down list, select SiteMinder as your SSO solution.
Configuring SAP Roambi for use with SiteMinder When integrated with Roambi, the CA SiteMinder application provides authentication and Single
Sign-on (SSO) access to supported BI systems. In a Roambi configuration that includes
SiteMinder, the BI system trusts SiteMinder, which provides the authentication for the BI system. Roambi supports integration with SiteMinder with the following BI systems:
IBM Cognos
SAP BOE
- 131 -
Chapter 10: Single Sign-on (SSO)
Installing Web Agents for SiteMinder and SAP Roambi The SiteMinder application has two components: a policy server that sets rules and agents that enforce
the rules. If you are using SiteMinder with Roambi, you must use the Web Agent as an agent. A Web Agent with 4.x support enabled must protect both the BI layer (SAP BOE or Cognos) and
the Roambi layer of your configuration. (The Roambi layer receives the SMSESSION cookie
from the BI layer and is unable to do so without a Web Agent protecting both layers.) A Web Agent with 4.x support enabled must protect both the BI layer and the Roambi layer of
your configuration. (The Roambi layer receives the SMSESSION cookie from the BI layer and is
unable to do so without a Web Agent protecting both layers.) Install the Web Agent on either an Apache HTTPD or Microsoft IIS web server that is a reverse
proxy for Tomcat. The Web Agent generates the SMSESSION cookie that is passed from
Roambi to the BI system.
General SiteMinder configuration tips See the SiteMinder documentation and documentation for your BI system for general
instructions about installing and setting up SiteMinder. The following table lists the requirements for integrating SiteMinder with Roambi:
Component Requirement
SAP BOE and Cognos must be configured to have integration with
Directory service ActiveDirectory or LDAP. If you are using WinAD as a directory, you must set up Kerberos on Tomcat.
Web Agent
Authentication
schemes
When creating the Web Agent, enable Support 4.x agents so that you will
be able to enable the SharedSecret section in the Agent Properties box.
Supported authentication schemes for Roambi are BASIC, BASIC
over SSL, and Windows Authentication.
Registration schemes Not supported.
On the Domain Configuration screen for SiteMinder, set the following
Ream rules: Realm rules
AllowsEverything with Web Agent rules: Get, Post, Put Authentication events set to OnAuthAccept
Tips for integrating SiteMinder with Roambi and Cognos Make sure to set up the SiteMinder provider under the Automatic Logon node for regular
SiteMinder integration. The following table contains authentication and namespace recommendations for
integrating SiteMinder with Roambi and Cognos.
- 132 -
Configuring Roambi for use with
Site-Minder
Component Authentication level
Namespaces
Agent Configuration Object
Requirement Use light or regular authentication. LDAP, Windows AD, and SiteMinder namespaces are
supported. If using light authentication, two namespaces
are requred:
The SiteMinder TSP provider
A full authentication provider configured as LDAP
or AD to receive the request When modifying the SiteMinder Agent Configuration
Object, set the following values:
Set SetRemoteUser to yes.
Deactivate BadCssChars.
Deactivate DisableSessionVars.
LDAP namespace
Windows AD namespace
Use the following properties and settings (using Windows
as an example): User lookup = (sAMAccountName=${userID}) Use external identity? = true External identity mapping = (sAMAccountName=${environment("REMOTE_USER")}) Use the following properties and settings:
singleSignOnOption = IdentityMapping External identity mapping = (sAMAccountName=${replace(${environment (“SM_USER”)},”DOMAIN\\”,””)})
For more information on how to configure Cognos 8 components to use eTrust SiteMinder,
see the IBM web site: http://www.ibm.com/developerworks/data/library/cognos/page448.html
Integrating SiteMinder with Roambi and SAP BOE Although SAP BOE XI 3.0 is supported, SAP recommends using SAP BOE XI3.1 with
SiteMinder. Do not use SiteMinder with SAP BOE XIR2. To integrate SiteMinder with SAP BOE and Roambi:
Configure the web.xml file for InfoView for SiteMinder:
Navigate to the [TomcatDirectory]\webapps\InfoViewApp\WEB-INF
folder and open the web.xml file in a text editor. Locate the cms.default parameter, and add the CMS server name and
port number as its value. For example:
- 133 -
Chapter 10: Single Sign-on (SSO)
<param-name>cms.default</param-name>
<param-value>cmsserver.mycompany.com:6400</param-value>
Set the value of the authentication.default parameter to secWinAD
or secLDAP depending on the type configured for the CMC. For example:
<param-name>authentication.default</param-
name> <param-value>secWinAD</param-value>
Change the value of the sso.enabled parameter from false to true:
<param-name>sso.enabled</param-name>
<param-value>true</param-value>
Change the value of the siteminder.enabled parameter from false to true:
<param-name>siteminder.enabled</param-
name> <param-value>true</param-value>
Set the value of the siteminder.authentication paramter to secWinAD:
<param-name>siteminder.authentication</param-
name> <param-value>secWinAD</param-value>
Save the file and restart Tomcat.
Enable SiteMinder in the CMC:
Log in to the CMC and go to Authentication > Windows AD. Under Authentication Options, enable the option Enable Single Sign On
for selected authentication mode.
Scroll down to the SiteMinder options section, and click
Disabled. A SiteMinder configuration screen displays.
In the Policy Server box, type the names of the Policy Server(s), and click Add
after you add each server.
Specify the correct Accounting, Authentication, and Authorization ports for
each Policy Server that you added. Enter the name of the Web Agent, its Shared Secret, and confirm as
prompted. SiteMinder displays an Enabled message to confirm.
In the Roambi Administrator's Console, set the authentication type to secWinAD:
In the upper-right corner of the Administrator's Console, click the Portals tab to
display your list of portals in the left pane. On the left pane, select the SAP BOE portal that is using SiteMinder.
The Administrator's Console displays the General tab for the portal:
- 134 -
Configuring Roambi for Trusted Auth
Click the Configuration tab to display configuration details.
In the Authentication field, type secWinAD if this value was not already set
during the Roambi installation process. Follow the prompts to verify and save the change.
Configuring Roambi for Trusted Auth This section contains instructions on setting up Trusted Auth and Trusted Auth with SiteMinder for SAP BOE.
- 135 -
Chapter 10: Single Sign-on (SSO)
Configuring Roambi for Trusted Authentication with BOE Trusted Authentication security is an authentication proprietary to SAP BusinessObjects that
allows users to log in without using passwords when BusinessObjects uses Enterprise
authentication. Using Trusted Authentication with Roambi ES5 facilitates the creation of batch
views in Roambi because passwords are not exposed in the batch script. To set up BOE Trusted Authentication for Roambi:
Open the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-
INF/web.xml file in a text editor.
In the section containing the <filter> elements, locate the following comment:
<!--
uncomment the following block to enable SSO integration using HTTP
Header and Trusted Auth.
-->
As instructed in the XML code, uncomment the following block by removing the comment
tags (<!-- and -->). This block contains the following code:
<!--
<filter
>
<filter-name>HttpHeaderAuthFilter</filter-
name> <filter-
class>com.mellmo.roambi.servlet.filter.HttpHeaderAuthFilte
r </filter-class>
<init-param>
<description><![CDATA
[
specifies the name of the header to use to get the
user name.
]]></description> <param-
name>name</param-name> <param-
value>SM_USER</param-value>
</init-param> <init-
param>
<description><![CDATA
[
specifies where the filter is going to get the name of
the authenticated users.
Possible values are: header - the value is supplied by the HTTP Header. See
"name" param.
remoteUser - the value is supplied by the REMOTE_USER variable
by the app server.
]]></description> <param-
name>authType</param-name> <param-
value>header</param-value> </filter>
<filter-mapping>
- 136 -
Configuring Roambi for Trusted Auth
<filter-name>HttpHeaderAuthFilter</filter-name>
<url-pattern>/*</url-pattern> </filter-mapping> -->
4. Set the values for the two <param-value> elements:
If your BOE configuration is not using the BOE REMOTE_USER variable, set the param-value for the authType parameter to header. In the <param-
value> element for the name parameter, replace the string SM_USER with the
name of the header that is used to retrieve the the user name.
If your BOE configuration uses the BOE REMOTE_USER variable, set the
param-value for the authType parameter to remoteUser. The name
parameter will then be ignored by Roambi.
Save your changes and close the file.
Add the location of the TrustedPrincipal.conf file to your application server:
In Tomcat (or do the equivalent for your application server), go to the Windows
Start menu and go to Monitor Tomcat.
The Tomcat Properties window opens.
On the Tomcat Properties window, click the Java tab:
Scroll down to the bottom of the Java Options list, and add the following lines of text:
- 137 -
Chapter 10: Single Sign-on (SSO)
-Dbobj.trustedauth.home=PathToTrustedPrincipal.confFile
Replace the italicized text with the path to your TrustedPrincipal.conf file.
Copy this file from a configured BOE server and place it in a location that is user-
accessible and owned by Tomcat.
The TrustedPrincipal.conf file must contain the line:
SharedSecret=password
The password is configured in your internal BOE system. See your BOE
documentation for details.
Restart Tomcat.
When you create the SAP Business Objects portal, using the web-based administrator's
console, set the value for the Authentication parameter to secEnterprise.
Configuring Roambi for SiteMinder and
Trusted Authentication with BOE Roambi is compatible with a BOE configuration that uses SiteMinder for user authentication.
When using SiteMinder, BOE should also be configured to use Trusted Authentication and
secEnterprise authentication. For this configuration, the Apache web server and BOE should each be protected by a
SiteMinder web agent. If you tried to connect to an unprotected Tomcat server from a
SiteMinder-protected BOE server, authorization would fail. To set up SiteMinder with BOE for Roambi:
Open the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-
INF/web.xml file in a text editor.
In the section containing the <filter> elements, locate the following comment:
<!--
uncomment the following block to enable SSO integration using HTTP
Header and Trusted Auth.
-->
As instructed in the XML code, uncomment the block contained in the following the
comment tags. This block contains the following code:
<!--
<filter> <filter-name>HttpHeaderAuthFilter</filter-name> <filter- class>com.mellmo.roambi.servlet.filter.HttpHeaderAuthFilter </filter-class> <init-param>
<param-name>name</param-name> <param-value>SM_USER</param-value>
- 138 -
Configuring Roambi for Trusted Auth
</init-param>
</filter> <filter-mapping>
<filter-name>HttpHeaderAuthFilter</filter-name> <url-pattern>/*</url-pattern>
</filter-mapping> -->
Replace the string SM_USER with name of the cookie containing the user name for
your configuration.
Save your changes and close the file.
Add the location of the TrustedPrincipal.conf file to your application server:
In Tomcat (or do the equivalent for your application server), go to the Windows
Start menu and go to Monitor Tomcat.
The Tomcat Properties window opens.
On the Tomcat Properties window, click the Java tab:
Scroll down to the bottom of the Java Options list, and add the following lines of text:
-Dbobj.trustedauth.home=PathToTrustedPrincipal.confFile
Replace the italicized text with the path to your TrustedPrincipal.conf file.
- 139 -
Chapter 10: Single Sign-on (SSO)
Copy this file from a configured BO server and place it in a location that is
user-accessible and owned by Tomcat.
The TrustedPrincipal.conf file must contain the line:
SharedSecret=password
The password is configured in your internal BOE system. See your BOE
documentation for details.
Restart Tomcat.
When you create the SAP Business Objects portal, using the web-based
administrator's console, set the following values for the BOE parameters: On the Configuration tab, set the value for the Authentication parameter
to secEnterprise. On the Security tab, set the value for Single Sign-on Type to Trusted Auth
(not SiteMinder).
Configuring Roambi ES for Quest
Single Sign-on for Java Roambi ES supports SPNEGO-based Kerberos constrained delegation only when an
organization utilizes Single Sign-on for Java from Quest Software (Version 3.3). Single Sign-on
for Java is a third-party product that provides access management for Java applications utilizing
Microsoft Active Directory. Note: When configuring Roambi ES for Quest Single Sign-on for Java, your organization is
responsible for obtaining and maintaining compliance with the product license.
Installation Guidelines For complete installation instructions, see the Single Sign-on for Java documentation from
Quest Software and any relevant documentation for your BI system. In order to install Single Sign-on for Java on the application server:
Deploy the required JAR files for the SSO product by adding the files to the WEB-INF/lib
directory. You may optionally choose to deploy these files on the CLASSPATH.
vsj-standard.jar
vsj-license.jar
Deploy these third-party JAR files. These are supplied with Single Sign-on for Java:
commons-logging-1.1.jar. This implements the logging component.
jcifs-1.1.9.jar. This implements the CIFS/SMB networking protocol.
Edit the vsj.properties file with your configuration parameters. A sample template can
be found in the examples/ directory.
Deploy the vsj.properties file to the WEB-INF directory.
- 140 -
Configuring Roambi ES for Quest Single Sign-on for Java
Configuring Quest Single-Sign on for Java To configure Roambi ES to utilize Quest Single Sign-on for Java:
Open the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-
INF/web.xml file in a text editor.
In the section containing the filter elements, enable the authFilter:
<!--
<filter
>
<filter-name>authFilter</filter-name> <filter-
class>com.wedgetail.idm.sso.AuthFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>authFilter</filter-
name> <url-pattern>/*</url-pattern>
</filter-
mapping> -->
In the section containing the filter elements, enable the VSJFilter:
<!--
<filter
>
<filter-name>VSJFilter</filter-name> <filter-
class>com.mellmo.roambi.servlet.filter.VSJFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>VSJFilter</filter-
name> <url-pattern>/*</url-pattern>
</filter-
mapping> -->
Save your changes and close the file.
Restart the server.
When you add the portal that will use constrained delegation to Roambi ES, go to
the Security tab and set the value for Single Sign-on Type to Kerberos. Then,
enable SSO on the portal .
- 141 -
Chapter 11: Batch Processes
SAP Roambi batch processes help you create Roambi analytics reports more efficiently. You
can use batch processes to create new RBI files from a template but with a new data set. This
feature eliminates the need to have to build an entirely new report for each RBI file. You can set
up batch processes using the batch command line tool that is included with the Roambi server. This chapter discusses how to configure and run batch processes to create Roambi
analytics reports:
Determining the source data and folder IDs for batch processes
Running Roambi batch processes
Batch process command examples
Using a text file as the parameter source for a batch process
Using batch processes in SiteMinder-protected environments
Determining the source data and folder
IDs for batch processes
Before you can run a batch process, you will need to locate the source data and folder IDs
for the source portal.
To locate the source data and folder IDs for a portal:
In a web browser, type the following case-sensitive URL to view the Source Manager
for your domain:
http://roambi.[MyDomain].com/roambi/SourceManager
The browser displays an XML document showing the content of the site. The
following example shows the source information for an MS SharePoint portal:
<Sources>
<Source> <Name>SharePoint 2007</Name>
<Id>SharePoint_2007</Id>
<Description>Microsoft Reporting
Services</Description> <RequiredParameters>
<RequiredParameter> <Name>UserID</Name>
- 142 -
Chapter 11: Batch Processes
<Id>user_name</Id>
<ShowAsDescription>true</ShowAsDescription
> <PlaceHolder>username</PlaceHolder>
</RequiredParameter> <RequiredParameter> <Name>Password</Name> <Id>password</Id> <IsSecure>true</IsSecure> <ShowAsDescription>true</ShowAsDescription <PlaceHolder>password</PlaceHolder>
</RequiredParameter> </RequiredParameters> <HasDefaultPublishDir>YES</HasDefaultPublishDir> <IsAssociated>YES</IsAssociated> <AllowsDuplicateFileNames>YES</AllowsDuplicateFileNames>
</Source> </Sources>
Locate the portal ID. The portal ID is contained in the Id element that is a child of the
Source element. In the above example, the portal ID is SharePoint_2007.
In your web browser, log into the portal by typing a URL in the following format, where
PortalID is the ID that you just located and Username and Password are the credentials
used to access the portal:
http://[RoambiServerUrl]/roambi/SourceManager/[PortalID]?user_name=[Username]
&password=[password]
For example, the following URL logs onto the SharePoint_2007 portal at
roambi.mycompany.com as the Administrator with the password 1234:
http://roambi.mycompany.com/roambi/SourceManager/SharePoint_2007?user_
name=Administrator&password=1234
The page displays another XML document containing Folder IDs for the portal. The Folder ID
is contained in an Id element that is a child of the Content element for the folder.
If you will be creating batch processes that copy RBIs from one folder to another, record
these Folder IDs for use in your command. Log into a folder to view the Document IDs for the RBIs associated with that folder.
To log into a folder, copy and paste the Folder ID (preceded with a / character) to the
portal URL just after the Portal ID using the following format:
http://[RoambiServerUrl]/roambi/SourceManager/[PortalID]/[FolderID]?user_name=
[Username]&password=[password
For example:
http://roambi.mycompany.com/roambi/SourceManager/SharePoint_
2007/%252Fcontent%252Ffolder%255B%2540name%253D%2BReports%2527%255D?
user_name=Administrator&password=1234
- 143 -
Running Roambi batch
processes
Do not nest your Folder IDs, or the batch command will not succeed. For example, the
following URL has nested Folder IDs that will not work with batch processing:
http://Server.com/roambi/SourceMnaager/Portal_ID/FolderA_ID/FolderB_ID?user_
name=abc&password=def
The browser displays an XML document containing the IDs for the RBI files associated
with that folder. Record any IDs that you will be using for batch processes.
Continue to navigate through the folders until you have all of the Folder IDs and
document IDs that you will be using for batch processes. Once you have all of the IDs that you need, you can start running batch proceses. See
Running Roambi batch processes.
Running SAP Roambi batch processes
After you have obtained all of the Folder IDs and RBI document IDs that you will be using in
your batch processes (see Determining the source data and folder IDs for batch
processes), you can construct a command line statement to execute the batch process.
Executing the batch process command
Execute batch processes from the command line of the server machine where the
application server is installed. To execute the batch process utility, type the following command: C:\> java -jar roambi-batch.jar [option], ...
The batch command has five required parameters:
-server
-src_portal
-src_username
-src_password
-src _rbi
All other parameters are optional. The next section describes all available (required and
optional) batch parameters.
Batch process syntax The following arguments are valid batch process options:
- 143 -
Chapter 11: Batch Processes
Argument
-arg_file [FileName]
-connected
-del_params
-dst_folder [FolderPath]
-dst_password [Password]
-dst_portal [PortalID]
-dst_rbi [RBIName]
-dst_session [SessionID]
-dst_token [Token]
-dst_username [Username]
-dst_data [DataID]
-h
-logfile
-migrate
-overwrite
-server [URL]
-src_data [DataID]
-src_data_params
Description Specifies a text file containing the command
line arguments for a batch process. If present, specifies that the RBI file should
maintain a connection to the source report so that
Row Level security is maintained. If present, this option overrides any parameters in
the source report for the RBI with the parameters
provided by the batch process. Unique identifier specifying the destination folder
for the destination portal. Password for the destination portal. Sets a name for the destination portal. This name
should correspond to the Portal ID configured for
the Roambi server. Specifies the name for the destination RBI. You
must specify a value for this parameter when
creating a new RBI. Sets the destination session to authenticate into
the destination portal. Sets the destination token to authenticate into
the destination portal. Username to authenticate to the destination
portal. Not required unless the destination token
or destination session was not set. Defines which report to use from the destination
portal when creating or refreshing the RBI file.
Displays online "help" by listing all available
command options. Specifies a path to a log file to record batch
process events. Use this required parameter when migrating a
report definition from Cognos 8 to Cognos 10. If present, enables batch updated Roambi files to
be synchronized with devices when Auto Sync
Folders is enabled. URL for the Roambi server. Specifies the source data ID for the source RBI
file. This ID is unique to the portal where the
source data resides. XML-formatted source data parameters. For
- 144 -
Running Roambi batch
processes
example:
<parameters>
[XMLParameters] <parameter name="aaa" value="123"/>
<parameter name="bbb" value="jkl; xyz"/> </parameters>
-src_data_portal [PortalID]
-src_data_username [Username]
-src_data_password [Password]
-src_password [Password] -src_portal [PortalID]
-src_rbi [RBIID]
-src_session [SessionID]
-src_token [Token]
-src_username [Username]
-sso_username [Username]
-sso_password [Password]
-update_params
-v
For RBIs where the source report resides in a
portal other than the RBI, this parameter identifies
the portal where the source report resides. For RBIs where the source report resides in a portal
other than the RBI, this parameter is the username
for the portal where the source report resides. Password that corresponds to the -
src_data_ username parameter.
Password for authentication to the source portal. ID for the portal where the source RBI resides. ID for the source RBI file. This ID is unique to
the portal where the RBI resides. Sets the portal session for authentication into
the source portal. Sets the token to authenticate into the source portal. Username to authenticate to the source portal.
Not required unless the destination token or
destination session was not set. Single sign-on Username (for use with SiteMinder).
Do not use the other username or password-related
arguments if you are using Single Sign-on. Single sign-on password (for use with SiteMinder).
Do not use the other username or password-related
arguments if you are using Single Sign-on. Prompts the Roambi server to query the source
report for new parameter values. When using the
batch utility to create a template RBI, use -update_
params and -connected to ensure that the
resulting RBI files have updated parameter values. Displays the Roambi ES version.
- 145 -
Chapter 11: Batch Processes
Setting up a batch command when the source report resides
in a different portal than the RBI Some Roambi ES portals only store source reports and do not store RBIs. Source report-only
portals include MS Analysis Services and QlikView. In this case, you will need to use a second
portal to store your RBIs, in addition to the portal storing your source reports. When you use a
different portal to store your source data from your RBIs, you will need to use the following three
parameters in your batch command:
-src_data_portal [PortalID] : Identifies the portal storing the source report.
-src_data_username [Username]: Username to access the portal storing the source
report.
-src_data_password [Password]: Password that corresponds to -src_data_
username.
Defining a locale for the batch utility Some BI tools support and expose translated content by using a locale defined at the browser or user
level. When using the batch utility, you can define which locale the report should use for your data. You can define a user locale by passing parameters to the Java JRE engine. To define the user
locale, make sure that the user defined for the batch utility is set to use the default language. The
parameter values will be passed to the server, and the Roambi server will execute the report in the
specified language. For example, the following command sets the language to French: C:\> java -Duser.language=fr -Duser.country=FR -jar roambi-batch.jar -arg_file arguments_file If you use the batch utility to create an RBI and do not use the -connected parameter, the
resulting RBI will be translated to the language used by the batch command. In this case, the
language of the RBI will not change according to the language defined on the mobile device.
These types of RBI files are static and can only be refreshed via the batch utility.
Batch process command examples
The following sections contain example commands for common batch process scenarios.
Updating and replacing an RBI with new source data on the
same portal The most simple batch process uses an existing template RBI with updated data on the same
portal. As part of the command, you will need to send authentication information via the
command line to connect to the portal. To update and replace an RBI with new source data, type the following command: C:\> java -jar roambi-batch.jar -server [serverURL] -src_rbi [rbiID] -
src_ portal [EnterprisePortal1] -src_data [newSourceDataID] -src_username
[Username] -src_password [Password]
- 146 -
Batch process command
exam-ples
For example, the following command connects to a server at mycompany.com:8080 and
replaces the existing RBI RBI123 on the SAP portal with new data from the Data123 data
source. The batch process connects as the user Administrator with the password 1234: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal SAPPortal -src_data Data123 -src_username Administrator
- src_password 1234 For example, the following command connects to a server at mycompany.com:8080 and
replaces the existing RBI RBI123 on the portal with new data from the Data123 data source.
The batch process connects as the user Administrator with the password 1234: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal SASPortal -src_data Data123 -src_username Administrator
- src_password 1234
Copying an RBI to a new portal folder on the same portal To copy an existing RBI to a new folder on the same portal, use the same options as the
previous example, but instead of specifying new source data, specify a new destination folder:
C:\> java -jar roambi-batch.jar -server [serverURL] -src_rbi [rbiID] -src_ portal [EnterprisePortal1] -dst_folder [FolderID] -src_username [Username] - src_password [Password] For example, this command connects to the same portal, but copies the RBI to the
Folder123 folder: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -
src_rbi RBI123 -src_portal SAPPortal -dst_folder Folder123 -src_username
Administrator -src_password 1234 C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -
src_rbi RBI123 -src_portal Portal -dst_folder Folder123 -src_username
Administrator -src_password 1234
Creating a new RBI on a different portal
To create a new RBI on a different portal than the source portal, type the following command: C:\> java -jar roambi-batch.jar -server [serverURL] -src_rbi [rbiID1] -
src_ portal [EnterprisePortal1] -src_data [newSourceDataID] -src_username
[Username1] -src_password [Password1] -dst_portal [EnterprisePortal2 -dst_
folder [FolderID] -dst_rbi [rbiID2] -dst_username [Username2] -
dst_password [Password2 For example, this command uses an RBI created on SAPPortal1 and copies it to SAPPortal2
using the Data123 data source: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal SAPPortal1 -src_data Data123 -src_username Administrator
- src_password 1234 -dst_portal SAPPortal2 -dst_folder Folder123 -dst_rbi
NewRBI123 -dst_username Administrator -dst_password 4321
- 147 -
Chapter 11: Batch Processes
For example, this command uses an RBI created on Portal1 and copies it to Portal2 using the
Data123 data source: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal Portal1 -src_data Data123 -src_username Administrator -
src_password 1234 -dst_portal SASPortal2 -dst_folder Folder123 -dst_rbi
NewRBI123 -dst_username Administrator -dst_password 4321
Creating a new RBI on the same portal with a new name and
source parameters To create a new RBI on the same portal as the the source portal, but with a new name and new
data source parameters, type the following command: C:\> java -jar roambi-batch.jar -server [serverURL] -src_rbi [rbiID1] -
src_ portal [EnterprisePortal1] -src_data [newSourceDataID] -src_username
[Username1] -src_password [Password1] -dst_rbi [rbiID2] -src_data_params
[ParameterXML] For example: C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal SAPPortal1 -src_data Data123 -src_username Administrator
- src_password 1234 -dst_rbi NewRBI123 -src_data_params
"<parameters><parameter name=\"Quarter\" value=\"Q3\"/></parameters>" C:\> java -jar roambi-batch.jar -server http://mycompany.com:8080 -src_rbi
RBI123 -src_portal Portal1 -src_data Data123 -src_username Administrator -
src_password 1234 -dst_rbi NewRBI123 -src_data_params
"<parameters><parameter name=\"Quarter\" value=\"Q3\"/></parameters>"
Using the batch utility to create a template RBI when the
source report has parameters If you use the batch utility to create a template RBI that contains parameters, you will need to make
sure that the parameters have updated values when creating children RBI files from the template. To set up the batch utility to update parameter values, run an initial batch command using the -
update_params and -connected parameters. Together, these parameters instruct the
Roamib server to query the source report for new parameter values: C:\> java -jar roambi-batch.jar -update_params -connected [...other parameters] To save performance, when you run subsequent batch commands for the template RBI,
do not include the -update_params parameter.
- 148 -
Using a text file as the parameter source for a
batch process
Using a text file as the parameter source
for a batch process If you will be repeatedly running a batch process command with the same arguments, you can
store those arguments in a text file rather than typing them each time that you execute the
command. This option is particularly useful for storing source portal or other parameters that
rarely change.
Text file format for batch processes
The text file that you use to store batch process arguments should have the
following characteristics:
Each parameter/value pair should be on a new line separated by a carriage return.
Unicode characters are not supported.
Parameters in XML format do not need to be escaped
The following example text file contains arguments for the following parameters:
Roambi server
Source RBI file
Source data
Source Username
Source password
Destination RBI file
Source data parameters -server http://mycompany:8080
-src_rbi rbi123
-src_data Data123 -
src_username Administrator
-src_password 1234 -
dst_rbi RBI123
-src_data_params <parameters><parameter name="Quarter"
value="Q-3"/></parameters>
Running a batch process with arguments stored in a text file To run a batch process where the arguments are stored in a text file, specify the -arg_file
parameter followed by the name of the text file when you run the batch command: C:\> java -jar -roambi-batch.jar -arg_file [FileName]
- 149 -
Chapter 11: Batch Processes
For example, the following command will run a batch process with the arguments stored in a
text file called arguments.txt: C:\> java -jar roambi-batch.jar -arg_file arguments.txt
Using batch processes in
SiteMinder-protected environments If you will be using batch processes with portals that are protected by the Single Sign-on feature
by SiteMinder, you will need to use different parameters to indicate the username and password
for that portal:
-sso_username
-sso_password
These parameters replace the -src_username, -src_password, -dst_username, and -
dst_password parameters for any SiteMinder-protected portals.
For example, the following command updates the source data for an existing RBI on the
source portal: C:\> java -jar roambi-batch.jar -server http://mySiteminderProtectedserver:8080 -src_rbi rbiID -src_portal EnterprisePortal1 -src_data Data123 -sso_username Administrator -sso_password SSO1234
- 150 -
Chapter 12: Application Service
API
The SAP Roambi server provides an Application Service API, which allows third party
applications to launch a specific Roambi report via an exposed URL. The Application Service
API allows you to launch Roambi visualizations from your own third party applications. Although Roambi and the third party application interact as separate applications on the iOS
framework, mobile device users experience a seamless transition between the third party
application and the Roambi report. Additionally, the Application Service API allows for a
callback to the third party application when the application exits the Roambi report, which
returns the user to the application. This chapter discusses the steps to use the Application Service API to launch Roambi reports
from your third party applications:
Obtaining the report URL
Editing the report URL
Launching the report
Returning to the third-party application
Obtaining the report URL Before you can use the Application Service API, you will need to obtain the report URL for
the Roambi report that you want to launch from your 3rd party application. You can obtain
the report URL from two possible sources:
Obtaining the report URL from Roambi Publisher
Obtaining the report URL from a Roambicast email
If you obtain the report URL from a Roambicast email, you might need to edit the URL before
you can use it with the Application Service API. See Editing the report URL.
Obtaining the report URL from Roambi Publisher
To obtain the URL for a Roambi report via Roambi Publisher:
- 151 -
Chapter 12: Application Service API
Click through the Views in the carousel on the Roambi Publisher home page until
Open Existing Roambi is in front.
Once Open Existing Roambi is in front, click the phone preview to select it.
Publisher displays a preview for the Open an Existing Roambi option:
Click Select This View to select the option.
- 152 -
Obtaining the report URL
Publisher displays the Import Your Data screen, which you can use to browse to
your existing Roambi reports:
- 153 -
Chapter 12: Application Service API
Under Locations, select the portal/fileserver where you stored the report, then when the
file system opens on the right, browse to the report that you want to open:
- 154 -
Obtaining the report URL
When you select an RBI file, four buttons giving additional options in the lower-left
corner become enabled:
- 155 -
Chapter 12: Application Service API
- 156 -
Obtaining the report URL
- 157 -
Chapter 12: Application Service API
The Get URL button is the second button from the right:
5. Click the Get URL button to open a URL window:
- 158 -
Obtaining the report URL
The Application Service API URL for your Roambi report is located in the Launchpad
URL field.
Copy and paste the URL from the Launchpad URL field to a text file where you can
save the URL.
Click Close to close the window.
Obtaining the report URL from a Roambicast email To obtain the Roambi report URL from a Roambicast email:
Open the Roambicast email containing the URL for the report:
Right-click the Tap Here to Download link, and select Copy Link Location from the
context menu:
Paste the URL into a text editor. The URL should look similar to the following example:
http://roambi.myserver.com/rbi?sourceId=7e1f34ba-c635-46fe-ace6-
4732142d34b7&contentId=_s_p252Fusers_p252Fweblogic_p252FMichelle_
p252Fadventureworkscardex.rbi_e
- 159 -
Chapter 12: Application Service API
Follow the instructions in Editing the report URL to modify the report URL for the
Application Service API.
Editing the report URL
If you obtained your Roambi report URL by manually copying a link, such as by copying the
link in a Roambicast email (see Obtaining the report URL), you will need to edit the report URL
before you can use the URL with the Application Service API. To edit the Roambi report URl for use with the Application Service API:
Consider the following example URL:
http://roambi.myserver.com/rbi?sourceId=7e1f34ba-c635-46fe-ace6-
4732142d34b7&contentId=_s_p252Fusers_p252Fweblogic_p252FMichelle_
p252Fadventureworkscardex.rbi_e
Change the URL scheme in the URL prefix: If the URL starts with "https://", change the "https://" to "roambi://".
If the URL starts with "http://", change the "http://" to "roambi-
http://" For example, the sample URl should be changed to:
roambi-http://roambi.myserver.com/rbi?sourceId=7e1f34ba-c635-46fe-ace6-
4732142d34b7&contentId=_s_p252Fusers_p252Fweblogic_p252FMichelle_
p252Fadventureworkscardex.rbi_e
After you have edited the report URl, you can use the URL with the Application Service API.
Launching the report After you have obtained the URL for the Roambi report and edited the URL (if necessary), you
can use the report URL with the Application Service API to launch that Roambi report. To launch the Roambi report from your 3rd party application, use the UIApplication
openURL instance, as shown in the following example: [[UIApplication sharedApplication] openURL:[NSURL URLWithString:@”roambi- http://roambi.myserver.com/rbi?sourceId=7e1f34ba-c635-46fe-ace6- 4732142d34b7&contentId=_s_p252Fusers_p252Fweblogic_p252FMichelle_ p252Fadventureworkscardex.rbi_e”]];
Returning to the third-party application You can use the Application Service API to return end users to your 3rd party application when they
exit the Roambi report. Use a callback parameter to automatically return to your 3rd party application. To use a callback parameter to automatically return end users to your 3rd party application:
Encode the URL to your application. This encoded URL will become your callback parameter.
Append the callback URL to your UIApplication openURL as shown in the following
- 160 -
Linking to a specific
Cardex card
example:
[[UIApplication sharedApplication] openURL:[NSURL
URLWithString:@”roambi-http://roambi.myserver.com/rbi?sourceId=7e1f34ba- c635-46fe-ace6-4732142d34b7&contentId=_s_p252Fusers_p252Fweblogic_ p252FMichelle_p252Fadventureworkscardex.rbi_ e?callback=mycallbackURL%3A%2F%2F”]];
Linking to a specific Cardex card
Using the Application Service API, you can direct users to a specific card in a Cardex View.
You can direct users to a specific card by appending a Roambicast URL. To direct users to a specific Cardex card:
Obtain the Launchpad URL for the Cardex View RBI. See Obtaining the report URL
from Roambi Publisher.
Append the URL with the following code, replacing the variables with the values for
your Cardex card:
?defaults={"selections": [{"[CardTitleCategory]":
"[CardTitle]", "[TabTitleCategory]": "[TabTitle]"}]}
Note that the parameters values are case-sensitive. For example, the following URL
links to the Boynton Beach Outlets card in the Central region:
roambi-http://roambi.mycompany.com/roambi/SourceManager/0e339e4c-5b39-
4279-88d6-2907f3dcc1ad/_s_p252Fshared_p252FQA_p252RBI_p2527s_
p252Fcardex.rbi_e?defaults={"selections": [{"Store Name": "Boynton
Beach Outlets", "Region": "Central"}]}
Encode the URL so that JavaScript can be passed through the URL. You can use an
online tool such as the following web site to encode the URL:
http://meyerweb.com/eric/tools/dencoder/
The final, encoded URL should look similar to the following example:
roambi-http://roambi.mycompany.com/roambi/SourceManager/0e339e4c-
5b39-4279-88d6-2907f3dcc1ad/_s_p252Fshared_p252FQA_p252RBI_p2527s_
p252Fcardex.rbi_
e?defaults=%7B%22selections%22%3A%20%5B%7B%22Store%20Name%22%3A%20%22
Tallahassee%20Square%22%2C%20%22Region%22%3A%20%22East%22%7D%5D%7D
- 161 -
Chapter 13: Troubleshooting
This chapter summarizes common SAP Roambi server issues and their possible solutions:
Isolating issues
Using log files to troubleshoot issues with Roambi
Roambi Flow Issues
Timeout errors
MS Excel import errors and OpenOffice errors
Roambicast issues
File upload issues
Client device errors
Network configuration issues
Roambi Publisher issues
Batch Process Issues
General portal issues
SAP Business Objects Enterprise (SAP BOE) issues
Cognos Issues
SSRS Issues
Microsoft Analysis Services Issues
Liferay Issues
SSL Issues
Reverse proxy issues
Kerberos Issues
Isolating issues
To help isolate an issue, determine if the issue happens on different report types. For example, if
a Crystal Reports-based report fails, does a Web Intelligence-based report also fail?
To help isolate an issue, determine if the issue happens on different report types. For
example, if a report for a CataList fails, does a report for a Squares View also fail?
Next, try to determine if the issue happens on different data sources. For example, if a report
connecting to MS SQL Server fails, does a report connecting to an Excel spreadsheet also fail?
- 162 -
Chapter 13: Troubleshooting
While you are trying to isolate the issue, make sure to check the log files for errors and
other messages. See Using log files to troubleshoot issues with Roambi.
Using log files to troubleshoot issues
with Roambi When you encounter Roambi issues, use or inspect log files to help you identify errors.This
section describes how to enable and access Roambi log files for troubleshooting. For example, the following sample entry was added to the log file when a user tried to log into a
portal with an invalid username or password: 2010-04-01 13:03:11 [1755750938@qtp-367355325-4] ERROR
com.mellmo.roambi.SourceManagerServlet - getChildren failed com.mellmo.roambi.portal.exceptions.InvalidCredentialException: Enterprise
authentication could not log you on. Please make sure your logon
information is correct. (FWB 00008 In another example, the following sample entry was added because the SAP BOE SDK was
not available in the Roambi ES classpath: 2010-04-01 13:03:11 [1755750938@qtp-367355325-4] ERROR
com.mellmo.roambi.SourceManagerServlet - getChildren failed java.lang.NoClassDefFoundError: com/crystaldecisions/sdk/exception/SDKException
Enabling logging for Roambi on the server The first step to help troubleshoot most issues with Roambi is to enable additional logging.
Log file entries can help you determine the cause of the issue. The logging utility for Roambi
leverages the log4j package from Apache. To enable additional logging:
Navigate to the following directory:
/[AppServerDirectory]/webapps/[RoambiDirectory]/WEB-INF/classes
Open the log4j.properties file in a text editor.
Verify that the file contains the following line. If the line is not present, copy and paste the
line into the file:
log4j.rootLogger=INFO, stdoutAppender
To enable more verbose output for the Roambi ES logs, you can set log4j.rootLogger
to DEBUG or TRACE, instead of the default value of INFO. Note, however, that these more
verbose settings use more disk I/O and therefore can negatively impact performance. By default, log4j is configured to log to the STDOUT of the Java application server. This location
can vary by operating system and servlet container. For example, if you are using Apache Tomcat,
- 163 -
Using log files to troubleshoot issues with Roambi
Tomcat usually logs STDOUT to either the catalina.out or std.out file. These files
are located in the Tomcat/logs directory.
Accessing log files on client devices
To access iPhone or iPad log files for the Roambi Visualizer application:
Download the Apple iPhone Configuration Utility to a computer:
http://support.apple.com/kb/DL926
Follow the prompts to install the utility to the computer.
Connect the mobile device to the computer.
View the log files for the device: a. Start the configuration utility:
In the left pane, under devices, select the device.
The utility displays the Summary tab containing device details.
Click the Console tab to display the logs and traces for the device.
- 164 -
Chapter 13: Troubleshooting
To filter the results to only show Roambi logs and traces, type "Roambi" into the
search field.
Recovering crash logs for mobile devices
If the Roambi Visualizer application crashes on a mobile device, a crash log file is created
on the device. When the device is synced with iTunes on a computer, this crash log is
copied to that computer. Depending on your OS, the crash log will be copied to the following folder:
OS
Mac OS X
Windows XP
Windows Vista
Crash log folder ~/Library/Logs/CrashReporter/MobileDevice/
[DeviceName] C:\Documents and Settings\Application Data\Apple
computer\Logs\CrashReporter\[DeviceName] C:\Users\AppData\Roaming\Apple computer\Logs\CrashReporter\MobileDevice\
[DeviceName]
SAP Roambi Flow Issues
This section lists common issues and possible solutions for Roambi Flow.
Roambi Flow publishing and PDF issues
If you encounter issues publishing documents from Roambi Flow or working with PDF
documents in Roambi Flow, perform the following configuration checks:
- 165 -
Roambi Flow Issues
Was the wkhtmltoimage utility correctly installed to the .roambi folder? (See the
ES5 Installation Guide for instructions.)
Were all three of the jai_*.jar files copied from [ApplicationServerDirectory]
\webapps\[RoambiInstallation]\WEB-INF\lib to
[ApplicationServerDirectory]\lib? Verify that you see the following files in
[ApplicationServerDirectory]\lib: jai_codec-1.1.3.jar jai_core-1.1.3.jar
jai_imageio-1.1.jar
In the my.ini file (Windows) or my.conf file (Linux), make sure that the max_allowed_ packet
parameter is set to 30M under both the [mysql] and [mysqld] groups. (See the
ES5 Installation Guide for details.)
SSL issues with Roambi Flow on Linux
On Linux, make sure that the OpenSSL libraries were installed. Use the following
command to install OpenSSL:
$ sudo apt-get install openssl
SSL issues with Roambi Flow on Windows If your Roambi server or proxy server (if your configuration uses a proxy) uses SSL, you will need
to configure Tomcat so that the wkhtmltoimage utility can communicate with Roambi ES. To enable Tomcat so that wkhtmltoimage can communicate with Roambi ES:
In the directory where Tomcat is installed, navigate to the /conf directory and open
the server.xml file in a text editor.
Add a new <Connector> element to the server.xml file. This new connector should be
HTTP-only. Configure your Windows firewall to block the new connector port from
outside communication.
Edit the .roambi\config.json file to add the following attribute-value pair:
"poc_host":"http://[RoambiServerAddress]:[RoambiUnsecuredPort]/
[RoambiContextPath]"
Screen capture issues for Roambi Flow If Roambi Flow users are having trouble creating screen captures, and your Roambi ES
configuration includes SSL, SSO, and/or a reverse proxy, you might need to set up a Bypass
URL so that the Roambi server can access itself. To set up a Bypass URL:
Edit the .roambi\config.json file to add the following attribute-value pair:
"poc_host":"${BYPASS_URL}"
- 166 -
Chapter 13: Troubleshooting
Set the BYPASS_URL to an internal URL that the Roambi server can use to access itself.
Timeout errors
This section describes causes and solutions for common timeout errors.
Download timeouts
When a user's mobile device tries to download an RBI file from the Roambi server, the server
will try to refresh the RBI before returning to the device. If the refresh process takes too long
(over one minute, the server will instruct the device to call back later to a different URL.The
device and the server repeat this process until either the device finishes downloading the file or
the server fails. The callback process works well when the server can identify which URL the
device called from. If you did not configure the reverse proxy correctly, the Roambi server will
have a different URL than what the client requested, which can cause a download timeout. See
Reverse proxy issues to determine if the reverse proxy was configured correctly. If the reverse proxy is not the issue, check the iPhone device log that is available from the
iPhone configuration utility (see Using log files to troubleshoot issues with Roambi) to
determine which URL the device is trying to use for the callback. Look for an entry that is similar to the following example to determine what callback URL the
device is attempting to use: Dec 13 17:55:48 unknown Roambi[38613] <Warning>: -[MMDownloadManager
mellmoDownload:didFailWithError:] 1097 Error: Error
Domain=NSURLErrorDomain Code=-1001 "Connection Failed" UserInfo=0x5c7b20
{NSErrorFailingURLStringKey=
http://roambi.example.com:80/roambi/SourceManager/boeqa/_
sAc7CoJQaTDBFnn7W2GpaQL0_e?JSESSIONID=null, NSErrorFailingURLKey=http://roambi.example.com:80/roambi/SourceManager/boeqa/_
sAc7CoJQaTDBFnn7W2GpaQL0_e?JSESSIONID=null, NSLocalizedDescription=Connection
Failed, NSLocalizedFailureReason=The connection to the server timed out.,
NSUnderlyingError=0x54eeb0 "The request timed out."} Additionally, make sure that the port and hostname entries match the actual port and
host-name.
Tomcat session timeouts The Tomcat session timeout parameter specifies the number of minutes to keep a session
active if Tomcat does not receive any request from the client. If you are frequently
experiencing Tomcat timeout errors, increase the value of this parameter. To increase the time limit for Tomcat session timeouts:
Navigate to the /[TomcatDirectory]/conf directory.
Open the web.xml file in a text editor.
Locate the following code:
- 167 -
MS Excel import errors and
OpenOffice errors
<session-config>
<session-timeout>30</session-timeout> </session-config>
Increase the value of the session-timeout element. (Default is 30 minutes.)
MS Excel import errors and
OpenOffice errors This section lists common issues and possible solutions for importing MS Excel files into Roambi.
File import failed for MS Excel file If Roambi displays an error that an MS Excel file import failed, perform the following checks:
Check the log files for errors. (See Enabling logging.)
Check that OpenOffice is configured correctly. (See the SAP Roambi ES Installation Guide.)
Verify that the openoffice.properties file contains the correct settings and path for
your configuration. This file is located in [ApplicationServer]\webapps\
[RoambiDirectory]\WEB-
INF\classes\com\mellmo\roambi\data\plugins\ooexcel.
MS Excel file import fails after a long wait
Roambi occasionally fails at importing very large spreadsheet files. If you suspect that file size might be causing problems with the import, test your theory by
trying to import a sample spreadsheet, such as catalyst.xml, or superlist.xml.
Roambi should be able to import these files without any problem. If the cause of the issue is not file size, try manually starting the soffice.exe program for
OpenOffice. Respond to the introductory prompts so that soffice.exe does not display
on startup. When soffice.exe displays on startup, it can cause the Roambi file import to
hang in the background and does not register errors in the log files.
OpenOffice index out of range error on import of Excel If you see this error, make sure that each instance of OpenOffice that is configured in the
openoffice.properties file has a corresponding connStringInstanceentry. You should be able to find the openoffice.properties in the following location: [ApplicationServer]/webapps/[RoambiInstallation] /WEBINF/classes/com/mellmo/roambi/data/plugins/ooexcel/
- 168 -
Chapter 13: Troubleshooting
Missing entry for connStringInstance 1 in roambi-
settings.properties This error indicates an issue with the configuration of OpenOffice instances. See OpenOffice
index out of range error on import of Excel for the solution to this error.
java.lang.NoClassDefFoundError: com/sun/star/frame/XModel
If you see this error, check the application server error log for the following entry: ERROR com.mellmo.roambi.DataPluginManagerServlet - [SessionId=C4CE7CA908BD9C1A787E7857924909FE]- Caught throwable java.lang.NoClassDefFoundError: com/sun/star/frame/XModel This error occurs when required .jar files are missing or have been corrupted. On Linux, copy the following .jar files from the OpenOffice installation directory to the Tomcat /webapps/[RoambiInstallation]/WEB-INF/lib directory:
/[InstallationDirectory]/openoffice.org3/basis-link/ure-
link/share/java/juh.jar
/[InstallationDirectory]/openoffice.org3/basis-link/ure-
link/share/java/jurt.jar
/[InstallationDirectory]/openoffice.org3/basis-link/ure-
link/share/java/ridl.jar
/[InstallationDirectory]/openoffice.org3/basis-
link/program/classes/java/unoil.jar
On Windows, copy the following .jar files from the OpenOffice installation directory to the Tomcat \webapps\[RoambiInstallation]\WEB-INF\lib directory:
\[InstallationDirectory]\OpenOffice.org 3\ure\share\java\juh.jar
\[InstallationDirectory]\OpenOffice.org 3\ure\share\java\jurt.jar
\[InstallationDirectory]\OpenOffice.org 3\ure\share\java\ridl.jar
\[InstallationDirectory]\OpenOffice.org
3\Basis\program\classes\unoil.jar
Missing or corrupt files
Missing or corrupt files produce the following error message: [C:\Windows\system32\config\systemprofile\AppData\ Roaming\OpenOffice.org\ 3\user\uno_packages\cache\registry\ com.sun.star.comp.deployment.configuration. PackageregistryBackend\registered_packages.db] Berkeley Db error (0): Db::open: Invalid argument. This error indicates missing or corrupt OpenOffice .jar files. See
java.lang.NoClassDefFoundError: com/sun/star/frame/XModel for the solution to this error.
- 169 -
Roambicast issues
Application has failed to start The application has failed to start with the following error message: The application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem. If you see this error, shared .dlls, such as VC90 or CommonControls, were not installed
into the C:\WINDOWS\WinSXS folder. Reinstall OpenOffice to fix this issue.
Roambicast issues
This section lists common issues and possible solutions for Roambicast.
Roambicast does not successfully send emails If you are unable to use Roambicast to send emails, perform the following checks:
Check that your SMTP settings are configured correctly. See Configuring Roambicast.
If your SMTP settings are correct, check for a library conflict:
A library conflict can occur for Roambicast if your application server already has the
mail-1.4.1.jar and activation-1.1.jar files in its class path because these
files are also deployed with Roambi ES. If these files are already in your application
class path, remove them from the following Roambi directory:
[ApplicationServer]\webapps\[RoambiDirectory]\WEB-INF\lib
File upload issues
This section lists common issues and possible solutions for uploading files to Roambi ES.
MS Excel files do not upload See MS Excel import errors.
File size is too large If you are trying to import files into Roambi that are larger than 6MB, you are exceeding the default
limit for file uploads. You can increase this limit to avoid file upload errors related to file size. To increase the file upload limit:
Navigate to the following directory:
[ApplicationServer]\webapps\[RoambiDirectory]\WEB-INF
Open the profile.json file in a text editor.
- 170 -
Chapter 13: Troubleshooting
Locate the following block of code (file_size is shown in bold):
"features":{
"settings":{"storage":250,"file_size":6},
"views":["CATALOG","CATALOG_CARDEX","CATALOG_PIE","SIMPLE_LIST"
, "ITREND","CATALOG_CONTAINER"],
"functions":["collaboration","google_input","https","refresh"
, "upload","flash_download","flash_url","rpt_import"],
"sources":["google","roambi","boe"] },
Increase the value of the file_size parameter from 6 (MB) to a greater limit.
Client device errors
This section lists common issues and possible solutions for errors encountered on users'
mobile devices.
Users cannot download or refresh Roambi analytics
reports on their mobile devices If users are unable to download or refresh Roambi analytics reports on their client devices, check
Apache Tomcat to make sure that they are not encountering a Tomcat watched resources problem. Tomcat monitors specific static resources. By default, these watched resources are each context
found in the [ApplicationServer]\webapps\[RoambiDirectory]\WEB-INF\web.xml file.
Tomcat automatically reloads the context if the web.xml file changes. This behavior can both
negatively impact performance and potentially lead to fatal errors for Roambi ES libraries. To disable the watched resources behavior:
Navigate to the [ApplicationServer]\conf\ directory, and open the context.xml
file in a text editor. Locate and comment out the WatchedResources element as shown:
<!--<WatchedResource>WEB-INF/web.xml</WatchedResource> -->
Restart the application server.
Error: "Download failed" If a user's mobile device displays a "Download failed" error, perform the following checks to
identify the cause and correct this issue:
Make sure that the user has access to the source report and/or supporting files on the BI portal.
Verify that the user has permission on the database to refresh the data source.
Check that all of the necessary services of the BI system are running. For example, if the
portal is an SAP BOE portal, the WI ReportServer process must be running.
Check that all of the necessary services of the BI system are running.
- 171 -
Network
configuration issues
If your server configuration uses a load balancer or reverse proxy, see if you can download the
report directly from Tomcat. If you can download a report directly from Tomcat, the cause of
the problem is likely a configuration issue with the load balancer or reverse proxy.
Enable DEBUG mode for Roambi logging (see Using log files to troubleshoot issues with
Roambi). Check the logs for information as to why the download failed. If the Roambi
logs do not have this information, check the logs for your BI system.
Network configuration issues
HTTP 404 error after deployment of Roambi war file to
Tomcat Check the Tomcat logs for the following error message: Caused by: java.lang.LinkageError: JAXB 2.0 API is being loaded from the
bootstrap classloader, but this RI (from
jar:file:/C:/Program%20Files/Apache%20Software%20Foundation/Tomcat%206.0/
webapps/ROOT/WEB-INF/lib/jaxb-impl-
2.1.11.jar!/com/sun/xml/bind/v2/model/impl/ModelBuilder.class) needs 2.1 API. Use
the endorsed directory mechanism to place jaxb-api.jar in the bootstrap
classloader. (See http://java.sun.com/j2se/1.5.0/docs/guide/standards/) This error occurs when you use a JDK version that is older than 1.6.0_04. (SAP recommends
using JDK 1.6.0_04 or later, if possible.) If you must use a JDK version that is earlier than 1.6.0_04, use the following workaround:
Navigate to the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-
INF/lib folder.
Copy the following two files: jaxb-api-2.2.1.jar
jaxb-api-2.2.1.jar
Navigate to the [TomcatDirectory]/Tomcat6.0 folder and check if the /endorsed
folder exists as a subfolder. If not, create a subfolder named /endorsed. (Although
Roambi does not support Tomcat 5.5, if you are using Tomcat 5.5, this folder would be
located at [TomcatDirectory]/Tomcat5.5/common/endorsed.) Paste the two JAR files that you just copied to the /endorsed folder.
Restart Tomcat.
Troubleshooting the network configuration Roambi provides a utility to help troubleshoot possible network configuration issues. This
utility checks which URL the client is sending and which URL the Roambi server thinks that
the client is requesting. The utility also tests what would happen if the URL is returned in the
Location header for various status codes. To run the network configuration check, type the following URL in your web browser:
- 172 -
Chapter 13: Troubleshooting
http://[RoambiServerURL]/check_network.jsp
For example:
http://mycompany.com/roambi/check_network.jsp When the network is configured correctly, this URL displays a page similar to the following
example page:
If the URL or any of the ports are not configured correctly, the check_network URL
displays a page similar to the following example:
- 173 -
Roambi
Publisher issues
Roambi Publisher issues
This section lists common issues and possible solutions for errors encountered in
Roambi Publisher.
- 174 -
Chapter 13: Troubleshooting
Publisher displaying "sqlite library not found" messages If Roambi Publisher is displaying "sqlite library not found" messages, check Apache Tomcat to
make sure that they are not encountering a Tomcat watched resources problem. See Users
cannot download or refresh Roambi analytics reports on their mobile devices for instructions to
correct this issue.
Post Too Large
This error can occur when maxPostSize attribute is not properly set for the Apache
Tomcat connector. To set maxPostSize for the Tomcat connector:
Navigate to the server.xml file:
[TomcatDirectory][version]\conf\server.xml
Open the server.xml file in a text editor.
Locate the <Connector> element, which should look the same or similar to the
following example:
<Connector URIEncoding="UTF-8" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
enableLookups="false" maxHttpHeaderSize="8192" maxPostSize="8388608"
maxSpareThreads="75" maxThreads="150" minSpareThreads="25"
port="8080" redirectPort="8443"/>
If the maxPostSize attribute is missing, add this attribute with either the value
maxPostSize="-1" or maxPostSize equals the product of 1024 x 1024 x an
integer (for example, 8MB = 8388608). If Tomcat is redirecting to an Apache or or IIS web server, also add the
maxPostSize attribute to the connector for the AJP Port 8009.
HTTP Request Error
An HTTP Request error occurs when the maxPostSize is not properly set. See Post Too Large
for a solution to this issue.
Batch Process Issues
This section lists common issues and possible solutions for Roambi batch processes.
- 175 -
General portal issues
[main] INFO com.mellmo.roambi.UpdateRoambi -
reponse body:<errors><error>Failed to update parameter
values. Parameters table does not contain parameter: My
Prompt:</error></errors> This error indicates that the name of the prompt in the BI report in the batch script is incorrect.
To fix the issue, check and correct the name of the prompt in the BI report in the batch script.
The following example shows a valid prompt name and format: <parameters>
<parameter name=\"My Prompt:\" value=\"US\"/> </parameters>
[main] INFO com.mellmo.roambi.UpdateRoambi -
reponse body:<errors><error>Failed to update parameter
values. XML document structures must start and end
within the same entity.</error></errors> This error likely means that a set of double quotes was not escaped with forward slashes in the
batch script. If you failed to escape any double quotes, the command will fail because the XML
was malformed. The following example shows the correct use of escaping double quotes:
<parameters>
<parameter name=\"My Prompt:\" value=\"US\"/> </parameters>
Error: “Server could not complete the request” when
requesting a new parameter set on a batch Roambi. This error cab occur on a mobile device when the device is requesting a new parameter set
from a Roambi batch process. To fix this issue, try one of the following options:
Specify the -connected argument when running the batch process (see Running
Roambi batch processes). Hide the parameter in the Roambi analytics report using the -del_params argument
when running the batch process (see Running Roambi batch processes).
Hard code the condition into the data source so that no parameters are available.
General portal issues This section lists common issues and possible solutions for Roambi portals.
- 176 -
Chapter 13: Troubleshooting
Portal does not appear in Roambi Publisher If you have configured a portal in the Administrator's Console, the portal should automatically
appear and be available to Roambi Publisher users who have a portal account. If the portal is
not appearing in Publisher, perform the following checks:
Check that the portal settings in the Administrator's Console are correct.
Check the log files for errors. (See Enabling logging.)
Make sure that the portal has been enabled in the Administrator's Console.
SAP BusinessObjects Enterprise (SAP BOE)
issues This section lists common issues and possible solutions for SAP Business Objects Enterprise
(SAP BOE) portals.
Enabling JCE verbose logging for SAP BOE To help identify and troubleshoot SAP BOE issues, SAP recommends enabling JCE verbose
logging. To enable JCE verbose logging:
1. Navigate to the Java options for Tomcat: On Linux, navigate to /usr/local/tomcat/bin/catalina.sh, and locate
the JAVA_OPTS variabe.
On Windows, navigate to Start > AllPrograms > ApacheTomcat >
MonitorTomcat, and click the Java tab.
Add “-Dbobj.logging.log4j.config=verbose.properties” to the Java options. After enabling verbose logging, the client_verbose.log file will be generated in the
businessobjects directory for the Tomcat user. For example, on Windows 2003 this would be C:\Documents and Settings\Default User\.businessobjects\client_
verbose.log, or on Windows 2008, this would be
C:\Users\[UserName]\client_ verbose.log.
User cannot log in to SAP BOE portal
If a user cannot log in to the Roambi SAP BOE portal, check that the server name and
authentication method are correct. The server name should be the hostname of the server hosting the CMS. Set this value in
the Administrator's Console by going to Portals > [SAPBOEPortal] > Configuration >
Server Name. Set the authentication method by going to Portals > [SAPBOEPortal] > Configuration >
Authentication. Valid authentication values are secEnterprise, secLDAP, secWinAD,
and secSAPR3.
- 177 -
Cognos Issues
INCORRECT PORTAL CREDENTIALS: The username-
password combination you have used for this location are
either invalid or incorrect This error can occur if required .jar files are missing or corrupt. Make sure that all of the SAP BOE .jar files (as described in the ES5 Installation Guide) and Roambi plugin .jar file are copied to the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-INF/lib folder.
Server returned an HTTP error upon attempted login This error can occur if required .jar files are missing or corrupt. See INCORRECT PORTAL
CREDENTIALS: The username-password combination you have used for this location are
either invalid or incorrect for a solution to this error.
Cannot import a webi document If you are unable to import a webi document, check for the following error: com.mellmo.roambi.portal.exceptions.PortalException: Cannot initialize Report Engine server. (Error: RWI 00226) This error could be caused by a DNS configuration issue with the target BOE server. One clue
that this is the cause is that the other BOE servers function normally. To fix this, add the
correct hostname for the server to the Roambi server's /etc/hosts file. If you do not know
the host name, enable JCE logging on the Webi Server (see Enabling JCE verbose logging for
SAP BOE ), or check the DNS configuration for systems that are working. Additionally, make sure that no firewall exists between the Roambi server and BOE.
Cognos Issues This section lists common issues and possible solutions for Cognos portals.
Generating the Cognos logs Check the Cognos logs to verify basic configuration and connection information. To check the logs:
Stop the Cognos 8 service.
Start the Log Console: Rename the C8\logs directory.
Double-click the C8\bin\logconsole.exe file to launch the Log
Console application.
- 178 -
Chapter 13: Troubleshooting
From the Log Console, generate a new report: Under Components, select IPF Performance. In the top right pane, under Enabled, make sure that all of the check boxes are checked.
Under File, click Save.
Under Service, click Restart Service.
Wait for the service to start, then start Cognos Connection.
Re-run the report from Cognos Connection, and wait for the report to complete.
Stop the Cognos 8 service.
Return to the Log Console, and uncheck all of the boxes in the top right pane under
Enabled. Save the changes but do not restart the service yet.
Zip and send the C8\logs directory.
Delete the C8\configuration\ipfclientconfig.xml file, if it exists.
Restart the Cognos 8 service.
Verifying the Cognos configuration
To verify that the Cognos configuration is valid:
In the Roambi Administrator's Console, navigate to the Cognos configuration tab:
Portals > [CognosPortal] > Configuration
Verify the values in the following field: Dispatcher URL (example: http://cognos:9300/p2pd/servlet/dispatch)
Gateway URL (example:http://cognos/cognos8/cgi-bin/cognos.cgi)
Namespace (example: Cognos8)
Version (example: 83 or 84 with no period)
Make sure that a user can log into Cognos using the Gateway URL and Namespace.
INCORRECT PORTAL CREDENTIALS: The username-
password combination you have used for this location are
either invalid or incorrect. This error can occur if required .jar files are missing or corrupt. Make sure that all of the Cognos .jar
files (as described in the ES5 Installation Guide) and Roambi plugin .jar file are copied to the [TomcatDirectory]/webapps/[RoambiInstallation]/WEB-INF/lib folder.
Your Roambi installation is missing required library files.
Please contact your administrator. This error can occur if required .jar files are missing or corrupt. See INCORRECT PORTAL
CREDENTIALS: The username-password combination you have used for this loation are
either invalid or incorrect to fix this problem.
- 179 -
SSRS Issues
SSRS Issues
This section describes tips for troubleshooting common issues with the SSRS plugin
that is required for use with Microsoft SharePoint and Microsoft Reporting Services.
Non-functional parameters appear on the Roambi login
screen This issue occurs when one or more parameters for the portal were entered incorrectly
or contained typos. Specifically, you should double-check the values entered for
Windows NT Domain and Web Service URL for the portal. To check the values of these portals, in the Administrator's Console, go to Portals >
[PortalName] > Configuration. Verify that the Windows NT Domain is correct and that the
Web Service URLmatches the URL specified in the SSRS Config Manager. This URL should
not end in /ReportServer, which Roambi assumes by default.
Cannot login: user id or password invalid
If you see this error for a valid user-password combination, check that the authentication type
was correctly configured for SSRS. To check the authentication type:
Navigate to to the rsreportserver.config file for SSRS.
Locate the <AuthenticationTypes> element.
Check which authentication types are listed as child elements under this element. The default configuration using the startup as the Network Account is
<RSWindowsNegotiate/>. However, if you are using a specific Service NT account, you
will likely need to set <RSWindowsNTLM/>. If you have a Microsoft Analysis Services or
SharePoint portal, you will need to set <RSWindows Kerberos /> to integrate these tools
with Kerberos and SSRS.
Roambi analytics reports are not correctly displaying If Roambi analytics reports are not correctly displaying, check to see that the Roambi
Renderer is correctly installed. To check if the Roambi Renderer was correctly installed:
In a web browser, go to the SSRS Report Manager:
http://[ServerDNSName]/Reports
Go to a report, and check that under the export format options, Roambi Renderer is
visible as an available option. If Roambi Renderer is not visible, make sure that the ssrs.dll was copied to
[SQLInstallationDirectory]\MSRS10.MSSQLSERVER\Reporting
Services\ReportServer\bin.
- 180 -
Chapter 13: Troubleshooting
If Roambi Rendereris visible, but the Roambi Renderer is not generating XML,
make sure that the following files were correctly copied to SSRS: SQLInstallationDirectory\MSRS10.MSSQLSERVER\Reporting
Services\ReportServer\rssrvpolicy.config
SQLInstallationDirectory\MSRS10.MSSQLSERVER\Reporting
Services\ReportServer\rsreportserver.config
Config Manager webservice_url
If you specified the webservice_url parameter without including /ReportServer on the
end, Roambi automatically assumes its presence and will automatically use this ending. Make
sure that /ReportServer was entered in the Config Manager if you customized this value
there. Also make sure that each webservice_url that you defined uses a unique port.
HTTP 500 or 401 Not Authorized If you see this error, make sure that the data source user is authorized to refresh the report.
Cannot publish in SSRS If you cannot publish in SSRS, check the logs for the following entry: INFO org.apache.commons.httpclient.HttpMethodDirector - I/O exception (java.net.SocketException) caught when processing request: Software caused connection abort: socket write error If you see this entry, enable DEBUG mode in logging and use the DEBUG logging entries to
determine the best workaround.
Microsoft Analysis Services Issues
This section lists common issues and possible solutions for Microsoft Analysis Services portals.
Blink View does not display cubes in the database folder If the Blink View is not displaying any cubes in the database folder, make sure that the
msmpump.dll on IIS is configured for Integrated Auth only and does not include BASIC or
Anonymous auth.
Blink View displays error ”Not authorized” on login If the Blink View is displaying a "Not authorized" error when you log in, make sure that Kerberos
is configured properly. To check the Kerberos configuration, make sure that a ticket can be
issued using kinit and that the ticket is visible in kerbtray. See Kerberos Issues.
- 181 -
Liferay Issues
Cannot login. Get error “SSRS has authentication
to Navigate” This error indicates that the Authentication Type for SSRS might not have been set properly.
If you configured SSRS as a Network Account, check the
rsreportserver.properties file to make sure that the
<AuthenticationTypes> element has a <RSWindowsNTLM/> child element.
If you set the service to log in as an Admin user, use the
<RSWindowsNegotiate/> element.
Because MSAS (and SharePoint) require Kerberos, you should also include a
<RSWindowsKerberos/> element.
Liferay Issues
This section lists common issues and possible solutions for Liferay portals.
Incorrectly formatted Web Service URL As a first step, check that the Web Service URL is correctly formatted in the
Administrator's Console. In the Administrator's Console, go to Portals > [LiferayPortal] > Configuration, and check
the Web Service URL field. This URL should have the following format: http://[LiferayServer]:[Port]/tunnel-web/secure/webdav/liferay.com/[user]/document_library
For example:
http://liferay.mycompany.lan/tunnel-web/secure/webdav/liferay.com/guest/document_library
User cannot publish view in Liferay
Check for the following error: Error: com.mellmo.roambi.portal.exceptions.PortalException: com.mellmo.roambi.portal.plugins.webdav.WebDAVException: invalid path or name, or path too long If you see this error, then check for the following error in the Liferay Tomcat portal log: [DLWebDAVStorageImpl:623] com.liferay.documentlibrary.FileNameException: DLFE-1.rbi This error indicates that the .rbi file extension used by Roambi is not a supported file type. To fix this problem:
Log in to the Liferay portal using the Admin account.
In the server section, under Control Panel, select the Server Administration option.
- 182 -
Chapter 13: Troubleshooting
Click the File Uploads tab.
Add the .rbi file type as a supported file type.
Users and content are missing when Liferay starts If this problem occurs, check the LifeRay log for a "temp path not found" error. This error can occur if Liferay was installed under Program Files. To fix this, reinstall Liferay
under the root C:\ drive. Additionally, Java sometimes encounters errors when Liferay is installed
in a path containing a space.
Roambi batch process is successful, but the View does not
update using Community Liferay Server This issue is caused by a bug with Liferay Community Edition where sometimes Liferay does not
programatically update a file. This issue does not occur with Liferay Enterprise Edition.
User cannot log in to Roambi ES with new Liferay account New Liferay Portal users are required to log in to Liferay and set up a security question and
answer for their Liferay Portal user account. If a new user does not complete the account set up
process in Liferay, an error message will appear when the user attempts to log in to Roambi ES.
SSL Issues
This section lists common SSL errors and their possible solutions. If you think that you have
encountered an SSL error with Roambi, read through this section to try to solve the problem
before calling Roambi technical support.
Issue: Web browser hangs when attempting to access SSL
URL If your web browser hangs when you attempt to access the SSL URL, check the Tomcat logs to
see if the Apache Portable Runtime (APR) is loading. The APR loading indicates that the Tomcat
native SSL is loaded but that the SSL connector is using the older "HTTP/1.1" protocol, as
usually recommended by SAP. To correct this problem, delete the [TomcatDirectory]
\bin\tcnative-1.dll file so that Tomcat uses the HTTP/1.1 SSL protocol.
Issue: Intermediate certificates are missing on HTTP server
If intermediate certificates are missing, the openssl s_client -connect
[ServerURL]: [Port] command returns the following output verify error:num=20:unable to get local issuer certificate verify error:num=27:certificate not trusted verify error:num=21:unable to verify the first certificate
- 183 -
Reverse proxy issues
This output indicates that the server is returning a certificate but does not include the
certificate of the issuer, often when the issuer is an intermediate certificate. To fix this problem, add the intermediate certificates to the server. If you are using an IIS
web server, see Installing the intermediate certificates from the Certificate Authority (CA)
to IIS, otherwise, see the documentation for your web server.
Error message: "Cannot recover key" This error usually means that the password for the certificate key did not match the
keystore password. Use the following command to update the keystore password: $ keytool -keypasswd -alias [KeyAlias] -keystore [KeystoreName]
Error message: "Your credentials could not be verified
because the server could not be reached (-1206)” when
using mod_ssl on apache" If you are using the mod_ssl toolkit with Apache, the SSLVerifyClient=optional value is
not supported for Roambi and WebKit-based browsers. The only supported values for WebKit
are none and require. If you are using two-way SSL, use SSLVerifyClient=require.
Validation error: "verify error:num=19:self signed
certificate in certificate chain" When you verified the SSL requirements (see Validating the SSL requirements using
OpenSSL) one possible status error message is verify error:num=19:self signed
certificate in certificate chain. This error means that the certificate chain that
was returned by the server ends with a "self-signed certificate." Because a self-signed
certificate is not a trusted certificate, the validation check reported it as an error. To eliminate
the error, specify a trusted root CA. (See Specifying a trusted root CA for the server.)
Validation error: verify error:num=20:unable to get
local issuer certificate If you see this error when verifying the SSL requirements, it means that OpenSSL does not
know which root CA to trust. Because OpenSSL does not have a default trusted root CA, you
will need to explicitly specify which root CA OpenSSL should trust. To correct this error, specify a trusted root CA. (See Specifying a trusted root CA for the server.)
Reverse proxy issues
This section gives tips to help troubleshoot possible reverse proxy issues.
- 184 -
Chapter 13: Troubleshooting
Checking if reverse proxy is working properly
To check if the reverse proxy is properly working, check the /roambi/check_network.jsp
file. If reverse proxy is not properly working, the file will be shown in red.
Troubleshooting reverse proxy issues with Tomcat
If you are using Tomcat as your application server, check Tomcat's requestdumpervalve to
see if requests are successful. The host header and referer header need to be from the same
host; otherwise, the server will reject the request with a "Forbidden" message.
Kerberos Issues
This section describes tips for troubleshooting common Kerberos issues, plus some common
errors and their solutions.
Enabling Kerberos debug logging To enable Kerberos debug logging in Tomcat:
1. Navigate to the Java options for Tomcat: On Linux, navigate to /usr/local/tomcat/bin/catalina.sh, and locate
the JAVA_OPTS variabe.
On Windows, navigate to Start > AllPrograms > ApacheTomcat >
MonitorTomcat, and click the Java tab.
Add “-Dsun.security.krb5.debug=true” to the Java options.
Go to the Roambi log4j.properties file, and make sure that the default log level is
DEBUG. In your login.conf file make sure to set or add debug=true to the parameters.
Kerberos debug logging should now be enabled in the catalina.out log file. In the log file,
look for a "failure to authenticate" error.
Checking the Kerberos configuration See the Java documentation for a list of common Kerberos errors: http://docs.oracle.com/javase/1.5.0/docs/guide/security/jgss/tutorials/Troubleshooting.html
Additionally, in the krb5.ini file, make sure that the entries meet the following requirements:
All realms must be in all uppercase.
You must have a single space (and only a single space) before and after equals signs (=).
You cannot have any spaces before the definition of a realm (WindowsRealmName).
You must have a single tab (and only a single tab) before the entries for kdc =
and default_domain = .
- 185 -
Kerberos Issues
Listing SPNs To list all SPNs associated with a host, type the following command: $ setspn -L DOMAIN/hostname
SPNs must be unique. To list any duplicate SPNs associated with a host: $ setspn -Q HTTP/hostname
Verifying that a Kerberos ticket can be issued To verify that a Kerberos ticket can be issued, download and use the kinit utility: http://download.oracle.com/javase/1,5.0/docs/tooldocs/linux/kinit.html The following sample command requests proxiable and forwardable credentials for a
different principal and stores these credentials in the default location: $ kinit –fp [email protected]
Checking if a tgt ticket has been created and cached on the
client Use the kerbtray.exe tool to check if a tgt ticket has been created and cached on the client.
[Krb5LoginModule] authentication failed
This error indicates that a domain controller might be missing from the krb5.ini file. Make
sure that the krb5.ini file includes all necessary domain controllers in the
[domain_realm] section.
Client not found in Kerberos database (6)
This error indicates that a domain controller might be missing from the krb5.ini file. See [Krb5LoginModule] authentication failed for the solution to this problem.
- 186 -
Chapter 14: SAP Roambi ESX
This chapter discusses features and functionality that are only available in SAP Roambi ESX.
Roambi ESX consists of Roambi Analytics and Roambi Flow, specially licensed for sharing
free, 'external' Roambi content with the general public. From next-generation product collateral
to interactive financial reports, Roambi ESX lets you deliver unsecured Roambi content to the
general public, utilizing a Public Portal. Public Portals eliminate the need for end user
credentials and provide a seamless user experience for public-facing Roambi Analytics reports
and Roambi Flow publications. Note: When enabling public access to a portal storing your source data and Roambi files,
your organization is responsible to maintain its compliance with its portal license.
Included in this chapter:
About Public Portals
Adding a Public Portal
Adding Authentication Credentials to a Public Portal
Configuring a Public Portal
Enabling a Public Portal
Publishing Roambi Files to Public Portals
About Public Portals
When you designate a portal as public, users can gain access to the Roambi report files (RBIs)
and Roambi Flow publications published to the portal using the public account information.
To create and publish Roambi reports and Roambi Flow publications, authors must log into
the Public Portal using their personal access credentials and not the public account.
To download and access reports and publications on mobile devices, end users can access
Roambi files using the public account information which does not require access credentials.
Enabling the Public Portal option does not prevent users from logging into the portal
with credentials other than what you specify for the public account.
Important things to note about Public Portals:
- 187 -
Chapter 14: Roambi ESX
The Public Portal option is not available for portals that use single sign-on (SSO).
The Public Portal option must be enabled when you add a portal. If you would like to
designate a portal that has already been added to Roambi, you must delete the portal
from Roambi and then add it again it as a Public Portal.
Adding a Public Portal
Add a Public Portal as you would normally create a new portal in Roambi
ES5. To add a portal:
Click the Add Portal button in the lower left corner of the dashboard:
An Add Portal window opens:
From the Portal Source drop-down list, select the portal that will be used as the data
source for the portal. Depending on which portal you choose, the portal may also be
used to store Roambi RBI files and Flow publications. In the Name text box, type a unique name for the portal source.
When creating a Public Portal, it is recommended that you include "public" in the portal name.
This will ensure report authors know that they are importing data from and publishing reports to
a Public Portal. For more details, see Publishing Roambi Files to Public Portals.
Check the Enable Public Portal box.
Click Add.
- 188 -
You have successfully enabled a Public Portal for Roambi ESX. Next, see Adding
Authentication Credentials to a Public Portal.
Adding Authentication Credentials to a Public Portal
Next, add the public authentication credentials to the portal as follows:
Add the public authentication credentials to the portal:
On the left pane of the Administrator's Console, select the portal.
Click the Configuration tab:
On the Configuration tab, enter the required parameters for your portal type. The fields
requiring data entry will vary from portal to portal. For details, see the section that
pertains to your portal type in this guide. The Portal Status section displays a message prompting you to verify your settings.
- 189 -
Chapter 14: Roambi ESX
Click the Verify button to open a Verify Portal window:
Type the credentials that you use to access the portal. These credentials do not need to
be the same credentials as the username and password for the public account. Click Verify to close the Verify Portal window.
The Portal Status section of the configuration tab displays a message prompting
you to configure the Public Portal.
- 190 -
Configuring a Public Portal
To configure a Public Portal:
Click the Security tab for the portal.
The section is now visible. This section will not be visible unless you enabled the
Public Portal option when you created the portal:
In the Public Account field, click the Attach Account button:
- 191 -
Chapter 14: Roambi ESX
Enter the account credentials for your portal's public account. By specifying the account's
access credentials here, end users will be permitted to access the Roambi reports (RBIs)
and Roambi Flow publications on the portal without being prompted for credentials. Click Attach to attach the account.
The Public Account field now displays the username for the public account:
- 192 -
If you want to select a custom logo for the portal, click the Select button for Small
Logo and/or Large Logo and follow the prompts to change the logo.
If you want to allow users to browse the contents of the portal, rather than only being able to
access Roambi reports sent via Roambicast or Roambi Flow documents sent via Flow
Cast, toggle the Enable Browsing switch to ON. (Browsing is disabled by default.)
If you enable browsing, two more options become available: Available For and
Public Portal URL:
In the Available For field, select whether you want users to be able to browse Analytics
files (RBIs), Roambi Flow files, or both. The Public Portal URL contains the URL that you can copy and email to users or integrate
with another application.
Enabling a Public Portal To enable a Public Portal:
Click the Configuration tab for the portal.
The Portal Status section now displays a message about enabling the portal.
Toggle the Enable Portal swich to ON. The portal is now enabled and Roambi files that are published to the portal can now be
accessed by users via the public account credentials.
Publishing Roambi Files to Public Portals If you have more than one portal integrated with Roambi, ensure that your report authors
are aware that if they want to provide mobile end users with public access to a Roambi file,
they must always choose the Public Portal as the publishing location. This is true for both
Roambi reports (RBIs) and Roambi Flow publications. In order to avoid confusion in environments where portals may have similar names, MeLLmo
recommends that you always assign your Public Portal a unique name to clearly identify it as
public. For more information see the recommendation in Adding a Public Portal.
- 193 -