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

1 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016 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.

2 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

3 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

4 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

5 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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:

6 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

ReportSearchPath BurstKey Template DestinationFolder RoambiFileName Users Groups

/content/folder[@na Americas /Templates/Cognos /Roambi Files Sales Report [email protected]; Sales me='Mauricio']/report Sales Report Americas [email protected] Group [@name='Sales Report']

/content/folder[@na Asia Pacific /Templates/Cognos /Roambi Files Sales Report Asia [email protected] Sales me='Mauricio']/report Sales Report Pacific Group [@name='Sales Report']

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:

7 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

8 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

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

9 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

10 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

11 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

12 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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:

13 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

ReportSearchPath BurstKey Template DestinationFolder RoambiFileName Users Groups

/content/folder[@na Americas /Templates/Cognos /Roambi Files Sales Report [email protected]; me='Mauricio']/repo Sales Report Americas [email protected] rt[@name='Sales Report']

/content/folder[@na Asia /Templates/Cognos /Roambi Files Sales Report Asia [email protected] me='Mauricio']/repo Pacific Sales Report Pacific rt[@name='Sales Report']

/content/folder[@na Southern /Templates/Cognos /Roambi Files Sales Report [email protected] me='Mauricio']/repo Europe Sales Report Southern Europe rt[@name='Sales Report']

/content/folder[@na Northern /Templates/Cognos /Roambi Files Sales Report [email protected] me='Mauricio']/repo Europe Sales Report Northern Europe rt[@name='Sales Report']

/content/folder[@na Central /Templates/Cognos /Roambi Files Sales Report [email protected] me='Mauricio']/repo Europe Sales Report Central Europe rt[@name='Sales Report']

Schedule the Cognos Report

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

Set the frequency:

14 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

15 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

16 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

roambi-integration.config sample:

ReportSearchPath BurstKey Template DestinationFolder RoambiFileName Users Groups

/content/folder[@name= Americas /Templates/Cognos /Roambi Files Sales Report [email protected]; Sales Group 'Mauricio']/report[@nam Sales Report Americas [email protected] e='Sales Report']

/content/folder[@name= Asia /Templates/Cognos /Roambi Files Sales Report Asia [email protected] Sales Group 'Mauricio']/report[@nam Pacific Sales Report Pacific e='Sales Report']

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”)

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

● Users:

17 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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://:\folder\subfolder

18 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

19 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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:

20 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

21 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

$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

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.

22 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

23 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

Update roambi-integration.config

Add an entry for each burst key:

ReportSearchPath BurstKey Template DestinationFolder RoambiFileName Users Groups

/content/folder[@name Americas /Templates/Cognos /Roambi Files Sales Report [email protected]; ='Mauricio']/report[@n Sales Report Americas [email protected] ame='Sales Report']

24 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

/content/folder[@name Asia /Templates/Cognos /Roambi Files Sales Report Asia [email protected] ='Mauricio']/report[@n Pacific Sales Report Pacific ame='Sales Report']

/content/folder[@name Southern /Templates/Cognos /Roambi Files Sales Report [email protected] ='Mauricio']/report[@n Europe Sales Report Southern Europe ame='Sales Report']

/content/folder[@name Northern /Templates/Cognos /Roambi Files Sales Report [email protected] ='Mauricio']/report[@n Europe Sales Report Northern Europe ame='Sales Report']

/content/folder[@name Central /Templates/Cognos /Roambi Files Sales Report [email protected] ='Mauricio']/report[@n Europe Sales Report Central Europe ame='Sales Report']

Schedule the Cognos Report

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

Set the frequency:

Set the options:

25 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

26 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

$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

27 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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

28 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

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.

29 SAP BusinessObjects Roambi Cloud Cognos Adapter - May 2016

Table of Contents