Expose publication forms via API

[jardakotesovec]

Describe the issue
There are challenges when the forms are both manipulated client and server side. In future we might shift to client side form building. But for current efforts with new submission listing and workflow, it will be best to just expose the forms as private API. More detail discussion is available here - #10331

Proposed solution
This is based on the discussion linked above. I am ok with details being different (different url, multiple forms together or individual, etc) as long as I can get to them via API.

I propose example following url, that would expose individual forms
GET /submissions/{submissionId}/publications/{publicationId}/_components/titleAbstract

Which would return json from titleAbstractForm->getConfig().

Publicaton forms
Following forms needs to be exposed

• Title & Abstract: TitleAbstractForm (pkp-lib) + some additional logic in WorkflowHandler.php for wordLimit, which is specific for OJS
• Metadata: PKPMetadataForm (pkp-lib)
• References: PKPCitationsForm (pkp-lib)
• Identifiers: PKPPublicationIdentifiersForm (pkp-lib)
• Permissions & Disclosure: PKPPublicationLicenseForm (pkp-lib
• Issue: IssueEntryForm (ojs)
• submission payment form - SubmissionPaymentsForm (ojs)

In terms of implementation its mostly about cherry-picking from PKPWorkflowHandler.php for common forms, and WorkflowHandler.php for ojs specific forms + this handler might modify some of the pkp-lib forms.

Considerations
In terms of the permissions - publications forms are presented to editors and authors, not reviewers. But in general following permissions that are in place for given /publications/{$publicationId} should be good starting point.

What application are you using?
OJS version 3.5

[ewhanson]

Hey @jardakotesovec, I've done some initial testing with this and this approach seems good. With the endpoint returning the JSON from $form->getConfig(), what else needs to be done on the UI library side of things for it to be used? Is that within the scope of this issue? Additionally, are you ready to have the old PHP-instantiated forms removed at this point or should they stick around until the submission workflow work is complete?

[jardakotesovec]

@ewhanson This issue is just expose via API. I will use that on ui-library side of things.

Workflow handlers eventually will be removed completely. Once we have all apps moved to the side modal workflow.

[ewhanson]

Perfect, thanks @jardakotesovec.

[ewhanson]

Implementation overview

Copy over existing form creation to an API endpoint and return as JSON the results of $form->getConfig(). The scope of this issue is only to add the new endpoints, not remove the old ones yet. This will need to be completed for all the publication forms described above.

I did some initial exploring with the TitleAbstract form, and was able to generate the desired results as described below. Note, this example does not consider that the primary logic for this endpoint will be in pkp-lib with some additional functionality that is specific to ojs as noted above. This is an example of the rough shape of the implementation.

Example

1. Create an endpoint in PKPSubmissionController under the appropriate roleAuthorizer middleware group, e.g.:

Route::get('{submissionId}/publications/{publicationId}/_components/titleAbstract', $this->getTitleAbstractComponent(...))
    ->name('submission.publication.components.titleAbstract')
    ->whereNumber(['submissionId', 'publicationId']);

2. Move any code needed to instantiate the form to the endpoint: note the example below does not consider separation between pkp-lib and ojs specific code nor does it include all the necessary authorization/sanity checks. In this case, most of this is directly from WorkflowHandler::getTitleAbstractForm() from OJS and the necessary setup for the arguments passed into it. Also note that to use $this->getAuthorizedContextObject(Application::ASSOC_TYPE_SUBMISSION), the endpoint function name must be added to the $requiresSubmissionAccess array.

public function getTitleAbstractComponent(Request $illuminateRequest): JsonResponse
{
    $submission = $this->getAuthorizedContextObject(Application::ASSOC_TYPE_SUBMISSION);
    $context = $this->getRequest()->getContext();

    if ($submission->getData('contextId') !== $context->getId()) {
        $context = app()->get('context')->get($submission->getData('contextId'));
    }

    $publication = Repo::publication()->get((int) $illuminateRequest->route('publicationId'));

    $locales = collect($context->getSupportedSubmissionMetadataLocaleNames() + $submission->getPublicationLanguageNames())
        ->map(fn (string $name, string $locale) => ['key' => $locale, 'label' => $name])
        ->sortBy('key')
        ->values()
        ->toArray();

    $latestPublicationApiUrl = $this->getRequest()->getDispatcher()->url($this->getRequest(), Application::ROUTE_API, $context->getData('urlPath'), 'submissions/' . $submission->getId() . '/publications/' . $publication->getId());

    $section = Repo::section()->get($publication->getData('sectionId'), $context->getId());
    $titleAbstractForm = new TitleAbstractForm(
        $latestPublicationApiUrl,
        $locales,
        $publication,
        (int) $section->getData('wordCount'),
        !$section->getData('abstractsNotRequired')
    );

    return response()->json($titleAbstractForm->getConfig(), Response::HTTP_OK);
}

3. All existing authorization and role checks will need to be preserved and the usual API endpoint sanity checks will be required as well.

[ewhanson]

Hey @taslangraham, could you have a look at this issue? I've tried to capture all the relevant details above, but if anything is unclear, please let me know. Thanks!

[jardakotesovec]

@ewhanson Thank you!

[taslangraham]

@ewhanson sure thing!

[taslangraham]

Ready for review @ewhanson

PRs

• PKP-Lib:
  • Added individual endpoint for each component along with the necessary role, authorization, and sanity checks
• OJS
  • Implement OJS specific logic for endpoints returning TitleAbstractForm, IssueEntryForm, SubmissionPaymentsForm forms
• OPS:
  • Add app logic for handler returning TitleAbstractForm as OPS also has additional logic((here and here) in WorkflowHandler.php for wordLimit
  • Add endpoint to return IssueEntryForm in OPS as I observed that OPS' WorkflowHandler.php also adds IssueEntryForm
• OMP
  • submodule update

[ewhanson]

Looks really good @taslangraham! Just a few comments, but otherwise ready to go!

[taslangraham]

Thanks for the review @ewhanson! I've made the changes you suggested. If there are no objections, I'll go ahead and merge

[ewhanson]

Looks good @taslangraham. Feel free to merge!

[jardakotesovec]

@taslangraham @ewhanson Thanks guys! Great work.. will connect it with the UI once its merged and let you know if there are any issues, but looking promising! :-)

[taslangraham]

All merged @jardakotesovec @ewhanson

[jardakotesovec]

Just notice that if I hit this endpoint I get following PHP warnings.. but no idea whether its concern or not..

2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] PHP Notice:  Only variables should be passed by reference in /Users/jarda/git/pkp/pkp-main-2/ojs-main-2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] PHP Notice:  Only variables should be passed by reference in /Users/jarda/git/pkp/pkp-main-2/ojs-main-2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] PHP Notice:  Only variables should be passed by reference in /Users/jarda/git/pkp/pkp-main-2/ojs-main-2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] PHP Notice:  Only variables should be passed by reference in /Users/jarda/git/pkp/pkp-main-2/ojs-main-2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] PHP Notice:  Only variables should be passed by reference in /Users/jarda/git/pkp/pkp-main-2/ojs-main-2/lib/pkp/classes/middleware/traits/HasRequiredMiddleware.php on line 63
[Mon Sep  9 15:37:36 2024] [::1]:63901 [200]: GET /index.php/publicknowledge/api/v1/submissions/7/publications/8/_components/titleAbstract

[jardakotesovec]

Actually this seems to be present for almost any request.. Therefore not related to this one. Sorry for noise..