Companies

Part of the user manual. Related: CONTACTS · EDMS · PERMISSIONS · TENANCY.

A company in REBIM is an organisation — a firm, supplier, subcontractor, or any party with a presence in the tenant's directory. Companies are a thin concept: a small set of identifying fields, plus links from contacts and document revisions. They live alongside contacts as the corporate side of the same directory.

TL;DR

  • DirectoryCompany rows are tenancy-wide entries. Created via the Contacts UI or Django admin.
  • Two display fields matter: code (short identifier, e.g. ACME) and name (full name, e.g. Acme Engineering Ltd). UI renders as [ACME] Acme Engineering Ltd.
  • Companies link in two places:
  • Contacts — each contact has a primary company FK plus a M2M affiliations list for secondary firms.
  • Document revisions — EdmsDocumentRevision.contractor FK identifies which company authored that revision (surfaces in the compliance dashboard's Contractor column).
  • Companies carry tenancy (TENANCY) like every other DataModel record.

Company fields

Field Purpose
name Full display name — "Acme Engineering Ltd"
code Short identifier — "ACME". Used as a [CODE] prefix in display strings.
address1, address2, locality, post_code Postal address — house/name, street, town/locality, post code
telephone Main switchboard number
email General email address
directory_industry (FK) Industry classification (Architecture, Engineering, Construction, etc.) — informational
tenants (M2M) Tenancy (TENANCY)
owner (FK to User) The user who created the company (DataModel field)

The code + name pair is the canonical display format. Both fields should be filled — code for the compact identifier prefix, name for the long form. The frontend joins them as [CODE] Name when rendering company-bound rows (People + Contacts tables, compliance dashboard).

Where companies surface

1. Contact primary company

Each DirectoryContact.company is an optional FK to one DirectoryCompany. This is the primary affiliation — "who does this contact work for, today?" One company per contact.

Used in:

  • The Contacts table's Company column.
  • The People table's Company column.
  • The compliance dashboard's Contractor column (indirectly — see below).

2. Contact affiliations (M2M)

DirectoryContact.affiliations is an M2M to multiple companies. Used when a contact is associated with several firms — consultants, people working across joint ventures.

Different from company (the primary FK). A contact's company should also typically appear in affiliations, but the system doesn't enforce that.

3. Document revision contractor

EdmsDocumentRevision.contractor is an FK to DirectoryCompany. It records which company authored this specific revision.

Surfaces in:

  • The compliance dashboard's Contractor column (per-document, taken from document.active_revision.contractor).
  • Compliance reports + CSV exports that group documents by contributing party.

The contractor on a revision is not automatically derived from the uploader's contact's company — they're independent. An admin might re-assign the contractor on a revision (via the modify-contractor bulk action — see below) even when the uploader is a different person.

The modify-contractor bulk action

REBIM provides a bulk "set contractor on multiple documents at once" action for compliance workflows. Usage:

  1. Open the EDMS Documents tab.
  2. Filter / search the documents to the set you want to re-tag.
  3. Trigger the bulk action — backend endpoint expects a modify_contractor POST with the target company's PK plus the list of documents.
  4. The backend sets document.active_revision.contractor to the selected company on each matching document.

Use cases:

  • Contractor reorganisation — Acme Engineering merges with Beta Consultants, retagging all Acme-authored revisions to the merged entity.
  • Bulk-correcting an attribution mistake on imported documents.
  • Compliance bake — ensuring a known set of documents is attributed to the right party for reporting.

This is a tenant-admin operation. See PERMISSIONS for who can run it (currently requires the WRITE PERMISSIONS group plus edit access on the documents).

Visibility and permissions

Visibility

Companies are tenancy-filtered only. A user with overlapping tenancy sees the company; otherwise they don't. No project-membership filter applies — companies aren't project-scoped.

A practical consequence: if you can see a contact, you can see their company too (because tenancy applies the same filter to both). There's no scenario where a contact's primary company is invisible to a viewer who can see the contact itself.

Permissions

See PERMISSIONS § Contacts — the same edit-gate rules apply to companies as to contacts. Summary:

  • View — anyone with overlapping tenancy.
  • Create / Edit / Delete — WRITE PERMISSIONS group + (project admin OR superuser OR row owner).

There's no dedicated "Companies" UI tab — company management is a side-effect of contact management + admin panel access. To manage companies in volume, use the Django admin panel directly (superuser only). The frontend handles routine "add a new company from the contact form" inline cases.

Practical operations

Create a new company

Two paths:

  • From a contact form (inline) — when editing a contact, pick "Add new company" in the company dropdown. Fills name + code; the rest can be added later via admin.
  • From the admin panel — Django admin → Directory → Companies → Add. Full form including address, industry, tenancy.

Edit a company

Admin panel. The frontend's contact form lets you change a contact's linked company but doesn't expose the company's own attributes for editing — that's deliberate (most users shouldn't need to change a company's name; if they do, it's a tenant-admin operation).

Re-tag a contact's primary company

Edit the contact. Pick a different company in the dropdown. Save.

Re-tag a document revision's contractor

Edit the document → manage revisions → change the active revision's contractor field. Or use the bulk modify-contractor action for many documents at once (see The modify-contractor bulk action).

Merge two companies

REBIM doesn't have a "merge" action. The manual flow:

  1. Pick the survivor company (the one to keep).
  2. For each contact whose company points at the disappearing company, edit them to point at the survivor.
  3. For each contact who has the disappearing company in affiliations, edit them to swap it for the survivor.
  4. For document revisions with contractor pointing at the disappearing company, use the modify-contractor bulk action to re-tag.
  5. Once the disappearing company has no references, delete it.

Referential integrity blocks delete if any reference remains.

Delete a company

Admin panel. Blocked if the company is referenced by any contact's company FK, contact affiliations, or revision contractor. Clear the references first (the merge flow above is the typical path).

Troubleshooting

Symptom Likely cause First check
Contact's company name displays as just the code (no name) Company has code set but name blank (or vice versa) Edit the company in admin, fill both fields
Compliance dashboard Contractor column blank for a document document.active_revision.contractor is null — the revision was uploaded without a contractor tag Manage revisions on the document, set contractor on the active revision
Can't delete a company Referenced by at least one contact's company / affiliations / revision contractor Clear references first (or use the merge flow); referential integrity will surface which refs remain
Same company appearing twice in the dropdown Two DirectoryCompany rows with the same name created independently. Common after data import Merge them (manual flow above)
Companies visible in admin but missing from the contact form's company dropdown Tenancy mismatch — the company's tenants don't overlap the viewer's tenancy Add the right tenancy to the company in admin
Bulk modify-contractor doesn't change anything visible The action sets active_revision.contractor, not the document's. If the doc has multiple revisions, only the active one was retagged Confirm the active revision's contractor; historical revisions retain their original tags

For developers

This page is for users and admins. Implementation pointers:

  • Models: apps.directory.models.DirectoryCompany, DirectoryIndustry. Both tenancy-aware DataModel subclasses.
  • Serializer: apps.directory.serializers.DirectoryCompanySerializer — used inline when companies are nested in contact responses.
  • Viewset: apps.directory.views.DirectoryCompanyViewSet — standard BimViewSet (tenancy-filtered list/CRUD).
  • The [CODE] Name display join is client-side, in app_contacts.js and app_people.js (grep for contact_company_name). If you want to change the format, those are the two render sites.
  • The contractor link on revisions: apps.edms.models.EdmsDocumentRevision.contractor (FK). Set via the revision form OR the modify-contractor bulk action in apps/edms/views.py (grep for modify_contractor).
  • No dedicated UI tab. If companies ever grow more complex — per-company project listings, contracts, certifications, etc. — a dedicated tab + viewset becomes worth building. Until then, admin-panel-only is correct.

See devdocs/ for codebase-level material.