Skip to Content

Synopsis: In this series of Blogs, I’ll explore how the Web Intelligence RESTful Raylight Web Services allow users to automate and simplify the management, modification, creation and updates to a batch of Web Intelligence documents.  This series will be of interest to Web Intelligence administrators, designers, consultants and power users, to save time and effort and get the most out of your investment in Web Intelligence.

Previous Entry http://scn.sap.com/community/restful-sdk/blog/2013/09/06/scripting-web-intelligence-the-restful-raylight-web-services–working-it

The Tech

As mentioned in my previous blog entries, the Web Intelligence RESTful Raylight Web Services is quite easy to learn and use to manage and manipulate Web Intelligence documents.

The nature of the RESTful API makes learning it a snap – it emphasizes a hands-on approach, starting small and quickly extending your knowledge to build up your expertise.

You should first become a bit familiar with three technologies:  REST, XML and JSON.  I won’t go into too much detail here, there’s plenty of resources out on the Web that ggoes into great detail on each.

REST

The REpresentational State Transfer architecture is based on server-client HTTP communication – the communication protocol of the Web.  Objects are uniquely identified by an Uniform Resource Identifier (URI), and requests are made using the HTTP methods GET, POST, PUT and DELETE.  Each method represents a change in state for the resource: you GET the resource, you POST changes to the resource, you PUT a new resource, and you DELETE the resource.

Additional information is pass with the method via HTTP headers, parameters and body. 

For Raylight, the “server” component is the BusinessObjects Platform RESTful Web Service provider that is deployed on the Web Application Container Server (WACS).  The client is the programming language you’re using to make the RESTful calls.

XML

When you request information concerning a Web Intelligence document, some of the info are returned in XML form.  The eXtensible Markup Language pretty much the standard when it comes to representing a document in a programming-language-neutral format, and WebI is no different – structure of WebI reports or data providers are returned, manipulated and updated using XML.

The good thing about XML is that pretty much all modern programming languages have libraries to parse and manipulate XML structures, making the job much easier.

JSON

For  most Raylight method calls, you can specify whether the request or return bodies are sent or returned in XML or JSON form, via specifying the Content-Type or Accept headers as either application/xml or application/json.   Which one should you choose?

I personally prefer the Javascript Object Notation – it’s easier to read, use and manipulate than XML.  A simple example, here’s the logon credentials in XML format:

<attrs xmlns="http://www.sap.com/rws/bip">
  <attr name="userName" type="string">Administrator</attr>
  <attr name="password" type="string">Password1</attr>
  <attr name="auth" type="string" possibilities="secEnterprise,secLDAP,secWinAD,secSAPR3">secEnterprise</attr>
</attrs>
 
and here’s it in JSON:

{
    "userName": "Administrator",
    "password": "Password1",
    "auth": "secEnterprise"
}

The simplicitly of JSON is part of its design – it was first developed as a means for JavaScript to serialize information across HTTP (although it still retains JavaScript in its name, JSON isn’t JavaScript specific).  

When it comes to representing the structure of a WebI document, XML is preferred, but when it comes to sending request information, JSON is much easier to work with.

RESTful Client

When working with REST, you’re making a series of HTTP requests, where you construct the body the request as either JSON or XML.  This encourages an exploratory, hands-on way of learing Raylight.   Indeed, the first time I used Raylight, I didn’t even use a scripting language, I used  a RESTful Client.

What’s a RESTful Client?  It’s a app that allows you to construct, send and receive HTTP method requests.  There’s plenty of free, well-made and easy-to-use Clients out there.  Many are available as web browser plugins, so that you can use a familiar web browser to send/receive HTTP.  Popular ones are REST Client for Firefox, and Advanced REST Client or POSTMAN for Chrome. 

I use POSTMAN (http://www.getpostman.com), and this is what it looks like:

postman.JPGPOSTMAN Chrome plug-in RESTful Client

POSTMAN has features common with other RESTful clients, the ability to construct HTTP method calls, specifying HTTP headers, defining HTTP body in many different formants including XML and JSON, ability to save a request for later re-use, and the ability to define environment variables, such that common values need not be retyped.

How I learned was to crack open the Raylight documentatoin (http://help.sap.com/businessobject/product_guides/sbo41/en/sbo41_webi_restful_ws_en.pdf), start up POSTMAN, and follow along the doc starting from the “Logon & Logoff to the BI platform” section on down, creating the needed HTTP URI, headers and JSON or XML bodies in POSTMAN.

I create a Logon request.  Try that out.  Understand the structure of the return.  Great.  I save the logon token in a POSTMAN environment variable, so that I can send it in the HTTP header X-SAP-LogonToken on later request. 

Then I start building further requests.  Requests to get documents list, document detail, export a document, etc.   I save each HTTP request I built so I can re-use later.  Soon, I have a nice collection of HTTP requests saved up, that I can call as needed, and string together fairly complex interactions.    I send the logon request.  I capture the logon token.  I use that to send a documents list.  I pick a documentId and send a document details request.  Use that to then send a document reports list request, then a request for a specific report specification, that represents the structure of the report in XML.  I edit the XML and send it with a report update request.  Then send a save document request.   Send an unload document request then a logoff request.   By stringing together the various HTTP requests I’ve built in POSTMAN, I’ve just completed a workflow for WebI document editing.  Without writing one single line of code

With this, I’ve pretty much built up a troubleshooting tool – if I ever get unexpected behavior when programming against Raylight, I can always fire up POSTMAN, copy over the Enterprise Session logon token, then take over the troubleshooting of the workflow using POSTMAN rather than code.

Summary

A RESTful API is just a sequence of HTTP requests, and you don’t necessarily need a scripting language to call HTTP.  You can use what’s known as RESTful Clients, that allows you to do HTTP without writing one line of code. 

By using such clients, you can quickly learn the correct ways to make the HTTP calls, and understand any returned data in XML or JSON format. 

It would help guide you in implementing any workflow with a scripting language, and provide an easy-to-use troubleshooting tool if you ever encounter issues.

Have fun!

Next Entry: http://scn.sap.com/community/restful-sdk/blog/2013/09/08/scripting-web-intelligence-the-restful-raylight-web-services–logonlogoff-loadunload

To report this post you need to login first.

1 Comment

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

Leave a Reply