diff --git a/content/platform/overview/creating-an-event-against-an-asset/index.md b/content/platform/overview/creating-an-event-against-an-asset/index.md index 18115665d..f90e2deba 100644 --- a/content/platform/overview/creating-an-event-against-an-asset/index.md +++ b/content/platform/overview/creating-an-event-against-an-asset/index.md @@ -294,6 +294,10 @@ curl -v -X GET \ {{< /tab >}}} {{< /tabs >}} +<<<<<<< HEAD +Please see the [Administation](/platform/administration/) section for information on how to manage your assets. +======= In the next section we look at a specific type of Asset, the Document Profile Asset. +>>>>>>> main diff --git a/content/platform/overview/instaproof/index.md b/content/platform/overview/instaproof/index.md index 56a083877..e5af39222 100644 --- a/content/platform/overview/instaproof/index.md +++ b/content/platform/overview/instaproof/index.md @@ -9,7 +9,7 @@ images: [] menu: platform: parent: "overview" -weight: 38 +weight: 37 toc: true --- Instaproof provides data provenance and authenticity with a simple drag-and-drop. diff --git a/content/platform/overview/public-attestation/index.md b/content/platform/overview/public-attestation/index.md index 6a363b767..602730c56 100644 --- a/content/platform/overview/public-attestation/index.md +++ b/content/platform/overview/public-attestation/index.md @@ -9,7 +9,7 @@ menu: platform: parent: "overview" - weight: 36 + weight: 38 toc: true aliases: - /docs/beyond-the-basics/public-attestation/ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersion.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersion.png new file mode 100644 index 000000000..8219f7556 Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersion.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersionDetails.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersionDetails.png new file mode 100644 index 000000000..987a5ede9 Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AddNewVersionDetails.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/AssetOverview.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AssetOverview.png new file mode 100644 index 000000000..d67dfb151 Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/AssetOverview.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/EventDetails.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/EventDetails.png new file mode 100644 index 000000000..5491f4e09 Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/EventDetails.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/MoreEventDetails.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/MoreEventDetails.png new file mode 100644 index 000000000..c0774150c Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/MoreEventDetails.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/RecordEvent.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/RecordEvent.png new file mode 100644 index 000000000..15ed353a9 Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/RecordEvent.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/WithdrawEvent.png b/content/platform/overview/registering-an-event-against-a-document-profile-asset/WithdrawEvent.png new file mode 100644 index 000000000..9a6ef0dee Binary files /dev/null and b/content/platform/overview/registering-an-event-against-a-document-profile-asset/WithdrawEvent.png differ diff --git a/content/platform/overview/registering-an-event-against-a-document-profile-asset/index.md b/content/platform/overview/registering-an-event-against-a-document-profile-asset/index.md new file mode 100644 index 000000000..920455a80 --- /dev/null +++ b/content/platform/overview/registering-an-event-against-a-document-profile-asset/index.md @@ -0,0 +1,339 @@ +--- +title: "Registering an Event Against a Document Profile Asset" +description: "" +lead: "" +date: 2023-07-26T13:07:55+01:00 +lastmod: 2023-07-26T13:07:55+01:00 +draft: false +images: [] +menu: + platform: + parent: "overview" +weight: 36 +toc: true +--- + +It is rare for a document to remain unchanged during it's lifetime. Some documents are expected to go though many versions (e.g product documentation) while others (e.g. an employment contract) change much less frequently. + +If you need to update your registered Document Profile Asset you can record this as an Event. The [Document Profile](/developers/developer-patterns/document-profile/) defines two types of Event; Publish and Withdraw. + +Document Registration is the first Event with each new version being recorded as a Publish Event. + +There is also the option to record an event (Record Event) that is important but is not formally part of the document profile. An example of this could be a document content review or a change in security classifiation. + +When the document version is no longer to be used there is a Withdraw Event. + +These Events track key moments of an Document's lifecycle; details of Who Did What When to each version of the document. + +{{< note >}} +Before registering an Event, follow [this guide](/platform/overview/registering-a-document-profile-asset/) to register your first Document Asset. +{{< /note >}} + +## Registering Events + +1. Open the Asset Overview for a Document Profile Asset. + +{{< tabs name="add_event" >}} +{{{< tab name="UI" >}} +When viewing your Document, you have the choice of `Add New Version` (publish a new version), `Withdraw Document` (the document has reached End of Life) or `Record Event` (any other event that you wish to record). +{{< img src="AssetOverview.png" alt="Rectangle" caption="Document Asset Overview" class="border-0" >}} +{{< /tab >}} +{{< tab name="YAML" >}} +To use the YAML Runner, please visit [this link](https://python.rkvst.com/runner/index.html) for installation instructions. + +To create your Event, use the action `EVENTS_CREATE`. +```yaml +--- +steps: + - step: + action: EVENTS_CREATE + description: Record event against My First Document. + asset_label: assets/ + behaviour: RecordEvidence +``` +The `asset_id` must match the Asset ID found in the details of your Document. See [Step 7 of Registering a Document Profile Asset](/platform/overview/registering-a-document-profile-asset/). +{{< /tab >}} +{{< tab name="JSON" >}} +Create an empty file, in later steps we will add the correct JSON. + +```json +{ + +} +``` + +{{< /tab >}}} +{{< /tabs >}} +
+{{< note >}} +In addition to the Asset and Event attributes that are part of the Document Profile, it is possible to record other attributes that are not part of the profile. These are: + +* `Event Attributes` - Attributes specific to an Event, i.e. a new author. +* `Asset Attributes` - Attributes of the Asset that may change as a result of the Event, i.e. the new document hash. +{{< /note >}} +
+2. Adding a New Version. + +{{< tabs name="add_new_version" >}} +{{{< tab name="UI" >}} +Click on the `Add New Version` button.
+Information that is specific to the Document Profile is entered in the Document Information tab. As with registering the document, the new version can be dragged into the Auto-fill box or you can manually enter the document hash. +{{< img src="AddNewVersion.png" alt="Rectangle" caption="Document Information" class="border-0" >}} +The Advanced Options tab is for additional Asset and Event attributes that are not part of the document profile. +{{< img src="AddNewVersionDetails.png" alt="Rectangle" caption="Advanced Options" class="border-0" >}} +{{< /tab >}} +{{< tab name="YAML" >}} + +Add your `event_attributes` and `asset_attributes` as key-value pairs. + +Fill out the metadata about your Event; `operation` and `behaviour` detail what class of Event is being performed. By default this should always be `Record` and `RecordEvidence`, respectively. + +In the asset attributes section you should include the required RKVST asset attributes as defined by the document profile. The new document version hash value is `document_hash_value`, the hash algorithm is `document_hash_alg` and the `document_status` which must be `Published`. + +In the event attributes section you should also add the required RKVST event attribute `arc_display_type` together with any other event specific attributes. The Document Profile specifies that `arc_display_type` must be `Publish`. + +```yaml +--- +steps: + - step: + action: EVENTS_CREATE + description: Record event against My First Document. + asset_label: assets/ + operation: Record + behaviour: RecordEvidence + asset_attributes: + document_hash_value: 84684c83afd5e9cb3a83439872eae74798979ff5754b15931dbe768092174ec9 + document_hash_alg: sha256 + document_version: "2" + document_status: Published + event_attributes: + arc_description: Publish version 2 of My First Document + arc_display_type: Publish + document_version_authors: + - display_name: Dee Author + email: dee@writeme.org + - display_name: Anne Author + email: anne@writeme.org + confirm: true +``` +{{< /tab >}} +{{< tab name="JSON" >}} +Add your `event_attributes` and `asset_attributes` as key-value pairs. + +Fill out the metadata about your Event; `operation` and `behaviour` detail what class of Event is being performed. By default this should always be `Record` and `RecordEvidence`, respectively. + +In the asset attributes section you should include the required RKVST asset attributes as defined by the document profile. The new document version hash value is `document_hash_value`, the hash algorithm is `document_hash_alg` and the `document_status` which must be `Published`. + +In the event attributes section you should also add the required RKVST event attribute `arc_display_type` together with any other event specific attributes. The Document Profile specifies that `arc_display_type` must be `Publish`. + +```json +{ + "operation": "Record", + "behaviour": "RecordEvidence", + "asset_attributes": { + "document_hash_value":"84684c83afd5e9cb3a83439872eae74798979ff5754b15931dbe768092174ec9", + "document_hash_alg":"sha256", + "document_version":"2", + "document_status":"Published" + }, + "event_attributes": { + "arc_description": "Publish version 2 of My First Document", + "arc_display_type": "Publish", + "document_version_authors": [ + { + "display_name": "Dee Author", + "email": "dee@writeme.org" + }, + { + "display_name": "Anne Author", + "email": "anne@writeme.org" + } + ] + } +} +``` + +This Event will be POSTed to a specific Asset endpoint when the curl command is run. To do this, you will need to include the correct `assets/` string for the asset in the URL. +{{< /tab >}}} +{{< /tabs >}} +
+ +3. The Withdraw Event. +{{< tabs name="withdraw_event" >}} +{{{< tab name="UI" >}} +If a document is no longer required, or if for any reason it is decided that it should no longer be used, then a document can be withdrawn.
Withdrawal is optional and it is usually the final event in the document lifecycle. It can be reversed in RKVST by publishing a new version. +{{< img src="WithdrawEvent.png" alt="Rectangle" caption="Withdraw Event" class="border-0" >}} + +{{< /tab >}} +{{< tab name="YAML" >}} + +Use the attibute/value pairs in the example below to register a `Withdraw` event. +```yaml +--- +steps: + - step: + action: EVENTS_CREATE + description: Withdraw My First Document. + asset_label: assets/ + operation: Record + behaviour: RecordEvidence + asset_attributes: + document_status: Withdrawn + event_attributes: + arc_description: Withdraw My First Document + arc_display_type: Withdraw + confirm: true +``` +{{< /tab >}} +{{< tab name="JSON" >}} + +Use the attibute/value pairs in the example below to register a `Withdraw` event. +```json +{ + "behaviour": "RecordEvidence", + "operation": "Record", + "asset_attributes": { + "document_status":"Withdrawn" + }, + "event_attributes": { + "arc_description":"Withdraw My First Document", + "arc_display_type":"Withdraw" + } +} +``` +{{< /tab >}}} +{{< /tabs >}} +
+4. Recording a Generic Event. + +The `Record Event` button provides a way to record generic events that are not part of the Document Profile lifecycle. The asset and event attributes are in separate tabs in this Event type. + +See [Creating an Event Against an Asset](/platform/overview/creating-an-event-against-an-asset/) for more information on this event type. +{{< tabs name="record_event" >}} +{{{< tab name="UI" >}} + +{{< img src="RecordEvent.png" alt="Rectangle" caption="Submitting the Event" class="border-0" >}} + +{{< /tab >}} +{{< tab name="YAML" >}} +```yaml +--- +steps: + - step: + action: EVENTS_CREATE + description: Record event against My First Document. + asset_label: assets/ + operation: Record + behaviour: RecordEvidence + event_attributes: + arc_description: Document review + arc_display_type: Review + confirm: true +``` +{{< /tab >}} +{{< tab name="JSON" >}} +```json +{ + "operation": "Record", + "behaviour": "RecordEvidence", + "event_attributes": { + "arc_description": "Document Review", + "arc_display_type": "Review", + }, +} + +``` +{{< /tab >}}} +{{< /tabs >}} +
+5. Registering the Event +{{< tabs name="register_event" >}} +{{{< tab name="UI" >}} +Once your form is complete, click on the `Record Event` button to register the event. +{{< img src="RecordEvent.png" alt="Rectangle" caption="Submitting the Event" class="border-0" >}} +{{< /tab >}} +{{< tab name="YAML" >}} +Use the [archivist_runner](https://python.rkvst.com/runner/index.html) to run your YAML file! + +```bash +$ archivist_runner \ + -u https://app.rkvst.io \ + --client-id \ + --client-secret \ + my_first_document_event.yaml +``` +{{< /tab >}} +{{< tab name="JSON" >}} +Use the curl command to run your JSON file! See instructions for [creating your `BEARER_TOKEN_FILE`](/developers/developer-patterns/getting-access-tokens-using-app-registrations/) here. + +```bash +curl -v -X POST \ + -H "@$BEARER_TOKEN_FILE" \ + -H "Content-type: application/json" \ + -d "@/path/to/jsonfile" \ + https://app.rkvst.io/archivist/v2/assets//events +``` +{{< /tab >}}} +{{< /tabs >}} +
+6. Viewing Event details. + +{{< tabs name="view_event" >}} +{{{< tab name="UI" >}} +The Event History can be seen in the Asset Overview from step 1, simply click on any Event row to view it.
+The Document tab shows information about the document version that you are viewing and also provides a drag-and-drop box that allows you to check any locally stored versions of the document that you have against this specific version. + +{{< img src="EventDetails.png" alt="Rectangle" caption="Viewing an Event" class="border-0" >}} + +The More Details tab provides information about the Event itself and incluides a link to the transaction. It also includes any optional attributes that were included in the Event. + +{{< img src="MoreEventDetails.png" alt="Rectangle" caption="Viewing Event Attributes" class="border-0" >}} + +{{< /tab >}} +{{< tab name="YAML" >}} +The `EVENTS_LIST` action can be used to view all Events, or filtered using attributes (`attrs`) to view details of a specific Event. + +To view all Events, use: +```yaml +--- +steps: + - step: + action: EVENTS_LIST + description: List all events. + print_response: true +``` +To view the details of the Event you just created for My First Container, use: +```yaml +--- +steps: + - step: + action: EVENTS_LIST + description: List Events against the Document 'My First Document'. + print_response: true + asset_label: assets/59e2b78b-d555-49a0-8775-f336b640122e + attrs: + arc_display_type: Publish +``` +{{< /tab >}} +{{< tab name="JSON" >}} +Event data can be viewed using curl commands. + +To view all Events across all Assets, use: + +```bash +curl -v -X GET \ + -H "@$BEARER_TOKEN_FILE" \ + https://app.rkvst.io/archivist/v2/assets/-/events +``` + +To view the details of the Event you just created for My First Document, use: + +```bash +curl -v -X GET \ + -H "@$BEARER_TOKEN_FILE" \ + https://app.rkvst.io/archivist/v2/assets//events/ +``` +{{< /tab >}}} +{{< /tabs >}} + + diff --git a/content/platform/overview/scitt-receipts/index.md b/content/platform/overview/scitt-receipts/index.md index 226603219..a54817bd6 100644 --- a/content/platform/overview/scitt-receipts/index.md +++ b/content/platform/overview/scitt-receipts/index.md @@ -9,7 +9,7 @@ menu: platform: parent: "overview" - weight: 37 + weight: 39 toc: true ---