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 ⏱️ GitHub Repository
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:
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.
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).
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 mariusobert, in the - Ep.46 - The SAP Business Application Studio with Marius Obert – with dj.adams.sap.
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.
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.
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:
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:
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/f8520f572a6445a7bfaff4a1bbc... 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.
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:
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.
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.
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>
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.
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.
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…
CTRL+SHIFT-P
CMD+SHIFT+P
VCAP_SERVICES={ //content }
npm run start
npm run start
{
"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/**"
]
}
}
npm run start
/captrelloTimesheetManager/captrelloTimesheetManager/
/ captrelloTimesheetManager/index.html
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
37 | |
10 | |
6 | |
4 | |
3 | |
3 | |
3 | |
3 | |
2 | |
2 |