What administrators need to know about SAP BI 4.1. and SAP Jam integration

New to SAP BI 4.1 is the integration with SAP Jam. The integration allows to bring business context to reports and dashboards, while providing collaboration that is supported by data which exists inside SAP BusinessObjects Enterprise.

In this post I like to highlight some of the things administrators need to know about the integration as well as describe how to set up the integration between SAP BI 4.1 and SAP Jam. For a feature overview please see Make better decisions by combining BI with social collaboration

A prerequisite for the integration is that each user must be registered in SAP Jam with a unique email address that corresponds to the user’s Enterprise email address stored with the user object. The email addresses will be mapped between BI platform and SAP Jam. If the email address on the BI platform does not match to an email address on your SAP Jam organization then the user will see the following error message in BI launch pad:
“SAML authentication failed. Detail: Could not find unique user with email Jane@myCompany.com in company ‘MyCompany’.”

Note, that Enterprise users can only change their email address on a BI platform account if the “Edit User Attribute Right” was specifically granted to them; it is denied out of the box. This change was done in order to prevent users to change their email address to impersonate another Jam user. In most customers cases this should not be a problem as email addresses are often imported from an external source such as LDAP.

Additional two more security rights were introduced in BI 4.1 to allow fine grained control about who is able to view and post comments on a particular report. These rights can be set on a folder or document level and are inherited in the same way as other security rights.

• Comment on documents right, determining on whether a user is allowed to comment on documents and instances
• View comments on documents right, , determining on whether a user is allowed to view comments on documents and instances that

Now let’s look into the steps required to set up the integration. Before you begin the set up you need to ensure that you have administrative rights on the BI platform as well as administrative rights to your SAP Jam organization.

1. Enable Jam Collaboration in Central Management Console (CMC)
   1. Go to the Application page in CMC
   2. Right click on Collaboration
   3. Choose the Properties menu
      
   4. Check the “Enable Collaboration” checkbox
   5. Fill out the following information
      • Connection URL: This is the URL of your SAP Jam instance
      • Unique Identity Provider ID: This value will be associated with the certificate used to configure integration on the collaboration application’s administration console. It should be a unique value, for example something like <CompanyName>_<SystemID>_<Client>
   6. Press the Generate button under the Identity Provider Base64 Certificate. This will generate a certificate in the Identity Provider Base64 Certificate field.
   7. Copy the certificate in Identity Provider Base64 Certificate field in order to generate an OAuth Consumer Key from your SAP Jam organization.
      
   8. Keep page open
2. Register a new SAML trusted IDP for SAP Jam
   1. Log on to the Jam site and Navigate to the Administration page
      
   2. On the left site, select SAML Trusted IDPs
   3. Click on Register your identity provider
      
   4. Fill out the following information
      • IDP ID: Fill in the same value as in the CMC Unique Identity Provider ID field
      • Allowed Assertion Scope: Set to Users in my Company
      • X509 Certificate (Base64): Paste in the Identity Provider Base64 Certificate value you copied from the CMC
        
   5. Press Save
   6. Press Register
3. Create an OAuth client for SAP Jam
   1. On the left site of the Jam UI, select OAuth Clients
   2. At the bottom of the page. Click Add OAuth Client
   3. Fill out the following information
      1. Name: Fill in the same value as in the CMC Unique Identity Provider ID field
      2. Integration URL:  A link to find out more about this application
      3. X509 Certificate (Base64): Paste in the Identity Provider Base64 Certificate value you copied from the CMC
         
   4. Press Save
   5. In the list of OAuth find the newly created OAuth and click on View
   6. Copy the Key value
      
4. Enter OAuth key in Central Management Console (CMC)
   1. Go back to your Collaboration page in CMC
   2. Paste the OAuth key from SAP Jam into the OAuth Consumer Key field
5. Set up the connection using proxy
   1. Provide information about the proxy host in the HTTP Proxy Host and Port boxes.

In addition to the steps above, it needs to be ensured that BI platform has a valid certificate from an authorized CA in order to successfully connect to SAP Jam as SAP Jam in a secured site and BI platform needs to retrieve the secured content. If you do not have the certificate imported, you will see the following error when trying to use any of the collaboration features.
“This error occurred: A problem occurred while connecting to SAP Jam servers. Check your connection settings, or contact your system administrator.”

Below are the steps to export and import the certificate into the BI platform.

1. Export certificate from browser (Internet Explorer, other browsers work similar)
   1. Open SAP Jam website in your browser
   2. At the top of the browser, click on the “Lock” symbol to open the security report
      
   3. Click on “View Certificatesd.
   4. Go to the Details tab
   5. Click on “Copy to File”
   6. Follow the steps in the wizard to save the .cer file
2. Import the certificate to the keystore (for default tomcat; steps may vary on different web application servers)
   1. Copy the .cer file to your BOE machine
   2. Go to <InstallDir> \SAP BusinessObjects Enterprise XI 4.0\win64_x64\sapjvm\jre\bin
   3. In the command line run
      “keytool -list -keystore ..\lib\security\cacerts”
      • See that you have x entries in keystore
   4. In the command line run
      “keytool -import -alias <alias> -keystore ..\lib\security\cacerts -file <your .cer file location>”
   5. Repeat step c to confirm you have x+1 entries.
3. Restart Tomcat

You should now be able to log on to BI launch pad and start collaborating.