Have you ever wondered what would happen if you took software used for business processing and somehow combined it with software used for 3D games?  Something like this:

/wp-content/uploads/2014/05/equation590_463470.png

Well wonder no longer.  This article describes how to fit a 3D game front-end on top of the SHINE (SAP HANA Interactive Education) demo content available in your SAP HANA system.  The 3D game client runs on your Mac or PC and connects to your HANA server.  The client reads Purchase Order (PO) information from the HANA system and creates PO “creatures” in the game that you can then hunt, analyse and shoot to approve or reject them in the HANA system.  There is also a reporting element, where 3D bar charts can be climbed on to give you a different perspective on your data – OLTP (of sorts) and OLAP in a single 3D world.

Have you ever wanted to actually shoot your data?  Well now you can 🙂 .  Details on how to install and run the client yourself, along with its source code are given later.

This video gives you a better idea of how it plays out.  This shows a Rev72 system having POs approved and rejected and some bar charts analysed, occasionally showing the SHINE Web interface for comparison:

The cardboard boxes are the POs, with images of their contents from the Rev72 system.  Here are some screenshots:

devscr po rejected 2.png

A PO is Rejected

devscr po approval.png

A PO is Approved

devscr charts.png

A Bar Chart

As you can see, if you reject a PO in the game it explodes, whilst approved POs zoom upwards to their (religion-neutral) “PO Heaven”.  These changes are reflected in HANA before the graphical effects happen in the game.  If you stand on the switches near the bar charts you control what the charts display, and these are showing the same data as you see in the SHINE web reports.

You may well ask “why on earth would I want to connect a 3D front-end to HANA?”  That is a very valid question, and one I’ve asked myself more than once.  Think of it as a Proof of Concept showing what sort of things are possible with a 3D interface over HANA.  It is arguably a form of “gamification“, and this article is the “Making of” companion to another article posted over on the SCN gamification area which looks more at the gameplay aspects (such as they are) and how the PoC could be developed further.  It is interesting to see that a company that make 3D Virtual Reality goggles, called Oculus Rift. were recently bought by Facebook, so 3D may be becoming more mainstream in future.

You can install the client on your PC or Mac and connect to any HANA server that has the SHINE content installed (it is there by default now if you are on a recent revision).  There is no backend install required on the HANA system, you just need the local client.  A big thanks to Aron MacDonald for his input to this work, helping with testing and providing valuable feedback and ideas.  To try out the 3D Game Client for yourself follow the next section:

1) How to Install and Play HANA SHINE 3D

Backend Prerequisites

If you don’t have access to one already, you can get your own HANA system. The following versions are supported: Rev 60 / SP6, Rev 70 / SP7 and Rev 72.  SP8 is not tested yet, but will work if the SHINE content is similar.

IMPORTANT: for Rev 72 you must make sure that your user id has a default Session Client set.  If this is not in place the 3D game client will not detect your HANA version correctly and charts won’t work (the setting is needed for the SHINE currency conversion).  To make the setting, in HANA Studio, Systems tab -> Security -> Users, make sure your user has its Session Client set to 001, like this:

setting client to 001.png

To check that you’ve got the SHINE content installed, you can check that you can see data in the PO Worklist application using these links:

SHINE PO Worklist Entry Points


Version URL to PO Worklist
Rev 60 / SP6 <server ip address>:80<instance>/sap/hana/democontent/epm/ui/poworklist/WebContent/poWorklist.html
Rev 70 / SP7 <server ip address>:80<instance>/sap/hana/democontent/epm/ui/poworklist/poWorklist.html
Rev 72 <server ip address>:80<instance>/sap/hana/democontent/epmNext/ui/poworklist/poWorklist.html


The above links take you to the web front-end for the SHINE PO Worklist.  There you can check data, and see POs changing their status to Rejected and Approved.

Front-end Prerequisites

There are some front-end prerequisites.  You need one of: Windows XP with SP2 or later; Windows 7 with SP1 or later; Windows 8; Mac OS X Snow Leopard 10.6 or later. Windows Vista is not supported.  You also need a graphics card with DirectX 9 level (shader model 2.0) capabilities. Any card made since 2004 should work.  The front-end does not work on the CAL remote desktop PC on AWS, it does need to be run locally.

How to Install Front-end Client

Windows

To download the client go here: https://www.dropbox.com/s/wda5ae2h5dfbeeq/Epm3d_Windows_x86.zip

To install, just unzip it into any folder, there is no actual installer.


Windows 64 bit

To download the client go here: https://www.dropbox.com/s/x6iut2p65itk7ti/Epm3d_Windows_64.zip

To install, just unzip it into any folder, there is no actual installer.

MacOS

To download the client go here: https://www.dropbox.com/s/4jzm9snfawi6ox3/Epm3d_MacOS.app.zip

To install the client see Aron’s document, you have to skip past a couple of screens during start-up.

How to Play

  • Run the executable.
  • On the first popup enter your HANA system details, and press check connection:

login screen.png

  • If the check connection fails, error messages telling you why will appear in the box at the bottom of the screen.  See also the troubleshooting section below.
  • Then press Start.
  • There is help displayed in-game, press F1 to toggle it, but for completeness the help is here too:
  • Once in the game, use mouse to look around and the keys WASD or cursor keys to move around.  Stand on the buttons nearby the charts to interact with them (refreshing charts and changing their type).
  • With a PO box highlighted, click left mouse or press Y to approve the PO in the system.  Click right mouse or press N to reject a PO.  These approvals or rejections are reflected in the HANA system (in fact they won’t appear in the game until they are successfully posted to the HANA system).  You can check the data in HANA has changed using the links to the SHINE PO Worklist given above.

Troubleshooting

  • If the client does not start at all, it is most likely your PC is too old (>10 years old wont have good enough graphics card).
  • If the client starts but the connection check fails, make sure system details and user details are correct.  Make sure user has rights to view and change the SHINE content, which you can check using the SHINE PO Worklist Entry Points links above.
  • If the client does not detect your version as Rev72, and you know you’re using Rev72, this is almost certainly because your user id does not have a default client set, see Back-end Prerequisites section above.

For Advanced Players

  • Hold down the Shift key (Windows) or the Alt key (Mac) when you start the executable and an additional dialog appears.  This allows you to specify screen resolution and graphics quality, and also to edit the controls.

config dialog.png

  • To invert the mouse press “m” during gameplay.  This inverts the up-down axis for the mouse when you are looking around, some people find this easier to use.

2) How to Create a 3D HANA Client

So with all that out of the way, finally we can get to the “How to” part.  The game client was built using a product called Unity. Unity was designed originally for developing 3D games, but is also used for 3D visualisation like walk-throughs of buildings.  There is a free edition which has a few advanced features removed, but all the heavy lifting of 3D development is done for you.  Lighting, physics, input, cross-platform builds and much more are either done for you entirely or at least are well supported by the Unity engine.  All you need to do is some C# or JS scripting to control the behaviours of objects and glue stuff together.  I chose to use C# as most tutorials tend to use that, although you can mix scripting languages if you wish across different objects.

The communication between the client and HANA is all done using oData and XSJS services, the same services that are used by the standard SHINE web frontend.  To find these I used the web frontend (see the links in section “SHINE PO Worklist Entry Points” above) with Fiddler running, and that way I could see all the oData and XSJS calls that were being made.  With that, it was easy to generate the necessary URLs.


Trivia: SP6 used UPPERCASE for field names, so oData service calls are eg “PURCHASEORDERID”.  SP7 changed this and used TitleCase for fields, so oData service calls became eg “PurchaseOrderId”.  Then Rev72 went back and used UPPERCASE again, so URLs are back to saying “PURCHASEORDERID”.  What will SP8 bring, back to TitleCase perhaps?

The source code and assets are all available in GitHub.  Unity is easy to use, but not so intuitive that you can dive in immediately and follow it all.  At least do the intro videos tutorials provided the Unity team to learn the interface or you’ll quickly get pretty lost (at least I did).

To help orientate yourself if your looking through the Unity project files, the various objects in Unity link together like this:

Unity Client Architecture Diagram

/wp-content/uploads/2014/05/archsimple590_464249.png

The boxes in the above diagram are mostly C# scripts in the Unity project.  Most of the communication between objects is event driven (you’ll see lots of On* event handlers in the scripts, for example when collisions happen, or when an oData query returns).  There are also per-frame calls made by the Unity engine, so every 1/50th of a second (or thereabouts) the Update() method is called, which is used to handle drawing things and collecting user input.

I hope this article proves interesting, the source code is there to pull apart and reuse, any feedback is welcome.

To report this post you need to login first.

15 Comments

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

    1. Kevin Small Post author

      To get the host, instance, username and password, you need to ask your HANA system administrator.  If you have setup your own a HANA CAL instance then those details are available in the CAL portal and the “getting started” docs that accompany it.

      I don’t know if this 3D frontend will still work with the more recent HANA revisions, last ran it on SP7… it depends if the SHINE demo content has changed much.

      (0) 
      1. Jose Amaya

        Thanks for your response Kevin,

        This frontend works with HANA Cloud? or is for On-Premise?

        We recently bought a productive enviroment (cloud, not on-premise) and they gave us an account with administrator acces to it, the administrator is the person using that account but does not know. 

        Hope you can help me run your frontend

        (0) 
          1. Jose Amaya

            Kevin when you say it won’t work you mean the exe file or your approach?  I’m trying to adjust your code to use HCP and I’m having this problem when building and running on Unity

            Assets/_Scripts/GameManager/GameManager.cs(353,49): error CS1502: The best overloaded method match for `UnityEngine.WWW.WWW(string, byte[], System.Collections.Generic.Dictionary<string,string>)’ has some invalid arguments

            this is the line

            www = new WWW(url, null, headers);

            in GameManager – GetWwwData

            Any ideas why?

            (0) 
            1. Kevin Small Post author

              Hi Jose,

              Yes when I say it wont work I do mean the exe, it expects URLs to be made up of the server name, port and instance number.  You will see this pattern in the code when building http requests:

              http://” + host + “:80” + instance

              However, in principle, if you can make an OData call to HCP to see the SHINE data, then it should be possible to get it working.  So you need http calls like this to work, or their HCP equivalent:

              <server ip address>:80<instance>/sap/hana/democontent/epmNext/services/poWorklist.xsodata/PO_WORKLIST(PurchaseOrderId=’0300000000′,PurchaseOrderItem=’0000000010′)/?$format=json

              There may be some additional changes needed to get the logon part to work.  To get the logon part working before, I used fiddler and tried to mimic the exact contents of the http request sent when I first manually logged on to the HANA box.  That gave me the values to put into the “headers” variable that you see near the end of method GameManager.GetWwwData:

              //———————————————————

              // With login

              //———————————————————

              // prep headers

              Hashtable headers = new Hashtable();

              headers[“Accept-Language”] = “en-US,en;q=0.8”; // prevents a 500 error saying “Multiple resources found. Inconsistency between data model and service description found”

              string userAndPasswordCombo = _username + “:” + _password;

              byte[] bytesToEncode = Encoding.UTF8.GetBytes(userAndPasswordCombo);

              string encodedText = Convert.ToBase64String(bytesToEncode);

              headers[“Authorization”] = “Basic ” + encodedText;

              print(“WWW ———— calling now: ” + url);

              www = new WWW(url, null, headers);      

              So finally, regarding the Unity error.  Is that at build time or runtime?  Can you see what the data types are and what values there are in the “url” and “headers” variables?  The error is saying there is no method it can use, so I’m guessing one of the variables is the wrong type or maybe null?

              (0) 
  1. Kevin Small Post author

    Hi Raphael and Jose,

    I tried opening the source project in Unity 5.3 and the API that I used to make http calls seems to have changed, hence the error messages. I will have a look to see how easy it is to fix.

    Kevin.

    (0) 
  2. Kevin Small Post author

    The exe still does not support HCP. I don’t have access to HCP with SHINE installed to be able to test (I have a trial account only and it doesn’t support SHINE).

    However, it may still be possible to get working.  If you want to change the base URL that the exe uses for the SHINE service, go into the constructor of the VersionTranslator class and adjust _urlEpmBase to point to the root folder for your SHINE services.

    e.g. the exe expects _urlEpmBase to follow this pattern:

    http://<server>:80<instance>/sap/hana/democontent/epm/services/

    The exe ultimately makes calls like this:

    http://<server>:80<instance>/sap/hana/democontent/epm/services/poWorklistQuery.xsjs?cmd=getTotalOrders&groupby=PARTNERCITY&currency=USD&filterterms=

    If you change _urlEpmBase to be something appropriate for SHINE on HCP then it should be possible to get working.

    (0) 
    1. Jose Amaya

      Kevin some great work you did here, thank you for going to the trouble of updating it, It does work for HCP with the change that you suggest

      No words, brillant! I’ll try to understand the code to build a native HCP one, I get lost in how the data get process

      (0) 

Leave a Reply