Embed an SAP Analytics Cloud Story in a Simple Web App

After performing the preparatory steps, you can now create the app.

1. Download the sample code from the following Git repository and place it into a directory of your choice.

   https://github.com/SAP-samples/analytics-cloud-api-embed-story

   The code represents a simple example of how to embed an SAP Analytics Cloud story into a web app.

   The code consists of three files: index.html and LogResponse.html represent the client code, and server.js contains the Node.js server code.

   • index.html is the start page of the app. It provides a link to log in to SAP Analytics Cloud.

   • LogResponse.html hosts the <iframe> where the SAP Analytics Cloud story gets rendered.

   • server.js implements a server with Node.js, leveraging the Express framework. The server listens for http requests and sends responses. This makes it possible to use a very simple, generic URL http://localhost:<port> to open the web app in the browser.

2. Add additional Node.js packages. The server.js code uses some Node.js modules that need to be installed on your machine.

   • Open a command-line interface (CLI, e.g. Command Prompt on Windows), navigate to the root folder of the app (that is, the folder where you have placed the three downloaded files) and initialize the Node Package Manager (npm) by running the following command:

     npm init -y
     

     This creates a new file package.json in your root folder. package.json documents all dependencies of the node modules you will be using.

   • Now install the Node.js modules necessary for the application into the root folder of the project. Again, open the CLI and execute the following commands from the root folder of your project.

     npm install express@4.17.1 --save
     

     This installs Express, which is a Node.js web application framework.

     npm install express-session@1.16.2 --save
     

     This installs the session middleware of the express framework.

     npm install connect-timeout@1.9.0 --save
     

     The app uses this module to time out requests.

     npm install simple-oauth2@2.2.1 --save
     

     This installs the Node.js client library for OAuth2.

     The modules are installed in a folder called node_modules which is generated inside the root folder. Note that package.json is updated by all dependent modules you have added. Additionally, a new file called package-lock.json is generated into the root folder.

3. Open the file LogResponse.html with an editor of your choice (for example, Notepad on Windows, to name a very rudimentary editor). Edit the value of the variable url and assign the URL of the SAP Analytics Cloud story that you want to embed in the app. The URL has to follow the following syntax:

   https://<TENANT>/sap/fpa/ui/tenants/<TENANT_ID>/bo/story/<STORY_ID>

   Replace <TENANT> with the public SAP Analytics Cloud URL for your tenant, <TENANT_ID> with your tenant ID in lowercase letters, and <STORY_ID> with the ID of the story you want to open.

   If you want to find more please check this documentation: URL syntax.

   Tip: You can use the sample story Sample – Revenue Analysis which is available on all SAP Analytics Cloud systems. You can find it on your SAP Analytics Cloud system under Main Menu > Browse > Files > Samples.

4. Open the file server.js with your editor.

   • Edit the value of the constant PORT: use the port you have specified for the definition of the Redirect URI of your OAuth client.

   • Edit the value of the session secret, which is used to sign the session cookie. You can use any string value. For the purpose of this tutorial you can for example take the value of the sample code. Of course, in a productive scenario you should use a strong secret.

   • Edit the value of the variable credentials:

     • for the client object get the values for the id and secret attributes from the OAuth client you have created on the SAP Analytics Cloud system administration page in step 1 ( Main Menu > System > Administration > App Integration > Edit OAuth Client). Replace the placeholders in the sample code.

     • for the auth object get the values from the OAuth Clients chapter of the same SAP Analytics Cloud system administration page and replace the placeholders in the sample code. Please note that the values of attributes authorizePath and tokenPath differ depending on whether your SAP Analytics Cloud system runs on a Neo or on a Cloud Foundry environment.

       authorizePath

       /oauth2/api/v1/authorize	Neo
       /oauth/authorize	Cloud Foundry

       tokenPath

       /oauth2/api/v1/token	Neo
       /oauth/token	Cloud Foundry

   If you are using the SAP Analytics Cloud, embedded edition, please refer to this documentation.

Now you can start the application.

1. Start the server with your CLI tool from the root directory of our application. Start the server with the command node server.js.

   

2. Open a browser window and open URL http://localhost:<port>. <port> is the port you have specified in the file server.js. The start page of the app is displayed.

   

3. Click on link Log In to SAP Analytics Cloud. A request to the path /authorizationcode is made. You can find the path in the file server.js.

   app.use('/authorizationcode', function(req, res){
       console.log("inside authorizationcode");
   
       var authorizationUri = oauth2.authorizationCode.authorizeURL({
   	  	redirect_uri: redirecturi
   
   	});
   
   	console.log("authorizationUri: " + authorizationUri);
   	res.redirect(authorizationUri);
   });
   

   Now the app starts the authorization workflow. The first step in this workflow is a request to the SAP Analytics Cloud authorization server asking for permission to access your protected data with your SAP Analytics Cloud user. So, the app redirects to the authorization URL and the app logs the authorizationUri into the CLI.

   However, when you start the app for the first time with a browser (or any time with a new incognito browser window), a redirect to the login screen of the identity provider assigned to the SAP Analytics Cloud system is performed first. This is necessary because SAP Analytics Cloud needs to authenticate the user and their permissions.

   

4. The user enters their credentials (e-mail and password) and presses the button to log in to SAP Analytics Cloud. The SAP Analytics Cloud authorization server identifies the user and creates a session cookie on your computer (domain of the authorization URL). If you log in later to SAP Analytics Cloud with the same browser, this cookie is read and no new user authentication is required.

   Now that the SAP Analytics Cloud user is identified, the SAP Analytics Cloud authorization server displays a screen to authorize the app or, more precisely, to authorize the OAuth client to access the user’s SAP Analytics Cloud data. The user confirms this by pressing the button Authorize.

   Note that this screen is displayed only for the Neo environment.

   

5. SAP Analytics Cloud creates the authorization code (AC) and sends a response to the redirect URL http://localhost:<port>/callback. Again, a handler function is triggered by this request to the /callback path.

   app.use('/callback', function(req, res){
   console.log("inside callback");
   
   // the authorization code is sent from SAC to the /callback page.
   // the code is part of the URL parameters
   var code = req.query.code;
   console.log("Authorization Code: " + code);
   
   var tokenConfig = {
     	code: code,
     	redirect_uri: redirecturi
   };
   
   // get the access token:
   oauth2.authorizationCode.getToken(tokenConfig)
   	.then((result) => {
   
   	  	const token = oauth2.accessToken.create(result);
   	  	console.log("Access Token: " + token.token.access_token);
   
   	req.session["tokens"] = token;
   	res.redirect("logonresponse");
   	})
   	.catch((error) => {
   	  	console.log('Access Token Error', error.message);
   });
   });
   

   With the AC the application now can request the authorization token (AT). It sends AC together with OAuth client ID and the secret to the SAP Analytics Cloud authorization server. The server validates the user’s AC, creates the AT, and sends it back to the redirect URL of the app. The app stores the AT in the current session. Finally, the app redirects to the page localhost:<port>/logonresponse which renders LogResponse.html. Now the authentication workflow is complete.

   In case you have troubles retrieving the access token, please double check the OAuth Client ID and Secret are set correctly in server.js.

6. Page localhost:<port>/logonresponse hosts the <iframe> in which the SAP Analytics Cloud story will be rendered. The user clicks on the Display Story button.

   

   This triggers a request that reads the AT from the session.

   The AT is used in a second request to finally retrieve the SAP Analytics Cloud story data.

   // 1. step: get the access token from session via page /getToken
   $.ajax({
     type: 'GET',
     data: JSON.stringify(data),
     contentType: 'application/json',
     url: '/getToken',
     success: function (data) {
       console.log('success');
       console.log(JSON.stringify(data));
   
       var token_details = JSON.parse(data);
   
       var postheaders = {
         'Authorization': 'Bearer ' + token_details.access_token,
       };
   
       // 2. step: get the SAC story
       $.ajax({
         type: 'GET',
         url: URL,
         contentType: 'application/json',
         headers: postheaders,
         xhrFields: {
           withCredentials: true   //required if url is cross-domain
         },
         success: function (data, status, settings) {
           console.log(settings.getResponseHeader("X-CSRF-Token"));
           console.log(JSON.stringify(data));
   
           $("iframe").attr("src", URL);
         },
   
         error: function (xhr, ajaxOptions, thrownError) {
           alert(xhr.status);
           alert(thrownError);
         }
       });
     }
   });
   

   Your story gets rendered inside the iframe.