List of Projects MetPlus System Behavior and Design

System Behavior and Design

Updated about 6 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:

  1. 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. 
  2. 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:

  1. The AA fills out a form for the new person that includes the person's name (first, last) and email address.
  2. 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.


    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:

    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


    comments powered by Disqus