Starts a user login session in a Mobile Web application for the current JSDOSession object by sending an HTTP request with user credentials to the Web application URI specified in the object's constructor.
This method throws an exception if it is not possible to send a request to the specified Web application.
On a successful login, the JSDOSession object sets its connected property to true. If the login fails, the object leaves its connected property set to false.
This method is always executed asynchronously.
Note: Before invoking this method, ensure that you set the authenticationModel configuration property in the constructor of the JSDOSession object correctly (see the notes on authentication models).
Note: If the browser or mobile device has already authenticated a user login session, this method completes successfully.
Note: This method does not support proxy servers (servers that function as a security service).
A string expression containing a user ID for the method to send to the Web server for authentication.
Note: The userName property of the JSDOSession object returns the most recent value passed to this method for the current JSDOSession object.
password
A string expression containing a password for the method to send to the Web server to authenticate the specified user.
Promise method signatures
Following are the signatures of methods that are observed in the jQuery Promise that login( ) returns:
Syntax:
done: function ( session , result , info ) fail: function ( session , result , info ) always: function ( session , result , info )
session
A reference to the JSDOSession object on which login( ) was called.
result
A constant indicating the overall result of the call that can have one of the following values:
progress.data.Session.AUTHENTICATION_SUCCESS — The user login session started successfully. You can use JSDOs to access any Mobile services supported by the Web application to which the JSDOSession object has logged in.
progress.data.Session.AUTHENTICATION_FAILURE — User login failed because of invalid user credentials (username or password).
progress.data.Session.GENERAL_FAILURE — User login failed because of a non-authentication failure.
info
A JavaScript object that can have the following properties:
errorObject — Any error object thrown as a result of sending a login request to the Web server.
xhr — A reference to the XMLHttpRequest object sent to the Web server to start a user login session.
You can also return the result of the most recent login attempt on the current JSDOSession object by reading its loginResult property. For a more specific status code returned in the HTTP response, you can also check the value of the loginHttpStatus property.
Note: You can log out from a Web application and then log in again using the same JSDOSession object. The login will use the same serviceURI and authenticationModel settings originally passed to the constructor, but you must pass any required credentials each time login( ) is called.
General Web server interaction
The general Web server interaction with and response to this method depends on the authentication model that the Web server uses and how resources are accessed and protected. You configure the authentication model for each Mobile Web application deployed to the Apache Tomcat and specify both the Web application URI and its corresponding authentication model to the JSDOSession object constructor. For more information on the authentication models that a JSDOSession object supports, see the description of the constructor for the progress.data.JSDOSession class.
For more information on these authentication models and how to configure them for a Mobile Web application, see the deployment sections on Web server authentication models in OpenEdge Development: Mobile Applications and your Web server documentation.
Caution: You must be sure that security is configured to complete authentication before the application requests resources in the JSDO catalog. Although it is possible to configure application security so that only the Mobile resources in the catalog require authentication, Progress Software does not recommend this approach. Instead, Progress Software recommends that you require authentication for application resources in addition to those defined in the catalog, and require that the authentication occur prior to accessing any resources in the catalog. Once the user is authenticated, the Web server provides access to all other resources, including catalog resources, according to the user's authorization settings.
Note: Unless the application design guarantees that the user will be prompted by the Web browser or native device container to provide credentials before a login( ) call occurs, Progress Software recommends (in some cases requires) that the Mobile App pass the credentials as parameters to the login( ) method. In addition, you must correctly pass the value of the authenticationModel configuration property to the JSDOSession object's constructor. Coding the Mobile App in this way ensures that the proper credentials are submitted to the server and promotes a favorable user experience.
Example
The following code fragment calls the login( ) method on the JSDOsession object, empSession. This example uses the Promise done( ) and fail( ) methods to check the result of the call along with any error object thrown as a result of the request, then assembles an appropriate message to display in an alert box. It also uses a try-catch block in case the login( ) method throws an error object instead of sending the request to the server:
var msg; var xhr;
try { empSession.login( { userName : uname, password : pw }).done( function( session, result, info ) { msg = "Logged in successfully”; }).fail( function( session, result, info ) { if ( result === progress.data.Session.AUTHENTICATION_FAILURE ) { msg = "Employee Login failed. Authentication error"; } else if ( result === progress.data.Session.GENERAL_FAILURE ) { msg = "Employee Login failed. Unspecified error"; if ( info.errorObject ) { // Process error object thrown during login . . . } if ( info.xhr ) { // Process XHR sent during login . . . } } xhr = info.xhr; }); } catch(errObj) { msg = "Employee Login failed. Error attempting to call login"; msg = msg + '\n' + errObj.message; }
progress.data.Session.AUTHENTICATION_SUCCESS — The user login session started successfully. You can use JSDOs to access any Mobile services supported by the Web application to which the JSDOSession object has logged in.