Remember how in the first post of these series, we called Web IDE but we were redirected to the UAA screen asking for our user name and password? We will understand what happened there after we understand the concept of routing in XS Advanced.

But first, coffee architecture

As developers, we also need to understand what is going on behind the IDE to make better design decisions. Your system administrator or BASIS friend will also appreciate that (and it’s always a good idea to have them on your side).

You can find the following picture as Figure 4 in the SAP HANA Administration Guide.

All those coffee drinkers (devs, deployers, admins) and users will use a URL to access an application. In the example of the first blog, we called the Web IDE using the default hostname and port in a HANA express system (https://hxehost:53075 ). That’s a request.

Take the word Web dispatcher… savor it…it’s almost self-explanatory.

Well, maybe it isn’t: it catches the requests from a client used by the coffee drinkers (a browser, the Command Line Interface, etc) and sends it to the right application.

Before it can send it to the right application, the controller needs to know the following:

• Which applications are running:It knows because it keeps the applications and their state in the BlobStore and ConfigStore.
• The entry endpoint of that application: It knows which is the right app thanks to either the port or some magic redirection using the subdomain (a.k.a, hostname based routing). An MTA has it’s own entry point. We’ll see this later.
• Whether the user is authorized or not to access that resource: That is, whether the request comes with a token id saying it’s ok to show content to that user or the user needs to provide credentials to get such pass.

A sample conversation between the coffee-drinking user, the Web Dispatcher, the UAA service and a Super Cool App would be something like:

(Yes, I know sequence diagrams… but wasn’t this more fun?)

Now yes, understanding routing in XSA development

Let’s say your application is the Super Cool App. You’ve built it using the introductory tutorials for XS Advanced and right after you cloned the initialized repo from GitHub, you created an HTML5 module. This web module has an index.html file that should be presented to authenticated users first.

Read that functional spec again: “authenticated users”. Do we build a little table with users, passwords and scopes they can access for each micro-service? Not ever since the first tiny app at school and luckily never again…

Go back to the architecture diagram above and take a look at the UAA box. It has everything you need, right?

You need an instance of the UAA service for your application, so you create it with xs cs xsuaa <<plan>> <<service instance name of your choice>>. 

So how does the app know you have a UAA service it can use?

• You added the new service to the mta.yaml file, as a resource
• You want it to be deployed first, because the web module will need it, so you also add it as dependency for your new web module
• You are modifying the authentication method in xs-app.json to route.

Is that it? Now the web module magically uses routing?

This looks like magic but it is not. Something is reading that xs-app.json file. Go and open the package.json file that Web IDE kindly created for you:

There’s the anonymous hero here: the approuter.js module. This Node.js module was automatically included in the file that lists the basic dependencies for your web module to run.

Even if you do not know what package.json is for, I bet you can appreciate the scripts section. The first thing that seems to get started is the “approuter.js”.  Just like the web dispatcher to the platform, this app router serves as an entry point for an MTA application. It is the entry endpoint the Web Dispatcher talks to and the one responding that a user needs authentication or delivering the index.html (welcomeFile).

The router will look for the xs-app.json file in its working directory and there is when it bumps into the “route” value (it could also have a “none” value). This simply means the definition of how to authenticate is delegated in each route configuration:

And you can see all of the authentication types are “xsuaa” because our applications shouts “you shall not pass”. It could also have “basic” or “none” as values but you want it to call the UAA Service you instantiated using the CLI.

How does it know that is the Service you want?

Because, remember, you declared it in the resources section in the yaml file and it got bound to your application when you built (deployed) the modules (or using command xs bs):

These binding process sets a super environment variable called VCAP_SERVICES that stores the services bound to an app and their config so it can invoke them later. Here is a sample output for command “xs env <<app>> ” showing the VCAP_SERVICES variable:

And you may (or should) be wondering who is “core-backend” in the routes destination? That’s another variable you can set on the the yaml file for example. It could have whatever value you want as it is an identifier for the node.js module declared as a destination:

If you are still struggling to understand the MTA.yaml file, I would encourage you to read the help. They have already explained it better than I ever could.

A reference for package.json is also provided here.

It was this CodeTalk video with a very quick intro to XSA and Web IDE that inspired (reminded) me to finish these series. i think we can wrap it up now. Not because I have covered all the topics but because you can continue on the path to XSA ninja on your own.

If you think this can be of use for someone else, please share.

As usual, i would love to stay in touch on Twitter or on LinkedIn and see what you are building. Cheers!

PS: For those of you asking for some specific tutorials on XSA (Fiori Launchpad, API calls, OData V4 and Java, three-dimensional localization of a cat), I do hear you and keep your wishlist. Time is the only constraint.