Create and save an organization
What It Does
Organization creation or correction joins identity, organizational context, contact points, files and customer-defined values at one local persistence boundary. Harbor West Chapter can be created beneath its national body with its own address and type policy. Staff receive one saved organization, while dependent projections can follow later.
Our reading is that this flow’s distinct boundaries explain two otherwise surprising results: a create can spend a number without committing, and removing a shared organizational source can also change several people. The built console supplies organization creation but no general organization editor; service save behavior remains relevant to integrations and selected record actions.
What Starts It
A coordinator creates an organization from the configured form, or an integration submits creation or maintenance input. The request includes its classification and any parent reference. Existing general organization maintenance is available through the service even where the live console has no general editor. Parent moves and detail changes start a guarded organization transaction.
The Flow
The diagram shows the sequence and service seams. Each synchronous stage waits for its result, while captured-event, queue and scheduled stages can run after the originating request has returned. The hop descriptions below identify the write and failure boundary, so the last arrow must not be mistaken for one atomic transaction across every participant.
Hop by Hop
1. Console create screen
The create screen offers active organization types and loads the effective create form for the chosen type. It collects the parent and contact-point values allowed by that form. Existing Organization 360 actions do not amount to a general organization correction form.
2. Entities route and duplicate guard
The route establishes create authority, rejects attempted ordinary lock changes and asks the duplicate guard about blocking conditions. Possible-duplicate feedback precedes any business insert. A deliberate override has its own grant and recorded reason rather than relying on the existence of an enabled Create button.
3. Shared record-asset pipeline
The logo is copied into permanent file handling before the organization transaction. This prepares a stable reference but introduces a recovery seam: database rollback cannot undo that copy. If later validation fails, cleanup has to retire the abandoned file separately.
4. Entities persistence (one transaction)
Persistence validates and normalizes the organization, including parent, type and typed contact points. Creation evaluates initial role compliance without a transition notice; later ordinary saves do not automatically reevaluate policy. Owner, children, custom values and permitted audit work commit together, with updates checking the locked owner version.
5. Database triggers
Removing an organization source invokes database disconnection work for each dependent contact. Those snapshots and their version advances commit with the source removal. The database then captures organization history and the affected contacts’ own histories, so a failure cannot leave dangling live source references.
6. CRM change-event consumers
Consumers update region, linked-person region, search and duplicate projections after commit. Each handler has its own delivery and retry outcome. A saved organization therefore remains valid even if search is briefly stale or a dependent region update must be retried.
When Something Fails
Hop 1 — Console create screen
The failure boundary is: Show returned field errors in the create form. The remaining work or data is: No partial business write remains. The creator receives form feedback.
Hop 2 — Entities route and duplicate guard
The failure boundary is: Refuse blocked duplicates unless the caller has override permission and supplies a reason. The remaining work or data is: No partial business write remains. The caller receives the result.
Hop 3 — Shared record-asset pipeline
The failure boundary is: Return an asset error without replacing the saved logo. The remaining work or data is: Prepared copies from an unsuccessful attempt await cleanup. Asset cleanup logs expose deferred removal.
Hop 4 — Entities persistence (one transaction)
The failure boundary is: Roll back the organization aggregate if any transactional step fails. The remaining work or data is: A creation number can be spent and prepared files can remain. The caller receives the result.
Hop 5 — Database triggers
The failure boundary is: A trigger or capture failure rolls back removal and all resulting changes. The remaining work or data is: No partial business write remains. Organization and affected contact histories show committed work.
Hop 6 — CRM change-event consumers
The failure boundary is: Retry failed SQS handlers and dead-letter after five receives. The remaining work or data is: The saved organization can precede region and search updates. Consumer logs and dead-letter messages identify failures. This failure is downstream of committed input; operators investigate its own delivery rather than treating the caller’s original save as failed.
Repeats and Races
A current-version organization no-op leaves modification stamps and capture unchanged. Organization create differs from contact replay: an occupied supplied identity is refused, and an unkeyed repeated request can create another organization. A caller investigating an ambiguous response must read the intended result rather than assume replay support.
Owner locking and version checks coordinate corrections, while compliance also uses an advisory lock. Concurrent parent changes still pass the hierarchy’s cycle enforcement. A parent move alters read-derived descendant ancestry without writing every descendant, and initial counter allocation can remain spent after a failed create.
What Is Observable
The creator receives form feedback. The caller receives the result. Asset cleanup logs expose deferred removal. Organization and affected contact histories show committed work. Consumer logs and dead-letter messages identify failures.
The person or initiating caller sees the synchronous result at its own boundary. Captured history establishes committed local changes; logs, durable job state and queue outcomes explain remaining work. A successful database change, accepted downstream request and completed delivery are different observations and must be investigated through the component that owns each one.
Open Design Questions
The built organization page lacks a general edit form and a revision-history entry, although service operations exist. Type changes do not immediately refresh stored compliance. These findings remain visible rather than implying that every service capability has a complete console path or immediate policy propagation.