Additional checks interface (add quotes to string values, make result table columns consistent)

[duncandewhurst]

Building on the check documentation in Open-Telecoms-Data/lib-cove-ofds#8 (comment), I've been thinking about how we display additional check results to users and have sketched up the following interface (colours, fonts, sizes are all placeholders, but hopefully it gives an idea):

My thinking is:

• Don't show passing checks to reduce the amount that users need to read and for consistency with the validation errors section
• Group results by check so that users can tackle common issues as a group
• When the page loads, only expand the first 3 failures for each check so that users don't need to scroll past many similar failures to get the next type of check.
• Allow users to expand the list of failures for each check to see all the failures (not currently shown in wireframe)
• For consistency checks, show both values so that users can identify the problem

@odscjames is it feasible to implement something like this as part of the current sprint?

@lgs85 please take a look and share your feedback/suggestions (I'm definitely not a UI expert!)

[odscjames]

I've put on board and we'll see how much we can do - even just grouping them would be good.

[odscjames]

A first go at grouping is now in - as each type now has separate tables, this also allows someone to start checking which columns come up for each type of error and to specify which columns should come up. Try uploading the files in https://github.com/Open-Telecoms-Data/lib-cove-ofds/tree/8db98fd56cf2a5fe8a2563160c27ec3209bbba04/tests/fixtures/0_1_0_alpha

[duncandewhurst]

Thanks! I like the approach of having separate tables for checks that can relate to multiple objects. I think that's better than the 'Object identifier' approach in the issue description:

I've specified the columns that should appear in the results table for each check type and the values for each column in the additional checks spreadsheet.

I've also noted some things that need updating:

• Use code formatting for text in backticks, e.g. `/spans/route/type` in the image below

• Make the check title (e.g. 'Span route geometry' in the image above) either the same font size or smaller than the 'Additional checks' heading,
• Rename 'Orphaned nodes' to 'Unreferenced nodes' (I've updated the feedback title column in the additional checks spreadsheet)
• Colour the additional checks box according to the failure severity in the additional checks spreadsheet.
  • Error - red
  • Warning - yellow
  • No failures - green
• Add the number of failures to the check heading (see image in issue description)
• Remove the '_name_set_but_not_in_original' checks (see comment in additional checks spreadsheet)
• Add a link to the schema reference documentation at the end of the description for each check, e.g. for the node location type check: https://open-fibre-data-standard.readthedocs.io/en/0.1-dev/reference/schema.html#network-schema.json,/definitions/Geometry,type. I've added a column with links in the additional checks spreadsheet.

I've opened a couple of other issues related to the results interface:

• Move external links feedback outside of additional checks box #19
• Additional fields: Report examples and child fields (add quotes to string values, copy-edits) #20

[duncandewhurst]

Please can you add the following introductory sentence to the additional checks box:

Your data failed the following additional checks. You should check for errors in your mapping and data pipeline.

bf7f167: please can you include the link to the schema docs as part of the feedback description paragraph, e.g. for the Node location type check:

Your data contains nodes with incorrect location types. /nodes/location/type must be 'Point'. For more information, see Geometry.type.

I've updated the feedback description column in the additional checks spreadsheet with the exact text to use for each check.

[odscjames]

please can you include the link to the schema docs as part of the feedback description paragraph
Add the number of failures to the check heading (see image in issue description)
Colour the additional checks box according to the failure severity in the additional checks spreadsheet.

all on 2022-11-08

Make the check title (e.g. 'Span route geometry' in the image above) either the same font size or smaller than the 'Additional checks' heading,

Getting this exactly right really depends on some good design work that should really be done for the whole site - for now I've just changed h3's to h4's and it kinda works. on 2022-11-08

[duncandewhurst]

please can you include the link to the schema docs as part of the feedback description paragraph
Add the number of failures to the check heading (see image in issue description)

Looks good on 2022-11-08

Colour the additional checks box according to the failure severity in the additional checks spreadsheet.

Can't test due to Open-Telecoms-Data/lib-cove-ofds#5 (comment)

Make the check title (e.g. 'Span route geometry' in the image above) either the same font size or smaller than the 'Additional checks' heading,

Getting this exactly right really depends on some good design work that should really be done for the whole site - for now I've just changed h3's to h4's and it kinda works. on 2022-11-08

Good enough for now, but agree that design work is needed outside of this sprint.

[duncandewhurst]

The priority outstanding action for this issue is adding the necessary columns to the results tables for each check, from #13 (comment):

I've specified the columns that should appear in the results table for each check type and the values for each column in the additional checks spreadsheet.

[odscjames]

Next version of library will have everything but path - that's a harder one to add. EDIT this is now on live!

(Whoops, I have phase ref name and organsation ref name but I've missed phase name and organsation name - I'll come back to those)

[odscjames]

Are the columns in the correct order?

eg span_start_node_not_found says "Network identifier (.id) / Span identifier (Span.id) / Path (e.g. /spans/0/start) / Node reference (Span.start | Span.end)" and that's the order the 4 columns should be in?

I'm not going to re-order them today, but it's just HTML tables in cove_ofds/templates/cove_ofds/additional_checks_table.html so this is an easy task for me or someone to pick up later.

[duncandewhurst]

Looking good so far!

Are the columns in the correct order?

Yep, please order the columns as specified in the spreadsheet.

[odscjames]

Columns are in correct order and all columns specified in spreadsheet should now be on live - please test!

[duncandewhurst]

Looks good, thanks!

A couple of outstanding tasks from earlier comments:

• When the page loads, only expand the first 3 failures for each check so that users don't need to scroll past many similar failures to get the next type of check.
• Allow users to expand the list of failures for each check to see all the failures (not currently shown in wireframe)
• Add code formatting for text in backticks

And some minor changes for consistency:

• Add quotes to string values
• Rename 'Span route geometry' check to 'Span route type'
• Node location type: Rename 'Type' column to 'Value'
• Node location coordinates: Rename 'Coordinates' column to 'Value'
• Span route geometry: Rename 'Type' column to 'Value'
• Span route coordinates: Rename 'Coordinates' column to 'Value'
• Phase references: Rename 'Phase reference' column to 'Value'
• Phase names: Rename 'Phase reference name' column to 'Value'
• Organisation references: Rename 'Organisation reference' column to 'Value'
• Organisation names: Rename 'Organisation reference name' column to 'Value'

[odscjames]

Ticking backticks off as that already has a separate issue: #35

[odscjames]

Ticking off show/hide comment, as that is moved to #65

[odscjames]

All the label changes are ready for testing on live

[duncandewhurst]

The changes look good. Still need to add quotes to string values.

Also, whilst testing I noticed that the columns for the result tables for the organisation references check are inconsistent:

Please can you remove the 'field' column from the results tables for nodes and spans?

Edit: I've renamed the issue to reflect the outstanding tasks.

[odscjames]

Please can you remove the 'field' column from the results tables for nodes and spans?

Ready for testing on live

[duncandewhurst]

Looks good. Thanks!