Skip to content

Module relationships

Why this matters

Relationships are the connections between modules: a case "belongs to" an applicant; an applicant "has many" cases; a case "has many" documents; a company "has many" cases and "has many" contacts. These connections are what makes ImmCase not just independent lists — they're what generates related tabs and lets you navigate between records.

Relationship types

  • belongsTo — a record points to another. Example: a case belongs to an applicant. Implemented with an FK column.
  • hasMany — a record has several on the other side. Example: an applicant has many cases.
  • hasOne — a record has exactly one on the other side. Less common.
  • belongsToMany — many-to-many with a join table. Example: applicants and consultants (an applicant can be handled by several consultants; a consultant handles several applicants).
  • morphTo / morphMany (polymorphic) — a record can relate to several distinct record types. Example: a comment can belong to an applicant or a case indifferently.

Create a relationship

  1. Open the source module → Relationships tab → Add relationship.
  2. Fill in:
  3. Relationship type.
  4. Target module.
  5. Name of the relationship (how it's called in code, templates, etc.).
  6. Label of the related tab (what the user sees).
  7. Foreign key (if applicable) — which field holds the reference.
  8. Save.

ImmCase: - Creates the FK column in the source module's table (if belongsTo). - Generates the related tab in the parent module's detail view. - Allows accessing connected records in templates and reports.

Screenshot: relationship editor with type, modules, and foreign key

How relationships look in use

In an applicant's detail, the Cases, Companies, Documents tabs are each a relationship made visible. When you enter the Cases tab, what you see is: "every case where the applicant_id field points to this applicant".

ImmCase uses the related module's display_name field to show each record in the list. That's why it matters to have display_name well configured.

Modify or delete relationships

  • Rename the label — instant, no effect on data.
  • Change relationship type — only viable if there's no data; with data, can corrupt.
  • Delete the relationship — the tab disappears but data (related records) remains — just visually disconnected. You can recreate the relationship later and they reconnect automatically if the FK is still present.

Common patterns in ImmCase

  • Case belongsTo Applicant.
  • Applicant hasMany Cases.
  • Case belongsTo Company (sponsor, employer, school).
  • Company hasMany Cases.
  • Case hasMany IMM forms.
  • Applicant hasMany Documents (polymorphic).
  • Case hasMany Documents (polymorphic).

Watch out for

  • Polymorphic relationships are complex. If you need a comment to belong to an applicant OR a case, it's polymorphic. Useful but harder to maintain — ask your technical administrator before configuring.
  • Foreign keys with data don't change. If you rename the FK, existing data loses the reference. Decide the name well from the start.
  • Deleting the parent can affect children. If you set the relationship with cascade, deleting an applicant deletes their cases automatically. If you set with restrict, deleting the applicant fails while they have cases. Decide based on risk.

Where to next