CrossRef and DOI UI/UX quality of life improvements

[ewhanson]

Outline of changes to be made to the CrossRef and DOI plugins to improve the usability of the CrossRef plugin and DOI management workflows.

DOI Tasks

• Restrict the availability of custom DOI suffixes
• Remove "nuclear button" options to clear and/or reassign DOIs from web GUI
• Provide a direct link to the DOI management page in Dashboard for managers
• Remove DOI management functions that have been scattered throughout the OxS UI

CrossRef Tasks

• Update DOI management to use new Vue.js display UI
• Add a "Select all" button
• Add an Issues filter
• Add DOI status filters
• Provide straightforward actions for selected DOIs (e.g. batch reset or clear DOIs, check status, etc.)
• Improve DOI submission error feedback

[ewhanson]

Hi @NateWr and @asmecher, thanks for your initial feedback and for taking a look at the work so far. I prepared draft pull requests for OJS, pkp-lib, and the UI library.

Thanks!

PRs:
pkp/ojs#2949
pkp/ui-library#134
#6466

[NateWr]

Looks good, Erik! I haven't looked at the code, but here are a few suggestions for the UI/UX.

1. Move the menu item to the top group and call it "DOIs". This should be treated like content that is managed regularly rather than settings.
2. "Article DOI Management" -> "Article DOIs" (same with issues)
3. Convert the issue select filter to FieldSelectIssues (plural -- see the submission lists)
4. The ListPanel needs support for pagination.
5. "Not Published" -> "Unpublished"
6. "! Needs Depositing" -> "Not Deposited"
7. We can't use a <list-item>'s value slot for text like that, because it has a fixed width and the width of text will change from language to language. Try using a Table with a custom column for the field. There may be accessibility issues with that which need to be investigated. The Table component is a DataGrid but we may need to look more closely at how to implement editable cells... or consider an alternative. Maybe even turning the whole bottom bit into a Form to meet accessibility requirements.
8. The crossref deposit string (notDeposited). This should be at the DOI level, rather than the submission level, right? Wouldn't each DOI have its own status?
9. I'm seeing settingValue null in the console when I click Edit on a DOI.

The most common action here will be to go in and deposit all outstanding DOIs, right? I'm always nervous about Select All features because those only work for the items in the list, but users don't always clearly understand that there may be additional items in other pages that are not included in the action. We also can end up with submissions falling through pagination gaps as they select all in one page, deposit, go to the next page and repeat. In the time between depositing one page, and loading the next page, the count can change, so that a submission moved from page 2 to page 1. That submission will not get deposited because the user thinks they've already done everything on page 1.

If we think the most common desired action is to deposit all outstanding DOIs, let's make an action that does that. Here's an example of how that can work:

In terms of the design/layout, I think we're in danger of having too much button clutter at the top. Here are some ideas to consolidate controls and reduce cognitive load.

Consider moving the select/actions stuff into a single control. The way that it is done now, the Actions don't appear to be related to the Selected items. Here's what that might look like:

And lastly, there's always an option to show filters by default. This can reduce the number of buttons at the top. And my guess is that managers will rarely want to use the default view. They'll want to be looking for published submissions or filter by issues.

[NateWr]

I forgot to add that you can see the hacking I did for these suggestions at NateWr/ui-library@d6c0273

[NateWr]

Sorry, I also forgot my recommendations for the expanded item area. The actions should be moved down below the list. This will also keep it from cluttering the summary with badges/buttons.

[NateWr]

Last one, I swear! I notice that the list includes incomplete submissions. These can probably be removed (pass a false isIncomplete param in the getParams). You might even consider removing everything that's not in Copyediting/Production -- though check with James/Mike first.

[ewhanson]

Thanks, @NateWr! This all sounds great and is really helpful. I'll work on getting this implemented and ping you once it's done.

[bozana]

Hi @ewhanson, I have taken a look into the code and everything looks very good for me (a lot of things are also new for me, but as far as I could see it for now...). Great work! ⭐
I have only two questions:
It is checked if the Crossref plugin is enabled in order to add/provide the Crossref functions, right? I think the import/export plugins are enabled per default, so maybe it could be checked if the required Crossref plugin settings are there, e.g. depositor name, instead? (I actually suppose that all this and some fine tuning will come when the Crossref deposit function is integrated and/or with some of those TODOs left in the code... but wanted to double check and keep in mind...)
Could there maybe be a way to consider changing/editing/assigning a DOI to different article versions? -- Currently only the last published version is considered in the new DOI Management page. As far as I understand this is the main way that we would like to support, but -- as currently possible in the identifier tab -- we allow the editor to assign different DOIs to different versions/publications, but leave also the responsibility to him/her to register it correctly/manually. Would this kind of support be possible/make sense in the new DOI Management page as well?
Thanks a lot!

[ewhanson]

Hi @NateWr, I've gone through and updated the UI aspects of the the DOI Management page based on your feedback. Would you be able to have a look. Here are a few notes on the changes. Thanks!

• As you suggested, I replaced using the <list-item>’s value slot with a Table. With it set as a table, the column size is changing when interacting with it. Do you have any recommendations on how to handle this?
  
• You asked about notDeposited and how it’s currently at the submission level rather than the DOI level. The data is sent to Crossref at a submission level, so the status will be the same for all DOIs associated with a submission.
• Regarding which submission to include on the DOI management page, I talked with Mike about this, and his perspective was that only published articles should be showing up here. I’m not sure if this would conflict with some of the potential use cases, so I’ll hold off on making that change for now.

The drafts PRs are the same as before.

PRs:
pkp/ojs#2949
pkp/ui-library#134
#6466

[ewhanson]

Hi @ewhanson, I have taken a look into the code and everything looks very good for me (a lot of things are also new for me, but as far as I could see it for now...). Great work! ⭐
I have only two questions:
It is checked if the Crossref plugin is enabled in order to add/provide the Crossref functions, right? I think the import/export plugins are enabled per default, so maybe it could be checked if the required Crossref plugin settings are there, e.g. depositor name, instead? (I actually suppose that all this and some fine tuning will come when the Crossref deposit function is integrated and/or with some of those TODOs left in the code... but wanted to double check and keep in mind...)
Could there maybe be a way to consider changing/editing/assigning a DOI to different article versions? -- Currently only the last published version is considered in the new DOI Management page. As far as I understand this is the main way that we would like to support, but -- as currently possible in the identifier tab -- we allow the editor to assign different DOIs to different versions/publications, but leave also the responsibility to him/her to register it correctly/manually. Would this kind of support be possible/make sense in the new DOI Management page as well?
Thanks a lot!

Hi @bozana, thanks so much for the feedback! And sorry for taking so long to get back to it.

For your first question, right now the import/export plugins are not loaded by default, only the generic and pubId plugins are (hence the messy work around). This came up before in #5467, which resulted the pubId plugins being loaded from the beginning alongside the generic ones. One solution that we talked about before would be to create a generic plugin wrapper around the current Crossref import/export plugin so that it would be loaded at the beginning. What are your thought on that idea?

Regarding assigning DOIs to different versions of the article, based on feedback from Mike Nason, the goal right now is to remove the ability for editors to assign different DOIs to different versions (this will be removed from the identifiers tab). Based on the workflow Mike outlined to me, when a new version of a publication is created, the metadata (including information about the update) should be pushed to Crossref to update the existing DOI. I don’t think adding this in to OJS specifically makes sense quite yet, but this type of functionality will be necessary if the new DOI Management page is going to be used with OPS in the future.

How does all that sound to you?

[NateWr]

based on feedback from Mike Nason, the goal right now is to remove the ability for editors to assign different DOIs to different versions

I'm sympathetic to @AhemNason's position, but at the Barcelona sprint it was clear that there is not agreement on this point (cc @mtub). Some institutions will want/expect to be able to assign a different DOI to different versions. The current DOI assignment UI was designed to discourage but permit this.

I'll keep this in mind during my review and see if there is some way that we can work this into the new UI, while still discouraging it as a normal practice.

[ewhanson]

Thanks for the context @NateWr. That's helpful to know. I'll take a look at adding support for that on the export/depositing side of things.

[AhemNason]

It wasn't just my opinion. It was Crossref's.

[AhemNason]

Multiple versions of pre-prints is recommended. Using Crossmark for DOIs for published articles is recommended.

[NateWr]

Looks good @ewhanson! A lot of work here and it's coming along great.

only published articles should be showing up here.

Yes, I agree. I think the list should load with only published items and "unpublished" should be a filter that can be toggled on/off. Also, it should not be possible to deposit unpublished items. In fact, for the first release of this, I'd be happy if unpublished items were just ignored completely.

You asked about notDeposited and how it’s currently at the submission level rather than the DOI level. The data is sent to Crossref at a submission level, so the status will be the same for all DOIs associated with a submission.

Got it. Either way, we'll need to map the status string, like notDeposited, to something that people understand. I've been thinking some more about how to separate out the DOI management from the depositing. I'd like to see something that indicated the status more clearly and gave the plugin some room to say more.

Here's a quick mockup that shows how that might work, as well as how we can provide access to editing other versions when needed:

The Crossref box should change depending on the status:

As you suggested, I replaced using the ’s value slot with a Table. With it set as a table, the column size is changing when interacting with it. Do you have any recommendations on how to handle this?

This is going to be challenging, because the save status and other things all need to happen inline. Let's talk about this some more once we've talked about the nested components thing I talk about here. But one idea is to move the saving out of the individual DOI field and use a UI more like this:

Here are some additional things to address/discuss:

1. The expand/collapse button works on all items regardless of which are selected. This should only effect the selected items.
2. The URL for each submission should maybe go to the workflow. The published URL doesn't work for items that aren't published. (This won't matter if we remove all unpublished items for now.)
3. When I edit a DOI and click save, the old DOI is restored to the input field. Is this just not done yet?
4. When the page loads, the DOIListPanel says "no items found" while it is fetching items. This needs to say loading. Here's an example of how to do that.
5. The checkbox positioning is slightly off. Assign .doiListPanel .listPanel__selector { line-height: 100%; } to veritically centre the checkbox.
6. The DOI field is still there in the publication tab. Presumably this will be removed when we're done, right?

[ewhanson]

Hey @asmecher and @NateWr, I'm working on setting up an API call for handling the exporting/depositing actions for the Crossref plugin and ran into an issue. I'm using a custom API endpoint to trigger the exporting/depositing logic from CrossRefExportPlugin but run into trouble in the filter here: https://github.com/pkp/crossref-ojs/blob/bf4d17d6c4bd7de8b25916c49e75617599e39af1/filter/IssueCrossrefXmlFilter.inc.php#L194-L197

if ($issue->getDatePublished() && $issue->getStoredPubId('doi')) {
	$request = Application::get()->getRequest();
	$journalIssueNode->appendChild($this->createDOIDataNode($doc, $issue->getStoredPubId('doi'), $request->url($context->getPath(), 'issue', 'view', $issue->getBestIssueId($context), null, null, true)));
}

The request in this case is coming from the APIRouter and I'm getting this exception: "APIRouter::url() should not be called with an op, path or anchor. If a new context is passed, the context path must be passed instead of the context object."

Any advice on how to approach handling this from within an API call or starting a new request to handle the exporting/depositing?

Thanks!

[asmecher]

@ewhanson, OJS picks a router if you don't specify one, and in this case it picked the API router when you actually want to generate a page router URL. You can manually specify what kind of router you need as follows:

$dispatcher = $request->getDispatcher();
$url = $dispatcher->url($request, ROUTE_PAGE, $context->getPath(), ...)

[ewhanson]

Thanks @asmecher, that's exactly what I was looking for!

[fgnievinski]

I'd like to suggest splitting in three the current option of the CrossRef plugin to enable DOI for (all) galleys:
a) enable DOI for supplementary materials
b) enable DOI for article main body file formats
c) enable DOI for article main body items (tables, figures)

Option (a) is more common in commercial publishing, where additional DOIs would be registered for supplementary materials (meaning appendices to the article main body) only if they are expected to be specifically linked to from the article main body. Examples are additional tables or figures or a detailed methods section too large for the main body. Supplementary materials are special also because sometimes they are indexed for citation analysis ("Use and mis-use of supplementary material in science publications"[1]).

Option (b) could be disabled by default. We shouldn't be encouraging the assignment of additional DOIs for each file format (PDF, HTML, XML) of the article main body (full "text" plus display items, such as figures and tables). It may create confusion, as normally users should be citing the landing page, not a specific file format. At least for CrossRef, one should "Ensure that your DOI links resolve to a landing page."[2]

Option (c) are items already included in the article main body, such as figures and tables with regular numbering (Fig. 1, Tab. 1), not supplementary numbering (Fig. S1, Tab. S1). I think it could be disabled by default. Notice I've avoided the term "component", as it has a narrower meaning in the context of CrossRef:[3]

"Components are only intended to be used for supplementary materials (e.g. figures, charts, tables, etc.) that have a single parent-child relationship to some publication."

I thought the present issue #6062 would be a good opportunity to disentangle these three types of galleys currently lumped together in the CrossRef plugin: (a) supplementary materials, (b) different file formats of the main body, and (c) specific items in the main body.

[NateWr]

@fgnievinski I've created a new issue for this suggestion, because Erik is almost done with this one and when he merges the proposed changes we'll close this issue. You can find the new issue at #7666, and I'll leave an additional comment there.

[bozana]

Are we planing to provide any help message when validation errors occur? Does this maybe belong to the TO-DO "Improve DOI submission error feedback" listed above?

[NateWr]

@bozana, we capture the error response from Crossref and set an "error" status on the DOI. The DOI management UI then provides a button to view the error message when a deposit has failed. This is just the XML error message from Crossref, so not always very user friendly, but it's a first step.

[bozana]

Thanks a lot @NateWr. In my case: I wanted to export an XML file and got the message that validation error occurred. I am not sure if the validation also happens before the registration with Crossref -- earlier it was so... I then needed to take a look at the XML file in the temp/ folder to see what is wrong... I think in my case the DOI was not assigned to that object at all. The status was 'Unregistered', so maybe this might/should be differentiated too?

[NateWr]

Ahh, I'm not sure how validation errors are handled with the XML export option.

[AhemNason]

Hey folks, I just wanted to break down the error message and what's useful for us and what's useful for Crossref when helping someone with support.

Of the stuff present here, the biggest one is the error itself, obviously. I don't know that we have, necessarily, easier or more user-friendly ways to represent this data but, I could probably create a list of "layman's terms" answers for common problems and we could match against the error language, if that sounds amenable to folks.

The only other big pieces here are the submission ID and the batch ID. Probably also timestamp. If we could change the error modal to have like...

• timestamp
• submission id (crossref will ask clients for this when troubleshooting an issue)
• batch id
• error message
• and then a button for "view details" to expand the full json/xml error, that would probably help folks a lot...

To answer bozana's other question, validation can happen before deposit if you've selected the "validate xml" checkbox. This is like a sanity check before deposit or export. It will tell you if something is invalid before an attempt at a deposit.

[bozana]

Thanks @AhemNason. I know it was so earlier, but with the new changes I do not know when it happens -- I would need to take a deeper look in the code...

Those validation errors are 'impossible' to make user friendly :-( -- It can be anything... But...

[AhemNason]

Could Crossref perhaps be of assistance in pushing us less wild error messages somehow?

[ewhanson]

All steps outlined in this meta issue have been addressed! 🎉