Merge pull request #3933 from open-formulieren/feature/3359-refactor-…

…pre-registration-ref

[#3359] Refactor pre registration

docs/developers/plugins/registration_plugins.rst

@@ -106,6 +106,8 @@ Public Python API
 .. autoclass:: openforms.registrations.base.BasePlugin
    :members:
 
+.. autoclass:: openforms.registrations.base.PreRegistrationResult
+
 **Module documentation**
 
 .. automodule:: openforms.registrations

src/openforms/forms/tests/test_api_form_plugin_options.py

@@ -28,9 +28,6 @@ class RegistrationPlugin(RegistrationBasePlugin):
     def register_submission(self, submission, options):
         pass
 
-    def get_reference_from_result(self, result: dict) -> None:
-        pass
-
 
 class PaymentPlugin(PaymentBasePlugin):
     configuration_options = EmailOptionsSerializer

src/openforms/forms/tests/test_form_admin.py

@@ -28,9 +28,6 @@ class Plugin(BasePlugin):
     def register_submission(self, submission, options):
         pass
 
-    def get_reference_from_result(self, result) -> str:
-        return "foo"
-
 
 @disable_admin_mfa()
 class FormAdminTests(FormListAjaxMixin, WebTest):

src/openforms/forms/tests/test_serializers.py

@@ -289,9 +289,6 @@ class UnicornPlugin(BaseRegistrationPlugin):
             # This doesn't pass registry.check_plugin
             # configuration_options = None
 
-            def get_reference_from_result(self, *args, **kwargs):
-                pass
-
             def register_submission(self, *args, **kwargs):
                 pass
 

src/openforms/payments/tests/test_services.py

@@ -27,9 +27,6 @@ def register_submission(self, submission, options):
     def update_payment_status(self, submission: Submission, options):
         pass
 
-    def get_reference_from_result(self, result):
-        pass
-
 
 class UpdatePaymentTests(TestCase):
     def setUp(self):

src/openforms/registrations/api/tests/test_endpoints.py

@@ -35,9 +35,6 @@ class Plugin(BasePlugin):
     def register_submission(self, submission, options):
         pass
 
-    def get_reference_from_result(self, result: dict) -> None:
-        pass
-
 
 register("test")(Plugin)
 

src/openforms/registrations/base.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
 from rest_framework import serializers
 
@@ -16,6 +17,14 @@ class EmptyOptions(JsonSchemaSerializerMixin, serializers.Serializer):
     pass
 
 
+@dataclass
+class PreRegistrationResult:
+    """Encapsulate the submission reference and any intermediate result from pre-registration."""
+
+    reference: str = ""
+    data: dict | None = None
+
+
 class BasePlugin(ABC, AbstractBasePlugin):
     configuration_options: SerializerCls = EmptyOptions
     """
@@ -38,33 +47,18 @@ def register_submission(
     ) -> dict | None:
         raise NotImplementedError()
 
-    @abstractmethod
-    def get_reference_from_result(self, result: Any) -> str:
-        """
-        Extract the public submission reference from the result data.
-
-        This method must return a string to be saved on the submission model.
-
-        :arg result: the raw underlying JSONField datastructure.
-        """
-        raise NotImplementedError()
-
     def update_payment_status(self, submission: "Submission", options: dict):
         raise NotImplementedError()
 
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
+    def pre_register_submission(
+        self, submission: "Submission", options: dict
+    ) -> PreRegistrationResult:
         """Perform any tasks before registering the submission
 
-        For plugins where the registration backend does not generate a reference number, an internal reference number
-        can be set on the submission in this step.
+        For plugins where the registration backend does not generate a reference number,
+        no need to implement this method.
         """
-        pass
-
-    def obtain_submission_reference(
-        self, submission: "Submission", options: dict
-    ) -> None:
-        """Obtain the reference number generated by the registration backend and set it on the submission."""
-        pass
+        return PreRegistrationResult()
 
     def get_custom_templatetags_libraries(self) -> list[str]:
         """

src/openforms/registrations/contrib/camunda/plugin.py

@@ -7,7 +7,7 @@
 """
 
 import logging
-from typing import Any, NoReturn
+from typing import Any
 
 from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
@@ -19,10 +19,9 @@
 from django_camunda.utils import serialize_variables
 
 from openforms.submissions.models import Submission
-from openforms.submissions.public_references import set_submission_reference
 
 from ...base import BasePlugin
-from ...exceptions import NoSubmissionReference, RegistrationFailed
+from ...exceptions import RegistrationFailed
 from ...registry import register
 from .checks import check_config
 from .complex_variables import get_complex_process_variables
@@ -144,16 +143,6 @@ def register_submission(
             }
         }
 
-    def get_reference_from_result(self, result: dict[str, str]) -> NoReturn:
-        """
-        Extract the public submission reference from the result data.
-
-        We never return, as the Camunda API response does not contain anything useful
-        and readable for the end-user and we cannot make assumptions about the process
-        model. The instance ID is a UUID, which is not suitable for end users.
-        """
-        raise NoSubmissionReference("Deferred to Open Forms itself")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         # TODO: we could ask for a BPMN message to be specified so we can signal the
         # process instance? This needs to be documented properly for the modellers
@@ -173,6 +162,3 @@ def get_config_actions(self) -> list[tuple[str, str]]:
                 ),
             ),
         ]
-
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)

src/openforms/registrations/contrib/demo/plugin.py

@@ -3,10 +3,9 @@
 from django.utils.translation import gettext_lazy as _
 
 from openforms.submissions.models import Submission
-from openforms.submissions.public_references import set_submission_reference
 
 from ...base import BasePlugin
-from ...exceptions import NoSubmissionReference, RegistrationFailed
+from ...exceptions import RegistrationFailed
 from ...registry import register
 from .config import DemoOptionsSerializer
 
@@ -22,9 +21,6 @@ def register_submission(self, submission: Submission, options: dict) -> None:
         if options.get("extra_line"):
             print(options["extra_line"])
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("Demo plugin does not emit a reference")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         print(submission)
 
@@ -34,9 +30,6 @@ def check_config(self):
         """
         pass
 
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)
-
 
 @register("failing-demo")
 class DemoFailRegistration(BasePlugin):
@@ -47,9 +40,6 @@ class DemoFailRegistration(BasePlugin):
     def register_submission(self, submission: Submission, options: dict) -> NoReturn:
         raise RegistrationFailed("Demo failing registration")
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("Demo plugin does not emit a reference")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         pass
 
@@ -59,9 +49,6 @@ def check_config(self):
         """
         pass
 
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)
-
 
 @register("exception-demo")
 class DemoExceptionRegistration(BasePlugin):
@@ -72,9 +59,6 @@ class DemoExceptionRegistration(BasePlugin):
     def register_submission(self, submission: Submission, options: dict) -> NoReturn:
         raise Exception("Demo exception registration")
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("Demo plugin does not emit a reference")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         pass
 
@@ -83,6 +67,3 @@ def check_config(self):
         Demo config is always valid.
         """
         pass
-
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)

src/openforms/registrations/contrib/email/plugin.py

@@ -1,6 +1,6 @@
 import html
 from mimetypes import types_map
-from typing import Any, NoReturn, TypedDict
+from typing import Any, TypedDict
 
 from django.conf import settings
 from django.urls import reverse
@@ -21,14 +21,12 @@
 )
 from openforms.submissions.exports import create_submission_export
 from openforms.submissions.models import Submission
-from openforms.submissions.public_references import set_submission_reference
 from openforms.submissions.rendering.constants import RenderModes
 from openforms.submissions.rendering.renderer import Renderer
 from openforms.template import render_from_string
 from openforms.variables.utils import get_variables_for_context
 
 from ...base import BasePlugin
-from ...exceptions import NoSubmissionReference
 from ...registry import register
 from .checks import check_config
 from .config import EmailOptionsSerializer
@@ -187,9 +185,6 @@ def send_registration_email(
             },
         )
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("Email plugin does not emit a reference")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         recipients = options.get("payment_emails")
         if not recipients:
@@ -215,9 +210,6 @@ def get_config_actions(self) -> list[tuple[str, str]]:
             (_("Test"), reverse("admin_email_test")),
         ]
 
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)
-
     def get_custom_templatetags_libraries(self) -> list[str]:
         return [
             "openforms.registrations.contrib.email.templatetags.registrations.contrib.email.registration_summary"

src/openforms/registrations/contrib/email/tests/test_backend.py

@@ -41,7 +41,6 @@
 from openforms.utils.tests.html_assert import HTMLAssertMixin
 from openforms.variables.constants import FormVariableSources
 
-from ....service import NoSubmissionReference, extract_submission_reference
 from ..constants import AttachmentFormat
 from ..models import EmailConfig
 from ..plugin import EmailRegistration
@@ -471,17 +470,6 @@ def test_register_and_update_paid_product_with_payment_email_recipient(self):
         # check we used the payment_emails
         self.assertEqual(message.to, ["[email protected]", "[email protected]"])
 
-    def test_no_reference_can_be_extracted(self):
-        submission = SubmissionFactory.create(
-            form=self.form,
-            completed=True,
-            registration_success=True,
-            registration_result="irrelevant",
-        )
-
-        with self.assertRaises(NoSubmissionReference):
-            extract_submission_reference(submission)
-
     @override_settings(DEFAULT_FROM_EMAIL="[email protected]")
     def test_submission_with_email_backend_export_csv_xlsx(self):
         email_form_options = dict(

src/openforms/registrations/contrib/microsoft_graph/plugin.py

@@ -1,5 +1,4 @@
 from pathlib import PurePosixPath
-from typing import NoReturn
 
 from django.urls import reverse
 from django.utils import timezone
@@ -17,11 +16,10 @@
     MSGraphRegistrationConfig,
 )
 from openforms.submissions.models import Submission, SubmissionReport
-from openforms.submissions.public_references import set_submission_reference
 from openforms.template import render_from_string
 
 from ...base import BasePlugin
-from ...exceptions import NoSubmissionReference, RegistrationFailed
+from ...exceptions import RegistrationFailed
 from ...registry import register
 from .config import MicrosoftGraphOptionsSerializer
 
@@ -78,9 +76,6 @@ def register_submission(self, submission: Submission, options: dict) -> None:
 
         self._set_payment(uploader, submission, folder_name)
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("MS Graph plugin does not emit a reference")
-
     def update_payment_status(self, submission: "Submission", options: dict):
         config = MSGraphRegistrationConfig.get_solo()
         client = MSGraphClient(config.service)
@@ -129,6 +124,3 @@ def get_config_actions(self):
                 ),
             ),
         ]
-
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)

src/openforms/registrations/contrib/objects_api/plugin.py

@@ -1,6 +1,6 @@
 import logging
 from functools import partial
-from typing import Any, NoReturn
+from typing import Any
 
 from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
@@ -18,12 +18,10 @@
 from openforms.submissions.exports import create_submission_export
 from openforms.submissions.mapping import SKIP, FieldConf
 from openforms.submissions.models import Submission, SubmissionReport
-from openforms.submissions.public_references import set_submission_reference
 from openforms.variables.utils import get_variables_for_context
 
 from ...base import BasePlugin
 from ...constants import RegistrationAttribute
-from ...exceptions import NoSubmissionReference
 from ...registry import register
 from .checks import check_config
 from .client import get_documents_client, get_objects_client
@@ -169,9 +167,6 @@ def register_submission(
 
         return response
 
-    def get_reference_from_result(self, result: None) -> NoReturn:
-        raise NoSubmissionReference("Object API plugin does not emit a reference")
-
     def check_config(self):
         check_config()
 
@@ -186,9 +181,6 @@ def get_config_actions(self):
             ),
         ]
 
-    def pre_register_submission(self, submission: "Submission", options: dict) -> None:
-        set_submission_reference(submission)
-
     def get_custom_templatetags_libraries(self) -> list[str]:
         prefix = "openforms.registrations.contrib.objects_api.templatetags.registrations.contrib"
         return [