Additional data for submissions/{ID}/participants API

[jardakotesovec]

Describe the issue

I would like to use the /submissions/{id}/participants API to replace the "Participants" grid with vue.js component. This issues describe the data requirements to be able to do it.

Behaviour of legacy participant grid

This is the grid we know from workflow page.

My understanding how the list of participants for legacy grid gets created

1. It fetches all userGroups that are assigned to given stage and submission via stage_assignments table. That gives it list of User groups to present in the UI (StageParticipantGridHandler.php -> loadData)
2. Than for every present user group it gets all the users assigned again via stage_assignments table (StageParticipantGridHandler.php -> loadCategoryData)
3. Additionally it checks whether whether user is still in such user group to indicate whether that "Role ended"

Missing context in the /participants API

What I am missing to mimic this behaviour is getting the stage assignment user group - ideally not just id, but either whole object or at least the name to be able to present it in the UI.

In current endpoint I get list of participating users, along with the user groups that user is currently in. Which I can use to check the "Role ended" scenario. But I don't know via which user group the user was assigned to in stage_assignments table.

Also stageAssignmentId is needed for some operations.

Additionally it might be good to include the context about the stageId, which also comes from stage_assignments table. I might not use it at this point, as I can filter by stageId using query param. But its also important participant context that might be useful at some point.

Without breaking changes it could be added like this for example:

[
  {
    fullName: "Daniel Barnes",
    ...
    ...
     stageAssignmentId: 65,
     stageAssignmentUserGroup: { id: ..., name: {...}}
     stageAssignmentStageId: 15
  }
]

What application are you using?
OJS, OMP or OPS version 3.5

[jardakotesovec]

@Vitaliy-1 Hi Vitaliy, can I ask you just sanity check that what I described in the issue is accurate?

@ewhanson Hi Erik, any guidance how to add this additional context to the existing endpoint? In terms of the naming/structure.

After these feedbacks, this I think could be labeled as "Try me" as it should be relatively friendly issue to work on.

[taslangraham]

I can pick this up once @Vitaliy-1 and @ewhanson provide their feedback

[jardakotesovec]

Just did small update to also include stageAssignmentId

[ewhanson]

@jardakotesovec, would this be a good candidate for the include type of thing we've been talking about over in #10290? Or is this additional info that will always be needed from the participants endpoint?

[jardakotesovec]

@ewhanson In this case I would suggest that it should include both user (participant) and stage assignment data by default as these are somewhat essential to get full picture what kind of participant it is (stageAssignmentGroupId) and also stageAssignmentId is also essential for example to remove that participant.

[ewhanson]

Thanks @jardakotesovec. That make sense. I think the best approach without breaking changes would be to include this information in the summary data that's generated as a result of summarizeReviewer() here:

pkp-lib/classes/user/maps/Schema.php

Lines 49 to 57 in d95ecb1

	/**
	* Summarize a user with reviewer data
	*
	* Includes properties with the apiSummary flag in the user schema.
	*/
	public function summarizeReviewer(User $item): array
	{
	return $this->mapByProperties(array_merge($this->getSummaryProps(), ['reviewsActive', 'reviewsCompleted', 'reviewsDeclined', 'reviewsCancelled', 'averageReviewCompletionDays', 'dateLastReviewAssignment', 'reviewerRating']), $item);
	}

The actual new new data would need to be fetched in mapProperties() here:

pkp-lib/classes/user/maps/Schema.php

Lines 98 to 103 in d95ecb1

	/**
	* Map schema properties of a user to an assoc array
	*
	* @hook UserSchema::getProperties::values [[$this, &$output, $user, $props]]
	*/
	protected function mapByProperties(array $props, User $user): array

That should be enough to include it when calling the participants endpoint. This approach would additionally include the new information in a few different places (anywhere reviewer data is fetched).

So the array_merge above would also include [..., 'stageAssignmentId', 'stageAssignmentUserGroup', 'stageAssignmentStageId'] as would the mapByProperties method to include the data in the shape you described above.

Does that fit with the needs you have?

[jardakotesovec]

@ewhanson I will look more detail tomorrow. But surprised that this would be handled via summarizeReviewer. I am interested in participants (editors, author,...), not reviewers for this endpoint.

[taslangraham]

@jardakotesovec
During a discussion yesterday, @ewhanson pointed out that, while rare, a user may have multiple assignments to the same stage or multiple assignments overall on a submission. To address this, the response structure will be updated to include all of a user's stage assignments, as shown below:
Note the stageAssignments property, which contains a list of the user's stage assignment details:

[
  {
    "fullName": "Daniel Barnes",
    ...
    "stageAssignments": [
      {
        "stageAssignmentId": 65,
        "stageAssignmentUserGroup": { "id": ..., "name": {...} },
        "stageAssignmentStageId": 15
      },
      ...
    ]
  }
]

[taslangraham]

Ready for review @ewhanson

PRs

• pkp-lib: https://github.com/pkp/pkp-lib/pull/10383/files
  • Updates mapByProperties in pkp-lib/classes/user/maps/Schema.php to include user's stage assignment information once a submission and stage Id is provided
• OJS(submodule update): submodule update ojs#4434
• OMP(submodule update): submodule update omp#1696
• OPS(submodule update): submodule update ops#768

[ewhanson]

Thanks @taslangraham! Looks good, just a few small comments in the PR.

[taslangraham]

@ewhanson thanks for the review. I've responded to your comments and made a few minor cleanup

[jardakotesovec]

@taslangraham Hi Taslan,
I came across some other use cases on participants client side, where also recommendOnly and canChangeMetadata would be useful.
Could you please add these? These are on the stage_assignments table, so hopefully its quick addition.

Thank you!

[taslangraham]

@jardakotesovec Sure thing, I'll update shortly

[taslangraham]

@jardakotesovec I've updated the pkp-lib pr to include the additional fields. Changes can be viewed here

[ewhanson]

Thanks @taslangraham and @jardakotesovec. I'll have a final look at it now.

[ewhanson]

@taslangraham, looks good to me! The app submodule commits need to be updated again, but feel free to merge once that's done.

[taslangraham]

All merged @ewhanson @jardakotesovec