Add com.instructure.User.observees variable expansion

Closes PLAT-5744
flag=none

Test Plan
- Install an LTI tool (LTI version does not matter)
  The new tool should have the following custom
  variable in it's course_navigation config:
  `$com.instructure.User.observees`
- Navigate to a course that contains several students
  and an observer who is linked to more than one
  student
- Act as the observer and launch the tool
- Verify the new variable is expanded to a comma-
  separated list of LTI IDs that identify the
  users the observer can observe

Change-Id: I14d4db655f0732b40da2508af7d149124e4f5bea
Reviewed-on: https://gerrit.instructure.com/c/canvas-lms/+/237058
Tested-by: Service Cloud Jenkins <svc.cloudjenkins@instructure.com>
Reviewed-by: Evan Battaglia <ebattaglia@instructure.com>
QA-Review: Evan Battaglia <ebattaglia@instructure.com>
Product-Review: Karl Lloyd <karl@instructure.com>

doc/api/tools_variable_substitutions.md

@@ -160,6 +160,20 @@ particular placement:
    </cartridge_basiclti_link>
 ```
 # Supported Substitutions
+## com.instructure.User.observees
+If the current user is an observer in the launch
+context, this substitution returns a comma-separated
+list of user IDs linked to the current user for
+observing.
+
+Returns an empty string otherwise.
+
+**Availability**: *when launched in a course*  
+**Launch Parameter**: *com_instructure_user_observees*  
+
+```
+ "86157096483e6b3a50bfedc6bac902c0b20a824f","c0ddd6c90cbe1ef0f32fbce5c3bf654204be186c"
+```
 ## Context.title
 The title of the context.
 

lib/lti/variable_expander.rb

@@ -137,6 +137,29 @@ module Lti
       end
     end
 
+    # If the current user is an observer in the launch
+    # context, this substitution returns a comma-separated
+    # list of user IDs linked to the current user for
+    # observing.
+    #
+    # Returns an empty string otherwise.
+    #
+    # @launch_parameter com_instructure_user_observees
+    # @example
+    #   ```
+    #    "86157096483e6b3a50bfedc6bac902c0b20a824f","c0ddd6c90cbe1ef0f32fbce5c3bf654204be186c"
+    #   ```
+    register_expansion 'com.instructure.User.observees', [],
+                      -> do
+                        ObserverEnrollment.observed_students(@context, @current_user).
+                          keys.
+                          map { |u| Lti::Asset.opaque_identifier_for(u) }.
+                          join(',')
+                      end,
+                      COURSE_GUARD,
+                      default_name: 'com_instructure_user_observees'
+
+
     # The title of the context
     # @launch_parameter context_title
     # @example

spec/lib/lti/capabilities_helper_spec.rb

@@ -113,7 +113,8 @@ module Lti
          com.instructure.Course.canvas_resource_type
          com.instructure.Course.allow_canvas_resource_selection
          com.instructure.Course.available_canvas_resources
-         com.instructure.Person.pronouns)
+         com.instructure.Person.pronouns
+         com.instructure.User.observees)
     }
 
     describe '#supported_capabilities' do

spec/lib/lti/variable_expander_spec.rb

@@ -1040,6 +1040,44 @@ module Lti
             end
           end
         end
+
+        describe '$com.instructure.User.observees' do
+          subject do
+            exp_hash = { test: '$com.instructure.User.observees' }
+            variable_expander.expand_variables!(exp_hash)
+            exp_hash[:test]
+          end
+
+          let(:context) do
+            c = variable_expander.context
+            c.save!
+            c
+          end
+          let(:student) { user_factory }
+          let(:observer) { user_factory }
+
+          before do
+            context.enroll_student(student)
+            variable_expander.current_user = observer
+          end
+
+          context 'when the current user is observing users in the context' do
+            before do
+              observer_enrollment = context.enroll_user(observer, 'ObserverEnrollment')
+              observer_enrollment.update!(associated_user_id: student.id)
+            end
+
+            it 'produces a comma-separated string of user UUIDs' do
+              expect(subject.split(',')).to match_array [
+                Lti::Asset.opaque_identifier_for(student)
+              ]
+            end
+          end
+
+          context 'when the current user is not observing users in the context' do
+            it { is_expected.to eq "" }
+          end
+        end
       end
 
       context 'context is a course and there is a user' do