Table of Contents Chapter 1: Getting Started with SAP Roambi Roambi ES product overview Getting help Chapter 2: Configuration and Customization

Transcription

1

2 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

3 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

4 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

5 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 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

6 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 s 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

7 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

8 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

9 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

10 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

11 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

12 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 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-

13 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

14 Configuring Roambicast Verify that the default values are correct for your SMTP server, or make the necessary changes for the server. Depending on your server configuration, these settings might include the following fields: Domain Host: SMTP server domain name. From address displayed in the From field of a sent . URL Host for s: Host value used to construct links for s. 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 (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 . To validate the SMTP settings by sending a test 1. On the SMTP Settings tab, click the Send Test button to display a Send Test prompt. 2. In the field, enter a valid address. 3. Click the Send button. Within a few moments, you should receive an at the Send Test 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 , depending on how you installed the Roambi server: - 6 -

15 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- For HTTPS: roambi:// 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- For HTTPS: roambi:// 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- 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 To use HTTP: roambi- To use HTTPS: roambi://[roambiserver] The RoambiServer parameter should contain the URL used to access the Roambi server

16 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> <paramvalue>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

17 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-japanesegothic.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

18 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

19 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:

20 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

21 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 , the 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:

22 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

23 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

24 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:

25 Chapter 3: Portal Management

26 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

27 Chapter 3: Portal Management The Console displays the Portal Details:

28 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

29 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:

30 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

31 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-

32 Chapter 3: Portal Management Click the Configuration tab to view the server configuration. Note that options on this screen vary by portal type:

33 Configuring server details for a portal

34 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

35 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 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 (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)

36 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: 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: Liferay Liferay has the following available Portal Parameter: Web Service URL: URL for the Liferay portal. For example:

37 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: 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 "/"

38 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, 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:

39 Specifying a root folder for client devices

40 Above the Portal Details, click the Folders tab. The Console displays the Portal Folders:

41 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

42 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

43 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 autosynchronization. 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 redownload 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:

44 Configuring Auto-synchronization for folders

45 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

46 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:

47 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:

48 Chapter 3: Portal Management

49 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:

50 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:

51 Chapter 3: Portal Management Configuration 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 Steps 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 Refresh folders? Y Y Y Y Y Y Comments Application is sent into the background when Smart Cover is on, regardless of lock settings, because of the default Smart Cover settings. 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

52 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:

53 Chapter 3: Portal Management Above the Portal Details, click the Folders tab. The Console displays the Portal Folders: -

54 Specifying a working directory (Roambi Flow only) Under Roambi Flow Working Directory, click the Select Folder button. An Add Working Directory window opens:

55 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

56 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:

57 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

58 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:

59 Chapter 3: Portal Management Click the Configuration tab to display portal configuration options

60 Enabling or disabling a portal

61 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.)

62 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:

63 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

64 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

65 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:

66 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

67 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:

68 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 s 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

69 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:

70 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 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

71 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:

72 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:

73 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 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 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-andwipe 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

74 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:

75 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

76 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:

77 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

78 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

79 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

80 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

81 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.

82 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:

83 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

84 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:

85 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:

86 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

87 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

88 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:

89 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:

90 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

91 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=username&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

92 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-protectionrelevant 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 Personal data Business purpose Blocking Deletion Retention period End of purpose (EoP) Definition Information about an identified or identifiable natural person. 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. A method of restricting access to data for which the primary business purpose has ended. Deletion of personal data so that the data is no longer usable. The time period during which data must be available. 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

93 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.

94 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

95 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:

96 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:

97 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:

98 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

99 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

100 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

101 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: Note: 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 This section does not discuss setting up the BIG-IP appliance itself. See the documentation for your appliance for specific instructions

102 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

103 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

104 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"

105 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:

106 Chapter 8: Firewall Placement VPN options for the iphone provide additional flexibility. See the Apple web site for documentation about setting up VPN: 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

107 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. Rightclick 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

108 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

109 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)' '" -pattern 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 / ProxyPassReverse / Force to ssl RewriteEngine On ReWriteCond %{HTTPS}!=on RewriteRule.* [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:

110 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:

111 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:

112 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

113 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: 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!

114 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

115 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>statusoverride.enabled</param-name> <paramvalue>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> <filtername>spnegoauthfilter</filter-name> <filterclass>com.mellmo.roambi.servlet.filter.spnegoauthfilter</filterclass> <init-param> <description><![cdata[the 'application name' in Java logic.conf file.]]></description> <param-name>app_name</param-name> <paramvalue>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</paramname> <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>

116 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</paramname> <param-value>120</param-value> </init-param> </filter> <filter-mapping> <filter-name>spnegoauthfilter</filtername> <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

117 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:

118 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: 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

119 Using Threat Management Gateway (or Internet Security and Application Server) with Roambi C:\> ktpass /princ /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

120 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

121 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/apachetomcat /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: 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: Follow the instructions from the OpenSSL web site to download and install this utility to the machine where you installed Tomcat

122 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( ) depth=3 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN = TEST Root CA, address = root@example.com 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/ Address=root@example.com -----BEGIN CERTIFICATE END CERTIFICATE s:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST SubCAUK 1/ Address=root@example.com i:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root CA UK/ Address=root@example.com -----BEGIN CERTIFICATE END CERTIFICATE s:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root CA UK/ Address=root@example.com i:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root CA/ Address=root@example.com -----BEGIN CERTIFICATE END CERTIFICATE s:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root CA/ Address=root@example.com i:/c=gb/st=herts/o=tmuk TEST ONLY/OU=TMUK TEST ONLY/CN=TEST Root CA/ Address=root@example.com -----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

123 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:

124 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:

125 Chapter 9: SSL CONNECTED( ) depth=3 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN = TEST Root CA, address = root@example.com verify return:1 depth=2 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN = TEST Root CA UK, address = root@example.com verify return:1 depth=1 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN = TEST SubCAUK 1, address = root@example.com verify return:1 depth=0 C = GB, ST = Herts, O = TMUK TEST ONLY, OU = TMUK TEST ONLY, CN = myserver.local verify return: 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:

126 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

127 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: 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]

128 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( ) 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 1/ema-ilAddress=admin@mycompany.com --- 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( ) 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:

129 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 1/ema-ilAddress=admin@mycompany.com --- 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]\keystore\key.keystore" keystorepass="pass" clientauth="false" sslprotocol="tls" />

130 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=" " 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"

131 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=" " 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

132 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: 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

133 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. Click OK. 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. 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

134 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

135 Chapter 10: Single Signon (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

136 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:

137 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:

138 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:

139 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

140 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:

141 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

142 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 Registration schemes Not supported. Realm rules 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. On the Domain Configuration screen for SiteMinder, set the following Ream 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

143 Configuring Roambi for use with Site-Minder Component Authentication level Namespaces 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: Agent Configuration Object Set SetRemoteUser to yes. Deactivate BadCssChars. Deactivate DisableSessionVars. Use the following properties and settings (using Windows as an example): LDAP namespace Windows AD namespace 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: 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:

144 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</paramname> <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</paramname> <param-value>true</param-value> Set the value of the siteminder.authentication paramter to secwinad: <param-name>siteminder.authentication</paramname> <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:

145 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

146 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</filtername> <filterclass>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> <paramname>name</param-name> <paramvalue>sm_user</param-value> </init-param> <initparam> <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> <paramname>authtype</param-name> <paramvalue>header</param-value> </filter> <filter-mapping>

147 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 <paramvalue> 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:

148 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 useraccessible 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> <filterclass>com.mellmo.roambi.servlet.filter.httpheaderauthfilter </filter-class> <init-param> <param-name>name</param-name> <param-value>sm_user</param-value>

149 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

150 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 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

151 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> <filterclass>com.wedgetail.idm.sso.authfilter</filter-class> </filter> <filter-mapping> <filter-name>authfilter</filtername> <url-pattern>/*</url-pattern> </filtermapping> --> In the section containing the filter elements, enable the VSJFilter: <!-- <filter > <filter-name>vsjfilter</filter-name> <filterclass>com.mellmo.roambi.servlet.filter.vsjfilter</filter-class> </filter> <filter-mapping> <filter-name>vsjfilter</filtername> <url-pattern>/*</url-pattern> </filtermapping> --> 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

152 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: 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 Services</Description> <RequiredParameters> <RequiredParameter> <Name>UserID</Name> Reporting

153 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: &password=[password] For example, the following URL logs onto the SharePoint_2007 portal at roambi.mycompany.com as the Administrator with the password 1234: 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: [Username]&password=[password For example: /%252Fcontent%252Ffolder%255B%2540name%253D%2BReports%2527%255D? user_name=administrator&password=

154 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: 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:

155 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

156 Running Roambi batch processes example: [XMLParameters] -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 <parameters> <parameter name="aaa" value="123"/> <parameter name="bbb" value="jkl; xyz"/> </parameters> 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

157 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]

158 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 -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 -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 - src_rbi RBI123 -src_portal SAPPortal -dst_folder Folder123 -src_username Administrator -src_password 1234 C:\> java -jar roambi-batch.jar -server - 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 -src_rbi RBI123 -src_portal SAPPortal1 -src_data Data123 -src_username Administrator - src_password dst_portal SAPPortal2 -dst_folder Folder123 -dst_rbi NewRBI123 -dst_username Administrator -dst_password

159 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 -src_rbi RBI123 -src_portal Portal1 -src_data Data123 -src_username Administrator - src_password 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 -src_rbi RBI123 -src_portal SAPPortal1 -src_data Data123 -src_username Administrator - src_password dst_rbi NewRBI123 -src_data_params "<parameters><parameter name=\"quarter\" value=\"q3\"/></parameters>" C:\> java -jar roambi-batch.jar -server -src_rbi RBI123 -src_portal Portal1 -src_data Data123 -src_username Administrator - src_password 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

160 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 -src_rbi rbi123 -src_data Data123 - src_username Administrator -src_password 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]

161 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 -src_rbi rbiid -src_portal EnterprisePortal1 -src_data Data123 -sso_username Administrator -sso_password SSO

162 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 If you obtain the report URL from a Roambicast , 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:

163 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

164 Obtaining the report URL Publisher displays the Import Your Data screen, which you can use to browse to your existing Roambi reports:

165 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:

166 Obtaining the report URL When you select an RBI file, four buttons giving additional options in the lower-left corner become enabled:

167 Chapter 12: Application Service API

168 Obtaining the report URL

169 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:

170 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 To obtain the Roambi report URL from a Roambicast Open the Roambicast 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: p252fadventureworkscardex.rbi_e

171 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 (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: p252fadventureworkscardex.rbi_e Change the URL scheme in the URL prefix: If the URL starts with " change the " to "roambi://". If the URL starts with " change the " to "roambihttp://" For example, the sample URl should be changed to: roambi- 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- 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

172 Linking to a specific Cardex card example: [[UIApplication sharedapplication] openurl:[nsurl URLWithString:@ roambi- 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]"}]} d6-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: The final, encoded URL should look similar to the following example: 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- roambi- 5b d6-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

173 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?

174 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: :03:11 [ @qtp ] 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 In another example, the following sample entry was added because the SAP BOE SDK was not available in the Roambi ES classpath: :03:11 [ @qtp ] 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,

175 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: 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

176 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:

177 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 jar jai_core 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":" [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}"

178 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= sac7cojqatdbfnn7w2gpaql0_e?jsessionid=null, NSErrorFailingURLKey= 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:

179 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/

180 Chapter 13: Troubleshooting 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=C4CE7CA908BD9C1A787E FE]- 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: Missing entry for connstringinstance 1 in roambisettings.properties /[InstallationDirectory]/openoffice.org3/basis-link/urelink/share/java/juh.jar /[InstallationDirectory]/openoffice.org3/basis-link/urelink/share/java/jurt.jar /[InstallationDirectory]/openoffice.org3/basis-link/urelink/share/java/ridl.jar /[InstallationDirectory]/openoffice.org3/basislink/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

181 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 s If you are unable to use Roambicast to send s, 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 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

182 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

183 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 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 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 jar jaxb-api 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:

184 Chapter 13: Troubleshooting For example: 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:

185 Roambi Publisher issues Roambi Publisher issues This section lists common issues and possible solutions for errors encountered in Roambi Publisher

186 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=" " 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 = ). If Tomcat is redirecting to an Apache or or IIS web server, also add the maxpostsize attribute to the connector for the AJP Port 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

187 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

188 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 secsapr

189 Cognos Issues INCORRECT PORTAL CREDENTIALS: The usernamepassword 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

190 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: Gateway URL (example: 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 usernamepassword 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

191 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: 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

192 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

193 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: For example: 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

194 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

195 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

196 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: 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 =

197 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: The following sample command requests proxiable and forwardable credentials for a different principal and stores these credentials in the default location: $ kinit fp admin@mycompany.com 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

198 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:

199 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

200 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

201 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

202 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:

203 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:

204 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 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

205