Dynamic Reports - Clarifying mapping of API fields to UI text elements on Issues pages

[Mike Turley]

Hey team,

On today's design sync call I walked through the Issues page as it currently stands (which I will also be demoing at this week's Konveyor Community Meeting) and raised some questions about whether we are displaying the right fields from the hub's JSON objects in the right places. It was suggested that I start a thread here to involve everyone in reaching a consensus on this stuff.

Before I get into the specific fields, it may help to share an overview of how objects returned from the Hub are mapped to the different pages in the UI since the naming is a bit funky. The part of the UI being demoed this week is the "All issues" tab of the Issues page, which has the following views:

• Issues Table: A list of the hub's RuleReport objects, which are Issues collated by ruleset and rule.
• Affected Applications Table: A list of the hub's AppReport objects, filtered by ruleset and rule, which contain properties from an Application and from the Issue that matches each unique combination of [app id, ruleset, rule].
• Issue Detail Drawer: Opens when clicking an application on the Affected Applications Table, and contains an Affected Files Table. This table is a list of the hub's FileReport objects matching the issue id on the AppReport.
• File Incidents Detail Modal: Opens when clicking a file name in the Issue Detail Drawer. Shows details for Incidents matching the issue id on the AppReport and the filename on the FileReport.

Most of the text in the mockups for these views (see the clickable prototype here) come from obvious places in these objects. The ones I'm not sure about are the meaningful-to-the-user "names" of things. (the screenshots contain text from mock data provided by the "hack" scripts in the hub repo):

• The "issue name" shown on the Issues Table: currently I am using the `name` field on the RuleReport, which I believe is the `name` field of the underlying hub Issue object (which I guess comes directly from the analyzer's "Violation" object per today's call? correct me if I'm wrong @Jeff Ortel @Shawn Hurley ). For this we want a human-readable name that explains what the problem is - perhaps this should instead be a rule name? We decided not to display the ruleset and rule in this table, so it is important that this name is meaningful.
  
  This name is also shown in the breadcrumb bar of the Affected Applications page to indicate which row of the Issues Table the user came from:
  
  
  
• The "issue name" shown on the Issue Detail Drawer and the File Incidents Detail Modal: I'm currently using the `issue.name` field on the AppReport. It seems to me that this should be the same "issue name" used above, and I believe the way the AppReport is implemented this name does in fact also come from the underlying Issue object.
  Note also that the application name is shown in small text above this, and I'm not sure if the two should be swapped. This drawer will be reused when clicking on an Issue in the future Single Application tab as well, so it is important to show both the "issue name" and the application name on it.
  
  This AppReport issue.name is also currently being used in the File Incidents Detail Modal above the incident's line number and message:
  
  
  
• Lastly, the "All incidents" tab of this modal contains a list of the incidents beyond the first 5 we show detail for. I currently just show the line number and the beginning of the `message` field, but the mockups also have an incident name in this table. I'm not sure where that incident name would come from, and if it is just the issue name again it wouldn't be useful here since it would be the same text on every row. If we do want a name column with something different on each row here, where does that come from? I imagine that's also what we would want to show in the last screenshot above.
  
  

Right now it seems like the Issue `name` is being used for all of the above under the hood, and I don't know where that value comes from or whether it is useful to the user. Does anyone know if there is something better to use that indicates what rule is being violated? Someone mentioned that it should be the first line of the `message`, in which case that should ideally be made its own field somewhere or used as the Issue `name`.

If anyone has input on the above or anything else about how we display the underlying data in these views, please let me know!

Thanks,

Mike

[Shawn Hurley]

Hello All,

Thanks for starting this thread, Mike!

I want to ensure rule authors understand what data would be displayed where.

What we have as the output is:

https://github.com/konveyor/analyzer-lsp/blob/main/hubapi/violations.go#L24

For each entry of a RuleID to a violation that this rule has triggered.

The violation struct is here: https://github.com/konveyor/analyzer-lsp/blob/main/hubapi/violations.go#L52-L74.

We have a description pulled from the rule description here: https://github.com/konveyor/analyzer-lsp/blob/main/engine/engine.go#L488.

It appears that this value may be the ruleID, I think this would be fine, but I do think that we need to agree on what that is.

While ruleID is a unique string, if we advertise that this will be displayed, it could be reasonable to be the displayable field.

We have considered something about the first line from the description as well in the past.

Whatever we decide, we need to update the rules documentation to ensure it captures this decision.

@Jeff, can you help me understand what the addon maps to the name field on the RuleReport?

Thanks,

Shawn Hurley

> On Jun 13, 2023, at 5:03 PM, Mike Turley <mtu...@redhat.com> wrote:
>
> Hey team,
>
> On today's design sync call I walked through the Issues page as it currently stands (which I will also be demoing at this week's Konveyor Community Meeting) and raised some questions about whether we are displaying the right fields from the hub's JSON objects in the right places. It was suggested that I start a thread here to involve everyone in reaching a consensus on this stuff.
>
> Before I get into the specific fields, it may help to share an overview of how objects returned from the Hub are mapped to the different pages in the UI since the naming is a bit funky. The part of the UI being demoed this week is the "All issues" tab of the Issues page, which has the following views:
> •
> Issues Table: A list of the hub's RuleReport objects, which are Issues collated by ruleset and rule.
> • Affected Applications Table: A list of the hub's AppReport objects, filtered by ruleset and rule, which contain properties from an Application and from the Issue that matches each unique combination of [app id, ruleset, rule].
> • Issue Detail Drawer: Opens when clicking an application on the Affected Applications Table, and contains an Affected Files Table. This table is a list of the hub's FileReport objects matching the issue id on the AppReport.
> • File Incidents Detail Modal: Opens when clicking a file name in the Issue Detail Drawer. Shows details for Incidents matching the issue id on the AppReport and the filename on the FileReport.
> Most of the text in the mockups for these views (see the clickable prototype here) come from obvious places in these objects. The ones I'm not sure about are the meaningful-to-the-user "names" of things. (the screenshots contain text from mock data provided by the "hack" scripts in the hub repo):
> •
> The "issue name" shown on the Issues Table: currently I am using the `name` field on the RuleReport, which I believe is the `name` field of the underlying hub Issue object (which I guess comes directly from the analyzer's "Violation" object per today's call? correct me if I'm wrong @Jeff Ortel @Shawn Hurley ). For this we want a human-readable name that explains what the problem is - perhaps this should instead be a rule name? We decided not to display the ruleset and rule in this table, so it is important that this name is meaningful.

> <Screenshot 2023-06-13 at 4.25.25 PM.png>
> This name is also shown in the breadcrumb bar of the Affected Applications page to indicate which row of the Issues Table the user came from:

> <Screenshot 2023-06-13 at 4.31.53 PM.png>
>
> • The "issue name" shown on the Issue Detail Drawer and the File Incidents Detail Modal: I'm currently using the `issue.name` field on the AppReport. It seems to me that this should be the same "issue name" used above, and I believe the way the AppReport is implemented this name does in fact also come from the underlying Issue object.
> Note also that the application name is shown in small text above this, and I'm not sure if the two should be swapped. This drawer will be reused when clicking on an Issue in the future Single Application tab as well, so it is important to show both the "issue name" and the application name on it.

> <Screenshot 2023-06-13 at 4.39.13 PM.png>
> This AppReport issue.name is also currently being used in the File Incidents Detail Modal above the incident's line number and message:

> <Screenshot 2023-06-13 at 4.39.49 PM.png>
>
> • Lastly, the "All incidents" tab of this modal contains a list of the incidents beyond the first 5 we show detail for. I currently just show the line number and the beginning of the `message` field, but the mockups also have an incident name in this table. I'm not sure where that incident name would come from, and if it is just the issue name again it wouldn't be useful here since it would be the same text on every row. If we do want a name column with something different on each row here, where does that come from? I imagine that's also what we would want to show in the last screenshot above.

> <Screenshot 2023-06-13 at 4.43.42 PM.png>
> Right now it seems like the Issue `name` is being used for all of the above under the hood, and I don't know where that value comes from or whether it is useful to the user. Does anyone know if there is something better to use that indicates what rule is being violated? Someone mentioned that it should be the first line of the `message`, in which case that should ideally be made its own field somewhere or used as the Issue `name`.
>
> If anyone has input on the above or anything else about how we display the underlying data in these views, please let me know!
>
> Thanks,
> Mike
>

> --
> You received this message because you are subscribed to the Google Groups "konveyor-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to konveyor-dev...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/konveyor-dev/CA%2Bc%3D3NtwVx%2BQFZM4YZz467MXNrYeBxprCJ%3Dz%2BFXWMW8C6t0RnA%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

[Mike Turley]

I have an another unknown to tack on here. This is the mockup for the expanded content of an Issue in the Issues Table:

Under "Level of effort", there is a sentence explaining "Trivial change or 1-1 library swap". This implies to me that we need some kind of mapping of effort number ranges to sentences describing the meaning of that level of effort. Is this something we just want to remove?

[Shawn Hurley]

Hello,

We have the concept of “Effort” that is just an `int,` rule authors can put any value into it. We don’t have any idea of a string or some set values that are allowed.

We need to understand if the hub is doing a conversion if we want to do int ranges or something to a string.

Is there any user value for this string vs. a number?

Thanks,

Shawn Hurley

> On Jun 14, 2023, at 12:51 PM, Mike Turley <mtu...@redhat.com> wrote:
>
> I have an another unknown to tack on here. This is the mockup for the expanded content of an Issue in the Issues Table:
>

[Mike Turley]

I think it may have been from an earlier design iteration when we were not sure what "effort" was going to mean. If nobody objects, I think we can just show the number.

[Shawn Hurley]

Plus one from me, no objections for effort,

To make sure it is not lost, we still need to understand rule id vs. name in the RuleReport.

Thanks,

Shawn Hurley

[Mike Turley]

Bumping this thread. Does anyone know who would have the answer to this question about what name for a rule/issue is meaningful to show a user? @Pranav Gaikwad maybe?

[Pranav Gaikwad]

There is no specific Name field in the Rule. The reason is that name and ID fields are kind of the same i.e. we need the ID to be unique, but its just a string. So an imaginary rule with ID "awesome-golang" would really just have "Awesome Golang" as its name. Also, the rule name won't be very useful in the context of an issue.

On the other hand, there is a description field in every rule that really tells what the rule is about. We can use the first line from the description (and wrap it after certain characters) as issue column on the first page. Even better, split them into ID and Description column and have both displayed.

In any case, in the expanded drawers, we can keep the ID as the title in bold and following text (wherever applicable) be description or message (depending on whether it's an incident or an aggregate view).

[Pranav Gaikwad]

Here is an example of descriptions we have for Rules https://github.com/konveyor/rulesets/blob/86c5118cad573292cd1ffde26182626264aec406/default/generated/azure/02-azure-logging.windup.yaml#L3-L5

[Mike Turley]

Thanks Pranav!

To view this discussion on the web visit https://groups.google.com/d/msgid/konveyor-dev/564bd820-ccea-4975-afe8-78d4be82103an%40googlegroups.com.