TMF Phase 1 Engineering Specs

This page contains CiviCRM Engineering specifications for phase 1 of the TMF Project - Nominations and Applications

Drupal Setup

Implement Student and Nominator as Drupal roles
Configure Drupal to automatically assign self-registering users to Role = Student
Implement a CiviCRM Profile for User Registration which collects name and address info from self-registering users. (A dump of this profile definition should be added tmf/sql/tmf_data.mysql)
Implement login_toboggan module if desired to allow new users to pick a password, etc.
Implement login_destination or similar module to redirect user to TMF locker module after login
Implement TMF Locker module which displays content and links based on Drupal role, CiviCRM contact ID, and CiviCRM task status. (CiviCRM-related locker content and APIs to retrieve the CiviCRM info are described below.)

Drupal / CiviCRM Application Flow

Nominators

Nominators are created by SPO via Drupal admin, and assigned Role = Nominator. Login information is emailed to them (automatically by Drupal? or ??).
On login, they are redirected to the TMF locker.
The TMF locker provides Nominators with links to "nominate a student" and to "edit (existing) nominations"
When a nomination is submitted:
- Send "invite" email to nominated student with link to verify login form when a nomination is submitted.
- Send cc: of invite to a specified TMF staff member.
- Create Drupal user record (role=Student, status = Blocked)
- Create CiviCRM contact record (sub_type = "Student").
- Create CiviCRM student record (tmf_student with Scholarship Type = Vista).

Nominated Students

The nominated student links to the "login verification" form from the invite email.
They enter their email address and select a Drupal user password.
On submit, they are redirected to the TMF locker.
The locker provides "new" students with link to "Application pre-screening"
Once prescreen is completed, student is directed to begin the application. At this point, the locker will provide links to Start, Edit and/or View Application (based on application status - details below)
When application is completed, email is sent to student with cc: to specified TMF staff

Self-registering Students

These students use the standard drupal "register" link and enter user name + TMF determined contact info (as configured in a CiviCRM Profile)
Upon registration, they are automatically assigned the Student role and redirected to the TMF locker.
Remaining work-flow is the same as for registered students

Tasks and Task Statuses

The following tasks will be used to track Nominator and Student actions for this phase:

Application Prescreen
Scholarship Application
- Personal Section
- Household Section
- School Section
- Essays Section
Scholarship Nomination

Each task will have an associated status. Possible values are:

Not Started
In Progress
Completed
Cancelled
Deferred

NOTES:

Prescreen submissions that don't meet the "requirements" will carry a status of "In Progress" for that task.
Set Scholarship Application task status to "Completed" when all sections are "Completed"

TMF Locker

This is a module which provides links, task status information and other resources as specified by TMF including deadlines, documentation requirements, etc. Users see the appropriate links and content based on their "role" (Student or Nominator)

Student Locker

Student locker will include different links depending on current task statuses for the Prescreen and Application tasks.
Task statuses are retrieved using a CiviCRM API (see below).
If Prescreen task status = Not Started or In Progress - display link to "Prescreen"
If Prescreen task status = Completed - display links to "Edit" and "View" your scholarship application.
- If Scholarship Application task is Not Started, link text could be modified to say "Start Your Application", etc. The locker module will control this behavior after evaluating task status.
- CA should check w/ TMF about business rules for determining when an application is no longer editable. Example - should a student be allowed to continue editing a "Completed" application?

Nominator Locker

Includes the following links:

Link to "Nominate a new student" (always visibile)
Listing of Nominated students w/ status for each nomination. This info is retrieved using CiviCRM API (see below).
- If status = In Progress, link to Edit Nomination.
- If status = Completed, link to View Nomination.

CiviCRM APIs for the Locker Module

The following code is needed in the locker module to initialize CiviCRM and include needed php files:

The following APIs are used by the Locker module:

crm_uf_get_match_id ($user->uid)

This is a core API. Locker invokes this on initialization to retrieve the corresponding CiviCRM contact ID for the logged in user.

CRM_TMF_API::getStudentTasks( $contact_id )

This is invoked by the locker for the Student role - it returns an array of all existing tasks with task status for each and formatted links (href's) where appropriate for the student. The locker code will evaluate statuses and determine which items to display and which links to render based on TMF business rules.

CRM_TMF_API::getNominations( $contact_id )

This API returns status and links for all existing nominations for the specified Nominator. Invoked by the locker for the Nominator role.

CRM_TMF_API::getTaskStatus( $responsibleID, $targetID, $taskID )

Use this API to get the task status for a given task and a specific combination of responsible and target contact Id's. The Nominator locker uses this to check on the status of the "Nominator Contact Information" task (task Id = 13):

Creating locker links

The locker should use the following function to format a "Prescreen" link:

The locker should use the following function to format a "Begin Scholarship Application" link:

The locker should use the following function to format a "Enter Nominator Contact Information" link:

The locker should use the following function to format a "New Nomination" link:

New User Verification Form

This is the form that nominated students are linked to in their invite emails.
The form elements and layout can be exactly the same as for Quest version (Quest/Form/Verify.php).
Successful postProcess should invoke quest_drupal_user_update_and_redirect ($params) - same as Quest version. This locker module function updates the user status to Active (not Blocked) and redirects them to the locker.

Pre-screen

This is a wizard/controller with a single form. Path: civicrm/tmf/prescreen. Params: id=$contact_id

Prototype is here: http://mcconnell.civicactions.net/mockups/preScreen.php
Form fields are not persisted in DB.
If the scholarship type is known, only present the corresponding "block" in the second half of the form. Else, present both blocks. (tmf_student.scholarship_type_id uses option_group values from "scholarship_type" option_group)
Prescreen will check for contact_sub_type in preProcess. If sub_type is SET and is NOT 'Student', abort w/ error message.
PostProcess: If all checkboxes are checked:
- Create student record if not created already. Set is_prescreen = 1 and scholarship_type_id to Scholar or Vista based on which submit button is clicked
- Contact sub_type is set to 'Student'
- Redirect to main application: civicrm/tmf/app?reset=1&id=$contact_id

Nominate Application

This is a wizard/controller with 4 forms (no sections). Path: civicrm/tmf/nominate. Params: id=$contact_id&scid=$student_contact_id&action=add or update. (scid is not passed for action = add)

Prototype is here: http://mcconnell.civicactions.net/mockups/nom_personalInformation.php
Nominator Information
Populate civicrm_county table with options as shown in mockup by adding inserts to tmf/sql/tmf_data.sql.
Implement county functionality for our standard address block (select, setDefault, save to civicrm_address.county_id.).
Implement county_other as a custom field.
Use "Mailing" as nominator location_type and set is_primary = true
The remaining 4 fields (Place of employment, title, how long knows, relationship to student) are moved to the next screen. These are stored in StudentRanking table.

Student Information

Name/address/phone/email info on this form is stored in standard CiviCRM fields, sub_type = "Student"
The 4 fields moved from the prior form are stored in StudentRanking
PostProcess
- Validate that email address is NOT the same as the Nominator email address
- Check for existing CiviCRM contact with matching name+email. If found, update student contact info, else insert new contact with address, phone, email info. Use "Home" as student location_type and set is_primary = true. Calculate and set a contact hash (as we do for Quest Recommender contacts).
- Create Student record (tmf_student with Scholarship Type = Vista) if one doesn't already exist.
- Create StudentRanking record to store remaining fields. NOTE: There should be one StudentRanking record for each student+nominator combination - students may have multiple StudentRanking records
- Create Nominator / Nominatee relationship between the two contacts.
- NOTE: This sequence of DB operations should be run inside a single transaction

Student Assessment

All info on this form is stored in tmf_student_ranking

Written Assessment

All info is stored in tmf_essay.
Insert appropriate tmf_essay_type records (include inserts in tmf/sql/tmf_data.mysql)
Change button text on this form from "Save and Continue" to "Submit Nomination"

On Nomination Completion

When nomination is submitted (completed):

Invoke locker function to create Drupal user record (role=Student, status = Blocked): tmf_drupal_create_user() (This function should NOT create user for student if one already exists.)
Send "invite" email to nominated student with link to verify login form when a nomination is submitted. This is same as Quest Recommender invite logic. There should be two templates - one for new or not-verified user, and one if user is already verified.
Send cc: of invite to a specified TMF staff member.

Scholarship Application

General Comments

This is a wizard/controller with four sections. There is a task associated w/ each section - and a "meta" task for the entire application. The controller needs to set task statuses on form submits.
Prototype is here []
Students can not apply for BOTH programs (tmf_student.scholarship_type_id indicates which scholarship program they are applying for)
Some forms have conditional fields based on scholarship type.
There will not be a "Submit Application" form. When the Submit Application link is clicked OR when the final form page in the Essays section is submitted, the controller checks that all sections/forms are complete. If true, set Scholarship Application task status = Completed and redirect to Locker.

Personal Section

Populate civicrm_county table with options as shown in mockup by adding inserts to tmf/sql/tmf_data.sql.
Use new county functionality (implemented for Nominator above) (select, setDefault, save to civicrm_address.county_id.). [
Implement county_other as custom field (same as for Nominator contacts)

Household Section

(TBD)

School Section