Pkp-lib: Improve author/user names

[asmecher]

• [ ] Support multilingual names (important for users that work in e.g. both Cyrillic and Latin character sets)
• [ ] Consider whether to remove the Western-centric First, Middle, Last name divisions

[asmecher]

@jmacgreg and @ctgraham, IIRC both of you worked a couple of sprints ago on a document that surveyed the third-party standards we support to see whether metadata mismatches would be imposed by e.g. having multilingual names, or not having first/middle/last. Does either of you have that handy?

[crosfield]

I think the second problem is easily solved. In Russia and some other Eastern European countries instead of the Middle Name is a Patronymic Name (father's name). It is always specified in the articles, for example, in Russian journals. The First Name is always the proper Name, and Last Name - Surname (family name).

[asmecher]

@crosfield, the second issue isn't really a problem in Western/Eurocentric cultures; it's definitely a problem elsewhere. See https://www.w3.org/International/questions/qa-personal-names, which recommends just going with a single field. However, as with multilingual names, the problem will be finding a model that plays well with all the various metadata standards we need to provide data to.

[ctgraham]

A brief summary of the sprint outcomes is:

Discriminate name localization based on script changes
    that is, when installed locales diverge in script types (latin, cyrillic, arabic, etc.), then and only then, multilingual name entry is enabled.
Clarify "first" and "last" names as "given" and "surnames". Require only "given" name.
    This means that an institution or an organization would only have a given name, as well as individuals who use mononyms.
Provide optional fields to customize the display of the name in the event that name ordering is not "Given-name Surname".
    All users would be able to fill in a field "preferred method for being addressed"
    Authors and reviewers would be able to add a "published name"
    Citation plugins should provide a preview option, and allow the author to change the display of the name within the citation.

I'll see if I can find the sprint document, which also surveyed name usage in various metadata formats.

[ctgraham]

The sprint document has a substantial focus on handling mononyms:
https://docs.google.com/document/d/17oAPcCTL3tc7MhlcHpyVekv6_AxTHDc6BirHD3lVtJA/edit

[asmecher]

@NateWr, would a switch in name fields "first (required)/middle (optional)/last (required)" to "given (required)/family (optional)" have nasty impacts on the CiteProc stuff?

[NateWr]

Nope. That's the breakdown they expect:

https://github.com/pkp/citationStyleLanguage/blob/master/CitationStyleLanguagePlugin.inc.php#L335-L344

[litvinovg]

I've made some modifications to make fistName lastName and middleName fields multilanguage. I've moved these fields into author_settings table.
Fogot to add dropping sql fields first_name, last_name and middle_name, sorry.
Hope it will be use usefull for you.
There are 3 pull requests as a solution for this issue:
https://github.com/pkp/pkp-lib/pull/3128
https://github.com/pkp/ojs/pull/1731
https://github.com/pkp/citationStyleLanguage/pull/14

[asmecher]

@litvinovg, thanks for contributing! This will probably require another look, but some broad comments...

• This doesn't consider removal of the Western-centric First, Middle, Last name divisions. IMO we should tackle that at the same time as we add multilingual support, otherwise we'll have more name data models to consider (and these are a real maintenance headache).
• Upgrades aren't considered yet
• This leaves user accounts non-localized, meaning users will still be forced to pick a single locale for their accounts, then enter any other locales when submitting an article. (The article submission process might be broken too, see next point)
• I suspect the changes to Identity will cause problems with PKPUser/User subclasses, as they don't expect first/middle-last names to be localized
• I think there are a lot of uses of getFirstName/getMiddleName/getLastName that are not adapted, at least by using getLocalized..., or ideally by supporting multiple locales in whatever place they're used (e.g. CrossRef etc).

[asmecher]

See also https://forum.pkp.sfu.ca/t/dual-language-journal/13157

[vasylOstrovskyi]

@asmecher My modifications mentioned in the above forum discussion include 21 files with modification of classes and templates, and about 200 lines of code, providing quite usable (basic level is sufficient for my needs) installation. As above, it is based on putting names to author_settings and user_settings, but most critical issues are resolved. I really need this and plan to spent some more time to resolve more issues which are important for me.
Of course, this does not resolve the mentioned name division problem. However, I see that many people will be happy without it.
If you think that it is worth doing, I will upload my work to github. However, I am new with it and will need some advices about details of the process.

[alireza08]

Hello all,
Dear @vasylOstrovskyi , I am also working on this item. please guide me about the files that need to be modified; or if possible, share the modified codes with me. we can complete this together.
Best,

[litvinovg]

I have added some commits to use localized getters, moved user's fields first_name,last_name and middle_name to settings table too. It seems to work well now. I have defined constants to change field names more easily.
Sorry about spaces in code.

[alireza08]

Hi @litvinovg ,
Thanks for the shared codes. it works great and saved me a lot of time. however, in the Users page , user first name and last names are not displayed in either languages. (attached screenshot)
please let me know about which files should be edited and I'll try to develop it.

Cheers,

[litvinovg]

You should enter names for authors and users again because in original code there is no information in what language you have entered old names. Another approach is to create a script to transfer first_name, last_name, middle_name from users and authors tables into user_settings and author_settings and specify your locale.

[alireza08]

Hello @litvinovg,
Yes, I was aware of that and filled user_settings and author_settings tables with the correct value based on locale. But, the names are not displayed.
Interestingly, if I search a name, correct values for first_name and last_name appear in the grid box.
Any ideas?

Best,

[litvinovg]

You must haven't applied all the commits from authors_multilanguage branches in ojs and pkp-lib.

[litvinovg]

alireza08, lets discuss this on PKP forum. This issue isn't the right place for this discussion.

[litvinovg]

asmecher, In my opinion current West-centric name divisions could be used elsewhere without any problem because:

1. first name could be used as Given, last name - as Family, middle name could be omitted.
2. Usually the reason for using OJS is to be cited and available in Western world.

As you may have seen I have added some commits to authors_multilanguage branches and now has been successfully tested by some users on PKP forum and by editors on our journals' sites.
It would be great if you could find a way to use this code in some unstable OJS branch. I suppose, I have taken into account your previous comments. If you want me to add some more fixes in code, just let me know.
Updated pull requests
https://github.com/pkp/ojs/pull/1763
https://github.com/pkp/pkp-lib/pull/3194

[vasylOstrovskyi]

Dear @litvinovg, I did some work in parallel and also have a working installation. I am not yet comfortable with github, so I put my patch to this location. If there are some pieces of code which you could incorporate into your code, feel free to do that. Also I put there a database migration script.

[damatveev]

Dear @vasylOstrovskyi, нow to apply your update?

[vasylOstrovskyi]

Dear @damatveev, the patch I mentioned is in the standard diff format. For Linux, use 'patch' utility, or ask Google 'how to apply patch'. However it seems that Georgiy Litvinov's work is much more complete, so it probably could be better to use his work instead. The database migration php script should be placed into tools/ directory and run from commandline.

[bozana]

@asmecher, @NateWr: The current CSL plugin requires family name. And we are implementing the family name to be optional. Thus for those rare cases, where we do not have the family name, do you think we can provide to CSL the author's given name as the family name (and no given name)? I actually do not see other possibility. But maybe this is also OK -- this is how author's name is, if we call it given or family name. What do you think?

[asmecher]

Hmm, @bozana, yes, I think that's a good suggestion -- but I think @NateWr also said the CSL developers are quite responsive, so it might be worth filing an issue on their repo.

[NateWr]

I think that would raise questions about the CSL style formats themselves. Just about every format I'm aware of expects a two-part name, since that's how a correct citation can be formatted. I'm not sure if it makes sense for citeproc-php to work without a family name, since the CSL spec pretty much requires it...

[NateWr]

Hmm, I was speaking off-the-cuff. It looks like the schema doesn't technically mark _any_ author property required:

https://github.com/citation-style-language/schema/blob/master/csl-data.json#L78-L83

Does the CSL plugin actually cause an error when no family name is provided?

[bozana]

@NateWr, yes, family name is required, if not provided there is an error in my log file.
I found this "Personal names require a “family” name-part, and may also contain “given”, “suffix”, “non-dropping-particle” and “dropping-particle” name-parts." here (the specification document that is linked from the citeproc-php README): http://docs.citationstyles.org/en/1.0.1/specification.html?highlight=familyName i.e. when you search after "familyName" on that page, but I haven't taken a deeper look what all that there means... :-\
But, it seems to be so -- the CSL plugin only requires family name...

[NateWr]

Nice work sniffing that out. It sounds like maybe the specification isn't strictly accurate.

do you think we can provide to CSL the author's given name as the family name (and no given name)?

That sounds pretty reasonable to me. I think if you posted an issue on the https://github.com/citation-style-language/schema repo, pointing out that the formal schema doesn't seem to require a family name but the guidance says it's required, they might have some thoughts on how they're planning to handle that.

[bozana]

First/test PRs -- for discussion:
https://github.com/pkp/orcidProfile/pull/38
https://github.com/asmecher/lensGalley/pull/28
https://github.com/pkp/citationStyleLanguage/pull/33
https://github.com/pkp/reviewReport/pull/11
https://github.com/pkp/pkp-lib/pull/3671
https://github.com/pkp/ojs/pull/1956
https://github.com/pkp/omp/pull/536
The PRs are for the first review round.

Left:

• consider changing of the site primary locale and the submission locale.

[bozana]

Some notes to discuss:
1. Generally:
- Instead of first and last name, now there are given and family name.
- Middle name, salutation, suffix and initials are removed.
- There is the new "Preferred Public Name" field/setting.
- Given, family and preferred public name are multilingual.
2. The site primary locale is the required and default/fallback locale for users.
3. At the registration only the fields in the UI locale exist. Then the data (given name, family name and affiliation) is copied for the site primary locale.
4. In the user data forms (user and profile forms) the site primary locale is considered and required (for the given name).
5. User import: if the given name in the site primary locale is missing, an existing given and family names will be copied for the site primary locale.
Shall here the affiliation be treated in the same way i.e. copied for the site primary locale? -- According to the Nate's comment below, also the affiliation is treated in the same way.
6. What if the site primary locale changes?
7. The submission locale is the required and default/fallback locale for authors.
8. During submission, the submitter is considered as the author per default. The submitter data (given and family name) in the default site primary locale is copied for the submission locale in this submission step 1.
Maybe also the current UI locale (instead of only site primary locale) should be considered here, and if the data in that locale exists, then to copy them for the submission locale? -- According to the discussion below, the site primary locale will be considered.
9. Author import (as part of the submission): if the given name is missing for the submission locale, the import error occurs (differently to user import, in the native import the error management exists).
10. The new preferred public name field is not per-filled per default. (Most of the languages, e.g. Serbian and Russian) do support/contain also the western "first last name" order.)
11. There is no locale fallback for the new preferred public name -- as defined in the function getFullName(): if the preferred public name exists in the UI locale, it will be used, else the appropriate combination of the given and family name is used.
12. Upgrade/migration:
- First and last names are copied as they are into users_settings and author_settings table and for the site primary locale, using the new setting name 'givenName' and 'familyName'.
- Middle name is added to the given name.
- Salutation and suffix are migrated to the new 'preferredPublicName' setting. They are migrated as there were used till now in the function getFullName, in the appropriate combination with the first and the last name. Because till now they were used as they are no matter what is the locale, they are migrated/copied for each locale -- users for each site supported locale, authors for the existing submission locales (i.e. for which the title exists).
Shall we consider all journal locales for the migration of the author's middle name and suffix into the preferredPublicName here? -- According to the Nate's comment below, all journal locales will be considered for author's migration.
13. The function getFullName decides when the preferred public name and when the given and the family name are used. Whenever the function getFullName() was used without parameters till now, the preferred public name will be used, if exist. Whenever the function getFullName(true) was used with that "true" parameter till now, the preferred public name will not be considered. For this see the use and the definition of the function getFullName().
Where else should preferred public name not be used? -- According to the Nate's comment below, I will check that the preferred public name is not used in any third party service/interface.
14. At some places in the system, where only the user/author last name was used till now, now the getFullName() is used:
- submission backend und author dashboard, page title
- sections listing, section editors
- submission information center, title
15. I've checked all submodules and, as far as I could see it, only the following are affected: CSL, lensGalley, orcidProfile and reviewReport. Correct?
16. I have adapted the plugins/metadata/mods34 plugin, but I have no idea if this is correct and how to test it :-\
17. I ignored lucene plugin.
18. We would then later maybe need someone to test the LDAP plugin.
19. What is the Openurl10 plugin? :-P

@asmecher and @NateWr, if you could take a look at all this, it would be fantastic! :-)
Above all the logic behind the changes, maybe a few examples: the fallback to a locale, custom form validation for the lastName, how getLocalizedData and getLocalizedFamilyName (Identity.inc.php and PKPAuthors.inc.php) is implemented, how getFullName as well as preferred public name is functioning, suggestUsername, getAuthorString, migrateUserAndAuthorNames, ....

THANKS A LOT!!!

[NateWr]

Wow, looks like a lot of work here! I haven't looked at the code yet but here's a first pass at your questions (if I leave one out, it's because it's fine or I can't help):

User import: if the given name in the site primary locale is missing, an existing given and family names will be copied for the site primary locale. Shall here the affiliation be treated in the same way i.e. copied for the site primary locale?

I think so.

What if the site primary locale changes?

Oh. Hmm. Good question. We need it to be populated don't we? My ideal workflow would look something like this:

1. Click to change the site primary locale. A confirmation modal appears saying are you sure, we'll need to update the names in your database, this could take a while.
2. Click yes, the request is fired off. On a very large site, we'll probably need some way to process the changes in multiple requests.

What happens to the system before this work is done? What kind of problems are caused? Maybe we can just run this on a cron job if it's not too disruptive to work a day in the system without the names....

During submission, the submitter is considered as the author per default. The submitter data (given and family name) in the default site primary locale is copied for the submission locale in this submission step 1. Maybe also the current UI locale (instead of only site primary locale) should be considered here, and if the data in that locale exists, then to copy them for the submission locale?

I would say stick with the submission UI locale during submission. 95% of the time this won't be a problem and editors can be responsible for tidying up any wayward data later.

Shall we consider all journal locales for the migration of the author's middle name and suffix into the preferredPublicName here?

Yes? Unless there's a good reason not to we might as well...

[NateWr]

Where else should preferred public name not be used?

I would say use it everywhere unless we need to interface with a third-party syntax (eg - CSL, import/export, crossref, etc.)

Ok, I'll take a run through the code and then try out some of the cases you suggested.

[bozana]

Thanks a lot @NateWr!

A few comments:

What happens to the system before this work is done? What kind of problems are caused?

I think this was not a problem, because earlier the user names were not localized, but now, that they are i.e. above all the given name because it is required, we have to rely on a locale that will make given name always exist for it.
I will see what SQL would be needed for user names in case the site primary locales changes and also see how it performs...

I would say stick with the submission UI locale during submission. 95% of the time this won't be a problem and editors can be responsible for tidying up any wayward data later.

So, this means: If the submitter data (given and family name, eventually also affiliation?) do not exist in the submission locale, see first if they exists in the current UI. If so copy them into/for the submission locale. If they do not exist in the current UI, then take the data in the default site primary locale and copy then into/for the submission locale. OK?

THANKS A LOT!!!

[NateWr]

So, this means: If the submitter data (given and family name, eventually also affiliation?) do not exist in the submission locale, see first if they exists in the current UI. If so copy them into/for the submission locale. If they do not exist in the current UI, then take the data in the default site primary locale and copy then into/for the submission locale. OK?

Hmm, I'm not too fussed either way. In both cases, the user isn't actually entering any of this information during the submission step? In that case, if the correct locale is missing, I guess I'd be tempted to rely on the site's primary locale. But if you think we're likely to get more accurate data from the current locale then take that.

[NateWr]

The code looks great. This is a huge refactor. Kudos for getting through it! I've tried a bit of manual testing and it looks good. I signed up as a new user, modified some users from the admin, changed from the profile area, and looked at the authors display on the frontend and in the metadata.

I only ran into one issue. Here's what I did:

1. Register as new user with just a given name in the site primary locale.
2. Go into my Profile page.
3. Add a family name in a locale that doesn't have a given name.

When I did that, the following appeared, which looks like the form's being tossed into an alert():

Doing the same thing worked fine when I tried these steps from the Edit User modal.

[bozana]

I considered all comments from @NateWr, from here and in the PRs. Thanks a lot @NateWr!
The decisions from here I also added to the summary comment above.
The only one thing left is to consider the changing of the site primary locale and submission locale.
Also, I could do a little bit more testing with OMP.
Else, @asmecher, it is ready for you to take a look :-)
THANKS!!!

[asmecher]

Phew, @bozana, that's a tremendous amount of work. I've scanned the PRs and see a lot of assumptions, but they're sensible ones, and the admittedly increased complexity (particularly in SQL) is balanced by need and some nice clean-up along the way. I suggest we merge this and allow it to evolve/improve/undergo testing in master. That'll give @lilents a chance to rebase against these changes for the versioning code, and give us the longest possible cycle of dev with this stuff well in place.

And thanks for a thorough review, @NateWr -- I had a few immediate questions that I then found well-explored between you and @bozana already. I agree with the convo I saw.

I just had a couple of minor comments I made on the PRs individually -- but certainly nothing worth holding up on. Please go ahead!

[Ph-We]

We'd be happy to test it thoroughly as soon as it's merged!

[bozana]

Thanks @asmecher! I would then rebase and, this change https://github.com/pkp/pkp-lib/issues/3771#issuecomment-395382498 and merge... OK?

[asmecher]

Yes! :fireworks:

[bozana]

Everything merged, thus closing :tada:

[bozana]

@litvinovg, THANKS A LOT for contributing!!! :star2:

[mpbraendle]

We are not happy with the introduced changes for multilingual names. See my comment on https://forum.pkp.sfu.ca/t/translation-of-the-authors-name/14474/122?u=mpbraendle

[asmecher]

We are not happy with the introduced changes for multilingual names.

(Resolved with https://github.com/pkp/pkp-lib/issues/4675 -- to be included in OJS/OMP 3.1.2-1)