Skip to content

Moving a Domain Between Companies Developer Guide

Ed Mozley edited this page Nov 19, 2026 · 1 revision

πŸ› οΈ Moving a domain between companies - Developer Guide

(#384, built by @cloudcogsio, merged for 5.7.0.) For someone changing the move, or adding a company-owned field to domains.

User guide: Moving a domain between companies.

πŸšͺ Front door

Every rule is in one method: DomainsService::moveToCompany() (includes/services/domains.php). The page's endpoint and the REST route are thin adapters over it, so they cannot disagree about what a move means. If you add a column to domains that points at a company-owned record, add it to moveClearFields() - otherwise a moved domain keeps a value its new company cannot see or pick.

πŸ“ Files

File What it does
🟣 includes/services/domains.php moveToCompany(), moveGroup(), moveLinkCounts(), moveClearFields()
🟣 api/domains/move_to_company.php The page's endpoint: POST {id, company_id}, CSRF-checked
🟣 api/v1/resources/domains.php apiDomainsMoveToCompany(); apiDomainsUpdate() refuses a different company_id
βšͺ api/v1/lib/routes.php, openapi_schemas.php, spec.json Route, DomainMoved schema, reference
🟑 domains/view.php + assets/js/domains-view.js Move button and dialog (mMove, ids mv*)
βšͺ lang/*/domains.php move.*, hist.f.company, hist.f.cost_centre_id, help companies.p5/p6
🟒 tests/domain-move-company.php 25 checks, including REST over HTTP with FREEITSM_TEST_URL; refuses to run unless the database name contains "test"

🧱 What moves together

A subdomain must be in its parent's company, and a name's Public and Internal records are twins only within one company (domainTwin(), #249). So the move takes the whole group those two links join - the domain, its twin, and the subdomains of either, followed until nothing new turns up (capped at 1,000):

$group = self::moveGroup($conn, $row, $oldStore);   // id => true, the domain included

Asked to move a subdomain, it refuses and names the parent - dragging a parent along unasked would surprise.

πŸ”’ Access, and one message for two cases

The actor must reach the source (loadForActor(), 404 otherwise) and the target. Analyst 0 is refused - "no analyst" is not "every company". An unknown company and a company you cannot reach get the same message, so probing ids reveals nothing:

$noAccess = new ServiceError('validation', 'invalid_field', 'You do not have access to that company.');

The REST route checks the key's company scope as well (apiKeyCanAccessTenant(), 403).

πŸ” Locking

TRAP: the transaction's first statement is a locking read (SELECT ... FOR UPDATE on the domain), and the group is followed with locking reads too. A plain read first would fix the snapshot before the lock, so a subdomain added meanwhile could be left behind in the old company. If the domain or any group member changed company in between, the move is a conflict and nothing happens.

Refused or cleared

What Why
Refused A name and scope the target already holds One record per name, per company, per scope
Refused Links to tickets or CMDB objects in another company Links must be in the domain's company (domainLinkTargetOk()); a link to a deleted ticket does not count, since the Links tab can neither show nor remove it
Refused A contract in another company A contract belongs to one company since 3.5.0
Cleared Registrar account, cost centre, customer person They do not exist in the target; each clearing is audited and returned in cleared

Refusals happen before any UPDATE, inside the transaction, so a refused move changes nothing.

After commit

afterDateChange() (the calendar) and domain.updated workflows run after the commit, once per moved record, so a move that rolled back never fires anything.

Default company

Moving to the default company stores tenant_id = NULL, as every company-scoped table does (storeTenant()); the test checks it.

Related: Domains - Developer Guide Β· Moving an asset - Developer Guide Β· REST API - Domains

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally