From baf64adcd0b904559cfc326045fe7d9547a7f653 Mon Sep 17 00:00:00 2001 From: Laura Ghiorghisor Date: Wed, 11 Dec 2024 13:28:56 +0000 Subject: [PATCH] Add documentation - overview of asset fields --- docs/asset_fields_overview.md | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/asset_fields_overview.md diff --git a/docs/asset_fields_overview.md b/docs/asset_fields_overview.md new file mode 100644 index 00000000..0d59983e --- /dev/null +++ b/docs/asset_fields_overview.md @@ -0,0 +1,40 @@ +## Asset fields overview + +Asset Manager stores a a number of fields whose values work together to enforce how the asset is served. +These fields are closely related to various document states from the publishing applications. +Whitehall uses most of the fields, since it implements a full "editioned" flow. The following examples are thus based on Whitehall's behaviour. + +1. `draft` + +Assets are set to draft (boolean `true`) when they first get created on a draft edition. When the document gets published, the draft state of the asset is also updated to `false`. +All assets associated with live content must be publicly available. Once `draft` is set to `false`, it should not be set back to `true`. There are other ways to further represent that the asset is no longer live, such as setting a `redirect_url` or a `replacement_id`. + +The draft state should always match the state of the `parent_document_url`. Recently, a [validation rule](https://github.com/alphagov/asset-manager/blob/cffce4e0e1323eab138e016de9b33536f62fef60/app/models/asset.rb#L288) has been added to ensure this, though no data patch was run for existing data. + +Assets must be in draft for certain authorisation protocols to apply. See [documentation](https://github.com/alphagov/asset-manager/blob/cffce4e0e1323eab138e016de9b33536f62fef60/docs/authorisation.md). + +2. `state` + +This is a representation of the internal Asset Manager processing of the asset, particularly around uploading and virus scanning status. +The state machine includes `scanned_clean`, `clean`, `scanned_infected`, `upload_success`, `uploaded`. + +NB: There are some invalid remnants of a previous state machine, including state values such as `deleted`, in the database. These should be removed. + +3. `deleted_at` + +The deletion timestamp gets set when an asset is deleted in the corresponding publishing application, either by deleting an attachment or discarding a document. +A `nil` value means the asset has not been deleted (default). + +4. `replacement_id` + +This is a BSON object ID, set when the user uploads a new file in the place of an old one, typically with the intention of preserving some contextual document metadata. +Default is `nil`. The replaced asset redirects to its replacement, provided the replacement is not in draft. + +Whilst deletion and replacements are mutually exclusive (an asset should not logically have both), they do coexist in the database. +Deletion, replacement, and draft work together to support previewing of draft content. An asset will not redirect to its replacement if the replacement is in draft. +This ensures that until the publish event is fired, the users can preview images and documents on the draft stack. + +5. `redirect_url` + +This is typically set when the parent edition is unpublished. Default is `nil`. It is usually set to the parent document URL. Because of this, most redirected assets will return a `404` status. +Upon re-drafting the parent edition, the redirect URL gets set back to `nil`.