Location: PHPKode > projects > Homeless Mangement Information System > hmis/READ_ME.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <title>Homeless Management Information System</title>
 <body link="#0000ff" vlink="#800080">
<p><font size="4" face="Arial Black">Homeless Management Information System 
  Updated 3/23/2004 
<p>  Current information on the HMIS program can be found at either <a
or <a href="http://homeless-mis.net">homeless-mis.net</a></p>
<p>  You are encouraged to provide your feedback (feature requests, bug reports, 
coding critiques, etc.) on the HMIS to <a
<p>  <b>Table of Contents</b><br>
  <a href="#install">HMIS Installation Instructions</a><br>
  <a href="#summary">HMIS Summary Description</a><br>
  <a href="#walk_through">Walk Through Demonstration of the System</a><br>
  <a href="#technical_summary">Description of the Technical Framwork of the 
  <a href="#security">Securing the HMIS</a><br>
  <a href="#development">Ongoing Development</a><br>
<p><a name="install"><font size="4" face="Arial Black">HMIS Installation Instructions</font></a></p>
  The HMIS depends on the Apache module version of PHP 4.x (<a
 href="http://php.net">php.net</a>); and either PostgreSQL 7.2 (or higher,&nbsp;<a
 href="http://postgresql.org">postgresql.org</a> ) or Microsoft SQL Server
2000 (or higher). <br>
The system was originally written/deployed on a Redhat 8.0 system (PHP 4
and Postgresql 7.2), and has been tested and deployed on a Windows 2000/IIS/SQL
Server 2000 platform. &nbsp;The system has also been tested on Debian/Sarge.<br>
The following installation instructions are for a Redhat 9.0 system, but
should work for any Linux distribution. The system is tested and deployed
on the Microsoft platform, but installation on Windows is not covered in
these instructions. &nbsp;If you want to do a Windows installation, modify
the /include/initialize.inc file as described in the file's comments<b>.<br>
These instructions will create an insecure demo version that under no circumstances
should be used in a deployed encvironment</b>. &nbsp;To actually deploy the
system, you must understand how to secure a web and database server, which
is not covered in these instructions. &nbsp;<br>
<p><i>Uncompress the files</i><br>
  Place the downloaded HMIS file in your html server root (/var/www/html/ 
on many systems), and uncompress the files (e.g., tar -xvzf /var/www/html/hmis-2.0.tar.gz). 
There should be four directories containing files; "/hmis", "/hmis/html_templates", 
"/hmis/include", and "/hmis/report_templates".  <br>
<p><i>Create the database</i><br>
In PostgreSQL, create a database called "hmis" that is accessible by the
"postgres" user.  By default, the system uses the "postgres" user with no
password. To get started, you need to allow password access to PostgreSQL
from PHP. To allow this edit /var/lib/pgsql/data/pg_hba.conf (In Debian /etc/postgresql/pg_hba.conf) 
as follows:<br>
In the section at the end, comment all lines out except:<br>
  <span style="font-family: monospace;">local&nbsp;&nbsp;&nbsp; all&nbsp;&nbsp;&nbsp; 
trust</span> <b><br>
<p><b>This default database setup is not secure; see <a href="#security">Securing
the HMIS</a> for details.</b> The PostgreSQL user and password can be modified
in the file "/include/initialize.inc". &nbsp;If you are using 
PostgreSQL 7.2 (i.e., Redhat 8.0) , comment out the line " $db_version
= 'pg_7.3' " in&nbsp;"/include/initialize.inc".   </p>
<p>From your browser, run the file "SETUP.php" (e.g., "localhost/SETUP.php"). 
You will be give the choice of setting up the system using test data, or setting
up a blank system. To experiment with the system, choose the option of importing
test data, and follow the directions in the <a href="#walk_through">walk
through</a>, substituting the system address with the address of your server
(e.g., "localhost/hmis/").<br>

I am interested in feedback on the installation process on different computers, so please contact me if you have issues at (360) 725-2930 or <a

   For help using the HMIS, see the "help.html" file (linked to at the top 
right of every page).</p>
<p>  </p>
<p><a name="summary"><font size="4" face="Arial Black">Homeless Management 
Information System Summary Description</font></a></p>
<p>The HMIS is an internet-based system to collect information on persons 
served by emergency shelters and transitional shelters.&nbsp; The system allows
for the collection and analyses of unduplicated, client-level information.&nbsp;
Properly deployed (see&nbsp;<a href="#security"><b><a
 href="file:///var/www/html/hmis/READ_ME.html#security">Securing the HMIS</a></b></a>),
the HMIS fulfills the <a
 href="http://www.hud.gov/offices/cpd/homeless/hmis/">HUD HMIS Data Standards</a>.<br>
<p>At the macro level this data can be used to assess the size and nature 
of the problem of homelessness, at state, regional, and individual shelter 
levels&nbsp; On the client level, the system can optionally be used (at the 
discretion of the shelter provider) to maintain client case histories, and 
share client histories with selected shelter providers.</p>
<p><b>Allowing Shelter-Level Customization is a Central Focus</b></p>
<p>It is unlikely that a single data collection scheme could ever be assembled
 that would satisfy even a minority of the hundreds of diverse shelter providers. 
The system attempts to address the diverse, and often divergent needs of different
providers using the following strategies:</p>
<p><i><b>System allows easy customization.</b>&nbsp;<br>
</i> The "core" system collects the information required by the <a
 href="http://www.hud.gov/offices/cpd/homeless/hmis/">HUD HMIS Data Standards</a>.
<p>Using a simple point and click interface, shelter providers can add their 
own questions to the report forms.&nbsp; Questions can be added at both the 
lead agency/county level, and at the individual shelter organization level.&nbsp;
 Providers can then use the data collected via the custom questions to measure
 subjects of particular interest to them, and/or to augment the client case
 histories collected by the system. None of the form are hard-coded into
the system - they are all defined in the database, so it is easy to change
the forms over time using the web-based point and click edit forms interface.</p>
<p><b>Client Confidentiality is Key</b></p>
<p>Although having better data on homelessness is important, preserving client
 confidentiality takes precedence.&nbsp; All client identifying information
is encrypted, and any other form field can be optionally encrypted, so that
a comprimise of the database does not result in the disclosure of private
<p style="page-break-before: always;"> </p>
<p><font face="Arial Black" size="4"><a name="walk_through">Walk Through of
the Draft Shelter Data System</a></font></p>
<p>This walk through is designed to introduce you to some of the features 
of the HMIS system.</p>
<p><b><font face="Arial">Logging Into the System</font></b></p>
<p align="left">1) Type the following in the address space on your web browser:
   <a href="http://homeless-mis.net/hmis/">homeless-mis.net/hmis/</a><br>
    2) In the "Enter Login" box, type: dorytildon<br>
    3) In the "Enter Password" box, type: droppingblue<br>
    4) Click on the "Press to Submit" button.<br>
    You should now be on the homepage of the Shelter Data System.   You will 
see on the top right of the page that you are logged in as user   "Dory Tildon," 
who works for the "Delta Shelter," which is s for the "Delta Shelter," which 
is    affiliated with the "Trundle County Housing Authority" group/lead  
<p align="left"><b><font face="Arial">Entering a new Client into System</font></b></p>
<p align="left">Click on "Add Clients" near the top   of the yellow menu
bar on the left of your screen.</p>
<p align="left">You should now see a screen with a series of forms, labeled
 "Household Member #1", "Household Member #2", etc. Fill in the blanks with 
an imaginary household, or so you can remember it later, enter your own household.&nbsp;</p>
<p align="left">Click on the "Click Here to Submit Form" Button on the bottom.</p>
<p align="left">After filling out the form, click on the "Click Here to Submit 
Form" button on the bottom of the page. If you made any errors, you will be
taken back to this page with the errors highlighted in red. Otherwise,  you
will be taken to the Household Intake page.</p>
<p>You can now continue filling out various type of reports for this household
by choosing the menu items "Clients" or "Households".&nbsp; </p>
<p align="left"><b><font face="Arial">Finding Out How Many People Were Served</font></b></p>
<p align="left">Click on the "Query Clients" button on the yellow menu bar
on the left of your screen. You should now see a list of reports you can
run queries against.  Check the box associated with "Client Profile" and
click on the "Submit Selection" button.</p>
<p> You should now see  questions you just saw on the previous "Client Profile"
report you sbumitted earlier.&nbsp; Try selecting different parameters on
the page, and clicking on the "Submit Query" button on the bottom of the page.
The "Count of..." text near the top of the page tells you how many clients
and/or households (depending on the reports you are querying) match the criteria
selected below. Because there are only a handful of demonstration client
reports in the system, many complex queries result in a count of "0".<br>
<p><font face="Helvetica, Arial, sans-serif"><b>Creating Reports</b></font><br>
<p>"Canned" reports can be accessed, such as the HUD Annual Progress Report,
by clicking on the menu item "View reports." &nbsp;other canned reports can
be added as needed using a templating system.<br>
<p align="left"><b><font face="Arial">Looking up a Client Already in the System</font></b></p>
<p align="left">Click on the "Clients" button on the yellow menu bar on the
left of your screen.</p>
<p align="left"> </p>
<p>You can look up clients already in the system by using the search fields.<br>
<p align="left">Type "Ted?" in the First Name field, and click on the submit
<p align="left">You should now see "Tedd Kelleher" as one of the search results
at the bottom of the screen. &nbsp;<br>
<p align="left">Click on the name "Tedd Kelleher" and you will now see a
profile of that client, including all the reports submitted for him any any
people related to him.<br>
<p align="left"><b><font face="Arial">Vacancy Report and Referral</font></b></p>
  You can use the system to track vacancies throughout a community, and refer 
a client (and their associated client information) to other organizations. 
<p>  Click on "Referrals/ Vacancy Report"menu item. You will see a list of
organization vacancy information. &nbsp;To refer "Tedd Kelleher" to "Alpha
Shelter" clikc on the dropdown box for Alpha Shelter under the column "Refer
household by selecting referral type below."</p>
<p>You will now see a refferal report. &nbsp;When you submit the form, Alpha
Shelter will receive an email notifying them that you have made a referral.
&nbsp;The email will contain a link that takes them directly to the referral
<p>    </p>
<p align="left"><b><font face="Arial">Defining Custom Questions For Inclusion 
in Your Reports</font></b></p>
<p align="left">The system is build around a philosophy of customization.&nbsp;
 Questions included on any form can be defined on the shelter  organization
level, and the lead agency/group level.&nbsp;&nbsp;</p>
<p align="left">This means shelters in county as a whole could decide to collect
information on veteran status, and an individual shelter in that same county
could choose to collect information on the primary cause of homelessness.</p>
<p align="left">This interface allows users to  1) Add your own questions 
to any of the reports, which will be used by anyone below you in the system 
hierarchy 2) Add optional questions that organizations below you can choose 
to use in their report. To customize the questions collected by the "Delta
 Shelter" organization, you must be logged in as the "Organization Administrator." 
Click on the "Log Off the System" button on the bottom of the yellow menu 
bar on the left of the screen.&nbsp;&nbsp;<br>
  In the "Enter Login" box type: rogernelson<br>
  In the "Enter Login" box type: inkswelling<br>
  Click on "Press to Submit."<br>
  You are now logged in as Roger Nelson, "Program Administrator" of the "Delta
<p align="left">Click on "Edit Forms" button near the bottom of the yellow
menu bar on the left side of your screen.</p>
<p> You should now see a list of reports that are available for you to edit.
You can edit any of the reports shown, using the interface presented.   </p>
<p align="left"><b><font face="Arial">Choosing What Users and Other Organizations
Can View Client Reports</font></b></p>
<p align="left">If you did not log in as the "Delta Shelter Organization
Administrator" as described above, do that now. Click on the "Set Permissions"
button on the yellow menu bar.</p>
<p align="left">By selecting various options shown, you can choose who client
 records your organization creates are shared with.&nbsp; At one extreme
you can share with everyone.&nbsp; At the other extreme, you can choose to
not share with yourself, so that once you enter a record it cannot be retrieved 
by anyone<b><font face="Arial">.</font></b></p>
Client Service Repor  Each report also gives the user the option of choosing
to "not share" the client information, overriding system sharing preferences
defined by the process above.<br>
In addition to choosing who has access to records, you can choose to have
an email sent to oneor more individuals every time a report action is taken
by clicking on the "Notified by email when reports are accessed" checkboxes.<br>
<p align="left"><b><font face="Arial">For More Information</font></b></p>
<p align="left">For more information or to comment on the system, contact 
Tedd Kelleher at (360) 725-2930 or <a
<p><a name="technical_summary"><font size="4" face="Arial Black">Description 
of the Technical Framwork of the HMIS</font></a></p>
   The HMIS is basically a set of PHP classes and functions that can generate 
HTML forms and store the submitted responses in a database. There are three 
basic pieces to the system: 
<p>  <b>User Authentication and Permissions</b><br>
  The HMIS classifies its users into a hierarchy of four categories (System 
Administrator, Group Administrator, Organiation Administrator, and System
 User). The System Adminstrator can setup groups, the Group Administrator 
can setup Organization Administrators, etc.  This hierarchy reflects the homeless
shelter system in Washington state, where "Groups" (counties) are lead agencies
collecting data on subcontractors (homeless shelters), which have staff (System
Users) that actually interact with the homeless.  Pieces of this system hierarchy
can easily be eliminated (ignored) by HMIS users that do not need so many
<p>  <b>Questions and Answers</b><br>
  Most of the questions/forms the system generates are created using data 
stored in the database.  The type of question (text, radio buttons, etc.), 
title of questions, default values, etc. are all contained in the database.</p>
<p>  The HMIS collects two types of reports; reports on clients and reports 
on households.  Households are defined as collections of clients.  This allows 
the system to easily track clients if they leave a particular household and 
join another, since clients are distinct from the households they are members 
<p>    There can be an unlimited number of reports in the system.  Currently 
the system only contains the reports necessary to fulfill HUD McKinney requirements.
  HMIS users at the System Administrator, Group Administrator, and Organiation
Administrator levels can easily add/edit the questions in the HMIS using
a point and click interface.  In fact, the exisiting questions could be easily
stripped out, and new questions could be added to track the outcomes of radially
different activities (e.g., "Miles of sewer pipe laid by city contractors").</p>
<p>     <b>Query of Stored Reports</b><br>
  Data entered into the system be queried using the query interface.  The 
generic interface can generate queries based on client and household characteristics.</p>
<p>  A good understanding of the database tables that make up the heart of 
the system can be obtained by reading the descriptive comments in the file
 "SETUP.php." Many of the most important classes and functions can be understood
by reading the comments contained in the associated *.php and *.ini files.</p>
<p>  If there is a specific section of code or functionality you would like 
help understanding, please don't hesitate to contact Tedd Kelleher at <a
or by posting at <a href="http://sourceforge.net/projects/hmis/">sourceforge.net/projects/hmis/</a>. 
 I will write documentation to address your specific needs, and/or guide you
through the specifics regarding the use and modification of the HMIS.  I
am in the process of actively developing better documentation, so please send
in your requests to guide my work.</p>
<p>  </p>
<p><a name="security"><font size="4" face="Arial Black">Securing the HMIS</font></a></p>
  No computer system is completely secure.  Improving the security of the 
HMIS system is on ongoing process that includes proper setup of the webserver,
database, your operating system in general, user policies, etc. If you do
not have the expertise to properly harden the security of the HMIS setup
yourself, there are a many reputable consultants/companies that can be contracted
with to setup and maintain relatively secure Linux/Apache/PostgreSQL/Unix 
or Windows/IIS/MS-SQL environments . 
<p> Below are <b>some</b> (not all) of the things you would need to do to
improve the security of your installation of the HMIS:</p>
<p>  Restrict access to the "*.inc" files. It is important that users are 
prevented from viewing the "*.inc" as plain text.  This can be done by restricting 
access to the "include" directory via your Apache "http.conf" file, and/or 
by modifying "http.conf" so that "*.inc" are parsed by Apache using PHP. 
You can also move the "*.inc" files to a directory completely outside your 
html root by modifying the include path defined the the HMIS system file "initialize.inc".</p>
<p>  Change the default postgres users to some other PostgreSQL user with 
more resticted rights and a secure password. The DB login/password are stored 
in the HMIS file "db_connection.inc".  Also, the access rights of the PostgreSQL 
user with access to the HMIS can be tuned to improve security.<br>
<p>Turn on encryption of the database. &nbsp;By default, encryption is disbaled
for this demo because some PHP installations (i.e., Redhat) do not support
the mcyypt extentions. &nbsp;Mycrypt support can be added to Redhat Linux,
and is standard on Debian Linux.<br>
<p>  In PHP's "php.ini" (located at /etc/php.ini on many systems) file set 
"register_globals to "Off".  Deploy the HMIS on a system using SSL, so that 
logins/passwords and client information are not being transmitted over the 
internet in plain text.</p>
<p>  Setup user policies regarding passwords, client machine security, firewalls, 
<p><a name="development"><font size="4" face="Arial Black">HMIS Development</font></a></p>
  The HMIS is currently under active development, with feedback from advisory 
groups and operating sites leading to changes almost every week. 
<p>    The system continues to be refined and tested using feedback from the
operating sites. If you have suggestions, please don't hestiate to contact 
Tedd Kelleher at hide@address.com</p>
Return current item: Homeless Mangement Information System