Collaboration in SAP Cloud Platform Portal sites with SAP Jam [Part 2]

[former_member199536]

"Note that our public GitHub repository, providing code samples for Cloud Portal on the Neo environment, is not available anymore. If you have further questions, contact us under sapportal@sap.com."

Hi, in the first part of this post we presented the SAP Cloud Platform portal default offering for SAP Jam integration allowing portal admins to add collaboration capabilities to their portal sites.

In this second part I want to focus on building custom integrations with Jam for Portal sites, and more specifically – how to add Jam Embedded Widgets to portal sites. The step-by-step guide requires a certain amount of technical skills.

By the end of this you will have the ability to embed a Jam company feed widget together with web content and business data in your portal page:



Prerequisites

1. You have an SAP Cloud Platform Trial account. (Otherwise register here).


2. You’ve enabled the following services in your trial account: SAP Web IDE, Portal and SAP Jam


3. You have enabled the Portal plugin for SAP Web IDE as described here.


4. Your SAP Jam account has some content in it to display – otherwise create some Jam Groups, upload files, add comment etc.


5. You’ve configured the SAP Jam integration with SCP and Portal as described here.


6. You’ve deployed the SAP Jam Java Servlet to your trial account as described here.

Note:

• The Java servlet is used to generate a single-use access token allowing the embeddable widget to obtain a valid SAP Jam UI session. For more information on authentication for SAP Jam Embeddable widgets read here.


• The Servlet assumes the OAuth2SAMLBearerAssertion destination file you created in your account for the Jam integration (prerequisite #3) is named sap_jam_odata. As the integration documentation requires the destination to be named – jam – you can change the destination name as it appears in the Java webapp source code.


• To validate the servlet is deployed and working properly run the following URL in your browser: https://<Application URL>?command=single_use_tokens

The Application URL can be found in the application dashboard in your trial account



The response should look like this:



7. You’ve created an AppToAppSSO destination file in your trial account – allowing the custom SAPUI5 app youre going to develop to connect to the Jam Java Servlet you deployed to your account. For more information on how to create destination files read here. For this destination fill in the following values:

Name: jam_servlet

Authentication: AppToAppSSO

URL: The application URL as copied in prerequisite #6. For example:

https://sapjamodatahcp<your account ID>.hanatrial.ondemand.com/SAP_Jam_OData_HCP



Ok, seems like we finally have everything in place… let’s start 🙂

 

Step 1: Get to know the SAP Jam Widget Builder

1. Launch SAP Jam from your trial account. Its available under the Collaboration set of services.


2. Once SAP Jam is opened click on the cog icon to open the settings and select Admin > Integrations > Widget Builders


3. Look at the Feed Widget Builder. Notice that you can use the builder to configure various feed types (Company, Group, My Follows…) and additional properties. After every change the builder generates a JS code snippet at the bottom of the page – this is the code we will embed in our portal widget.


4. Select [Authentication Type = Single-use Token] and [Feed Type = Company Feed]


5. Copy the code and paste in a text editor.

Look at the snippet you. It looks something like this:

<script type="text/javascript" 

src="https://developer.sapjam.com/assets/feed_widget_v1.js"></script>

<script type="text/javascript">



sapjam.feedWidget.init(

"https://developer.sapjam.com/c/i034051trial.hanatrial.ondemand.com.cubetree.biz/widget/v1/feed", "single_use_token");



var w = sapjam.feedWidget.create("myDiv", {type: "company", avatar: false, is_sso: true, post_mode: "inline", reply_mode: "inline"});



</script>

Note the following with regards to the snippet:

• The widget uses 2 URLs:

1. https://developer.sapjam.com/assets/feed_widget_v1.js
   Used to load the JS code required for the feed widget


2. "https://developer.sapjam.com/c/i034051trial.hanatrial.ondemand.com.cubetree.biz/widget/v1/feed”, Is the REST endpoint of your Jam account feed

From these URLs derive the following variable values for the widget configuration as exampled here:

1. 
   

   JAM Host: https://developer.sapjam.com

   
   


2. 
   

   Jam Account Domain: i034051trial.hanatrial.ondemand.com.cubetree.biz

   
   

• When creating the feed widget, we need to provide the ID of a div element available in the DOM of our applications view ["myDiv”] – this is where the Jam feed will be rendered.


• The widget creation accepts a map of parameters indicating the feed type, widget appearance and the access token we retrieved from Jam through the Java servlet.

 

Step 2: Get the Sample Code

The source code for the Jam Embedded Widget is available under this folder.

To get started with adding the widget to your portal site:

• Download the Cloud Portal  sample GitHub repository,


• Upload the Jam Embedded Widget to your SAP Web IDE


• Deploy the app to your SAP Cloud Platform account

Follow the steps described here under Download and Installation

 

Step 3: Create a Portal site

1. Open the SCP Portal service from your trial account list of Services (its under the User Experience category).


2. From your Portal Admin Space select Site Directory from the left side menu


3. Click on the + to create a new site instance


4. In the Create Site dialog enter your Site Name, select SAP from the list of Template Sources, select the Starter Site template and click Create.
   The new site is opened in the Site Designer tool. Now we can start adding content to our site

Step 4: Add the Jam Embedded Widget

1. Click on the main section area. This will expose the section’s action menu


2. Click on the + to open the Widget Catalog


3. In the Widget Catalog search for ‘Jam’. Notice that the 3 widgets provided by SAP are available and can be added to your portal site.


4. Select the Jam Embedded Widget you just created.
   


5. Notice that the widget is added to the page.

Step 5: Configure the Jam Embedded Widget

For the widget to connect to your Jam host and domain and retrieve the desired feed- we need to configure the widget settings.

1. Click on the widget to expose the widget settings icon


2. Click on the Widget Settings icon to open the configuration dialog.
   


3. In the widget settings enter the Jam Host and Jam Account Domain values you derived from the jam widget code snippet
   


4. Select the Feed Type - the widget can display the whole feed on a Company lever or the feed of a specific Jam group available on your Jam account.


5. You can configure the widget height under Visual Settings


6. Click Save.


7. Notice that the widget is rendering the selected feed

1. Now you can go ahead and perform additional changes:
   
   
   
   1. Add Web Content widgets to the same section
   
   
   2. Configure section settings, layout and appearance by clicking on the button in the section action menu.
   
   
   3. Add additional pages, with different layouts.
   
   
   4. Finally – publish the latest version of the site by clicking on the publish icon in the top menu
   
   
   
   


2. The site that you designer is opened in a new browser tab

 

Code Sample Notes

The flow implemented in the portal widget source code is integrates the jam code snippet in the following flow-

1:  Sends an ajax call to the Jam Java Servlet we deployed to our account and get the access token to a Jam UI user session

var URL = this.calculateURL(JAM_SERVLET) + "?command=single_use_tokens";

$.ajax({

	url: URL,

	method: "GET",

	success: function(result, status, xhr) {

		var xmlDoc = $.parseXML(result);

		var tokenNode = $(xmlDoc).find("single_use_token");

		if (tokenNode) {

			var token = tokenNode.attr("id");

			oDeferred.resolve(token);

		} else {

			oDeferred.reject(result);

		}

	}.bind(this),

	error: function(error) {

		oDeferred.reject(error);

	}

});

2: Bootstrap the SAP Jam Feed Widget JavaScript

3: Create the feed widget in a designated div element available in our DOM

this.boostrapJam(settings.jamHost).then(function(res) {

	if (sapjam && sapjam.feedWidget) {

		var containerID = this.getView().createId("jamContainer");

		$("#" + containerID).empty();

		var URL = settings.jamHost + "/c/"+ settings.accountDomain + JAM_ACCOUNT_FEED_SUFIX;

		sapjam.feedWidget.init(URL, "single_use_token");

		var w = sapjam.feedWidget.create(containerID, jamWidgetOptions);

	} else {

		MessageToast.show("Failed to bootstrap JAM feed.");

	}

}

4. The widget makes use of 2 destination files which are declared in the application's neo-app.json file:

{

"path": "/destinations/jam_servlet",

"target": {

      "type": "destination",

      "name": "jam_servlet"

  }

},

 {

 "path": "/destinations/jam",

 "target": {

       "type": "destination",

        "name": "sap_jam_odata"

      }

}