Skip to Content

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.

Step 2: Create a Custom app in SAP Web IDE

Now we want create a Portal widget that will render the JAM Embeddable snippet code. We will use the SAP Web IDE to develop this widget.

  1. Open the SAP Web IDE from your trial account (its under the DevOps category)
  2. Create a new project by right clicking on the Workspace root folder > New > Project From Template
  3. Select the SAPUI5 Application template and click Next
  4. Give the project a name – jamwidgetbuilder and click Next
    [Note: please stick with the project and view names as the source code provided here relies on these IDs]
  5. Select an XML view type , give the view a name – WidgetBuilder, and click Finish to generate the application source code project.
  6. A new (empty) SAPUI5 project is generated in your SAP web IDE workspace.

Note: the resources that you will need to edit in the next section are marked with a green rectangle

Step 3: Develop the app

Now we want add the custom code to render the Jam Embeddable content. Look at the snippet you copied from the Jam Widget Builder earlier. 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
  • 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.

Based on the snippet above – the flow that we want to implement in our application is:

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

2: Bootstrap the SAP Jam Feed Widget JavaScript

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

Lets start adding our custom code:

  1. Open the applications descriptor file [ jamwidgetbuilder/neo-app.json]:
  2. Add a new route definition referencing the destination file you create earlier in order to perform the ajax call to the Jam Java Servlet:
{
"path": "/destinations/jam_servlet",
"target": {
"type": "destination",
"name": "jam_servlet"
},
"description": "jam_servlet"
}

Click Save. The descriptor file should now look like this:

  1. Open the applications view file [ jamwidgetbuilder/webapp/view/view.xml
    <mvc:View controllerName="jamwidgetbuilder.controller.WidgetBuilder" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:mvc="sap.ui.core.mvc" displayBlock="true" xmlns="sap.m">
      <VBox direction="Column">
          <html:div id="jamContainer" style="height:800px"></html:div>
      </VBox>
    </mvc:View>
  2. Replace the existing code with the code below and save your changes:Note: the code creates the div element in the applications view in which the Jam feed will be rendered. The div ID [“jamContainer”] will be passed to the Jam Builder upon its instantiation.
  3. Open the applications controller file [jamwidgetbuilder/webapp/controller/controller.js]
  4. Replace the existing code with the code below and save your changes:

 

sap.ui.define([
"sap/ui/core/mvc/Controller",
"sap/m/MessageToast"
], function(Controller, MessageToast) {
"use strict";

return Controller.extend("jamwidgetbuilder.controller.WidgetBuilder", {

JAM_FEED_BOOTSTRAP_URL: "https://developer.sapjam.com/assets/feed_widget_v1.js",
JAM_ACCOUNT_FEED_ENDPOINT: "https://developer.sapjam.com/c/i034051trial.hanatrial.ondemand.com.cubetree.biz/widget/v1/feed",
JAM_SERVLET: "/destinations/jam_servlet",

onAfterRendering: function(){
   if(typeof(sapjam) !== "undefined"){
      return;
   }else{
      this.initJamWidget();
   }
},

initJamWidget: function(){

   this.getJamAccessToken().then(function(token){

      var jamWidgetOptions = {
         type: "company",
         avatar: true,
         is_sso: true,
         live_update: true,
         post_mode: "inline",
         reply_mode: "inline",
         single_use_token: token
      };

      this.boostrapJam().then(function(res){
      if(sapjam && sapjam.feedWidget){
         var containerID = this.getView().createId("jamContainer");
         $("#"+containerID).empty();
         var url = this.JAM_ACCOUNT_FEED_ENDPOINT;
         sapjam.feedWidget.init(url, "single_use_token");
         var w = sapjam.feedWidget.create( containerID, jamWidgetOptions);
      }else{
         MessageToast.show("Failed to bootstrap JAM feed.");
      }
    }.bind(this)).fail(function(error){
     MessageToast.show("Failed to bootstrap JAM feed.");
    });
   }.bind(this)).fail(function(error){
      MessageToast.show("Failed to get Jam access token.");
  }.bind(this));
},

getJamAccessToken: function(){
   var oDeferred = $.Deferred();
   var URL = this.calculateURL(this.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);
    }
  });
  return oDeferred;
},

calculateURL: function(sPath) {
   if (sap.ushell.Container) {
     return sap.ushell.Container.getService("URLHelper").createComponentURI(this.getOwnerComponent().getId(), sPath);
  }else{
    return sPath;
   }
},

boostrapJam: function(){
var oDeferred = $.Deferred();
$.ajax({
url:  this.JAM_FEED_BOOTSTRAP_URL,
dataType: "script",
async: false,
success: function(result, status, xhr){
oDeferred.resolve(result);
}.bind(this),
error: function(error){
oDeferred.reject(error);
}
});
return oDeferred;
}

});
});

Step 4: Convert the app to a Portal widget

In order to run the SAPUI5 application as a widget in an SCP Portal site we need to convert it to a portal component

  1. Right click on the jamwidgetbuilder root folder and select Convert to Portal service component
  2. In the popup select the Component.js file, enter the Widget Name , check the checkbox at the bottom left and click OK.

 

Step 5: Deploy the app

Now the app is ready to be deployed to the SAP Cloud Platform and made available for Portal Admins to add to their portal sites.

  1. Right click on the jamwidgetbuilder root folder and select Deploy > Deploy to SAP Cloud Platform
  2. In the popup verify that youre deploying a new app with the same Application Name used for the Project Name and click Deploy

Step 6: Create a Portal site and add the widget

In this step we want to create a portal site, add the new Jam Embedded Feed widget to it and make it available to our end users.

  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
  5. Click on the main section area. This will expose the section’s action menu
  6. Click on the + to open the Widget Catalog
  7. 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.
  8. Select the Jam Embedded Widget you just created.
  9. Notice that the widget is added to the section – rendering the Company Feed available in your Jam account
  10. 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

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

 

Further Steps: Try this on your own

The Jam Widget Builder accepts various parameters for selecting the widget type (feed, recommendations, share), feed type, appearance, and others. For the sake of simplicity, we hardcoded many of these parameter values in the controller.js code.

To make our portal widget more generic and robust we can expose these parameters in the Portal Admin UI and have a portal admin configure them – this way we can reuse this one portal widget to display multiple types of Jam Embeddable snippets. This can be achieved by using the Portal’s Widget Settings API for more information click here.

To see an example of how to use the widget settings API take a look at the this login sample widget which is part of the Portal open source accelerator and template GitHub repository.

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply