scf_control_write
Destructive
Updates or batch-updates an organization's scoped controls, including framework scoping and scope, basis, maturity, materiality or procedure overrides for compliance management.
Instructions
Change the organization's control scope (editor+; some methods admin): update or batch-update controls, scope or unscope a framework, set scope, basis, maturity, materiality or procedure overrides.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| basis | No | 'mcr' or 'dsr' to override; null clears the override (and its reason) so the basis is derived from the org's classified frameworks again [set_basis_override] | 'mcr' (mandatory compliance requirement) or 'dsr' (discretionary security requirement); null leaves it unclassified. Reclassifying MCR to DSR changes which exclusions need an approver, hence admin-only [set_framework_basis] Used by: set_basis_override, set_framework_basis. | |
| level | No | Target CMM level L0–L5 for this control; null clears the override (and its reason) and the control inherits its domain target Used by: set_target_maturity. | |
| owner | No | Accountable owner of the control Used by: update. | |
| action | No | 'include' pins the control in scope, 'exclude' pins it out, 'inherit' clears the override AND discards the recorded rationale (it stays in the audit trail) Used by: set_scope_override. | |
| method | Yes | update: Update a scoped control's implementation fields (write — editor+). Identify by scf_id. Only provided fields apply. Material controls: admin for not_applicable. at_risk raises a deficiency. batch_update: Batch-update up to 500 scoped controls in one transaction (write — editor+). Each operation targets an scf_id. Material/MCR controls: no deselect (409); at_risk raises a deficiency. scope_framework: Bulk-scope every control mapped to a framework into the organization (write — editor+ role). Creates a scoped-control entry for each control in the framework. unscope_framework: Unscope every control mapped only to these frameworks (destructive write — editor). Shared controls are kept. An MCR framework, or one taking out a material control, needs an admin and a reason. set_scope_override: Force one control in or out of scope (write — editor+). 'include'/'exclude' pin it; 'inherit' clears it. Excluding an MCR or material control needs an admin key and a reason (editors 403). set_basis_override: Override one control's derived obligation basis (write — ADMIN role): mcr or dsr with a reason, or null to clear and derive it from its frameworks again. 404 if the control has no scope record. set_framework_basis: Record why a scoped framework is in scope (write — ADMIN role): basis mcr|dsr, obligation_type and obligation_source. Replaces all three; null clears. Only an active (scoped) framework, else 404. set_target_maturity: Override one control's target maturity (write — ADMIN role): a level L0–L5 with a reason, or null to inherit its domain's target again (domain targets: scf_update_org_settings). set_materiality: Set whether one control is material (write — ADMIN's own key; a platform key gets 403): true/false with a reason, or null for the catalogue default (material at weighting 10). set_procedure: Link one control to its signed-off procedure document, or null to unlink (write — editor+). The document must be this org's procedure, approved or published when linked (400 otherwise). | |
| org_id | Yes | Organization UUID — obtain from scf_list_organizations | |
| reason | No | Why this control is being overridden — recorded in the audit trail (max 2000 characters). Required for 'exclude'. The admin making an MCR or material exclusion is recorded as its approver; there is no approver parameter [set_scope_override] | Why the derived basis is wrong for this control (max 2000 characters) — required when basis is set [set_basis_override] | Why this control departs from its domain target (max 2000 characters) — required when level is set [set_target_maturity] | Why (max 2000 characters). Required when material is true or false, and when a null clear makes a control weighted below 10 not material (400 otherwise) [set_materiality] Used by: set_scope_override, set_basis_override, set_target_maturity, set_materiality. | |
| scf_id | No | SCF control identifier in DOMAIN-NN format (e.g., 'AST-01', 'GOV-02') — NOT the UUID [update] | SCF control identifier in DOMAIN-NN format — obtain from scf_list_scoped_controls [set_scope_override, set_basis_override, set_target_maturity, set_materiality, set_procedure] Used by: update, set_scope_override, set_basis_override, set_target_maturity, set_materiality, set_procedure. | |
| material | No | true or false overrides the catalogue default; null clears the override. The admin is recorded as the approver: deciding a control is not material lets it be excluded or marked not_applicable without one Used by: set_materiality. | |
| priority | No | Implementation priority: 'high', 'medium', or 'low' Used by: update. | |
| frameworks | No | Framework slugs to remove, e.g. ['iso_27017_2015'] — obtain from scf_list_frameworks Used by: unscope_framework. | |
| operations | No | Update operations to apply (1–500 per call) Used by: batch_update. | |
| assigned_to | No | Assignee responsible for implementation Used by: update. | |
| document_id | No | Procedure document UUID — obtain from scf_list_documents; null unlinks. A later edit sends the document back to review; the link stays and scf_list_scoped_controls shows procedure_document_status Used by: set_procedure. | |
| target_date | No | Target completion date in ISO-8601 (YYYY-MM-DD) Used by: update. | |
| framework_id | No | Framework slug to scope (e.g., 'nist-800-53-r5') — obtain from scf_list_frameworks [scope_framework] | Framework slug of a framework the org has scoped — obtain from scf_get_framework_scope_summary [set_framework_basis] Used by: scope_framework, set_framework_basis. | |
| maturity_level | No | Maturity level with L prefix: L0 Not Performed, L1 Performed, L2 Planned, L3 Well Defined, L4 Quantitatively Controlled, L5 Continuously Improving Used by: update. | |
| removal_reason | No | Why these controls leave scope — recorded in the audit trail. Required (400 without it), with an admin key (403 otherwise), when a framework carries an MCR obligation or its removal would take a material control out of scope Used by: unscope_framework. | |
| completion_date | No | Actual completion date in ISO-8601 (YYYY-MM-DD) Used by: update. | |
| obligation_type | No | Where the obligation comes from: statutory, regulatory, contractual or discretionary; omitted or null clears it Used by: set_framework_basis. | |
| selection_reason | No | Justification for scoping decision — required for not_applicable or deferred Used by: update. | |
| obligation_source | No | The law, regulation or contract behind it (max 2000 characters); omitted, null or blank clears it Used by: set_framework_basis. | |
| implementation_notes | No | Free-text implementation notes and context Used by: update. | |
| implementation_status | No | New implementation status (lowercase): not_started, in_progress, implemented, ready_for_review, monitored, not_applicable, at_risk, or deferred. Moving to at_risk raises a deficiency (see scf_list_deficiencies). A material control (catalogue weighting 10, or set material by an admin) can only leave scope through scf_set_scope_override by an admin (other paths 409), and only an admin may mark it not_applicable (403 otherwise). Used by: update. |