Add capability to view documents related to the data asset

mjmcclung commented 8 months ago

https://openplus.monday.com/boards/4092908516/pulses/5722502248

User story

As someone with data management responsibilities (data custodian, strategic IM person) I want to be able to see all the documents related to my data asset in one place so that:

they are easily accessible,
I can better understand the data
I can understand how it has changed over time (e.g. data quality, conversion implications),
I can understand the implications of any agreements (MOU, ISA, service agreements or protocol agreements) or legislative requirements

Describe the idea

Add a way for the user to browse, view, or link to documents related to the data asset of interest (perhaps as a separate place, with tabs for each of the types of documents we want to link to). This could include things like a PIA, data migration information, information management plans, Memorandum of Understanding (MOU) between organizations, Information Sharing Agreements (ISA) between organizations, or even the applicable legislation.

Actions

[x] In Build screen, add Section 4: Related Documents which makes use of a taxonomy related_links the link text
[x] renumber current Sections 4 and 5 to 5 and 6
[x] implement a paragraph
[x] On the Node view, display links under the Info schedule in the sidebar as an unordered list of links
[x] load taxonomy values to related_links taxonomy
[x] Document new fields

NicoledeGreef commented 6 months ago

Keeping it simple, we could add some non-mandatory fields for storage of links to related documentation (ideally HTTP locations but LAN location acceptable):

field_privacy_impact_assessment field_info_mgmt_plan field_memo_of_understanding field_info_sharing_agreement field_related_legislation

In terms of the Build page, another section is warranted: Section 6: Related Documents

On the MR View screen, display values in the sidebar under Related Documents below Information management

If values are supplied, simply include and hyperlink the text below to the location supplied.

Privacy Impact Assessment Information Management Plan Memo of Understanding Information Sharing Agreement Related Legislation

mjmcclung commented 6 months ago

Rather than have a field for each potential document type, could we make it simpler by having a Document Type field with a taxonomy of values (that we can add to over time as we leverage/become aware of related items), and a second Document Link field that stores the link for the specific document type?

Some things may not be documents per se in today's digital world, like legislation (likely linked to a web page). Is there a better, more forward thinking name for this? Perhaps 'Related Documents' is good for where we are at right now, just wanted to throw this thought out there for consideration.

We need to build in the ability to have more than one document link of the same type, e.g. more than one legislation could apply.

Question: are there any security implications of including LAN links? Suggest perhaps having this section leverage visibility to restrict access.

NicoledeGreef commented 6 months ago

Yes, a taxonomy is the way to go. We looked at another solution that was fast but it is not ideal for end users (inputs or output side).

Description being edited for scope.

CraigClark commented 6 months ago

@lkmorlan I started working on this, but something isn't working.

I created a new section 6 and moved what's in section 5 now to section 6 and what's in section 5 to section 5. (works)
This freed up section 4 for the related links (works)
I created a new vocabulary document_type
I created a paragraph, documents which has an entity reference to document_type vocabulary and a link field which will only accept external links
I created a paragraph field on the data_set content type called field_related_document

When I test this, I see everything where is it supposed to be, however I cannot save section_4 with the paragraph in it. I get the error:

The metadata root record type cannot be changed.

I'm not sure what I'm doing wrong here. My work so far is in this branch https://github.com/bcgov/MFIN-Data-Catalogue/tree/295-related-documents

From the logs

Warning: Trying to access array offset on value of type null in _bc_dc_form_node_data_set_edit_form_submit() (line 595 of /var/www/html/html/modules/custom/bc_dc/bc_dc.module)

#0 /var/www/html/html/core/includes/bootstrap.inc(164): _drupal_error_handler_real(2, 'Trying to acces...', '/var/www/html/h...', 595)
#1 /var/www/html/html/modules/custom/bc_dc/bc_dc.module(595): _drupal_error_handler(2, 'Trying to acces...', '/var/www/html/h...', 595)
#2 [internal function]: _bc_dc_form_node_data_set_edit_form_submit(Array, Object(Drupal\Core\Form\FormState))
#3 /var/www/html/html/core/lib/Drupal/Core/Form/FormValidator.php(82): call_user_func_array('_bc_dc_form_nod...', Array)
#4 /var/www/html/html/core/lib/Drupal/Core/Form/FormValidator.php(275): Drupal\Core\Form\FormValidator->executeValidateHandlers(Array, Object(Drupal\Core\Form\FormState))
#5 /var/www/html/html/core/lib/Drupal/Core/Form/FormValidator.php(118): Drupal\Core\Form\FormValidator->doValidateForm(Array, Object(Drupal\Core\Form\FormState), 'node_data_set_e...')
#6 /var/www/html/html/core/lib/Drupal/Core/Form/FormBuilder.php(593): Drupal\Core\Form\FormValidator->validateForm('node_data_set_e...', Array, Object(Drupal\Core\Form\FormState))
#7 /var/www/html/html/core/lib/Drupal/Core/Form/FormBuilder.php(325): Drupal\Core\Form\FormBuilder->processForm('node_data_set_e...', Array, Object(Drupal\Core\Form\FormState))
#8 /var/www/html/html/core/lib/Drupal/Core/Controller/FormController.php(73): Drupal\Core\Form\FormBuilder->buildForm(Object(Drupal\node\NodeForm), Object(Drupal\Core\Form\FormState))
#9 /var/www/html/html/core/modules/layout_builder/src/Controller/LayoutBuilderHtmlEntityFormController.php(39): Drupal\Core\Controller\FormController->getContentResult(Object(Symfony\Component\HttpFoundation\Request), Object(Drupal\Core\Routing\RouteMatch))
#10 [internal function]: Drupal\layout_builder\Controller\LayoutBuilderHtmlEntityFormController->getContentResult(Object(Symfony\Component\HttpFoundation\Request), Object(Drupal\Core\Routing\RouteMatch))
#11 /var/www/html/html/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php(123): call_user_func_array(Array, Array)
#12 /var/www/html/html/core/lib/Drupal/Core/Render/Renderer.php(627): Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber->Drupal\Core\EventSubscriber\{closure}()
#13 /var/www/html/html/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php(124): Drupal\Core\Render\Renderer->executeInRenderContext(Object(Drupal\Core\Render\RenderContext), Object(Closure))
#14 /var/www/html/html/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php(97): Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber->wrapControllerExecutionInRenderContext(Array, Array)
#15 /var/www/html/vendor/symfony/http-kernel/HttpKernel.php(181): Drupal\Core\EventSubscriber\EarlyRenderingControllerWrapperSubscriber->Drupal\Core\EventSubscriber\{closure}()
#16 /var/www/html/vendor/symfony/http-kernel/HttpKernel.php(76): Symfony\Component\HttpKernel\HttpKernel->handleRaw(Object(Symfony\Component\HttpFoundation\Request), 1)
#17 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/Session.php(58): Symfony\Component\HttpKernel\HttpKernel->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#18 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/KernelPreHandle.php(48): Drupal\Core\StackMiddleware\Session->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#19 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/ContentLength.php(28): Drupal\Core\StackMiddleware\KernelPreHandle->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#20 /var/www/html/html/core/modules/page_cache/src/StackMiddleware/PageCache.php(106): Drupal\Core\StackMiddleware\ContentLength->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#21 /var/www/html/html/core/modules/page_cache/src/StackMiddleware/PageCache.php(85): Drupal\page_cache\StackMiddleware\PageCache->pass(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#22 /var/www/html/html/modules/contrib/shield/src/ShieldMiddleware.php(270): Drupal\page_cache\StackMiddleware\PageCache->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#23 /var/www/html/html/modules/contrib/shield/src/ShieldMiddleware.php(137): Drupal\shield\ShieldMiddleware->bypass(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#24 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/ReverseProxyMiddleware.php(48): Drupal\shield\ShieldMiddleware->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#25 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/NegotiationMiddleware.php(51): Drupal\Core\StackMiddleware\ReverseProxyMiddleware->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#26 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/AjaxPageState.php(36): Drupal\Core\StackMiddleware\NegotiationMiddleware->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#27 /var/www/html/html/core/lib/Drupal/Core/StackMiddleware/StackedHttpKernel.php(51): Drupal\Core\StackMiddleware\AjaxPageState->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#28 /var/www/html/html/core/lib/Drupal/Core/DrupalKernel.php(704): Drupal\Core\StackMiddleware\StackedHttpKernel->handle(Object(Symfony\Component\HttpFoundation\Request), 1, true)
#29 /var/www/html/html/index.php(19): Drupal\Core\DrupalKernel->handle(Object(Symfony\Component\HttpFoundation\Request))
#30 {main}

CraigClark commented 6 months ago

@lkmorlan this is ready for review/write tests/merge https://github.com/bcgov/MFIN-Data-Catalogue/tree/295-related-documents

I'll work on the docs now and I'll add the terms once this is merged to 1.0.x

CraigClark commented 6 months ago

Documentation for field_related_document, field_paragraph_document_type, and field_paragraph_document_link have been added to the metadata fields documentation.

CraigClark commented 6 months ago

Assigning to @lkmorlan to finish up

CraigClark commented 6 months ago

Tested on dv14 and it passes.

@NicoledeGreef to pass

NicoledeGreef commented 6 months ago

reviewed in dv14

NicoledeGreef commented 6 months ago

Data catalogue admin role needs the permission to edit the vocabulary (Document type).

NicoledeGreef commented 6 months ago

verified that DC Admin role can now edit the Column type taxonomy terms

mjmcclung commented 6 months ago

Only 1 of the 5 types of related documents would be an external URL at this point (legislation), which is an issue.

Also, I don't think just the document type will provide enough context for the user to find what they are looking for. There may be multiple legislation or sharing agreements in play and the user will need additional information to help them find the one they are interested in. A separate screen is needed which could then display the document type, its title, and a description (if needed). could the 'Related documents' be made into a link to this separate screen, similar to the more details for Info Schedules?

NicoledeGreef commented 6 months ago

Thank you for the feedback, @mjmcclung. I do believe this is built to spec. We have taken a simple approach to enable the concept in short order. Once we get the Catalogue in front of metadata editors I will be more comfortable iterating further on the concept.

For PIAs, we do have the FIN-ISP PIA Inventory; e.g. link to Finance Data Catalogue PIA These are not "external" links but they are HTTP (Default access is likely based on membership in a FIN security group (to reach the content without requesting permission).

In the shorter term, the dev team will explore the possibility of not requiring an http/https link to a related document. Possibly we can enable links to resources on the LAN; however, forming one of those correctly takes more tech know-how. Mapped drives are not terribly helpful (what's J:\ to one person might be Z:\ for another).

bcgov / MFIN-Data-Catalogue