KAAJEE    ICR (4851)

Login Web page for authentication. This is the Login Web page where users
enter their Access and Verify codes and choose an Institution from a
drop-down list.

For read-only access.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\                login.jsp

In addition, this login.jsp must configured in the application's web.xml file
as a form-login-page.

The following XML tags shows an example of how this may be configured in the
application's web.xml file:

<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>login/login.jsp</form-login-page>
<form-error-page>login/loginerror.jsp</form-error-page>
</form-login-config>
</login-config>

This is the error page to be used with KAAJEE for Form-based
authentication.

When this page is presented to the user, the most likely cause is that the
user is lacking the proper Security Keys required for the consuming
application.

For read-only access.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\                loginerror.jsp

In addition, this loginerror.jsp must be configured in the application's
web.xml file as a form-error-page.

The following XML tags shows an example of how this may be configured in the
application's web.xml file:

<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>login/login.jsp</form-login-page>
<form-error-page>login/loginerror.jsp</form-error-page>
</form-login-config>
</login-config>

This is the error page that KAAJEE redirects to when authentication fails
against a VistA M server after providing the access & verify codes plus
the target institution.

For read-only access.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\                loginerrordisplay.jsp

Login session timeout Web page.

This web page informs the user that his/her session has expired during login.

For read-only access.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\                SessionTimeout.jsp

Login persistent cookie information.

This web page informs the user how the persistent cookie information is used.

For read-only access.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\                loginCookieInfo.htm

KAAJEE configuration file.

Access to this file is restricted to read/write/modify as described in the
KAAJEE documentation.  For more detail regarding the parameters that may be
modified, refer to the KAAJEE documentation.

KAAJEE relies on a configuration file (i.e., kaajeeConfig.xml file) to read in
all administrator-configurable settings. You can use the kaajeeConfig.xml file
that is distributed with the KAAJEE software or you can create a KAAJEE
configuration file in your J2EE Web-based application and export it along with
your Web-based application.

The consuming application may use 'kaajeeConfig.xml' as the name of the KAAJEE
configuration file or any filename with an 'xml' extension.  This name is
identified by configuring web.xml to include a startup servlet (see also
component gov.va.med.authentication.kernel.InitKaajeeServlet) similar to the
following entry:

<servlet>
<servlet-name>KaajeeInit</servlet-name>
<servlet-class>gov.va.med.authentication.kernel.InitKaajeeServlet</servlet
-class>
<init-param>
<param-name>kaajee-config-file-location</param-name>
<param-value>/WEB-INF/kaajeeConfig.xml</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

The param-value of '/WEB-INF/kaajeeConfig.xml' associated with the param-name
of 'kaajee-config-file-location' identifies the filename and location of the
KAAJEE configuration file.

The kaajee-x.x.x.xxx.jar contains the KAAJEE java classes.
Access to this file is limited to read-only.  No modification are
permitted.

Note:  The 'x.x.x.xxx' in the name 'kaajee-x.x.x.xxx.jar' is used
as a placeholder and when referenced here in this Integration
Agreement represents the current version.  When actually using
this file, replace 'x.x.x.xxx' with the current version of the
KAAJEE JAR file.

The kaajee-x.x.x.xxx.jar file must be distributed in your application's
Enterprise Archive (.ear) file with an application-level classloader.
When you are ready to deploy/distribute your application,
perform the following steps:

a. (required) Package the kaajee-x.x.x.xxx.jar file
in your application's ear file (e.g., in a "../APP-INF/lib" folder
descendent from the root level of your application's ear file).

b. (required) Ensure that kaajee-x.x.x.xxx.jar is not located
in a deeper level of the classloader hierarchy
than that of an application, anywhere on the application server.
Otherwise, the singletons will be instantiated with settings
inappropriate for your application, and the KAAJEE security system
will function inappropriately for your application.

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it is referenced in the consuming application's web.xml file.

Configure KAAJEE Listeners (web.xml file)

KAAJEE has two similar listeners, both of which perform logout actions
for a user. Both of these listeners are available in case one listener
does not work with a specific container/platform (e.g., WebLogic, Oracle
9iAS, etc.):

Listener                        Description
========                        ===========
KaajeeSessionAttributeListener  The KaajeeSessionAttributeListener
listens for specific (individual)
session attributes that are
targeted for removal, which
signals a user session ending,
and performs user logout actions.

(see also component
gov.va.med.authentication.kernel.KaajeeHttpSessionListener)

Configure these listeners in your application's web.xml file as follows:

<listener>
<listener-class>

gov.va.med.authentication.kernel.KaajeeSessionAttributeListener
</listener-class>
</listener>

(see also component
gov.va.med.authentication.kernel.KaajeeHttpSessionListener)

HealtheVet-VistA small blue logo image file.

For read-only access.

This jpeg file is referenced by the KAAJEE login page to provide an image.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\images\         HealtheVetVistaSmallBlue.jpg

HealtheVet-VistA small white logo image file.

For read-only access.

This jpeg file is referenced by the KAAJEE login page to provide an image.

The consuming application needs to place this file in their deployable
artifact in the following directory/folder under the web context root:

Directory               File Name
=========               =========
..login\images\         HealtheVetVistaSmallWhite.jpg

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it is referenced in the consuming application's web.xml file.

Configure KAAJEE Listeners (web.xml file)

KAAJEE has two similar listeners, both of which perform logout actions
for a user. Both of these listeners are available in case one listener
does not work with a specific container/platform (e.g., WebLogic, Oracle
9iAS, etc.):

Listener                        Description
========                        ===========
KaajeeHttpSessionListener       The KaajeeHttpSessionListener
listens for session destruction.
It is looking for the whole
session being destroyed
and performs user logout actions.

(see also component
gov.va.med.authentication.kernel.KaajeeSessionAttributeListener)

Configure these listeners in your application's web.xml file as follows:

(see also component
gov.va.med.authentication.kernel.KaajeeSessionAttributeListener)

<listener>
<listener-class>
gov.va.med.authentication.kernel.KaajeeHttpSessionListener
</listener-class>
</listener>

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it may be referenced as a JavaBean by the consuming application.

The session key, properties and getter methods listed below are for read-only
access.

Session key used to obtain userInfo JavaBean:

SESSION_KEY

The key under which this value is placed in the session object
during login, and from which this object
can be retrieved by the enclosing web application post-login.

This SESSION_KEY is a public static final method that returns a string.

Applications may use the userInfo JavaBean to obtain user demographic
information.

This can be achieved by using the JSP action <jsp:getProperty...>

This JavaBean contains the following properties:

UserDuz
UserName01
UserNameDisplay
UserLastName
UserFirstName
UserMiddleName
UserPrefix
UserSuffix
UserDegree
LoginStationNumber
UserParentAdministrativeFacilityStationNumber
UserParentComputerSystemStationNumber

Alternatively, applications may access the getter methods directly.

Methods with a return type of java.util.TreeMap:

getPermittedNewPersonFileDivisions() Returns a list of the user's permitted
divisions returned as a TreeMap. The key value in the TreeMap is the Station
Number, which is a String. The object value stored under each key is a
VistaDivisionVO object.

(see also component gov.va.med.authentication.kernel.VistaDivisionVO)

This list represents all of the divisions on the VistA M Server that the user
could have logged into. Applications can display a list of other divisions
that the user could switch to within the application, allowing the user to
select a different division. It is then the application's responsibility to
use the proper division for its own internal business rules, and also to pass
the proper Division Station Number with each VistALink RPC call it makes to M.

getLoginDivisionVistaProviderDivisions() returns a list of divisions (based on
information in the SDS Institution table) whose Vista Provider is the same as
the Vista Provider computer system of the login division.  This list is
returned as a TreeMap.  The key value in the TreeMap is the Station Number,
which is a String. The object value stored under each key is a VistaDivisionVO
object.

(see also component gov.va.med.authentication.kernel.VistaDivisionVO)

This method is provided to applications to support division switching for all
divisions supported at the same computing facility as the login division,
regardless of whether explicit access has been granted to the user for any
particular division.  Applications can display a list of other divisions that
the user could switch to within the application, allowing the user to select a
different division.  It is then the application's responsibility to use the
proper division for its own internal business rules.  The application
developer should be aware that this method may not be appropriate when using
VistALink RPC calls as the login user may not be permitted access to a
specific division.

Methods with a return type of java.lang.String:

getLoginStationNumber() Returns the Station Number of the Division the user
selected at login. This can be used as a key to retrieve additional
information (e.g., name about the login division from the TreeMap of permitted
divisions returned by the getPermittedDivisions method).

getUserDegree() Returns the user's Degree value from the NAME COMPONENTS file
(#20).

getUserDuz() Return the user's DUZ from the NEW PERSON file (#200).

getUserFirstName() Returns the users' First Name value from the NAME
COMPONENTS file (#20)

getUserLastName() Returns the user's Last Name value from the NAME COMPONENTS
file (#20).

getUserMiddleName() Returns the user's Middle Name value from the NAME
COMPONENTS file (#20).

getUserName01() Returns the user's name as it's stored in the NAME field (#
.01) in the NEW PERSON file (#200). For example: KRNUSER,ONE E

getUserNameDisplay() Returns the Display Name of the user, as put together by
the Name Standardization APIs on M. For example: One E. Krnuser

getUserParentAdministrativeFacilityStationNumber() Returns the parent facility
of the Division used for login, as resolved on the login computer system based
on that system's INSTITUTION file (#4) from the SDS V. 3.0 (or higher) tables.

getUserParentComputerSystemStationNumber() Returns the computer system's
default Institution/Computer System Institution, as identified in the system's
KERNEL SYSTEM PARAMETERS file (#8989.3)

getUserPrefix() Returns the user's Prefix value from the NAME COMPONENTS file
(#20).

getUserSuffix() Returns the user's Suffix value from the NAME COMPONENTS file
(#20).

toString() Returns a string representation of the values in the object.

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it is referenced in the consuming application's web.xml file.

Configure KAAJEE Startup Servlet (web.xml file)

This Startup Servlet is needed by KAAJEE to read configuration parameters.
For further information regarding these configuration parameters,
refer to the current KAAJEE documentation.

Configure this startup servlet in your application's web.xml file.
The following XML tags shown below are an example of how to configure this
startup servlet in the application's web.xml file:

<servlet>
<servlet-name>KaajeeInit</servlet-name>
<servlet-class>gov.va.med.authentication.kernel.InitKaajeeServlet</servlet
-class>
<init-param>
<param-name>kaajee-config-file-location</param-name>
<param-value>/WEB-INF/kaajeeConfig.xml</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

In the above example, the <param-value> contains the folder/path location and
KAAJEE configuration filename relative to the applications's webroot context.

Also, the <load-on-startup> value contains an integer value of the order in
which you wish this servlet to start among other configured startup servlets.

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it is referenced in the consuming application's web.xml file.

This servlet is the main controller servlet that processes the login request.
It must be configured in the application's web.xml file.  For further details
refer to the current KAAJEE documentation.

This class is included in the kaajee-x.x.x.xxx.jar file and
is not a separate component.  It is listed here only to describe
how it is referenced and associated with other component(s).

VistaDivisionVO Object

The VistaDivisionVO object is used to store an individual division, when
division TreeMaps (i.e., tree structure, keyed on Division Station Number
strings) are returned by the LoginUserInfoVO methods.

Listed below are the Class Definition, Constructor Summary and Method Summary:

public class VistaDivisionVO
extends java.lang.Object
implements java.io.Serializable


Represents a VistA Division, including Station Name and Station Number.


Constructor Summary

VistaDivisionVO()

Instantiates a VistaDivision with all fields set to a null string.


The methods listed below are for read-only access:

Method Summary

boolean       getIsDefault()

Returns whether or not this is set to the default
Login Division.

java.lang.String       getName()

Returns the Station Name of the Division,
presumably from the VistA M Server
INSTITUTION file (#4) entry (depending
on the source of the information
the instance contains)

java.lang.String       getNumber()

Returns the Station Number of the Division,
presumably from the VistA M Server
INSTITUTION file (#4) entry (depending
on the source of the information
the instance contains)

java.lang.String       toString()

Returns a string representation of the Division
information


(See also component gov.va.med.authentication.kernel.LoginUserInfoVO
regarding division TreeMaps returned)

In order to retrieve this VistaDivisionVO object from these division TreeMaps,
the following collection, iterator and methods may be used:

java.util.Set
Set java.util.TreeMap.keySet()
java.util.Iterator
Iterator java.util.Set.iterator()