Skip to Content
Technical Articles

Timesheet Management with CAP & Trello ⏱️ – Setup the IDE & MTA Project #1

Hello there!

Welcome back to the first hands-on blog of this “Timesheet Management with CAP & Trello ⏱️ blog series. In this blog “Setup the IDE & MTA Project #1” we will setup the frame for our MTA-project and create the required instances with it.

If you missed some other blogs of this series, you can find them here:

Timesheet Management with CAP & Trello ⏱️
Timesheet Management with CAP & Trello ⏱️ – Setup the IDE & MTA Project #1 (this blog)
Timesheet Management with CAP & Trello ⏱️ – Setup a Database and Service Module #2
Timesheet Management with CAP & Trello ⏱️ – Connect to Trello API’s via a Node.js Module #3
Timesheet Management with CAP & Trello ⏱️ – Build the Trello Timesheet HTML5 Module #4
Timesheet Management with CAP & Trello ⏱️ – Add a Fiori Launchpad Site Module #5

The GitHub Repository is available here:

Timesheet Management with CAP & Trello GitHub Repository

 

Introduction

The development of this CAP-project and the integration with the Trello-services will take place inside the SAP Business Application Studio. Now why’s that? Because it is a lovely IDE, which offers the developer quiet some freedom during the development process. Not only it offers you a lot of freedom, but it also comes with some “prepackaged content”. More in particular some preconfigured workspaces so you can get started right away!

Since this blog post is about building our own timesheet CAP-project with Trello Services, we are not going into detail about this IDE. But that does not make it obsolete to check out the setup of this IDE (if not checked out already) or have a look some cool features it brings along. I would like to provide a small summary below of some very valuable content to get started and discover some cool features of the SAP business Application Studio.

More information:

But enough about the SAP Business Application Studio, time to check out and build this timesheet application!

There will be some major building blocks in this CAP MTA project as well as some smaller ones. But all very important and necessary features. Now what are those building blocks and features? Let’s list them up!

What will we need:

  • A Multi Target Application (MTA) project
  • An Approuter
  • An xsuaa instance/service
  • Appropriate roles assigned by role collections (xsuaa)
  • A HANA database (via CDS)
  • An OData V4 service (via CDS)
  • A Node.js application to authenticate and authorize against Trello
  • A User-Provided Service to store the Trello API Keys.
  • A UI5 App
  • A Fiori Launchpad Module

Now these services will all be needed to have a full working application at the end. The MTA project will not only work but will be also 100% secured with by our xsuaa service (also called Authorization & Trust Management) which will add the required authentication and authorization features. All Modules inside the Multi Target Application are secured and every single application inside the MTA project is accessible via the Approuter.

 

IDE | MTA | Service Instances | Configuration

All the features/services mentioned earlier, need to be implemented, setup and configured. So that’s what we will do, and we will start by creating our MTA project. But before we can start creating our MTA project, we need to setup our IDE its workspace. The workspace needs some extensions which are all provided by the SAP Business Application Studio by default (depending on the workspace selection).

 

Setup the SAP Business Application Studio Workspace

Once you followed all the necessary steps of the – Set Up SAP Business Application Studio for Development – Tutorial by SAP Developers, you will end-up at the following screen:

That’s exactly where you want to be, it is the start-screen of the SAP Business Application Studio and it will allow you to create a preconfigured development workspace for your project.

Here we continue obviously by pressing the “Create Dev Space” button.

In the next screen we provide a namespace and we select the option “SAP Fiori” as kind of application we want to create. This kind of dev space comes along with some predefined extensions such as “Basic Tools”, “Fiori Freestyle Tools”, “SAP Fiori tools”, … and much more. Since we want to place our application inside a Launchpad at the end of the development, we check the option for the “Launchpad Module” under the Additional SAP Extensions. We continue by pressing the “Create Dev Space” button.

This will start the creation of your workspace and you can follow the progress in the screen provided. As you can see the workspace has the status “STARTING”.

Once the workspace is ready, I will change to the status “RUNNING”. This means you can access your workspace inside the SAP Business Application Studio by clicking on the name of your workspace.

This will open up your workspace and provides you the following screen:

Now you can start to configure your workspace with all kind of preferences. But we will only cover the necessary steps for this CAP-project. The only two preferences I personally need during my development are the “Dark Theme” for the IDE and the “Format on Save” feature.

Which I discovered thanks to Marius Obert, in the – Ep.46 – The SAP Business Application Studio with Marius Obert – with DJ Adams.

 

Login to Cloud Foundry & Select Organization & Space

The first thing we want to double check here is that we are connected to our Cloud Foundry environment Space. The first time you open your workspace, your Cloud Foundry environment its organization and space are not yet set. As shown in the Business Application Studio in the left bottom of the screen.

To set the organization and space, select/press this message. This will open a popup window on the top of the screen, where you can change or keep the default (retrieved from your Cloud Foundry Subaccount – API Endpoint) Cloud Foundry Endpoint.

Hit enter to continue the login wizard. Here you your user (P or S) its email address.

Hit enter to continue the login wizard. In the next step you provide your password obviously.

Once logged in, you have to select the organization you want to connect to.

Once selected, you have to finalize the wizard by selecting a space to target. Notice that this is not your SAP Business Application its workspace, but your Cloud Foundry Space inside your Subaccount.

Once selected, the IDE will notice the login and displays a success message as well as a message that you a targeting your selected organization and space.

To save ourselves some screenshots and time we will initialize and continue the preparation of our CAP-project via the Command Line Interface. If you can setup the project via the CLI, you can setup the project via the UI-generator as well.

 

Install the CDS Tools

Since we chose the “SAP Fiori” option during the Business Application Studio Workspace creation we receive a lot of predefined extensions and we added the Launchpad Module as an additional SAP Extension.

But one very important extension we are missing here are the CDS Tools to generate CAP-projects and Modules. When we try to execute the “cds” command on the terminal we will see that the command is unknown:

Now you might wonder why we did not choose the “SAP Cloud Business Application Dev Space” option during the Workspace creation. Well the reason for that is, that we can add Module per Module to our MTA Project and describe them while we are still able to use the “CDS Tools” if we installed them. Remember what I said about all the different possibilities on the beginning of this Blog Series? There are so many different ways to start and setup your project and this is just one of them. Using the CAP Workspace would also be very feasible.

Now back to our “CDS Tools”, these tools can be installed by executing the following command on the terminal:

npm i -g @sap/cds-dk

Once executed, we can try to execute the “cds” command again and we will see that it is listing all the possibilities of the command.

With this you successfully prepared your IDE-Workspace and you are ready to setup your Multi Target Application Project.

 

Setup the MTA Project

Now that our IDE-Workspace is ready to be used, we can initialize our MTA-Project. We will do this by using the command-terminal instead of the GUI. The reason for that is that we save ourselves a ton of print screens with arrows and that we are using the terminal. Because the terminal is way cooler 😎 and if you can make it work in there, you can defiantly repeat the steps via the GUI (if they are foreseen of course).

Now to do so, run the following command on the terminal inside your “projects” directory:

yo

This will ask you which Yeoman-generator you want to use, and it will guide you through the wizard to initialize your project. We select the “Fiori Project” generator for the “Cloud Foundry” environment which will generate us the project holding an “Approuter” (Standalone), “mta.yaml” file (preconfigured) and an “HTML5 Module”. This all secured via an “XSUAA” service, since we told the wizard to add authentication to the project.

Provide the following configuration for your project (I recommend during these blogs you use the same names and naming-conventions):

Once the wizard has been completed, the Yeoman-generator will start generating your project.

When this process has finished, you will find the following project-structure inside your workspace:

As you can see it contains all the modules, services and directories as mentioned before.

Now let us have a look at the “mta.yaml” file. At this point it will hold 3 Modules and 3 resources:

Let us have a closer look at these Modules and Resources.

Modules:

Module

Purpose

trello-cap-timesheetmanagement-approuter

A Node.JS application that routes all the requests in the MTA to the respective Module/Application.

Requires:

  • Trello-CAP-TimesheetManagement_html_repo_runtime (Memory to run the Approuter, see entitlements Application Runtime)
  • uaa_Trello-CAP-TimesheetManagement (to add authentication and authorization, generated by the “yo Fiori Project”)

The 2 entries inside the requires section of this module are 2 resources which are also present inside the “mta.yaml” file under the “resources” section.

 

Trello-CAP-TimesheetManagement_ui_deployer

This module can be used to deploy your content to the HTML5 Application Repository.

 

Requires:

  • Trello-CAP-TimesheetManagement_html_repo_host (since it is required) which is declared inside the “resources” section to host the deployer application during the deployment process. Once the deployment is finished it will stop the ui-deployer module.

HTML5 Application Repository:

“HTML5 Application Repository allows application developers to manage the lifecycle of their HTML5 applications. In runtime, the repository enables the consuming application, typically the application router, to access HTML5 application static content in a secure and efficient manner.“

~ SAP Help Documentation

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/f8520f572a6445a7bfaff4a1bbcbe60a.html

In case you want to deploy updates for your UI5 application, and you do not want to use the ui-deployer any longer, since it takes a while, you can also use the “CF HTML5 Applications Repository CLI Plugin”. Which allows you to quickly deploy your new features without the usage of the ui-deployer. Do not forget to build you project before the deployment.

https://sap.github.io/cf-html5-apps-repo-cli-plugin/

 

TimesheetManager The HTML5 UI Module which holds the path to the UI5 app project inside the MTA.

This brings us to the Resources in the “mta.yaml”. Some of these resources were already required by some of the Modules as described in the table above.

Resource

Purpose

Trello-CAP-TimesheetManagement_html_repo_runtime

 

A resource which provides runtime memory for the applications.

Trello-CAP-TimesheetManagement_html_repo_host

 

Offers the possibility to deploy applications to the Cloud Foundry space.

uaa_Trello-CAP-TimesheetManagement

 

The XSUAA (Authorization & Trust Management) service allows you to use authentication and authorization inside your applications. At this very moment the Approuter is using this service and will later on send the authorization access tokens along to the requested modules to ensure authenticated and authorized access to the appropriate resources.

 

The scopes and role-templates can be configured inside the “xs-security.json” file, which is present in the root directory of the MTA-project.

 

 

The default content for such a security file looks like this and can be extended with more scopes and role-templates:

This “mta.yaml” file will be the core during the deployment process of the MTA-Project, since it will build the modules step by step (chronological) during the deployment process.

 

Configure the Approuter

Since we use the Yeoman-generator and in particular the “Fiori Project” generator an Approuter was already generated for us. But we still have to configure the routes and authentication inside our “xs-app.json” file inside the “trello-cap-timesheetmanagement-approuter” directory.

After generating the Approuter, the default configuration of the “xs-app.json” looks like this:

Basically, this means there is no authentication set and there are no routes declared.

Let us update this configuration a little so it looks like this:

The reason the “authenticationMethod” is set to “route” is because every route that will be declared inside the “routes” array will use authentication. If this value would be set to “none” (the only other possibility) authentication for all the routes inside the “routes” array would be disabled. So, to use authentication inside our routes we need to use the “route” value here.

The “routes” array contains a route with a regex as value for the “source” property. This means that every request will match the regex and it will be forwarded to the HTML5-Application-Repository, where the UI5 application is deployed. By telling the route to use “xsuaa” as “authenticationtype”, the request will be authenticated and authorized and will be processed in a secure wat.  The “welcomeFile” property is pointing out to “captrelloTimesheetManager”. This is your HTML5-Module its namespace concatenated without dots and slashes. This is the path towards your app inside the HTML5-Application-Repository.

More information about the Approuter configuration can be found here:

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/01c5f9ba7d6847aaaf069d153b981b51.html

 

Build the MTA-Project

To build our MTA-Project we execute the following command inside the root directory of our MTA-Project:

mbt build

This will create a “Trello-CAP-TimesheetManagement_0.0.1.mtar” file inside an “mta_archives” directory in the root directory of your project.

 

Deploy the MTA-archive

Now to deploy this created “Trello-CAP-TimesheetManagement_0.0.1.mtar” file we execute the following command inside the root directory of our project:

cf deploy mta_archives/Trello-CAP-TimesheetManagement_0.0.1.mtar --delete-services

The parameter “–delete-services” which is passed at the end of the command makes sure that the changed services are recreated, and the discontinued services are deleted.

After the deployment was successful, you will see that the Approuter was started. You can check this in your Cloud Foundry environment Space inside the applications section. Select the Approuter, to navigate to the overview page which is holding the URL to the Approuter:

Open the Approuter by pressing the URL:

When you have a look at the URL in the browser, you will see that it was extended with the following part: “/captrelloTimesheetManager/index.html”. This because our regex in our only route so far says that every URL that matches the regex should be navigated to the value in the “welcomeFile” property. Which is “captrelloTimesheetManager”, and points to the app in the HTML5-Application-Repository and opens the “index.html” file which is default behavior.

Last but not list the UI5 App from the HTML5-Module is displayed:

If you would copy paste the URL of this application into an incognito tab, you would see that you have to login before you can access the webapp. If we would have generated this project without an xsuaa service, the webapp would be public available. Which is normal since the Cloud Foundry Apps you develop come default without authentication.

 

Create an XSUAA Service-Key

Since there will be more Modules inside our MTA-Project, which will be consuming the XSUAA service instance as well, a Service-Key should be created.

This service-key can then be consumed by the different applications to authenticate the routed request and grant access to the resource.

This key can either be created via the GUI (Cloud Foundry Space > Service Instances > xsuaa instance > Service Keys > Create Service Key) where you pass a name for your Service-Key. Or via the command line using the following command:

cf create-service-key Trello-CAP-TimesheetManagement-xsuaa-service TrelloCapSK

Which uses the following strucutre:

cf create-service-key <xsuaa-instance-name> <xsuaa-service-key-name>

 

Configure the XSUAA Role-Templates

When we build and deployed the” Trello-CAP-TimesheetManagement_0.0.1” file, all the modules inside the “mta.yaml” file were created. This means also the “XSUAA” service instance, which used the “xs-security.json” file as configuration for the service.

In here a role-template of the type “Token_Exchange” was defined, which allows the token exchange over the different modules via the Approuter since it is using and forwarding the auth tokens.

A user needs the have the rights to make the Approuter do this, and for that a user needs a specific role which is present under a specific Role-Collection.

Now let us create this role-collection inside the “SCP Subaccount > Role Collections“.

Here you press the “+-sign” in the upper right corner to add a new Role-Collection. Let us name the Role-Collection “Trello-Timesheet-Management”.

Once the Role-Collection has been created, we select it to assign roles to it.

Here we press the “EDIT”-button on the top-right-corner to edit the Role-Collection. Once in edit mode, we press the “+-sign” in the ”Roles”-section to add a role to the collection. We search for the “Token-Exchange”-role (which was created because of the role-template inside our “xs-security.json” file) with the generated id holding your project name. We select this role and we Save our changes.

 

Assign Role-Collection to user

The Role-Collection has been created and the correct role has been assigned to it. Now the only thing left to do, is to assign this Role-Collection to our user. This can be done in your “Subaccount > Trust Configuration > Identity Provider”. We select the “sap.default” identity provider:

In the next screen we enter the email address of our SCP user and we select “Show Assignments”. This will list all our user its current Role-Collection assignments:

Now the “Assign Role Collection”-button has been enabled and we can add a Role-Collection:

We select our Role-collection called “Trello-Timesheet-Management” and we press “Assign Role Collection”:

With this you finished the implementation and configuration of the XSUAA Service Instance as well as the initialization, setup and configuration of the core of your MTA Project along with the required services.

 

Working in the Business Application Studio

Now when we use the Business Application Studio, we would like to test our ui5 app in this IDE too. I do not expect someone to build an app and deploy it without even testing it once.

No let us try to run this app!

For this we navigate to the “trello-cap-timesheetmanagement-approuter” directory inside our MTA-Project on the terminal. Here we execute the following command to start the Approuter (Since we want to use the Approuter to delegate our requests and provide us the required resources):

npm run start

When we ran this command, we will see our first error, this when we just want to launch the Approuter…

The error message tells us the following:

VError: xs-app.json/routes/0: Format validation failed (A route requires access to html5-apps-repo-rt service but the service is not bound.)”.

Now this actually makes sense, so do not lose hope guys!

The reason for this error is that in the Cloud Foundry environment when the app is deployed, the Approuter has access to this “html5-apps-repo-rt” service. But not inside the local run configuration in the Business Application Studio. So that’s why we get this error.

Obviously, there is a solution for this, so let us implement this!

To allow our Approuter to access this html5-apps-repo-rt” service, we will bind this service to it. This by using the command-pallet inside the Business Application Studio, which offers us a way to bind this service locally to our Approuter.

On Windows you press the following key-combination:

CTRL+SHIFT-P

On MAC you press the following key-combination:

CMD+SHIFT+P

This will open up the command-pallet where we search and select the “Bind a service to a locally run application” option:

This will open a new pop-up window where we select the directory/Module to bind the service to. Here we choose the “trello-cap-timesheetmanagement-approuter” since we want to bind the service to our Approuter and we press “Select folder for .env file”.

This will load the Cloud Foundry Services and it brings us back to the command-pallet. This time we have to select the service we want to bind to our Approuter. In this case we select the “Trello-CAP-TimesheetManagement_html_repo_runtime” service since the error said: “A route requires access to html5-apps-repo-rt service but the service is not bound”.

Just like we expected, the “.env” file was created inside our ”trello-cap-timesheetmanagement-approuter“ directory.

Now we have to adjust this file a little so that our Approuter can use it.

The first thing we want to do is to rename this “.env” file to “default-env.json”.

Once that’s done, we open the file and see that this file was not generated with a correct JSON-structure.

We want to change this structure:

VCAP_SERVICES={ //content }

We added the missing curly brackets and double quotes and replace the “=” sign with “:”.

With this we have a valid JSON-structure now and our Approuter can make us of this “default-env.json” file.

Inside your file you will see that your “html5-apps-repo” was retrieved and place inside along with all the configuration details and secret-keys. This way the Approuter can find and use the service.

Now let us try to run the Approuter again with the same command:

npm run start

And we get an error again….

This time the error logs are telling us that a UAA service is missing. In particular: “Error: No UAA service found”.

That is correct, since our Approuter is using the “authenticationMethod” “route” and the routes themselves are using “xsuaa” as “authenticationType” as configured inside the “xs-app.json” file.

So, let us repeat the step we performed above. Only this time when we have to select a service to bind to our Approuter directory, we select the “xsuaa” service instead of the to “html5-apps-repo-rt” service obviously.

This will create again a “.env” file inside the Approuter directory.

We open this file and we copy everything between the following lines:

Next we paste this content inside our “default-env.json” file so it looks like this:

Now we have our “xsuaa” and “html5-apps-repo-rt” locally bound to our Approuter.

You can also delete this “.env” file inside your Approuter directory now.

Time to run this Approuter again with:

npm run start

This time everything will be in place and our Approuter was able to start and the Business Application offers us the possibility to expose the service and open it. So we press “Expose and Open”:

This will open the command-pallet once more so we can provide a description for the service we are exposing. Let us call this “approuter” and press enter:

This will open a new tab with the Approuter service and once you thought you were finally there:

Again, an error….

Now why is that and what is it saying?

  1. The redirect_uri has an invalid domain.
  2. The request for authorization was invalid.

But what is the problem? We bound our xsuaa service to our Approuter right?

Yes we did, but there is only one small difference between the creation of an xsuaa service via the terminal or from the “mta.yaml” deploy process and the creation via the Business Application Studio.

These xsuaa service creations are based on the configuration inside the “xs-security.json” file inside your project. Now in this file there was one small configuration missing to make this xsuaa service work inside the Application Studio.

Let us have a look how this configuration would look if we create this xsuaa service via the Application Studio.

First, we stop the Approuter in the terminal by entering the CTRL+C keys.

Second of all we un-expose the Approuter service via the command-pallet by selecting the option “Un-expose”:

Next we select the service we want to unexposed which is the “approuter” service of course:

We open the command-pallet again and select the “Create a new service instance”:

We call it “Trello-CAP-TimesheetManagement-xsuaa-service-local”:

Next it will ask us the type of the service we want to create which is “xsuaa”:

We select the “application” service plan and continue:

This will bring us to the configuration of our “xsuaa” service. It show the content that would go into the “xs-security.json” file for creation. But we create it via this command-pallet now. One thing you will notice here is the “oauth2-configuration” which is holding the “redirect-uris”. These properties and values were missing in our “xs-security.json” file. It holds the redirect uri to make this authentication and authorization process work inside the Business Application Studio.

Do not mix or confuse these configurations, you do NOT need to add this “oauth2-configuration” and “redirect-uris” to your “xs-security.json” file. We just want to create a new xsuaa service for our local development inside the Application studio. So, we paste the following configuration (copied from our xs-security.json file) along with the “oauth2-configuration” and “redirect-uris” inside the command-pallet input field and we press enter.

{
    "xsappname": "Trello-CAP-TimesheetManagement-local",
    "tenant-mode": "dedicated",
    "description": "Security profile of called application",
    "scopes": [
        {
            "name": "uaa.user",
            "description": "UAA"
        }
    ],
    "role-templates": [
        {
            "name": "Token_Exchange",
            "description": "UAA",
            "scope-references": [
                "uaa.user"
            ]
        }
    ],
    "oauth2-configuration": {
        "redirect-uris": [
            "https://*.eu10.trial.applicationstudio.cloud.sap/**"
        ]
    }
}

This will create a new “xsuaa” service with the required configuration.

The next thing we want to do is to use the command-pallet again to bind our new create “xsuaa” service to our Approuter.

This will create a “.env” file once more and we copy this “xsuaa” configuration from it and replace the “xsuaa” configuration inside the “default-env.json” file with it. We also delete the “.env” file again. This way the correct redirect uris can be found and used during the local tests inside the Business Application Studio.

Time to run this Approuter again with:

npm run start

Expose the service and provide the service description and the app will open without authentication errors:

But you do get a “File not Found” and the reason for that is the following path in the URL:

/captrelloTimesheetManager/captrelloTimesheetManager/

It does not build the path 100% like it would when deployed, so adjust it like this:

/ captrelloTimesheetManager/index.html

Now you will see your app will open:

When you want to use Cloud Foundry services inside your project and you want to run it in the Business Application Studio or another IDE, you will need to add these services in the “default-env.json” file like we did a few times using the command-pallet.

The “xsuaa” service was a special one since it was using this redirect-URLs.

 

Wrap Up 🎁

Some of you will be very pleased to hear that at this point we can start the development of our CAP-MTA project. But these steps were necessary to configure and setup the core of our CAP-MTA.

We described the following requirements from the beginning and implemented the following ones:

  • A Multi Target Application (MTA) project
  • An Approuter
  • An xsuaa instance/service
  • Appropriate roles assigned by role collections (xsuaa)
  • A HANA database (via CDS)
  • An OData V4 service (via CDS)
  • A Node.js application to authenticate and authorize against Trello
  • A User-Provided Service to store the Trello API Keys.
  • A UI5 App
  • A Fiori Launchpad Module

 

I do hope you found this blog of the blog series “Timesheet Management with CAP & Trello ⏱️“ interesting, and that I succeeded in bringing this content in a clear and understandable way. Once you understand these concepts, the configuration and development process will be a piece of cake. But getting started with all these concepts can be hard sometimes. That’s why I wanted to show you guys this whole setup as well explained as possible. I hope I succeeded, and you enjoyed reading it. 😃

Now it is time for the development! Brace yourself!

See you in the next blog Timesheet Management with CAP & Trello ⏱️ – Setup a Database and Service Module #2

Kind regards,

Dries

4 Comments
You must be Logged on to comment or reply to a post.
  • First of all, thank you very much for your blog series. They help me understand the basics of development process in Cloud Foundry environment.

    I have a question regarding this post.

    To run the app locally, you bind html5-apps-repo-rt service to local approuter.

    When you run this app locally, does the approuter goes to retrieve the contents in Cloud Foundry?

    If you have made some changes to the app and not yet deployed the change to the Cloud Foundry, can you see the updated version or already deployed version?

     

    Best regards,

    Mio