List of Projects MetPlus System Behavior and Design

System Behavior and Design

Updated over 2 years ago by Patrick Bolger

Job life-cycle states:

Old State	New State	State change trigger	User who initiates state change	Business requirements on state change / in state
null	active	Job is created in PETS	Company admin Company contact Job developer	All agency job developers are notified of new job posting Job applications can now be made for the job
active	filled	Job Application is set to 'accepted' by user	(see JobApplication state change table)	(see JobApplication state change table) No job application can be made for the job
active	revoked	Job status is set to 'revoked' by user	Company admin Company contact Job developer	All agency job developers are notified of revoked job posting No job application can be made for the job
revoked	null	Job is deleted by user	Company admin Company contact Job developer	(see 'JobApplication' state change table)

For MVP, the last state change (revoked > null) will not be implemented.

JobApplication life-cycle states:

Old State	New State	State change trigger	User who initiates state change	Business requirements on state change / in state
null	active	JobApplication created	Job seeker Job developer	Job seeker's case manager notified Job seeker's job developer notified Company person (associated with job) is notified
active	accepted	Job Application status set to 'accepted'	Company admin Company contact	Job developer (primary) is notified New Job Applications not allowed Other Job Applications (for same job) are set to 'not_accepted' Job status set to 'filled'
active	not_accepted	Job Application status set to 'not_accepted'	Company admin Company contact Job developer	Job seeker is notified Job developer (primary) is notified
(any)	null	Job Application is deleted	Job seeker Job developer	Job developer notified (if Job seeker deleted the application)
(any)	null	Job is deleted by user	(see 'Job' state change table)	All associated Job Applications are deleted

For MVP, the last two state changes (any > null) will not be implemented.

User Authorizations Matrix: here.

Event Management: please see document here.

Action: Login

All users login using the same page and entering the same type of credentials (email, password). After the user is authenticated, we determine the type of user (job seeker, agency person or company (employer) person).

After login, the system sends the user to:

Home page (user = job seeker)
Company landing page (user = company person)
Agency landing page (user = agency person)

Action: Job Seeker Registration

There is wording on the home page specific to job seekers - describing the agency, the benefits of being associated with the agency, etc - and asking the site visitor to register via the button on the home page (currently in the upper right-hand corner). That button takes the user to a specific JS-registration page, where the visitor enters login credentials (email, password) as well as other data, such as name, year of birth, address, phone number, cell phone number (for text messaging), etc.

When all required information is entered, the user account is created and is available for use immediately.

*A word about company (employer) roles* - before describing employer registration actions, it is important to understand the two "roles" that a company person can take (aka "Company Person"). Note these describe actual persons who are associated with (presumably employees of) the Company (Employer):

Company Admin (CA) - there can be more than one CA per Company. This person can add and remove other employer people (Company Contacts) in PETS. This person can also perform all actions that an Company Contact can do.
Company Contact (CC) - this person can manage job postings from the Company - add, edit, delete, etc. There can be many CC's per employer.

Action: Company Registration

There is wording on the home page specific to employers - describing the agency, the benefits of being associated with the agency, etc - and asking the employer visitor to register via a separate link or button (separate from that used by the job seekers). That link takes the user to a specific company-registration page, where the visitor enters company information (EIN, company description, principal (local) address, website, etc.).

The registrant must also enter contact information for a contact person at the employer. (this contact person will become the default Company Admin (CA) if the employer registration is approved). This contact information includes:

Name (first and last)
Title
Email
Phone number

When the information is submitted, an email is sent to the contact person, confirming receipt of the registration request and stating that the agency will review the request.

At this point, there is a record created for the company, with status set to 'Pending Review'.

Also, there is a User record and a CompanyPerson record created for the company contact.

The User record does cannot be used to login.
The CompanyPerson record has status of 'Pending'.

Action: Review Company Registration

The agency admin can see the review task on the main admin page.

PENDING: The admin is also notified of this task (and other pending tasks) by a message upon logging in (probably by a flash message).

The agency now conducts whatever review process they want (that workflow/process is not managed by the system). When that is complete, the agency admin will view the task and accept the registration request (if it was in fact accepted by the agency).

When "accepted", the Company record is set to 'Active'.

The company contact will be activated as follows:

An email (subject: "Registration approved") is sent to the company contact. The email will state that the company registration has been accepted, and that the contact (receiver of the email) should will also receive a second email with instructions to activate their (personal) account in PETS.
The second email (subject: "Confirmation instructions") contains a link that the receiver will click on. The user's account will be confirmed in PETS (via an activation token in the link URL). Then, the following occurs:

The CompanyPerson status is changed to 'Active',
The contact is automatically logged in,
The contact is directed to a company admin home page (similar to agency admin home page), where features for a company admin will be available (such as inviting another company person to create an account in PETS).

If the company is "rejected", an email could be sent to to the company contact stating this rejection (language to be confirmed with client). The registration request will be maintained for historical reporting purposes. (alternatively, we could just be silent on a recommendation - this is a question for the client).

See design notes for this system behavior below.

Action: Company Contact Management

When the Company Admin logs in, they are sent to the company landing page. That page will have a top-menu item of "Employer Contacts" (visible only to 1) the company admin, and 2) the agency admin). When that menu item is chosen, the user will be sent to a page list all company contacts (including the company admin). The user will then be able to do the following:

Invite another employee (of the same company) to register as a PETS user - see below.
Delete a company contact.

Action: Company Person Registration

This process will essentially mirror the "Agency Person Registration" process below, with particulars changed as appropriate.

Action: Agency Person Registration

The registration of a new Agency Person occurs as follows:

The AA fills out a form for the new person that includes the person's name (first, last) and email address.
The AA submits the form, at which point:

An invitation email is sent to the new agency person.
The AA is directed to the 'Edit Agency Person" page, where the AA can set attributes for the invited agency person, including:

Role(s) (Job Developer, Case Manager, etc.)

Associated Job Seekers (for which this person will be the 'primary' job developer)
Job specialities

The invitee clicks on an "Accept invitation" link in the invite email.

The invitee is directed to a page where he enters (and confirms) his password.

Then, the new person is automatically logged in, the AgencyPerson status is set to 'Active', and the user is directed to the agency landing page.

DESIGN NOTES

This section will contain a description of pertinent aspects of the design of some of the behaviors listed above. This is useful because many (possibly all) of the implementations of these behaviors will involved code changes occurring in multiple places in the code base. The notes here will help a code reader make sense of that.

Action: Company Registration

Action: Review Company Registration

The company registration process will be managed by a dedicated controller: company_registrations_controller.

Create company

company status = 'Pending Approval'

Create user and send email:

don't send confirmation email but send specialized email

@user.skip_confirmation_notification! (before saving)
http://stackoverflow.com/questions/4790685/devise-is-it-possible-to-not-send-a-confirmation-email-in-specific-cases-eve

Email delivery scenarios

email address valid (delivery occurs)
email address invalid (added waffle issue to address later)

set user.approved = false

migration to add 'approved' to users table
configure as defined here: https://github.com/plataformatec/devise/wiki/How-To:-Require-admin-to-activate-account-before-sign_in

Company approval process (agency admin feature)

list of companies on agency_admin_home page (with status shown)
click on company name to see details (companies#show)

buttons:

'Approve Registration' (if status = 'Pending')
'Delete' (with confirm dialog box)
'Edit' company registration (see below)

cannot change company status
can change company contact info

link back to home (root) page

company registration 'show' view

add 'company contact' data
add address info

When registration is approved:

Set status of company to 'Active'
Set approved = true for company contact
Set company person status = 'Active'
Send email to company contact with link to login

user.send_confirmation_instructions (send deferred confirmation email)

Routes: (all to same controller: company_registrations_controller)

namespace: 'companies' (accessible to all)

new
create

namespace: 'admin/companies' (agency_admin only)

approve (registration)
destroy
edit
update
show

Revisions

Sub-documents

PETS system full description - created by Joao Pereira about 3 years ago