Merge pull request #1357 from TOMToolkit/redirect-facility

Initial POC for a facility that uses redirects

Author: Fingel

docs/observing/customize_ocs_facility.rst

@@ -74,7 +74,7 @@ Now add some code to this file to create a new observation module:
         name = 'CustomOCS'
         observation_forms = {
             'Instrument1': Instrument1ObservationForm,
-            'Spectra': SpectraObservationForm    
+            'Spectra': SpectraObservationForm
         }
 
 So what does the above code do?
@@ -156,7 +156,7 @@ by subclassing the base class of the full OCS observation form:
             # The init method is where you will define fields, since the field names are
             # set based on the number of configurations and instrument configurations our
             # form supports. You can also remove base fields here if you don't want them
-            # in your form. 
+            # in your form.
             for j in range(self.facility_settings.get_setting('max_configurations')):
                 for i in range(self.facility_settings.get_setting('max_instrument_configs')):
                     self.fields[f'c_{j+1}_ic_{i+1}_defocus'] = forms.IntegerField(
@@ -192,8 +192,8 @@ by subclassing the base class of the full OCS observation form:
             return Instrument1InstrumentConfigLayout
 
         def _build_instrument_config(self, instrument_type, configuration_id, id):
-            # This is called when submitting or validating the form, and it constructs the 
-            # payload to send to the OCS observation portal. You can get the payload with 
+            # This is called when submitting or validating the form, and it constructs the
+            # payload to send to the OCS observation portal. You can get the payload with
             # base fields and then add your new fields in here.
             instrument_config = super()._build_instrument_config(instrument_type, configuration_id, id)
             if self.cleaned_data.get(f'c_{j+1}_ic_{i+1}_readout_mode'):
@@ -251,8 +251,8 @@ the full OCS observation form: ``tom_observations.facilities.ocs.OCSFullObservat
                     ),
                     css_class='form-row'
                 )
-            )       
-            
+            )
+
             def get_final_ic_items(self, config_instance, instance):
             # This piece of layout will be added at the end of the base Instrument Config
             # Layout. There is also a method that could be overridden to add to the beginning,
@@ -319,7 +319,7 @@ the full OCS observation form: ``tom_observations.facilities.ocs.OCSFullObservat
             return SpectrographConfigurationLayout
 
         def _build_acquisition_config(self, configuration_id):
-            # This is called when submitting or validating the form, and it constructs the 
+            # This is called when submitting or validating the form, and it constructs the
             # acquisition config payload. Here we will add our extra fields into the payload
             acquisition_config = super()._build_acquisition_config(configuration_id)
             if self.cleaned_data.get(f'c_{configuration_id}_acquisition_mode'):
@@ -337,7 +337,7 @@ the full OCS observation form: ``tom_observations.facilities.ocs.OCSFullObservat
             return acquisition_config
 
 The above code should define a form which only has spectrograph instruments, and adds three new
-fields to the `acquisition_config` section of the form. 
+fields to the `acquisition_config` section of the form.
 
 Now that you have defined both new forms, your new OCS-based facility module should be complete!
 Try reloading your TOM and navigating to the details page for a specific Target. You should see
@@ -403,7 +403,7 @@ class, start by subclassing ``OCSSettings`` like this:
                     'elevation': 1804
                 },
             }
-        
+
         def get_weather_urls(self):
             # Returns a dictionary of sites with weather urls for retrieving weather data for each site
             return {
@@ -420,7 +420,7 @@ class, start by subclassing ``OCSSettings`` like this:
         name = 'CustomOCS'
         observation_forms = {
             'Instrument1': Instrument1ObservationForm,
-            'Spectra': SpectraObservationForm    
+            'Spectra': SpectraObservationForm
         }
 
         def __init__(self, facility_settings=CustomOCSSettings('CustomOCS')):
@@ -432,3 +432,34 @@ class. Please review
 `the base OCSSettings class <https://github.com/TOMToolkit/tom_base/blob/dev/tom_observations/facilities/ocs.py#L23>`__
 to see what other behaviour can be customized, including certain fields `help_text` or certain archive
 data configuration information.
+
+Redirect Faciltiies
+~~~~~~~~~~~~~~~~~~~
+
+Facilities that subclass `BaseRedirectObservationFacility` work differently than other facilities
+in that they do not provide any forms or validation logic. When a user decides to submit an observation
+using a redirect facility they are redirected to an outside URL where they will create an observation
+and be redirected back to the TOM when they are finished.
+
+In order to create a Redirect Facility, you need to subclass `BaseRedirectObservationFacility` and implement the
+`get_redirect_url()` method. Here is a simplified example from the `LcoRedirectFacility` class:
+
+
+.. code-block:: python
+
+    class LCORedirectFacility(BaseRedirectObservationFacility):
+        name = "LCORedirect"
+
+        def redirect_url(self, target_id, callback_url):
+            target = get_object_or_404(Target, pk=target_id)
+            query_params = self.target_to_query_params(target)
+            url = f"https://observe.lco.global/create?{query_params}&redirect_uri={callback_url}"
+
+            return url
+
+
+The outside website that the facility redirects to must also return the user to the specified callback_url
+that is passed in as part of the call to `redirect_url`. In addition, it needs to add a `observation_id`
+parameter to this URL which is the ID of the newly created observation on the facility side. The `target_id`
+and `facility` parameters must also be present, and should match the values passed in by the original
+callback_url.

tom_observations/facilities/lco_redirect.py

@@ -0,0 +1,50 @@
+import logging
+import urllib.parse
+
+from django.conf import settings
+from django.shortcuts import get_object_or_404
+
+from tom_observations.facility import BaseRedirectObservationFacility
+from tom_targets.models import Target
+
+logger = logging.getLogger(__name__)
+
+
+class LCORedirectFacility(BaseRedirectObservationFacility):
+    name = "LCORedirect"
+    observation_types = [("Default", "")]
+
+    def target_to_query_params(self, target) -> str:
+        set_fields = {
+            "target_" + k: v for k, v in target.as_dict().items() if v is not None
+        }
+        return urllib.parse.urlencode(set_fields)
+
+    def observation_portal_url(self) -> str:
+        return settings.FACILITIES.get("LCO", {}).get(
+            "portal_url", "https://observe.lco.global"
+        )
+
+    def redirect_url(self, target_id, callback_url):
+        target = get_object_or_404(Target, pk=target_id)
+        query_params = self.target_to_query_params(target)
+        callback_url = urllib.parse.quote_plus(callback_url)
+        portal_url = self.observation_portal_url()
+        url = f"{portal_url}/create?{query_params}&redirect_uri={callback_url}"
+
+        return url
+
+    def get_observation_url(self, observation_id):
+        return ""
+
+    def get_terminal_observing_states(self):
+        return []
+
+    def get_observing_sites(self):
+        return {}
+
+    def get_observation_status(self, observation_id):
+        return None
+
+    def data_products(self, observation_id, product_id=None):
+        return []

tom_observations/facility.py

@@ -221,6 +221,7 @@ class BaseObservationFacility(ABC):
     """
     name = 'BaseObservation'
     observation_forms = {}
+    is_redirect = False
 
     def __init__(self):
         self.user = None
@@ -591,3 +592,44 @@ class BaseManualObservationFacility(BaseObservationFacility):
     This specific class is intended for use with classical-style manual facilities.
     """
     name = 'BaseManual'  # rename in concrete subclasses
+
+
+class BaseRedirectObservationFacility(BaseObservationFacility):
+    """
+    A Redirect Facility is a facility which delegates observation creation to
+    an external website. A RedirectFacility does not need to provide a UI for
+    observation creation, meaning it does not include a Form. It does still
+    implement other methods inherited from BaseObservationFacility, such as those
+    related to fetching status, data products, etc.
+
+    Implementations will need to provide the redirect_url method. This constructs
+    a URL that the user will be redirected to. The arguments the target id and a
+    callback URL. The external website should be able to redirect the user back
+    to the callback URL in order to complete the observation creation process
+    on the TOM side, by fetching the observation either by API endpoint or
+    some other means, and storing it in the TOM database.
+
+    The passed in callback URL will contain the following query parameters:
+    - target_id: The ID of the target for which the observation was created.
+    - facility: The name of the facility that created the observation.
+
+    The remote facility is responsible for adding these query params:
+    - observation_id: The ID of the observation that was created.
+
+    """
+    is_redirect = True
+
+    def redirect_url(self, target_id: str, callback_url: str):
+        raise NotImplementedError("Must implement redirect_url")
+
+    def get_form(self, observation_type):
+        raise TypeError("RedirectFacility does not provide a form for observation creation")
+
+    def get_template_form(self, observation_type):
+        raise TypeError("RedirectFacility does not provide a form for observation creation")
+
+    def submit_observation(self, observation_payload):
+        raise TypeError("RedirectFacility does not submit observations on remote facilities")
+
+    def validate_observation(self, observation_payload):
+        raise TypeError("RedirectFacility does no observation creation or validation")

tom_observations/templates/tom_observations/partials/observing_buttons.html

@@ -1,3 +1,7 @@
-{% for facility in facilities %}
-<a href="{% url 'tom_observations:create' facility=facility %}?target_id={{ target.id }}" class="btn btn-outline-primary">{{ facility }}</a>
-{% endfor %}
+{% for facility, facility_class in facilities.items %}
+  {% if facility_class.is_redirect %}
+    <a href="{% url 'tom_observations:redirect' facility=facility %}?target_id={{ target.id }}" class="btn btn-outline-primary">{{ facility }}</a>
+  {% else %}
+    <a href="{% url 'tom_observations:create' facility=facility %}?target_id={{ target.id }}" class="btn btn-outline-primary">{{ facility }}</a>
+  {% endif %}
+{% endfor %}

tom_observations/tests/tests.py

@@ -290,6 +290,28 @@ def test_add_existing_observation_duplicate(self):
         self.assertEqual(ObservationRecord.objects.filter(observation_id=obsr.observation_id).count(), 2)
 
 
+@override_settings(TOM_FACILITY_CLASSES=['tom_observations.tests.utils.FakeRoboticFacility'],
+                   TARGET_PERMISSIONS_ONLY=False)
+class TestCallbackView(TestCase):
+    def setUp(self):
+        self.target = SiderealTargetFactory.create(permissions='PUBLIC')
+        self.user = User.objects.create_user(username='vincent_adultman', password='important')
+        self.client.force_login(self.user)
+
+    def test_callback(self):
+        """
+        The callback url is constructed by the OCS and the user is redirected to it after
+        the observation record is created. This tests that a corresponding ObvservationRecord is created
+        on the TOM side, just as if one was created using the built-in OCS form.
+        The view should redirect the user to the detail view of the observation record.
+        """
+        callback_params = f"?target_id={self.target.id}&facility=FakeRoboticFacility&observation_id=1234"
+        url = reverse('tom_observations:callback') + callback_params
+        response = self.client.get(url)
+        observation = ObservationRecord.objects.get(target=self.target, facility='FakeRoboticFacility')
+        self.assertRedirects(response, reverse('tom_observations:detail', kwargs={'pk': observation.pk}))
+
+
 @override_settings(TOM_FACILITY_CLASSES=['tom_observations.tests.utils.FakeRoboticFacility'])
 class TestFacilityStatusView(TestCase):
     def setUp(self):

tom_observations/urls.py

@@ -5,7 +5,7 @@
                                     ObservationGroupListView, ObservationListView, ObservationRecordCancelView,
                                     ObservationRecordDetailView, ObservationTemplateCreateView,
                                     ObservationTemplateDeleteView, ObservationTemplateListView,
-                                    ObservationTemplateUpdateView)
+                                    ObservationTemplateUpdateView, ObservationCallbackView, ObservationRedirectView)
 from tom_observations.api_views import ObservationRecordViewSet
 from tom_common.api_router import SharedAPIRootRouter
 
@@ -28,7 +28,9 @@
     path('groups/list/', ObservationGroupListView.as_view(), name='group-list'),
     path('groups/<int:pk>/delete/', ObservationGroupDeleteView.as_view(), name='group-delete'),
     path('<str:facility>/create/', ObservationCreateView.as_view(), name='create'),
+    path('<str:facility>/redirect/', ObservationRedirectView.as_view(), name='redirect'),
     path('<int:pk>/cancel/', ObservationRecordCancelView.as_view(), name='cancel'),
     path('<int:pk>/update/', ObservationRecordUpdateView.as_view(), name='update'),
     path('<int:pk>/', ObservationRecordDetailView.as_view(), name='detail'),
+    path('callback/', ObservationCallbackView.as_view(), name='callback'),
 ]

tom_observations/views.py

@@ -14,7 +14,7 @@
 from django_filters import CharFilter, ChoiceFilter, DateTimeFromToRangeFilter, ModelMultipleChoiceFilter
 from django_filters import OrderingFilter, MultipleChoiceFilter, rest_framework
 from django_filters.views import FilterView
-from django.shortcuts import redirect
+from django.shortcuts import get_object_or_404, redirect
 from django.urls import reverse, reverse_lazy
 from django.utils.safestring import mark_safe
 from django.views.generic import View, TemplateView
@@ -328,6 +328,7 @@ def get_initial(self):
             raise Exception('Must provide target_id')
         initial['target_id'] = self.get_target_id()
         initial['facility'] = self.get_facility()
+        initial['request'] = self.request
         initial.update(self.request.GET.dict())
         return initial
 
@@ -435,6 +436,22 @@ def form_valid(self, form):
         )
 
 
+class ObservationRedirectView(LoginRequiredMixin, View):
+    """
+    This view redirects the user to an outside facility using the URL
+    provided by the facility's redirect_url method (must be a RedirectFacility)
+    """
+    def get(self, request, *args, **kwargs):
+        facility_name = self.kwargs['facility']
+        facility_instance = get_service_class(facility_name)()
+        target_id = request.GET.get("target_id")
+        callback_url = request.build_absolute_uri(
+            reverse("tom_observations:callback")
+        ) + f"?target_id={target_id}&facility={facility_name}"
+
+        return redirect(facility_instance.redirect_url(target_id, callback_url))
+
+
 class ObservationRecordUpdateView(LoginRequiredMixin, UpdateView):
     """
     This view allows for the updating of the observation id, which will eventually be expanded to more fields.
@@ -467,6 +484,42 @@ def get(self, request, *args, **kwargs):
         return redirect(reverse('tom_observations:detail', kwargs={'pk': obsr.id}))
 
 
+class ObservationCallbackView(LoginRequiredMixin, View):
+    """
+    This is the view that handles the user returning **from** the facility back to the TOM.
+    The query parameters must include facility, target_id and observation_id as these are
+    the required parameters for creating an ObservationRecord. Once an ObservationRecord object
+    is created, permissions are assigned to it for the current user, and the user is redirected
+    to the observation detail page.
+    """
+    def get(self, request):
+        facility = request.GET.get('facility')
+        target_id = request.GET.get('target_id')
+        observation_id = request.GET.get('observation_id')
+        user = request.user
+        if not target_id:
+            messages.error(self.request, 'Missing required parameter: target_id')
+            return redirect(reverse('tom_observations:list'))
+        elif not all([facility, observation_id]):
+            messages.error(self.request, 'Missing required parameters: facility, observation_id')
+            return redirect(reverse('targets:detail', kwargs={'pk': target_id}))
+        target = get_object_or_404(Target, id=target_id)
+        observation, created = ObservationRecord.objects.get_or_create(
+            user=user,
+            facility=facility,
+            target=target,
+            observation_id=observation_id,
+            parameters=request.GET
+        )
+        assign_perm('tom_observations.view_observationrecord', user, observation)
+        assign_perm('tom_observations.change_observationrecord', user, observation)
+        assign_perm('tom_observations.delete_observationrecord', user, observation)
+        if not created:
+            messages.warning(self.request, "Observation record for this target and facility already exists.")
+
+        return redirect(reverse('tom_observations:detail', kwargs={'pk': observation.pk}))
+
+
 class AddExistingObservationView(LoginRequiredMixin, FormView):
     """
     View for associating a pre-existing observation with a target. Requires authentication.