From f00ef55291708260657d298699e099e1f08d510d 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_state_machine_overview.md | 43 ++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/asset_state_machine_overview.md diff --git a/docs/asset_state_machine_overview.md b/docs/asset_state_machine_overview.md new file mode 100644 index 00000000..01ae3706 --- /dev/null +++ b/docs/asset_state_machine_overview.md @@ -0,0 +1,43 @@ +## Asset state machine overview + +Asset Manager stores a a number of fields whose values work together to represent the state of an asset. +These fields are closely related to various document states from the publishing applications. + +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 should be updated to `false` by the publishing application. +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 should be set by the publishing application when an asset is deleted. +A `nil` value means the asset has not been deleted (default). + +4. `replacement_id` + +This is a BSON object ID, set by the publishing app 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. + +Publishing applications only send the next-in-line `replacement_id`. +It is Asset Manager that deals with backpropagating the replacement - see the `update_indirect_replacements_on_publish` [callback](https://github.com/alphagov/asset-manager/blob/13d68aee4d0c8cf2c81be7fafef309dc36436ca3/app/models/asset.rb#L174). +This ensures that all assets in a chain of replacements redirect to the latest one. + +5. `redirect_url` + +This is set by the publishing app when the parent edition is unpublished. Default is `nil`. It is usually set to the parent document URL. +Upon creating a new draft of the parent edition, the publishing app should set the redirect URL back to `nil`.