Additional fields in Submission schema in API for 3.5

[jardakotesovec]

On the meeting we agreed to include following fields to the submission schema. These are computed fields from stage assignments.

We agreed that keeping business logic on server side is better to not spread business logic too much between server side and client side. All these fields also are very business specific information, not really UI specific. Client side makes its own decision how to present things based on these flags.

Opened to different names, but these should be quite self-explanatory.

Submission listing /_submissions

• isCurrentUserRecommendOnly
• isCurrentUserDecidingEditor
• isDecidingEditorAssigned
• canCurrentUserChangeMetadata
• currentUserAccessRoles

Workflow side modal /submissions/{submissionId}

• isCurrentUserRecommendOnly
• isCurrentUserDecidingEditor
• isDecidingEditorAssigned
• canCurrentUserChangeMetadata
• currentUserAccessRoles
• currentUserRecommendation
• recommendations

Description for each field

isCurrentUserRecommendOnly (per stage)

• boolean
• meaning is that current user is assigned with the recommendOnly flag
• recommend only flag is relevant on multiple stages to decide what user can do, not only on review stage
• would be calculated for every stage

isCurrentUserDecidingEditor

• boolean
• this could be included only in review stages (including internal/external for omp ideally), as that information is not relevant in other stages
• meaning is that there is recommendOnly editor assigned, but its not me and I do have ROLE_ID_MANAGER or ROLE_ID_SUB_EDITOR role (https://github.com/pkp/pkp-lib/blob/main/pages/workflow/PKPWorkflowHandler.php#L637)

isDecidingEditorAssigned

• boolean
• If there is at least one recommendOnly editor - this indicates whether there is also ROLE_ID_MANAGER or ROLE_ID_SUB_EDITOR in stage assignments without recommendOnly flag
• this can be included in review stages as its not relevant for others

canCurrentUserChangeMetadata (not per stage)

• boolean
• this is not specific to stage, so it can be outside of the stages array
• reference implementation https://github.com/pkp/pkp-lib/blob/main/pages/workflow/PKPWorkflowHandler.php#L177
• basically its checking canChangeMetadata for assigned users to the stage assignment (regardless of what stage they are assigned) and ROLE_ID_MANAGER can do always edit it. Thats my understanding, but please double check it from linked implementation.

currentUserAccessRoles (per stage)

• array of roleIds
• stage specific, would be calculated for every stage
• it would follow the logic from (getAccessibleWorkflowStages)[https://github.com/pkp/pkp-lib/blob/b8d985fb8baebe981935ba2175616c6fd1a923b8/classes/user/Repository.php#L202], to combine assigned role and global ones.
• this already exist, but its not accurate as its fetching stage assignments twice, once filtered by stage and once for all stages and combines them together. Desired would be to get only the roleId for current stage

currentUserRecommendation - if I am recommend only editor (only in review stages)

• this be null or object, based on whether I am recommendOnly editor and whether decision has been made (last decision is relevant)
• relevant for review stages (ideally to include also internal one for OMP), so it makes sense to include it only in these stages
• object shape could be: {'decision': 3, label: 'Recommend Revisions'}
• reference for retrieving such decision - https://github.com/pkp/pkp-lib/blob/main/pages/workflow/PKPWorkflowHandler.php#L611C1-L612C1

recommendations - if I am deciding editor (only in review stages)

• array of object, for now I don't need more than this [{'decision': 3, label: 'Recommend Revisions'}]
• this is relevant when I am deciding editor - I need to see decisions from all recommendOnly editors
• reference implementation - https://github.com/pkp/pkp-lib/blob/main/pages/workflow/PKPWorkflowHandler.php#L645
• also make sense to include this only in review stages

[Vitaliy-1]

PRs
pkp-lib: #10523
ui-library: pkp/ui-library#489
OJS: pkp/ojs#4471

[Vitaliy-1]

@jardakotesovec Can you take a look at the data added to the Schema? Do we need anything else there?

[Vitaliy-1]

In short, changes in the schema affect 3 submission-related endpoints, to related to submissions list _submissions, _submissions/assigned and for retrieving data for individual submissions: submissions/[id]. Main changes are in the stage property, it now looks like:

{
  "stages": [
    {
      "id": 1,
      "label": "Submission",
      "isActiveStage": true,
      "editorAssigned": true,
      "isDecidingEditorAssigned": true,
      "isCurrentUserDecidingEditor": true,
      "currentUserAssignedRoles": [
        16
      ]
    },
    {
      "id": 3,
      "label": "Review",
      "isActiveStage": false,
      "editorAssigned": true,
      "isDecidingEditorAssigned": true,
      "isCurrentUserDecidingEditor": true,
      "currentUserAssignedRoles": [
        16
      ]
    },
    {
      "id": 4,
      "label": "Copyediting",
      "isActiveStage": false,
      "editorAssigned": true,
      "isDecidingEditorAssigned": true,
      "isCurrentUserDecidingEditor": true,
      "currentUserAssignedRoles": [
        16
      ]
    },
    {
      "id": 5,
      "label": "Production",
      "isActiveStage": false,
      "editorAssigned": true,
      "isDecidingEditorAssigned": true,
      "isCurrentUserDecidingEditor": true,
      "currentUserAssignedRoles": [
        16
      ]
    }
  ]
}

The trickiest part is with currentUserAssignedRoles, I've reproduced the logic from our authorization part of the system. I've also introduced new not stage related property - canCurrentUserChangeMetadata and moved availableEditorialDecisions out from stages. The latter was recently introduced and I'm not familiar with the logic there. Currently testing it, if it works as it should.