The goal of this how-to is to explain how you add a login to an existing application.
This how-to assumes the login will be done through Enterprise Manager integration. Enterprise Manager is intended to be used as a back-office portal centralizing all the common administration features such as user management and also the already existing application's back-offices. By integrating every existing back-office within Enterprise Manager, you'll have one single control panel, one common way to manage users, and thus one single entry point to administrate every specific application.
If your server doesn't has Enterprise Manager deployed. Please follow the Enterprise Manager Installation How-to.
Download the baseline eSpace (MyContacts_Baseline) available as an attachment of this how-to;
This baseline eSpace implements a very simple contacts management application. If you already completed the Developer Course I online training available in the Agile Network Academy you're probably already familiar with it. If not, don't worry, you'll get the hang of it in no time.
The goal of this baseline is simply to provide you with a start point so that you don't need to start from scratch. If you already have an eSpace to which you would like to add a login, feel free to use it.
Publish the baseline eSpace in your Server;
If you're not in a hurry and you're not yet familiar with the MyContacts application, play with it for a short while: add some contacts and some categories, just to get to know how it works;
Download the template eSpace (HowTo_Login) available as an attachment of this how-to;
This template is basically a slightly adjusted subset of the OutSystems Style Guide (a full fledged template to create new business applications faster) that only includes the login related parts.
Because developing a complete and fully functional authentication mechanism from scratch is not a trivial task, your approach will consist in merging this template into your own application and then making some minor adjustments to glue it together.
Open the eSpace with Service Studio;
Let's walk through it. Inspecting the eSpace Tree from bottom to top:
The Images folder contains some sample images to "beautify" your login page and application header;
The Exceptions and Permission Areas folders only have their standard elements;
The Site Properties folder includes 2 elements:
ApplicationName: The name of the application that will appear on the header;
CompanyName: The name of the company that will appear on the header;
The Session Variables folder only includes the standard elements;
The Entities folder includes a single referenced element:
USER_MASTER: This entity is owned by Enterprise Manager and it represents a user. It will assume the role of the System entity User in yourapplication;
The References folder displays the referenced actions from:
The Enterprise Manager eSpace;
The HTTPRequestHandler extension (a component that provide low level functionality over HTTP Requests);
If this just sounded like jiberish, don't worry, that's the purpose of having this template, so that you don't have to think about these low level details and weird technologies...
And finally what matters the most: the Screen Flows. Let's look at them one at a time, again from bottom to top:
The Common flow contains the a set of screens and web blocks to perform the login and do some basic account management tasks such as updating the active user information and changing the password. It also provides a LoginInfo web block that orchestrates this functionality by displaying information on the currently logged in user and providing links to the account management functionality.
Notice the 2 error handlers (Security Exception and All Exceptions). As you'll see later, all web flows in your application must have at least these 2 handlers directing to these 2 same screens (the ones on the Exception Flow). We again suggest you wonder around the flow and check out the screens and their business logic.
The Exceptions Flow: Error handling is a dirty job but someone has to do it ?. This flow handles 2 kinds of exceptions:
Unexpected errors: The truth is that something unexpected (an applicational bug or an external system failure) can always happen, and when it does you should provide your users with information about what just happened (to the extent possible) and some instructions on what should the user do next.
Security errors: These can be of again split in 2 categories:
Unregistered user: This means the user is trying to access a screen that requires an authenticated user and for some reason (typically the user hasn't logged in recently or it's last session already timed out) there is no active session. The course of action here is to redirect the user to the login screen.
No permission: This means the user has an active session but he/she isn't authorized to access the screen is trying to open (typically because a URL was typed directly in the browser). The course of action here is to redirect the user to a specific screen stating this fact.
We won't go into the specifics of the implementation of the handling of each of these errors but feel free to wonder around the flow and check out the screens and their business logic.
That's it. Remeber that the idea is for you to get the big picture of the login pattern template. Don't worry about the bits 'n bolts, you'll have plenty of time for that as you get more comfortable with the template.
Open the baseline eSpace (MyContacts_Baseline.oml);
If you don't feel confortable starting this merge without knowing the baseline eSpace take your time and walk through the eSpace tree.
Click on the 'Compare and Merge' button in the top toolbar;
Select the template eSpace (HowTo_Login.oml) and press the 'Open' button.
The 'Differences to Merge' window will be displayed. Select the elements as depicted bellow.
You're maybe wondering 'why those elements?'. Well, the rule is pretty straight forward: You pick 'all' the elements from the template eSpace (HowTo_Login) and you leave the elements from the baseline eSpace (MyContacts) untouched.
Press the 'Merge' button. Once merge is completed notice the new elements on the eSpace tree.
Incorporate the 'LoginInfo' Web Block into your own header:
Open your 'Header' Web Block (if you're using the baseline eSpace, expand the 'Screen Flows > CommonFlow' in the eSpace tree and pick the 'Header' Web Block through double-click);
Make sure the Outline Mode is turned on;
Place your cursor to the left of the header image (click on the image and then press the laft arrow key);
Press the Return key once to get some "free" space above the image;
Right-click the 'new line' symbol and pick 'Unlink' (the 'new line' symbol inherited the link wrapping the header image);
Drag the 'LoginInfo' Web Block from the eSpace tree (inside the 'Login' Screen Flow) and drop it when the cursor start blinking to the left of the 'new line' symbol;
Delete the 'new line' symbol. You Web Block should look as depicted bellow;
The 'LoginInfo' Web Block aims at being neytral and self contained. You should be able to easily integrate it in your own header layout and style, all you need is some "free" space in top-right corner of your header.
at came with the template: Login, Error and No permission)with your own:
Expand 'Screen Flows > Login' in the eSpace tree, right-click the 'Header' web block and pick 'Find Usages';
The list of locations where this web block is used will be displayed in the messages pane. Click on the 'Replace all usages with...' button;
A window that allows you to select the web block that will replace the 'template' header is displayed. Pick your own 'Header' Web Block through double-click;
Because the 'template' Header is no longer needed you can now delete it;
For each screen in the 'MainFlow' Screen Flow uncheck the 'Anonymous' Permission (in the screen properties)
When a screen doesn't allow anonymous access the platform throws a Security Exception whenever an unregistered user (a user who didn't logged in yet) tries to open this screen. This exception will be handled by the logic in the Exception flow we discussed earlier, but to set that behavior up we need an additional step...
Add the 'Security Exception' and 'All Exceptions' error handlers to the 'MainFlow' Screen Flow (and to any other Screen Flow you may have in your application:
Open the 'Common' Screen Flow (double-click the flow in the eSpace tree);
Select both error handlers and the 'Go To Destination' elements they're connected to;
Copy them (through ctrl+c or using the toolbar button);
Open the 'MainFlow' Screen Flow (double-click the flow in the eSpace tree);
Paste the error handlers (through ctrl+v or using the toobar button);
Change the 'Company Name' Site Property default value to your company name;
Adjust the layout and style of the screens copyed from the template to make them consistent with your application;
There is no magic recipe here. The screens from the template try to be as neutral as possible, but you'll always need to tweek them a bit to make them "fit" your layout and design. The CSS classes for each of the template screens are in their 'Style Sheet' property.
And YOU'RE DONE!
Make sure the TrueChange tab on the messages pane tells you your eSpace is valid;
1-Click Publish your application;
You'll need an Enterprise Manager user to test the login. If you don't have one yet, please follow the Enterprise Manager User Management How-to to guide you through the process.
Type your application URL in your web browser: "http://<SERVERNAME>/mycontacts" where <SERVERNAME> is the host name of the server where the MyContacts application was published to. The login page should be displayed.