Workflow report enhancement ideas

[AnnaSyme]

A list of things that I discovered while working on workflow reports that could be good to fix if anyone knows how. Not really bugs.

• Embedded dataset. If this file is a table, it appears in the report with a header line, and the columns are labelled "0" and "1" and so on. It would be good to have no header line.
• For: Insert current time as text. Time shows as "16 August 2023 at 06:42", it would be good to specify this is UTC
• For: Time workflow was invoked. Shows as "2023-08-16T06:33:14.822141". Would be good to format more clearly, and specify as UTC
• Useful inclusion: an image of the workflow (e.g. as on the canvas).
• General formatting: tables. It would be nice to be able to compress the spaces between lines more here; i.e. to have some option of more compact formatting.
• For: Job metrics as table. This can be shown for a particular job done by a tool. It would be good if the output shows what job/tool this is. (The user can add this in the report as a heading though).
• For: Job parameters as table. The output doesn't show what tool was used, it would be good if it did.
• Useful inclusion: current citation for the Galaxy instance it ran on.
• Useful inclusion: workflow version
• Useful inclusion: workflow licence
• Useful inclusion: annotation
• Workflow report doesn't display png or jpg image #16558

[hexylena]

xref #15220, but love all of these suggestions!

[jmchilton]

current citation for the Galaxy instance it ran on.

Is an oddly difficult thing to do but we should be able to make it configurable by Galaxy admins - similar things are needed for like service info on GA4GH service blocks. I assume you want this to be like a Galaxy title (e.g. "The European Galaxy server") and URL (e.g. https://usegalaxy.eu)... and not like a formal "BibTex" citation or something like that.

[bgruening]

@jmchilton I think a more structured about-configuration would be useful in general (maybe as a separate file). We can use that in the about-page as well for example or display the content via schemas.org Organisation.

[jmchilton]

An Organization is not a website right? I don't mind attaching an organization config parameter and deducing... things from that... an about configuration or service info stuff... but is that what is wanted for the report?

[AnnaSyme]

Thanks all, I think it would be useful to have the Galaxy title and the URL, and perhaps also the release number. Not sure the best way to structure it...

[jmchilton]

Galaxy version is available... it is generated at report runtime though... so useful if you generate your report right away potentially.

```galaxy
 generate_galaxy_version()
 ```

It would be nice to have a Galaxy version of the runtime execution for workflows though. We record galaxy_version for jobs but not for invocations.

[jmchilton]

I've thought a lot about Useful inclusion: annotation and I think it shouldn't be implemented. The annotation field is a property that belongs the abstract definition of the workflow (what we call a storedworkflow internally) and not the particular workflow that was executed (what we call a workflow internally). This means if you generate a report after the workflow has been updated - it will use the annotation of the newer version and potentially include bad information. Is that fair?

I've seen annotations used different ways in different places - sometimes some of that information would be really useful in the report and would benefit from richer markdown options. I think the thing that should be done there though is a longer term project of adding like "Instructions Markdown", "Inputs Markdown", "Outputs Markdown", "Implementation Markdown" as fields on the workflow object that can be updated overtime and appear in the run form, etc... I've seen internal workflows with rich, rich descriptions encoded in the annotation and I'm sad Galaxy doesn't support them better and just forces everything into a plain text simple textbox.

[abueg]

Hello! I was wondering if it would be feasible to have a table/list/textfile of various command lines run throughout a workflow, kind of like exporting it as a script. I ask since genome report/note publications often require such a table of commands run along with their parameters, so it would make it much easier to report that if I could just get the actual command lines that were used throughout a workflow. It wouldn't need to be all of the commands, so having the option to pick from the jobs (like how the current Job Parameters as a Table etc options are) would be fine.

[abueg]

for workflow reports, can we have a summary of the job states for the workflow invocation?

and if the workflow report species an output from a job that fails, can it say that job failed?

[assuntad23]

Status update on this issue (including PRs still in review):

• Embedded dataset. If this file is a table, it appears in the report with a header line, and the columns are labelled "0" and "1" and so on. It would be good to have no header line.
• For: Insert current time as text. Time shows as "16 August 2023 at 06:42", it would be good to specify this is UTC
• For: Time workflow was invoked. Shows as "2023-08-16T06:33:14.822141". Would be good to format more clearly, and specify as UTC
• Useful inclusion: an image of the workflow (e.g. as on the canvas).
• General formatting: tables. It would be nice to be able to compress the spaces between lines more here; i.e. to have some option of more compact formatting.
• For: Job metrics as table. This can be shown for a particular job done by a tool. It would be good if the output shows what job/tool this is. (The user can add this in the report as a heading though).
• For: Job parameters as table. The output doesn't show what tool was used, it would be good if it did.
• Useful inclusion: current citation for the Galaxy instance it ran on.
• Useful inclusion: workflow version
• Useful inclusion: workflow licence
  > * [ ] Useful inclusion: annotation
• Workflow report doesn't display png or jpg image #16558

[jmchilton]

for workflow reports, can we have a summary of the job states for the workflow invocation?

I think the workflow reports have been pretty explicitly designed to serve as a final summary of completed workflow invocations. I think a lot of the components and such will breakdown in unpredictable and unfriendly ways until the workflow has completed and completed successfully.

I think the invocation view in recent versions of Galaxy does a good job of summarizing the workflow status and letting you dig into state of jobs and steps and datasets and collections. I think augmenting those more static UIs would be the correct approach here to make it easier to understand the current state of the workflow. Does that make sense? If yes, would you be willing to create an issue with ideas for improving that UI.

[mvdbeek]

Some background on this: You can see the invocation report for a failed invocation or an invocation with failed jobs and have no clue that's the case. Something needs to either be in the report or we need to disable the report when something failed.

[jmchilton]

I agree we should degrade a lot more gracefully... I just don't think we should build features in this direction.

[jmchilton]

Assunta wanted me to comment on these two bullet points:

For: Job metrics as table. This can be shown for a particular job done by a tool. It would be good if the output shows what job/tool this is. (The user can add this in the report as a heading though).
For: Job parameters as table. The output doesn't show what tool was used, it would be good if it did.

I think we should not be auto-adding headers to components in general because we don't know the context they will be used in. I've articulated the issue with it in this PR (#16994) which has been merged and will be fixed in the next release of Galaxy.

That said - I do think the author of the document should be able to add titles and footers to any component. I've been doing some work in that direction. This PR (#16681) has a general syntax for headers and footers that can be added to a new component in that PR but I would like to generalize it to work with more of the components and I'll start with job metrics and job parameters.

The current prioritized TODO list for the markdown work to my mind is:

• Fix image display bug. (workaround history_dataset_as_image)
• Implement titles and footers on job metrics & job parameters (implemented in Expose more tool information / navigability in UI. #17105)
• Job-related parameters in invocation report don't work for map over jobs #16863
• workflow report publishing should publish the dataset #13926
• Workflow Reports/Pages papercuts #15220 -> PDF Embeds
• Make help completely not broken.
• Document full set of options for directives in help automatically.
• Workflow Reports/Pages papercuts #15220 -> Selecting an Image should filter on image types maybe? I.e. not list a bunch of hidden, tabular files?
• Workflow Reports/Pages papercuts #15220 -> List tags in addition to filenames in selector
• Workflow Reports/Pages papercuts #15220 -> Do not show hidden files in file selector (unless I check a box)
• Workflow Reports/Pages papercuts #15220 -> Permit multi-selection of e.g images to embed
• Workflow Reports/Pages papercuts #15220 -> Allow specifying a size for images that get embedded.
• Expose title, footer, size, and all other options in the GUI for adding various components. Currently adding a component is only selecting the target but we should expose additional options for customizing the component.

[jmchilton]

For: Job parameters as table. The output doesn't show what tool was used, it would be good if it did.

This is implemented in a way I'm very comfortable with in:

#17105

[assuntad23]

I think we can consider this initial list of WF report enhancement ideas complete, as most of the other issues that are linked here (in John's comment) are standalone issues that have their own issue number.