College Match - Section 12 Recommendations

This issue covers form rendering, validation, post-processing for new section 12 as shown in the mockups:
http://www.questbridge.org/app_staging/cm/appl/recommendations.html

Background
----------------
Submitting this form triggers a series of processes that results in the named teachers and counselor being asked to login to the site and file out a multi-page "Recommendation Form" about this student. The "people" that are entered on this form will be instantiated as civicrm_contact records as well as Drupal users. They will be assigned a task of "submitting a recommendation" for this student - and the resulting task_status records are the "link" between those contacts and rows on this form.

Form Processing
-----------------------

• Preprocess - Populate High School drop-down by retrieving organization_name for any org contact related to the student with civicrm_relatiionship_type.name_b_a = "School of" (relationship_type.id=8). There should be at least one such contact relationship. (These relationship(s) are created by the High School and Other School forms which will be required pre-requisite to this form.)

• Applicant (student) enters two teachers and one counselor in the Recommendations section and submits form. (all fields required in all 3 rows)

• For each of the 3 entities, application code checks for duplicate contacts on Email address. (NOTE: We do NOT use School field from this form for duplicate match - as some counselors (and possibly teachers) may work at multiple schools.) For each "recommender":

• • If no match on email address:
• Create a new contact record. (Make sure a hash (civicrm_contact.hash) is populated for each inserted contact.)
• Assign contact record to "Recommenders", AND either "Teachers" or "Counselors" (CiviCRM) groups.
• Create relationship "Teacher / Student" OR "Counselor / Student" between new contact and student (relationship_type.id=9 and 10).
• Create relationship "Teacher / School" OR "Counselor / School" between new contact and related high school org contact (identified by drop-down on recommender form). (relationship_type.id=11 and 12)
• Create Drupal user account. Use contact email for BOTH the Username (users.name) and Email (users.mail). Set verified status to FALSE (Paras is researching the correct way to set NOT VERIFIED status). Assign to Drupal Recommender role.
• Create uf_match record (links user to contact).

• • If match on email address:
• Create relationship "Teacher / Student" OR "Counselor / Student" (type 9 or 10) between matching contact and student.
• Check for existing relationship "Teacher / School" OR "Counselor / School" (type 11 or 12) between contact and related high school org contact and create if it doesn't exist.
• Check if already member of applicable CiviCRM Groups - "Recommenders AND ("Teachers" OR "Counselors"). If not, assign to group(s).

• Create Task Status record for the task Submit Recommendation (civicrm_task.id = 10)
• Responsible entity is teacher or counselor. Target entity is student. Initial status is Not Started.

• Send templated email to each teacher/counselor contact with text requesting them to complete the Recommendation form for the student. There are two cases that the Email template needs to handle (Quest will provide the final text for these - so you can just put in some placeholder stuff and the appropriate links):

1. If this teacher/counselor is a new contact, OR if it's an existing contact AND the associated Drupal User is NOT VERIFIED... email contains a link to a custom Verify Registration" form. This link includes contact hash value (h=) and an MD5 encrypted copy of their email address (m=).
2. If the teacher/counselor contact record already exists AND the associated Drupal User is VERIFIED...email contains a link to Drupal account login page.

NOTE: We are still confirming the Drupal convention for "verification". For now, let's use the Drupal users.status boolean as the verified flag.

• A student may decide to change Recommenders as long as the recommendation status from that person is Not Started or In Progress.
• When a recommender is "replaced", we follow the steps above for creating/updating recommender tables AND set the task_status for the "removed" recommender to Cancelled (task_status.status_id = 330). We also need to email the 'replaced' recommender regarding the status change (this could be a third case for the email template described above).

State Machine
-------------------
Add this new section to state machine. It must be completed and the High School section must be submitted/valid before this section is started.