Merge pull request #4006 from nhsuk/add-to-organisation-programmes

Add programmes option to `add-to-organisation`

Author: thomasleese

app/lib/mavis_cli/schools/add_to_organisation.rb

@@ -14,7 +14,11 @@ class AddToOrganisation < Dry::CLI::Command
                required: true,
                desc: "The URN of the school"
 
-      def call(ods_code:, team:, urns:, **)
+      option :programmes,
+             type: :array,
+             desc: "The programmes administered at the school"
+
+      def call(ods_code:, team:, urns:, programmes: [], **)
         organisation = Organisation.find_by(ods_code:)
 
         if organisation.nil?
@@ -29,6 +33,13 @@ def call(ods_code:, team:, urns:, **)
           return
         end
 
+        programmes =
+          if programmes.empty?
+            organisation.programmes
+          else
+            Programme.where(type: programmes)
+          end
+
         ActiveRecord::Base.transaction do
           urns.each do |urn|
             location = Location.school.find_by(urn:)
@@ -43,9 +54,7 @@ def call(ods_code:, team:, urns:, **)
             end
 
             location.update!(team:)
-            location.create_default_programme_year_groups!(
-              organisation.programmes
-            )
+            location.create_default_programme_year_groups!(programmes)
           end
         end
 

app/models/location.rb

@@ -49,6 +49,7 @@ class Location < ApplicationRecord
   has_many :sessions
 
   has_one :organisation, through: :team
+  has_many :programmes, -> { distinct }, through: :programme_year_groups
 
   # This is based on the school statuses from the DfE GIAS data.
   enum :status,

docs/api.md

@@ -35,7 +35,7 @@ Gets locations held by the service.
 
 ### Body
 
-See [onboarding documentation](onboarding.md).
+See [onboarding documentation](managing-teams.md).
 
 ## `DELETE /organisations/:ods_code`
 

docs/managing-teams.md

@@ -0,0 +1,92 @@
+# Managing teams
+
+Each SAIS team in Mavis will have their own set of schools, programmes they administer, and in some cases which schools they administer the programmes to and in which year groups.
+
+## Onboarding for the first time
+
+When first onboarding a new SAIS team, there’s a lot of information to include about it. The process involves creating a YAML file containing all the information about the organisation and using the `onboard` Rake task to add everything in to the service.
+
+### Configuration file structure
+
+```yaml
+organisation:
+  name: # Unique name of the organisation
+  email: # Contact email address
+  phone: # Contact phone number
+  ods_code: # Unique ODS code
+  careplus_venue_code: # Venue code used in CarePlus exports
+  privacy_notice_url: # URL of a privacy notice shown to parents
+  privacy_policy_url: # URL of a privacy policy shown to parents
+  reply_to_id: # Optional GOV.UK Notify Reply-To UUID
+
+programmes: [] # A list of programmes (flu, hpv, menacwy, td_ipv)
+
+teams:
+  team1: # Identifier to link team with school and links below, not used in app
+    name: # Name of the team
+    email: # Contact email address
+    phone: # Contact phone number
+    reply_to_id: # Optional GOV.UK Notify Reply-To UUID
+
+schools:
+  team1: [] # URNs managed by a particular team
+
+clinics:
+  team1:
+    - name: # Name of the clinic
+      address_line_1: # First line of the address
+      address_town: # Town of the address
+      address_postcode: # Postcode of the address
+      ods_code: # Unique ODS code
+```
+
+[Example configuration files can be found in the repo][config-onboarding].
+
+[config-onboarding]: /config/onboarding
+
+### Rake task
+
+Once the file has been written you can use the `onboard` Rake task to set everything up in the service.
+
+```sh
+$ bundle exec rails onboard[path/to/configuration.yaml]
+```
+
+If any validation errors are detected in the file they will be output and nothing will be processed, only if the file is completely valid will anything be processed.
+
+## After onboarding
+
+Once a team has been onboarding, the YAML configuration file can be deleted as it won’t be used again. Instead, a number of command line tools are provided for managing the team.
+
+### Adding new schools to an organisation
+
+The command `schools add-to-organisation` is provided to add new schools to an existing organisation.
+
+```sh
+$ bin/mavis schools add-to-organisation ODS_CODE TEAM URNS
+```
+
+- `ODS_CODE` refers to the ODS code of the organisation
+- `TEAM` refers to the name of the team in the organisation
+- `URNS` are the URNs of the schools to add
+
+Optionally, it's also possible to customise which programmes are administered at a particular school:
+
+```sh
+$ bin/mavis schools add-to-organisation ODS_CODE TEAM URNS --programmes VALUE1,VALUE2,...
+```
+
+### Changing administered year groups of a school
+
+Some SAIS teams will administer certain programmes to certain schools outside the normal year groups. For example, flu is often given at special education needs schools in years 12 and 13.
+
+To modify the year groups per programme per school, the follow two commands are provided:
+
+```sh
+$ bin/mavis schools add-programme-year-group URN PROGRAMME_TYPE YEAR_GROUPS
+$ bin/mavis schools remove-programme-year-group URN PROGRAMME_TYPE YEAR_GROUPS
+```
+
+- `URN` refers to the URN of the school to edit
+- `PROGRAMME_TYPE` refers to the programme being edited
+- `YEAR_GROUPS` are the year groups to add or remove

docs/onboarding.md

@@ -40,6 +40,17 @@
     end
   end
 
+  context "when customising the programmes" do
+    it "runs successfully" do
+      given_the_organisation_exists
+      and_the_team_exists
+      and_the_school_exists
+
+      when_i_run_the_command_with_flu_only
+      then_the_school_is_added_to_the_organisation_with_flu_only
+    end
+  end
+
   private
 
   def command
@@ -48,22 +59,42 @@ def command
     )
   end
 
+  def command_with_flu_only
+    Dry::CLI.new(MavisCLI).call(
+      arguments: %w[
+        schools
+        add-to-organisation
+        ABC
+        Team
+        123456
+        --programmes
+        flu
+      ]
+    )
+  end
+
   def given_the_organisation_exists
-    @organisation = create(:organisation, ods_code: "ABC")
+    @programmes = [create(:programme, :flu), create(:programme, :hpv)]
+    @organisation =
+      create(:organisation, ods_code: "ABC", programmes: @programmes)
   end
 
   def and_the_team_exists
     @team = create(:team, name: "Team", organisation: @organisation)
   end
 
   def and_the_school_exists
-    @school = create(:school, name: "School", urn: "123456", team: @team)
+    @school = create(:school, name: "School", urn: "123456")
   end
 
   def when_i_run_the_command
     @output = capture_error { command }
   end
 
+  def when_i_run_the_command_with_flu_only
+    @output = capture_error { command_with_flu_only }
+  end
+
   def when_i_run_the_command_expecting_an_error
     @output = capture_error { command }
   end
@@ -82,5 +113,11 @@ def then_a_school_not_found_error_message_is_displayed
 
   def then_the_school_is_added_to_the_organisation
     expect(@organisation.schools).to include(@school)
+    expect(@school.programmes).to eq(@programmes)
+  end
+
+  def then_the_school_is_added_to_the_organisation_with_flu_only
+    expect(@organisation.schools).to include(@school)
+    expect(@school.programmes).to contain_exactly(@programmes.first)
   end
 end