configuration

Record a configuration package so it can be validated and applied.

Code
Takes exactly one of file_id, for a package already uploaded here through
core.uploads uploadAttachment with type 'config_package', url, for a
presigned Amazon S3 link to one on the exporting site, or export_id, for
a saved export of this environment. A link is fetched and stored before
this returns, so what comes back always names a package held on this site.

Nothing is executed. Hand the returned id to import_configuration
to validate it, and again to apply it.

A link import is not a cheap record: the fetch and the store run in this
request, bounded by the fetch deadline plus the upload, so one call can
hold an app worker for the better part of two minutes. A handful of
operators at a time is the expected load.

Parameters
----------
file_id : str
    A package already stored on this site, uploaded through
    core.uploads uploadAttachment with type 'config_package'.
url : str
    A presigned Amazon S3 link to a package on the exporting site. Only
    https S3 hosts are accepted and redirects are refused, because the
    fetch happens from inside the cluster.
export_id : str
    A saved export of this environment. Its stored package is reused, so
    nothing is uploaded or fetched again.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration import record. Its id is what to process and poll.

Raises
------
marshmallow.ValidationError
    If none or more than one of file_id, url and export_id are given.

Delete a saved export and the package behind it.

Code
Refused while the export is still running, while an import that is still
running names it as its restore point, and while a running import is
reading its stored package: each would take away something the operator
is relying on right now.

A restore point whose import has settled is deleted like any other
saved export, and that import stops naming a package that is gone.

Parameters
----------
export_id : str
    The record id of the export to delete.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"deleted": bool}

Raises
------
marshmallow.ValidationError
    If export_id is missing or names no record.
BCValidationError
    If the export is still running, or is the restore point of, or holds
    the package being read by, an import that has not finished.

Export configuration settings as a package.

Code
Returns a configuration package that can be imported into another environment.
The package includes effective dates, lines, policy types, forms, items,
sublines, UW rules/questions, groups, quick quote templates, underlying
relationships, and quickcode values.

Parameters
----------
policy_type_id : str
    UUID of the policy type to export. Exports this policy type and any
    related (underlying) policy types.
exclude : list of str, optional
    Package entities to leave out (the package section names, see
    PACKAGE_ENTITIES). A promoted policy type always carries all of its
    configuration, so only these are accepted: forms, dynamic_deliverables,
    global_dynamic_deliverables, global_html_deliverables, brands,
    credit_tiers, authority_limits, system_tags, reports, settings,
    commission_structures, claims_payment_classifications. To leave out
    every file payload (PDF forms and Carbone templates), pass
    ["forms", "dynamic_deliverables", "global_dynamic_deliverables"].
package_name : str, optional
    What to call the package in the saved-exports list. Blank or absent
    means the record composes one from the selection.

Returns
-------
data : dict
    The configuration export record. Where the site runs Celery it comes
    back at status queued; poll get_configuration_export with its id.
    Otherwise the work runs here and the record is already complete. The
    package is never in this response either way: read it from the file
    the record names, through files/generate_download_url.

Return the environment this site is, and whether it is production.

Code
The page names it on every tab, in the progress states, and in the
production confirmation, so it is read from the server rather than
inferred from the hostname in the browser.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"name": str, "is_production": bool, "max_package_bytes": int}

    An unreadable live status is reported as production.

Return one configuration export by id.

Code
This is what the page polls while an export runs: status moves through
queued, processing and then complete or failed, and the record carries the
package it produced.

Parameters
----------
export_id : str

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration export record.

Return one configuration import by id.

Code
Carries the whole outcome once complete: what it touched, any warnings,
and where the package came from.

Parameters
----------
import_id : str

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration import record.

Return the audit note an import produced.

Code
History rows expand to it and the result step opens it. An import that
has not run yet, or whose note could not be written, answers found false
rather than an error.

Parameters
----------
import_id : str

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"found": bool, "note_id": str, "contents": str,
         "attachment_file_id": str}

Validate or apply a configuration package already recorded here.

Code
Takes an import_id from create_configuration_import, never the package
itself: a package reaches this site as an upload or a presigned link, and
is stored before anything runs against it. Sent twice in the ordinary
flow, once with dry_run and once without, and both runs hang off the one
record, the later replacing the earlier one's outcome.

Queues a background job where Celery is enabled and runs in this request
where it is not. Either way the answer is the record.

Validation Rules:
- Package version must equal this environment's package version; any other version, or none, is refused
- All location_ids in packet must exist in this environment
- Effective dates are matched by (effective_date value + location)
- Lines are unique by (line_definition_code + effective_id + location_id)
- Policy Types are unique by (policy_type_definition_code + effective_date_id + location_id)
- If entity exists with same unique key but different ID: reject
- If ID exists but unique key differs: reject
- If entity exists with same ID and unique key: update (idempotent)

Parameters
----------
import_id : str
    A package recorded by create_configuration_import.
dry_run : bool, optional
    If True, only validate the package without applying changes. Default
    is False.
take_restore_point : bool, optional
    If True, export the current configuration of every policy type the
    package would replace before applying it, and record that export as
    the import's way back. Default is True. Ignored on a dry run, which
    replaces nothing. Sending False applies with no way back.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The import record. Queued, it comes back at status queued; poll
    get_configuration_import with the same id. Run here, it is already
    complete. Either way the outcome is in ``summary``, and re-running
    replaces it:
    ::

        {
            "dry_run": bool,
            "version_compatible": bool,
            "validation_passed": bool,
            "applied": bool,  # non-dry-run transaction committed; check
                              # summary for per-section outcomes
            "warnings": [str, ...],
            "locations_affected": [str (UUID), ...],
            "summary": {
                "<section>": {...per-importer counters...}
            }
        }

Raises
------
marshmallow.ValidationError
    If import_id is missing, unknown, or names a record with no stored
    package.
BCValidationError
    If unable to acquire lock (another import is in progress)

Return configuration exports, newest first.

Code
Parameters
----------
limit : int
    Page size. Defaults to 25 and is capped at 200.
offset : int
    How many to skip.
status : str
    Optional filter: queued, processing, complete or failed.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"results": [...], "total": int, "offset": int}

    With ``status``, ``total`` is advisory and a page can hold fewer
    than ``limit`` results: a lost record is settled only when read.

Return configuration imports, newest first.

Code
Parameters
----------
limit : int
    Page size. Defaults to 25 and is capped at 200.
offset : int
    How many to skip.
status : str
    Optional filter: queued, processing, complete or failed.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"results": [...], "total": int, "offset": int}

    With ``status``, ``total`` is advisory and a page can hold fewer
    than ``limit`` results: a lost record is settled only when read.

Return what a package for this policy type would hold, before building it.

Code
Records nothing and produces no package: this is what makes the export
honest, because the underlying policy types it names are the ones an
import would replace.

Parameters
----------
policy_type_id : str
    UUID of the policy type the package would be built for.
exclude : list of str, optional
    Package entities to leave out, as export_configuration takes them.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    ::

        {"sections": [{"section": str, "count": int, "group": str}],
         "related_policy_types": [{"policy_type_id": str, "name": str}],
         "package_version": int,
         "location_abbreviation": str,
         "excluded_entities": [str],
         "excludable_entities": [str]}

Raises
------
marshmallow.ValidationError
    If policy_type_id is missing or is not a uuid.
BCValidationError
    If no policy type has that id.