SAP Roambi 2017-10-31 SAP Roambi Cloud SAP BusinessObjects Enterprise Plugin Guide 1
Table of Contents I. Overview Introduction How it Works II. Setup Requirements Roambi Requirements Created a Roambi View to be used as a template Install and configure RoambiScript Business Objects Enterprise (BOE) Requirements Roambi Configuration Creating API Key Setting up RoambiScript III. How to Use Step 1: Create the Template Step 2: Set up the Profile Create Profile Step 3: Create Publication Review the Publication Summary Sending the Publication to Enterprise Recipients Add Plugin to BOE Appendix A: Troubleshooting and Common Issues Appendix B: Resources I. Overview Introduction The Roambi Publisher Extension simplifies the process of updating a Roambi report with data coming from a Web Intelligence report. Additionally, with a publication, you can schedule the delivery of reports and create personalized data for different recipients. SAP Business Objects Enterprise Publisher Extension has provided a framework for 3rd party developers to execute scripts during the publication process. This Roambi publication extension is leveraging Roambi API (SAP Roambi Publisher SDK) behind the scenes. SAP Roambi will respect the row level data permissions as specified in BOE. 2
The key benefit of using this publication extension, is the report creator will not need to script its own API, but leverage the existing BOE interface and entities to deliver Web Intelligence reports as Roambi views. How it Works 1. An initial Roambi Report Template is published. 2. A Publication against the source Web Intelligence generates an XLS file for RoambiScript. 3. RoambiScript uses the source file and the Roambi Report Template to generate personalized version of the report to the recipient. 4. The new version of the SAP Roambi Analytics downloaded/synced to the device. II. Setup Requirements SAP Roambi Cloud Configuration Requirements 1. Administrator access to SAP Roambi Cloud 2. Create an Roambi Cloud API Token. 3. Invite BOBJ end-user(s) into the Roambi Cloud Account 4. Publish a Roambi report to be used as a template SAP BusinessObjects Enterprise (BOE) Configuration Requirements 1. SAP BOE version 4.0, 4.1 or 4.2. 2. Permissions to add BOE plugins (need folder access to the BOE server installation path) 3
3. Install and configure RoambiScript (Roambi Pub SDK) 4. Install Roambi BOE Publication Extension 5. Administrator access to BOE Central Management Console (CMC) 6. BOBJ end-user details has correct email address Roambi Configuration Creating a new API Token SAP Roambi BOE Publication Extension leverages the Roambi Cloud API to facilitate the creation of Roambi Cloud reports. No programming or API knowledge is required to use the components, but you do need to create an API token. 1. Go to View Account > API Tokens 2. Give it a name and click + 3. Copy the token and store it somewhere secure Note: This is the only time you will see the token. 4
Get the Account UID 1. Go to Invite Users > Info 2. Copy the Account UID Invite BOBJ end-user(s) into the Roambi Cloud Account Recipients of the Roambi reports will need to be members of the Roambi Cloud Account in order for them to have access. To invite new users or groups: 1. Login as an administrator to your Roambi Account 2. Tap the "Invite Users" icon, available from the home screen 3. Navigate to "People" within the administration console 4. Tap on the + button to reveal and select the "Invite Single User" or Invite Multiple Users option 5. For Single User invites, fill out the form while ensuring that the email address matches the user s email address in BOE. Tap the "Invite" button in the upper right corner. 5
For Multiple Users, click the download link to get a CSV template to fill out and upload here. Publish a Roambi report to be used as a template The Roambi BOE Publication Extension generates personalized Roambi reports to your recipients by using an existing Roambi report as a template. If you have not created a Roambi Report before, please review our Getting Started material and select a Roambi Template to create your first report. Tips on creating the Roambi report template is covered in Step 2 of the How to Use section. SAP BOE Configuration To enable the Roambi BOE Publication Extension, it requires placing two jar files on the BOE server: SAP Roambi Pub SDK (RoambiScript): roambi-api-cli.jar An API utility that the BOE publication will use to communicate to Roambi Cloud. Roambi BOE Publication Extension: roambi-boe-14-x-publicationextension-2.0.2.jar BOE Publication extension to set Roambi delivery options 6
Setting up RoambiScript 1. For more information on RoambiScript, see RoambiScript Publishing SDK. 2. Download the SAP Roambi Pub SDK from SAP Service Marketplace. 3. Create a folder on the BOE Server that can be easily referenced. In this documentation, the roambi-api-cli.jar (SAP Roambi Pub SDK) is saved in the C:\roambiscript folder. 4. In the terminal or command prompt, navigate to the location of roambiapicli.jar (eg. C:\roambiscript ) and run the following command to generate a properties file: java -jar roambi-api-cli.jar configure (Note: JAVA_HOME/bin folder must be in the Path environment variable) 5. After executing the above command, answer the prompts based on the details from your API client in Roambi. This will create a roambi-api-cli.properties file: If your network uses a proxy to connect to internet, then you will need to add additional parameters to the properties file. Follow the instructions in this KBase. Please note the roambi-api-cli.jar installation path (in this example it is C:\roambiscript). The publisher extension will need to reference this directory path. 7
6. Test RoambiScript to ensure that it is working properly before applying the BOE Publication Extension. In the command prompt, navigate to the roambi-api-cli.jar install path (eg. C:\roambiscript ) Run the following command: java -jar roambi-api-cli.jar ls --folder <admin email> <admin email> should be the email address of the admin account used to configure RoambiScript. This will list the contents of the Admin s personal folder and will display Run: 1. Failure: 0 on the last line to indicate the command was successful. If you receive Failure: 1 then check the /logs folder in the RoambiScript installation path for more details (eg. C:\roambiscript\logs) Setting up Roambi Publisher Extension 1. Download the Roambi BOE Publication Extension from the SAP Service Marketplace. Depending of your version of BOE, this is the Roambi BOE Publication Extension jar file you need to use: BOE 4.0: roambi-boe-14-0-publication-extension-2.0.2.jar BOE 4.1: roambi-boe-14-1-publication-extension-2.0.2.jar BOE 4.2: roambi-boe-14-1-publication-extension-2.0.2.jar (same jar as BOE 4.1). 2. Move the Roambi BOE Publication Extension jar file into BOE s publishingplugins folder: C:\Program Files (x86)\sap BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\java\lib\publishingPlugins Note: This will depend on your BOE installation path. The above folder path is the default path for BOE 4.0) 3. Restart BOE Server Intelligence Agent. a. Open Central Configuration Manager: 8
b. Restart Server Intelligence Agent. Wait a few minutes until all services are up and running. You can monitor this by clicking the Manage Servers icon in the toolbar. III. How to Use We will use an example to illustrate all the steps you need to perform to create a personalized Roambi report for your recipients powered by BOE. Here we will cover the process in 4 steps: 1. Establish the Use Case. 2. Create the Roambi Report Template 3. Create a Profile 4. Create a Publication Step 1: Establish the Use Case Our sales team have been requesting to visualize and review their sales reports. While they can get by on creating their own Excel charts on the desktop, it is inefficient, not standardized, and not the best use of the sales team time. Additionally, with sales team traveling most of the time, easy mobile access is a must. The IT team identified SAP Roambi as a suitable solution. They can transform each Web Intelligence reports into Roambi reports. However, they recognize this is not scalable especially with how quickly the sales team is growing, and each sales rep have different level of data access. They want to avoid having to create multiple Web Intelligence reports and multiple Roambi reports. Additionally, they gathered the following requirements: 9
Sales want to see revenue, profitability, and sales by state and product lines. Wants a dashboard like presentation, and not spreadsheet Reports should be updated daily Sales reps should only be able to see the metrics for their respective state (e.g. Tony, the Account Rep in Texas, should only see data from Texas) Sales manager should be able to see all the states under their supervision (e.g. Ally, the US Sales Manager, will see data from All the states) Managers should have the ability to filter data to specific states Step 2: Create the Template When creating a Roambi report as a template, the general workflow is: 1. Determine the data to be shared with your recipients. Decide if all recipients will get the same data or it will be filtered by specific category, product, or country. 2. Create or select a Web Intelligence report that contains the data. As a best practice, remove any header, footer, and additional formatting from the report. 3. Export the report as Excel file. 4. Upload to SAP Roambi Cloud and create your Roambi report. 5. Review and refine the Roambi View As with all design processes, creating a Roambi report will take few iterations and practice. General recommendation is to work through the steps outlined here, and get early feedback from recipients before investing on perfecting the smaller details. In regards to the example use case for the sales team, the first step is to gather the necessary sales data by state. The IT team created a Web Intelligence report that contains the following dimensions and measures 10
Sample Web Intelligencentelligence Report for Sales Team The report contains all states that have sales presence including (California, Colorado, Texas, etc.). The most important metric, Sales Revenue, is available. Additionally, IT team added Margin to help calculate profitability and included other common sales metrics. This report contains all the requested information to create a Roambi Dashboard. The report is downloaded as an Excel report and uploaded to SAP Roambi Cloud. 11
Screenshot of creating a Sales Team Dashboard in Roambi Publisher Since the desired presentation is a dashboard, choosing the Card View is an appropriate choice as the deliverable. Once you import the Web Intelligence reports, the dimensions and measures are available to create charts and visualizations. In this case, single value object, comparison charts, bar charts, area charts, and pie chart are used to display the requested information. Additionally, a filter dimension is applied on state, so that individual state data can be viewed separately. Once the design is complete, publish the Roambi View and save it in an easily accessible folder. In this case, the file will be published to a folder called Templates. Review the Roambi on the device and collect feedback on whether the data and visualizations are meaningful and address the sales team s needs. 12
Screenshot of creating a Sales Team Dashboard on the ipad Once the template is finalized, the remaining steps are to personalize the Roambi reports and deliver them. These steps are all configured within the BOE interface. The following steps assume you have no experience with BOE Publication. If you are already familiar with BOE publications, please skip to Step 5: Adding Roambi Publication Extension. Step 3: Create Profile To personalize the data for recipients, SAP BOE uses an object called Profile to facilitate the mapping of the data. From SAP BOE Introduction to Publishing: Profiles are objects in the SAP BusinessObjects Enterprise system that let you classify users and groups. They work in conjunction with publications to personalize the content that users see. Profiles link users and groups to profile values, which are values used to personalize data within a report. 13
This section outlines the steps to create profiles. It assumes that users or groups have been created already. It is important to note that the users email will need to match the email used in SAP Roambi Cloud. If using groups, the Group Name must match the Group name in SAP Roambi Cloud. 1. Login to Central Management Console (CMC). 2. Choose Profiles. 3. Select Manage > New > New Profile. 4. Create a name for the Profile (example: Publication Demo Profile) 5. Select Profile Targets and click Add. 6. Select the appropriate universe and object that will be used as a filter for the publication. In this case it is the efashion universe and Object State. 14
7. Select Profile Values and determine the users and/or groups that will receive the publication. When choosing a specific user, you can define the data value for personalization. In this case, Chris California will receive data only from California. Whereas Daniel Sutoyo will receive data from a subset of states. Once the steps are completed in creating a profile, it can be used to create personalized publication for any Web Intelligence documents based on this universe and selected object. Step 4: Create Publication Publication is a SAP BOE entity that enables you to schedule personalized reports. It leverages the users and profiles that you created in the previous steps. 1. Login to BI Launch Pad or CMC. 2. Select a folder where the publication will be generated. In this case Public > Publication Demo. 3. Click New > Publication to create the Publication. 4. Provide a title for the publication. In this example, it is State Sales. 15
5. Select a Web Intelligence report as a source document. This should be the same report you used to create your Roambi template. 16
6. In Enterprise Recipients add all the users or groups you want to receive the publication. These should be the users or groups you have included in the profile and must match the list of users/groups that are in Roambi Cloud 7. In Personalization select the local profile and object that the publication should be filtered on. In this example, select State as the query and Publication Demo Profile as the Enterprise Recipient Mapping. 8. In Formats, at the minimum you will need to select Microsoft Excel as output format. 17
9. In Destinations, select BI Inbox and check the Deliver objects to each user option. 10. In Roambi Cloud Publication Extension, you will need to add the Roambi Cloud Business Objects Publication Extension. Please refer to the table below for instructions on the parameters. 18
Field Publication Extension Name Class Name Parameter Value RoambiBusiness (can be a custom title) com.mellmo.roambi.businessobjects.publication.pu blicationextension templatepath=<path to RBI template>&roambiscriptfolder=<path to RoambiScript>&destinationFolder=<path to destination folder in Roambi File System>&title<name of the Roambi file>&cleaninbox<true or false> Important Notes templatepath (required): Roambi Cloud path to the Roambi Report Template file roambiscriptfolder (required): The local path of the RoambiScript jar file. destinationfolder (optional): A valid, existing folder in the Roambi File System (RFS) to which the Roambi file will be published. If not specified, the Roambi file will be published to users personal folder. title (optional): The Roambi file s name. If not specified, the title will be the publication name. The title can be a static title like Sales Report or it can be a dynamic title like 'Sales Report {State - Query 1}'. In this case, the variable name enclosed in {} will be replaced by the plugin with the value(s) used to generate the report. The variable name must be the same as shown in the Report Field configured in the Personalization step of the publication. cleaninbox (optional): If this parameter is true, the plugin will not create a copy of the excel file in users inboxes. If not specified it will default to false. The parameter values highlighted in yellow must be URL Encoded (or the whole parameter can be URL encoded): 19
templatepath=<path to RBI template>&roambiscriptfolder=<path to RoambiScript>>&destinationFolder=<path to destination folder in Roambi File System>&title<name of the Roambi file>>&cleaninbox<true or false> Example Parameter Values: templatepath= /Template/State Sales roambiscriptfolder= c:/roambiscript destinationfolder= /Roambi Files title= Sales Report cleaninbox= true Final Parameter to be entered: templatepath=%2ftemplate%2fstate%20sales&roambiscriptfolder=c%3a%2froambi script&destinationfolder=%2froambi%20files&title=%20report&cleaninbox=true In the latest version, the whole parameter can be URL Encoded. You can encode with this URL encoder here. Note: Strongly encourage you to store the source and url encoded parameter path in a document for your own reference. Once the publication extension is added, BOE does not let you edit it. You will have to remove and reinsert again. 11. The publication extension must be added in the list Before Publication Delivery 20
12. In Schedule, select the desired frequency to deliver the publication. You can select Run Now, to send the personalized reports. 13. Open Roambi Analytics and review the reports are correctly filtered for recipients. 21
Appendix A: Troubleshooting and Common Issues Where do I find RoambiScript, BOE Publication Extensions, and API Key? RoambiScript: Find it in SAP Service Marketplace Roambi BOE Publication Extension: Link Roambi API Key: Please refer to How do I create a Roambi API client? No reports are created after the Publication completes The Publication needs to be successful before RoambiScript is executed to generate any content. Delete the contents in the C:\roambiscript\logs directory Run the Publication again First check the Publication history to confirm that was successful without errors. If it failed, review the log provided for further details. If successful, then check the C:\roambiscript\logs to see if a new log was created. This indicates that RoambiScript may have encounted an error. Check the log for further details. How do I obtain log files? There are two log files you can pull for troubleshooting purposes: For BOE log files, right click on the BOE publication and click on History. 22
This will open a new pane of previous job runs. Clicking on the run entry will allow you to view the log files and other exported files (if you specified in your destination). For RoambiScript log file, go to the folder where you installed RoambScript. There is a folder called log and will contain the latest events. I am getting empty data set in my Roambi file Please check the following items 1. You provisioned the right users, and you are using a provisioned user to test the RBI contents 23
2. Check that your source report matches the dimensions used in the Roambi Report. 3. The profile values and filters for the user actually matches the data in the source report. Make sure you do not have additional query filter that restrict the data than intended 4. Make sure the data entry matches your filter (e.g. Texas_ ). You can check this by looking at the exported Web Intelligence or Excel report in the user s BOE inbox. Profile mapping and query needs to be accurate. It uses an AND clause Check that your RBI template can be accessed I get an invalid path in log The RBI is stored in the user s My Documents folder. And the My Documents folder is specific to the user s email address. Please Double check that the user email address is the same in BOE and in Roambi Cloud. I get an invalid template path in log Double check the user credential you are using for the api client key has access to the RBI template and the folder that stores the RBI My BOE log says it is complete, but I don t see anything Please check whether you have specified Excel as a format in the publication properties. At the minimum, the Excel format must be selected. How can I check if my data issue is a BOE issue or a Roambi Issue? In the destination tab of the publication properties, select where you want to review the exported file. For easy reference in BOE, select User InBox, and the in the format tab select both Excel and Web Intelligence report. This way, you can complete the Roambi RBI process and also look at the underlying data report in both Excel and Web Intelligence report. I still have issues with the plugin Please contact support. Please be sure to provide the following information: - BOE version - Brief summary of what you are trying to accomplish - Time of publication event - RoambiScript Log (This can be found in the folder where you installed RoambiScript) - The publishing parameters you used - Screenshot of Enterprise Recipients - Screenshot of Profile Values 24
25
Appendix B: Resources Introduction to BOE Platform Publication General overview of BOE publication extension and how it can be used to personalize data Personalization in SAP BOE Publication A more detailed step by step guide with additional screenshots and illustrations BOE Introduction to Publishing (PDF) An in depth guide to leveraging the publishing platform in BOE Adding a Publication Extension to your Publication Basic steps on adding a BOE publication extension Understanding Publication bursting modes This is a useful article if you have specific concerns on your database performance 26
27