table of contents - sap · pdf filesap businessobjects roambi cloud cognos adapter - may 2016...

SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

1

Table of Contents

I. Overview Introduction

II. Setup Requirements

Roambi Requirements Cognos Requirements

Roambi Configuration Creating API Key Setting up RoambiScript

III. How to Use Option 1: Cognos is configured to save ALL report outputs to the file system.

Installation and Configuration Preparation Configure Cognos Report for Bursting Update roambi-integration.config Schedule the Cognos Report Log Files

Option 2: Cognos is configured to save Individual report outputs to the file system.

Installation and Configuration Preparation Configure Cognos Report for Bursting Update roambi-integration.config Schedule the Cognos Report Log Files

Appendix A: Troubleshooting and Common Issues


2

I. Overview

Introduction Cognos allows users to create reports. Reports can be scheduled to run on different time intervals and the output can be saved in content manager or sent by email to different recipients. Optionally users can burst the report to produce multiple reports based on a key. Cognos offers two methods to save report outputs to the file system. You can configure Cognos to save All report outputs to the file system, or enable users to save individual reports to a specific folder in the file system. When configuring Cognos to save the All report outputs to the file system, you can provide a batch script that will be called every time a report output file is saved to the file system. In that script we can include the logic to launch the integration with SAP BusinessObjects Roambi Cloud. With this option, the integration with Roambi Cloud is basically controlled by Cognos. When configuring Cognos to save Individual report outputs to a specific folder, the integration with Roambi Cloud is not triggered automatically by Cognos, since with this option the script is not executed after each report output, the execution must be triggered manually or using an external scheduler.


3

II. Setup

Requirements

Roambi Requirements 1. Created a Roambi View to be used as a template. 2. Administrator access to Roambi. 3. Roambi API Client Key. 4. Install and configure RoambiScript. 5. Roambi Users invited into Account.

Cognos Requirements 1. Cognos Versions: 10.1, 10.1.1, 10.2.0, 10.2.2

Roambi Configuration The SAP BusinessObjects Roambi Cloud Cognos Adapter enables users to upload file to Roambi File System or use an existing Roambi report as template to create personalized Roambi reports to your recipients. If you have not created a Roambi Report, please review our getting started material and select a Roambi View to create your first report. There are examples in this user guide as well. 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 a sample data file as a template 3. Upload to Roambi and create your Roambi report 4. 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.


4

Creating API Key

The Roambi Cloud Cognos Adapter leverages the Roambi API to facilitate the creation of Roambi reports. No programming or API knowledge is required to use the components, but you do need to register an API client. To set up an API client please follow the steps outlined in the knowledge base article How do I create a Roambi API client? Please keep the details of the API client readily available, as it will be used in the next section.

Setting up RoambiScript

1. Download RoambiScript from SAP Service Marketplace. Create a folder that can be easily referenced. In this documentation, RoambiScript is installed in C:\roambiscript folder. For more information on RoambiScript, see this KBase.

2. Run roambiscript configure in the terminal to generate a properties file.


5

java -jar roambi-api-cli.jar configure

3. After executing the above command, it will create a roambi-api.cli.properties

file.

Open Note you will be required to enter the API client details you previously created in “Creating API Key.” This will ensure that this API utility is provisioned to talk to your Roambi Enterprise organization. Additionally, please note the RoambiScript installation path (in this example it is C:\roambiscript). The components will need to reference this directory path.


6

III. How to Use There are two options to configure your Cognos to work with Roambi Cloud. It depends on how you want to configure the report export. These are:

● Save ALL report outputs to the file system. ● Save INDIVIDUAL report outputs to the file system.

Option 1: Cognos is configured to save ALL report outputs to the file system. Everytime Cognos saves a report output to the file system, it saves two files: the actual report output file (the excel file in our case) and the descriptor file which is an xml file with metadata including the report search path and the burst key.

After saving those files, Cognos automatically invokes a script that was previously configured. Cognos passes the path of the output file and the descriptor file to the script. This script contains a line to call the roambi-cognos-integration.jar with the path of both files. The roambi-cognos-integration.jar program will check if the file is used by any Roambi file and refresh it. The program uses the roambi-integration.config file. This file is a csv file that contains the mapping between cognos reports and roambi files. roambi-integration.config sample:


7

ReportSearchPath BurstKey Template DestinationFolder RoambiFileName Users Groups

/content/folder[@name='Mauricio']/report[@name='Sales Report']

Americas /Templates/Cognos Sales Report

/Roambi Files Sales Report Americas

[email protected]; [email protected]

Sales Group


Asia Pacific /Templates/Cognos Sales Report

/Roambi Files Sales Report Asia Pacific

[email protected] Sales Group

Each entry is a map between a Cognos report and the Roambi file:

● ReportSearchPath: Cognos report search path. (i.e “/content/folder[@name='Mauricio']/report[@name='Sales Report']”)

● BurstKey:

Burst key. Applies only for burst reports. (i.e “Americas”)

● Template: This is the full path to the Roambi template file in RFS. (i.e “/Templates/Sales Report”)

● DestinationFolder:

This parameter is optional. It is the folder in RFS where the Roambi file will be generated. If it is not specified, the Roambi file will be created in the “My Documents” folder of the given Roambi users. (i.e “/Roambi Files”)

● RoambiFileName: Name of the Roambi file that will be generated. (i.e “Sales Report Americas”)

● Users:

Optional. Roambi users. Those users will have the permission to open the generated Roambi file. Use semicolon to separate multiple users. i.e. “[email protected];[email protected]”.

● Groups:


8

Optional. Roambi groups. Those groups will have the permission to open the generated Roambi file. Use semicolon to separate multiple groups. i.e. “Sales Group”.

Installation and Configuration Configure Cognos to save reports to file system and run script every time a file is saved:

1. In Cognos Configuration in the Explorer tree, select Data Access > Content Manager node and set the “Save report outputs to a file system?” option to True.

2. Set CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT properties in Cognos Connection Administration:

In Cognos Connection Administration, select “Status” tab and click on “System” option located in the left panel. Then in the “Scorecard” section of the Status/System UI, select the “All servers” drop down and navigate to “Services” > “Content Manager”.


9

For the Active Content Manager Service, select the drop down and select “Set Properties”.

Select “Settings” tab and click on “Environment” > “Advanced Settings” > “Edit”.


10

Set the values for CM.OUTPUTLOCATION and CM.OUTPUTSCRIPT

CM.OUTPUTLOCATION: This is the path to the folder where the Cognos reports will be saved. CM.OUTPUTSCRIPT: This is the path to the script that runs after a report output is saved to the target directory. The full file names of the output file and descriptor are passed to the script. Edit the script you configure in the CM.OUTPUTSCRIPT property and add the following line:

java -jar C:\roambiscript\roambi-cognos-integration.jar %* >> "%2-roambi.log"

Preparation

1. Create the Cognos report. The following is a report with sales data. It is recommended that the report just contain the table or crosstab with the data you want to import in Roambi. Avoid decorations like titles, header, footers. The report will be exported to Excel and if you include decorations, Roambi may not be able to import the report correctly.


11

2. Export the report to Excel 2007 and use that Excel file to create the Roambi template. In this example the Roambi template is a Card View saved to “/Templates/Cognos Sales Report” in RFS.


12

Once the Cognos report and the corresponding Roambi template are created, the Cognos user can automate the process of refreshing one or many Roambi files from the same Cognos report.

In this example we are going to explain how to burst this Cognos report by “Region”, refresh different roambi files and set permission to different roambi users per “Region”.

Configure Cognos Report for Bursting

Edit the cognos report with Cognos Report Studio. Select “File” menu and click on “Burst Options”.


13

Check the box “Make report available for bursting”. In the “Burst Groups” section, select Query1 and use “Region” in the Label and Groups. In the “Burst Recipient” section, select Query 1 and “Region” for Data Item. In the Type field assign “Email address”. Click “OK” and save the report.

Update roambi-integration.config

The roambi-integration.config file is a csv file that contains the mapping between cognos reports and roambi files. It has to be located in C:\roambi-script folder, same folder where the roambi-cognos-integration.jar file is located. If it does not exists, create it.

Add an entry for each burst key:


14







Asia Pacific

/Templates/Cognos Sales Report


[email protected]


Southern Europe


/Roambi Files Sales Report Southern Europe

[email protected]


Northern Europe


/Roambi Files Sales Report Northern Europe

[email protected]


Central Europe


/Roambi Files Sales Report Central Europe

[email protected]

Schedule the Cognos Report

In Cognos Connection, find the Cognos report and click on the schedule icon.

Set the frequency:


15

Set the options:

Check the “Override the default values” box. In the “Formats” section, only select “Excel 2007”. Check the “Burst the report” box. In the “Delivery” section, only select “Save” box and the “Save the report” option. Click “OK” to schedule the report. Every time the report runs according to the schedule, Cognos will save the report in the folder specified in CM.OUTPUTLOCATION setting, and it will call the script specified in the CM.OUTPUTSCRIPT setting, which will call the roambi-cognos-integration.jar file and update the roambi file(s) specified in the roambi-integration.config file, making the whole process automatic.


16

Log Files For each report that Cognos saves in the CM.OUTPUTLOCATION folder, the roambi-cognos-integration.jar will create a log in the same folder with information about the processing of that report. Roambi script also has its own log file: C:\roambi-script\log\roambi.log

Option 2: Cognos is configured to save Individual report outputs to the file system. What Cognos refers to as the “Save a Copy of Report Output Outside of IBM Cognos Software” is actually the ability to save individual report outputs or burst report outputs selectively to the file system. Notes:

This option (and its configuration parameters) are entirely independent of those for the Save All Report Outputs to File System option.

It is highly recommended to read the related blogs “Overview” and “Save All Report Outputs to the File System” to understand all the options and which configuration steps work with which feature.

Everytime Cognos saves a report output to the file system, it saves two files: the actual report output file (the excel file in our case) and the descriptor file which is an xml file with metadata including the report search path and the burst key.

Once the reports are saved in the selected folder, we’ll need to launch the integration with Roambi Cloud manually or triggered by an external scheduler, like the Windows Task Scheduler..


17

In this example we’ll use PowerShell script that will invoke the roambi-congos-integration.jar file for each of the files generated by Cognos. The roambi-cognos-integration.jar program will check if the file is used by any Roambi file and refresh it. The program uses the roambi-integration.config file. This file is a csv file that contains the mapping between cognos reports and roambi files. roambi-integration.config sample:






Sales Group


Asia Pacific



[email protected] Sales Group

Each entry is a map between a Cognos report and the Roambi file:

● ReportSearchPath: Cognos report search path. (i.e “/content/folder[@name='Mauricio']/report[@name='Sales Report']”)

● BurstKey:

Burst key. Applies only for burst reports. (i.e “Americas”)

● Template: This is the full path to the Roambi template file in RFS. (i.e “/Templates/Sales Report”)

● DestinationFolder:

This parameter is optional. It is the folder in RFS where the Roambi file will be generated. If it is not specified, the Roambi file will be created in the “My Documents” folder of the given Roambi users. (i.e “/Roambi Files”)

● RoambiFileName:

Name of the Roambi file that will be generated. (i.e “Sales Report Americas”)

● Users:


18

Optional. Roambi users. Those users will have the permission to open the generated Roambi file. Use semicolon to separate multiple users. i.e. “[email protected];[email protected]”.

● Groups:

Optional. Roambi groups. Those groups will have the permission to open the generated Roambi file. Use semicolon to separate multiple groups. i.e. “Sales Group”.

Installation and Configuration

In Cognos Configuration use the Menu item Actions -> Edit Global Configuration

– > [Tab] General -> [Property] Archive Location File System Root:

Do not be confused by the wording used here. “Archive Location File System” is

NOT referring to the setting for archiving/save all report outputs to the file

system. This is the setting ONLY for the feature to save report outputs as part of

the Save options in the run with options or schedule.

The format for the file root is one of the following

On the Cognos server file://<drive>:\folder\subfolder


19

Windows UNC format – file://\\server\share\folder – as shown in the screen

capture above. Note that for Unix/Linux, this requires Windows UNC

support.

Once the root folder is set, go to Cognos Connection Administration – >

Configuration -> Dispatchers and Services -> Define File System Locations:

It is possible to specify multiple sub-folders… one is defined as shown below

(RoambiReports)

You need to specify a name as will appear in the drop down for the user to select

when specifying “save to file location” in the advanced run options and the name

of the sub-folder (which can also be a sub-sub folder) in the file system.


20

As with any other Cognos object, the permissions to use these “sub-folders” can

be controlled for Cognos users, groups and roles. Note that the permissions for

the sub-folder in the operating system will also need to be set (for who can read

or write).

Saving Report Outputs

When a user goes to run or schedule a report and the select “save report output”

and then select advanced options they will now see a save to the File system

option:


21

The options available are:

Notes:

Multiple report output types can be specified

Burst report outputs are also supported

This capability is enabled for all users. There is no mechanism to

selectively allow users to save to the file system.

In this mode, file names are constructed using the report name (or specified

filename as listed above), plus the conflict resolution options, plus the language

of the selected locale, plus the output extension.

Examples:

Individual file – Sales Report by Region-en-us.xlsx

Burst File – Sales Report by Region-en-us-Americas.xlsx

Note that this includes the burst key/label (Americas)

Download the PowerShell script that will launch the Roambi Cloud Integration or

create a file called RBIntegrationLauncher.ps1 with the following content: #

# Change the Path to point to the Folder where the Cognos reports outputs will be saved #

$ReportPath="C:\CognosOutput\RoambiReports\"

$xlsx_files = Get-ChildItem $ReportPath *.xlsx $xml_files = Get-ChildItem $ReportPath *.xml


22

$record=0

foreach ( $xlsx in $xlsx_files ) { $excel_file = $ReportPath + $xlsx.Name $xml_file = $ReportPath + $xml_files.Name[$record] $log_file = $ReportPath + $xlsx.Name + ".log" write-host "Running Integration for: " $excel_file java -jar C:\roambi-script\roambi-cognos-integration.jar $excel_file $xml_file > $log_file $record++

}

Preparation

1. Create the Cognos report. The following is a report with sales data. It is recommended that the report just contain the table or crosstab with the data you want to import in Roambi. Avoid decorations like titles, header, footers. The report will be exported to Excel and if you include decorations, Roambi may not be able to import the report correctly.

2. Export the report to Excel 2007 and use that Excel file to create the Roambi template. In this example the Roambi template is a Card View saved to “/Templates/Cognos Sales Report” in RFS.


23

Once the Cognos report and the corresponding Roambi template are created, the Cognos user can automate the process of refreshing one or many Roambi files from the same Cognos report.

In this example we are going to explain how to burst this Cognos report by “Region”, refresh different roambi files and set permission to different roambi users per “Region”.

Configure Cognos Report for Bursting

Edit the cognos report with Cognos Report Studio. Select “File” menu and click on “Burst Options”.


24

Check the box “Make report available for bursting”. In the “Burst Groups” section, select Query1 and use “Region” in the Label and Groups. In the “Burst Recipient” section, select Query 1 and “Region” for Data Item. In the Type field assign “Email address”. Click “OK” and save the report.

Update roambi-integration.config

The roambi-integration.config file is a csv file that contains the mapping between cognos reports and roambi files. It has to be located in C:\roambi-script folder, same folder where the roambi-cognos-integration.jar file is located. If it does not exists, create it.

Add an entry for each burst key:







25


Asia Pacific



[email protected]


Southern Europe


/Roambi Files Sales Report Southern Europe

[email protected]


Northern Europe


/Roambi Files Sales Report Northern Europe

[email protected]


Central Europe


/Roambi Files Sales Report Central Europe

[email protected]

Schedule the Cognos Report

In Cognos Connection, find the Cognos report and click on the schedule icon.

Set the frequency:

Set the options:


26

Check the “Override the default values” box. In the “Formats” section, only select “Excel 2007”. Check the “Burst the report” box. In the “Delivery” section, only select “Save to the file system” box Click “OK” to schedule the report. Every time the report runs according to the schedule, Cognos will save the report in the folder specified in the file system option. To start the integration with Roambi Cloud, edit the RBIntegrationLauncher.ps1 script, and change the path at the beginning of the script to reflect the path where the report outputs are stored.

# # Change the Path to point to the Folder where the Cognos reports outputs will be saved #

$ReportPath="C:\CognosOutput\RoambiReports\"

$xlsx_files = Get-ChildItem $ReportPath *.xlsx $xml_files = Get-ChildItem $ReportPath *.xml

$record=0

foreach ( $xlsx in $xlsx_files ) {

$excel_file = $ReportPath + $xlsx.Name $xml_file = $ReportPath + $xml_files.Name[$record] $log_file = $ReportPath + $xlsx.Name + ".log" write-host "Running Integration for: " $excel_file java -jar C:\roambiscript\roambi-cognos-integration.jar $excel_file $xml_file > $log_file


27

$record++

} Make sure PowerShell has the right execution policy configured. You need at least RemoteSigned to run the script. Execute the script manually by typing the name of the script: ./RBIntegrationLauncher.ps1 or add a Task in the Windows Scheduler that executes the script at the desired times.

Log Files For each report that Cognos saves in the path defined file system folder defined, the roambi-cognos-integration.jar will create a log in the same folder with information about the processing of that report. Roambi script also has its own log file: C:\roambiscript\log\roambi.log


28

Appendix A: Troubleshooting and Common Issues Where do I find RoambiScript and API Key? RoambScript: Find it in SAP Service Marketplace. Roambi API Key: Please refer to How do I create a Roambi API client? 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

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. Check that your RBI template can be accessed I still have issues with the extension Please contact support. Please be sure to provide the following information:

- Cognos Version - Brief summary of what you are trying to accomplish - RoambiScript Log (This can be found in the folder where you installed

RoambiScript) - Components and parameters used - Screenshot of report


29

Appendix B: Version History Version 1.0: May, 2015. General Release of Roambi Cloud Cognos Adapter Version 2.0: October, 2015. Minor change to clarify you can use Roambi users and Roambi groups in the Permissions column of the configuration file. Version 2.1: November, 2015. Replace Permissions column with Users and Groups in the configuration file. Version 2.2: May, 2016. Update support link and SAP Service Marketplace link.


30