agreement-design-prototype 0.0.4 → 0.0.5

data/generate.rb

@@ -0,0 +1,57 @@
+require_relative "src/diagram"
+require_relative "src/doc"
+require_relative "src/data"
+require_relative 'model/geographic'
+require_relative "model/agreement"
+require_relative "model/fm"
+require_relative "model/supply_teachers"
+
+output_path = File.join(File.dirname(__FILE__), "gen")
+
+metamodels = [Agreements, Parties, Geographic, SupplyTeacherOfferings]
+
+diagram = Diagram.new(output_path, "metamodel")
+diagram.describe *metamodels
+
+doc = Document.new(output_path, "metamodel")
+doc.document_metamodel *metamodels
+
+models = [
+    Agreements::Supply_Teacher_Agreements,
+    Geographic::NUTS,
+]
+
+doc = Document.new(output_path, "supply_teachers")
+doc.document Agreements::Supply_Teacher_Agreements
+
+data = DataFile.new(output_path, "agreements", fmt: :json)
+data.output *models
+data = DataFile.new(output_path, "agreements", fmt: :yaml)
+data.output *models
+data = DataFile.new(output_path, "agreements", fmt: :jsonlines)
+data.output *models, select: :agreement, index: index_agreement_for_elasticsearch
+
+# create a store for all parties in all models
+parties= Parties.new :AllParties do
+  party do
+    org_name "CCS"
+  end
+end
+
+# put test catalogues into test output
+def test_data_file(name)
+  File.join(File.dirname(__FILE__), "data", name)
+end
+
+sm_offers= load_managing_suppliers(test_data_file("teacher-management-test.csv"), parties)
+sr_offers= load_recruitment_suppliers(test_data_file("teacher-recruitment-test.csv"), parties)
+
+data= DataFile.new( output_path, "teacher-management-test-offers", fmt: :jsonlines)
+data.output sm_offers, index: index_offering_for_elasticsearch
+
+data= DataFile.new( output_path, "teacher-recruitment-test-offers", fmt: :jsonlines)
+data.output sr_offers, index: index_offering_for_elasticsearch
+
+# can now do something like:
+#curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/offerings/offerings/_bulk --data-binary @teacher-management-test-offers.jsonlines
+

data/model/README.md

@@ -0,0 +1,48 @@
+##Metamodels
+
+Metamodels are ruby files that define our agreement
+data metamodels models, and supporting models. For 
+example. The main metamodles are
+
+- Agreement
+- Party
+- Geographic
+
+We also extend these (optionally) for each `Agreement`
+since different agreements may have special Offerings.
+For example the standard `Offering` type has the attributes 
+including
+
+- Item(s)
+- Name 
+- Supplier_id
+
+And the [Supply Teacher framework](supply_teachers.rb) lots have Offerings which add
+framework specific attributes such as:
+
+- Branch name
+- Branch contact
+
+So the Supply Teacher Framework extends our metamodel.
+
+Once we have the metamodel, CCS agreements are defined 
+by instanciating the relevant model domain, such as (in Ruby)
+
+```ruby
+Agreements.new(:SomeCategory) {
+
+  agreement {
+    kind :Framework
+    id SOME_ID
+    fwk_number "RM8330"
+    version "0.1.0"
+    description "This agreement is for the provision of Stuff"
+    start_date date(2018, 10, 01)
+  }
+}
+```
+
+Specifically, Catalogues are defined by creating instances
+of Offerings, either in data files, in code, or through
+an API. For example see the catalogue output as 
+[jsonlines](../gen/data/teacher-recruitment-test-offers.jsonlines)

data/model/agreement.rb

@@ -6,7 +6,7 @@ include DataModel
 domain :Agreements do
 
   SECTOR = Selection(:ALL, :Education, :CentralGov, :WiderGov, :Etc)
-  UNITS = Selection(:Area, :Currency)
+  UNITS = Selection(:Area, :Commission, :Commission)
   CLASSIFICATION_SCHEMES = Selection(:CPV, :CPVS, :UNSPSC, :CPV, :OKDP, :OKPD, :CCS)
   code(:CCS, description: "CCS invented schemes")
 
@@ -26,7 +26,7 @@ variable facts in their Offer to supplement the description of how they support
     attribute :unit, UNITS, " define the units, if one units matches "
   }
 
-  CATEGORY_OF_NEED = Selection(:Budget, :Location, :Service)
+  TYPES_OF_EXPRESSION_OF_NEED = Selection(:Budget, :Location, :Service)
   code(:Budget, description:
 "What is the budget the buyer has for their need?
 Match the budget to the value range of the agreement, and the value range of supplier offers.
@@ -38,14 +38,14 @@ Match location needs to locations of offers")
 "What sort of things do they need?
 Match the service to item types, their keywords, and offering titles.")
 
-  datatype(:Need,
+  datatype(:ExpressionOfNeed,
            description:
 " Defines a buyer's need which can be matched to agreement items and other details
 The need matches closely to our definitions of agreements under 'items types' and their classification
 schemes, but is not a one-to-one match.") {
     attribute :buyer_id, String, "The buyer expressing the need"
-    attribute :kind, Selection(:Budget, :Location,)
     attribute :kind, Selection(:Budget, :Location, :Service)
+    attribute :value, String
     attribute :unit, UNITS, "The units typically used to express the need"
   }
 
@@ -65,6 +65,7 @@ schemes, but is not a one-to-one match.") {
     attribute :fwk_number, String, "Framework (RM) number of related framework if required. @Example RM123"
     attribute :sf_typ, String, "SalesForce data type"
     attribute :sf_is, String, "SalesForce row id"
+    attribute :offerType, String, "Name of the subclass of the Offering, supporting the Agreement"
 
     # structure of agreement
     attribute :part_of_id, String, "Agreement this is part of, applicable only to Lots", links: :Agreement
@@ -80,7 +81,7 @@ schemes, but is not a one-to-one match.") {
 
   datatype(:Item,
            description: "Specifies the value of an item that is being offered for an agreement") {
-    attribute :type, String, " type of the item ", links: :ItemType
+    attribute :type_id, String, " type of the item ", links: :ItemType
     attribute :unit, UNITS, " define the units "
     attribute :value, Object, "an object of the type matching type->units"
   }
@@ -91,7 +92,6 @@ This may be extended for different agreements. A supplier may provide additional
 variable facts in their Offer to supplement the description of how they support the agreement. ") {
     attribute :agreement_id, String, "The agreement this offering relates to", links: :Agreement
     attribute :supplier_id, String, links: Parties::Party
-    attribute :offerType, String, "Name of the subclass of the Offering, supporting the Agreement"
     attribute :name, String
     attribute :description, String
     attribute :item, :Item, ZERO_TO_MANY, "details of the item"

data/model/fm.rb

@@ -1,13 +1,13 @@
 require_relative 'agreement'
 
-domain(:FM) {
+domain(:FM_Offerings) {
   datatype(:FM_Offering, extends: Agreements::Offering,
            description: " An offer for FM elements ") {
     attribute :sc_cleared, String
   }
 }
 
-Agreements.new :FM_Agreements do
+Agreements.new(:FM_Agreements) {
 
   FM_ID = "FM"
   agreement {
@@ -20,6 +20,17 @@ Agreements.new :FM_Agreements do
   }
 
   ENV_CLEANING = "#{FM_ID}.1a-C.3"
+
+  cleaning = itemtype {
+    id ENV_CLEANING
+    scheme_id :CCS
+    unit :Commission
+    code "CCS-building-area-method"
+    keyword "cleaning"
+    keyword "washing"
+    keyword "janitor"
+  }
+
   agreement {
     kind :Lot
     id "FM lot 1"
@@ -28,20 +39,12 @@ Agreements.new :FM_Agreements do
     min_value 0
     max_value 70000000
     version "0.1.0"
-    item_type {
-      id ENV_CLEANING
-      scheme_id :CCS
-      unit :Currency
-      code "CCS-building-area-method"
-      keyword "cleaning"
-      keyword "washing"
-      keyword "janitor"
-    }
+    cnew = item_type cleaning
   }
 
-end
+}
 
-FM.new(:FM_Catalogue) {
+FM_Offerings.new(:FM_Catalogue) {
   fm_offering {
     supplier_id "XYZ corp"
     name "XYZ's nifty school cleaning service"
@@ -50,7 +53,7 @@ FM.new(:FM_Catalogue) {
     sector :Education
     sc_cleared "TRUE"
     item {
-      type ENV_CLEANING
+      type_id ENV_CLEANING
       value 3000
     }
   }

data/model/party.rb

@@ -10,10 +10,35 @@ be one or the other. The onvolvement of the party with an agreement determine  t
 that contenxt.
 Details still to be added") {
     attribute :id, String, "UUID or Salesforce ID?"
-    #TODO add all the usual fields
+    attribute :org_name, String, "UUID or Salesforce ID?"
     # Supplier registration
     attribute :supplier_registration_completed, Date
     # Buyer registration
     attribute :buyer_registration_completed, Date
   }
+
+  datatype(:Address, description: "Address should include at least addres line 1 and ideally post code.
+will contain UPRN if we have derived it.
+  ") {
+    attribute :address_1, String
+    attribute :address_2, String, ZERO_OR_ONE
+    attribute :town, String, ZERO_OR_ONE
+    attribute :county, String, ZERO_TO_MANY
+    attribute :postcode, String, ZERO_TO_MANY
+    attribute :uprn, String, ZERO_TO_MANY
+  }
+  
+  datatype(:Contact, description: "
+  A way of contacting a party. Store contacts in a safe identity store. Do not store personal details elsewhere.
+  ") {
+    attribute :id, String, "a UUID for the person or contact point"
+    attribute :party_id, String, "contact is a link for this party", links: :Party
+    attribute :name, String, "address of the contact point"
+    attribute :address, :Address, ZERO_OR_ONE, "address of the contact point"
+    attribute :phone, String, ZERO_TO_MANY, "phone of the contact point"
+    attribute :email, String, ZERO_TO_MANY, "email of the contact point"
+  }
+
+  # TODO add contact links
+  # TODO add address
 }

data/model/supply_teachers.rb

@@ -0,0 +1,287 @@
+require_relative 'agreement'
+require 'csv'
+
+SUPPLY_TEACHER_FRAMEWORK_ID = "ST"
+SUPPLY_TEACHER_MANAGED_SERVICE_LOT_ID = "#{SUPPLY_TEACHER_FRAMEWORK_ID}.MS"
+SUPPLY_TEACHER_RECRUITMENT_LOT_ID = "#{SUPPLY_TEACHER_FRAMEWORK_ID}.AG"
+
+
+Agreements.new(:Supply_Teacher_Agreements) {
+  agreement {
+    kind :Framework
+    name "Supply Teachers framework"
+    id SUPPLY_TEACHER_FRAMEWORK_ID
+    fwk_number "RM1234" #TODO proper fwk number for Supply teachers
+    version "0.1.0"
+    description "This agreement is for the provision of Supply Teachers"
+    start_date date(2018, 10, 01) #TODO proper start date for Supply teachers
+  }
+
+  item_coding = lambda do
+    scheme_id :CPV; code "79610000/#{id}"; unit :Commission;
+  end
+
+  ST_ROLES = [:QT_NonSEN, :QT_SEN, :NQT_NonSEN, :NQT_SEN, :EdSup_NonSEN, :EdSup_SEN, :Senior, :Admin, :Nom, :FTA]
+  ST_DURATIONS = [:Up_to_1_week, :Between_1_and_12_weeks, :Over_12_weeks]
+
+  # Items common to both Lots
+  Common_ST_items = [
+      itemtype {
+        description "Qualified Teacher: Non-SEN Roles"
+        id :QT_NonSEN
+        include &item_coding
+        keyword "teacher"
+        keyword "non-sen"
+      },
+      itemtype {
+        description "Qualified Teacher: SEN Roles"
+        id :QT_SEN
+        include &item_coding
+        keyword "teacher"
+        keyword "sen teacher"
+        keyword "Special Education Needs"
+        keyword "Special Needs"
+      },
+      itemtype {
+        description "Unqualified Teacher: Non-SEN Roles"
+        id :NQT_NonSEN
+        self.instance_exec &item_coding
+        keyword "teacher"
+        keyword "non-sen"
+      },
+      itemtype {
+        description "Unqualified Teacher: SEN Roles"
+        id :NQT_SEN
+        self.instance_exec &item_coding
+        keyword "teaching assistant"
+        keyword "Special Education Needs"
+        keyword "Special Needs"
+      },
+      itemtype {
+        description "Educational Support Staff: Non-SEN roles (incl. Cover Supervisor and Teaching Assistant)"
+        id :EdSup_NonSEN
+        self.instance_exec &item_coding
+      },
+      itemtype {
+        description "Educational Support Staff: SEN roles (incl. Cover Supervisor and Teaching Assistant)"
+        id :EdSup_SEN
+        self.instance_exec &item_coding
+      },
+      itemtype {
+        description "Senior Roles"
+        description "Other Roles: Headteacher and Senior Leadership positions"
+        id :Senior
+        self.instance_exec &item_coding
+      },
+      itemtype {
+        description "Other Roles: (Admin & Clerical Staff, IT Staff, Finance Staff, Cleaners etc.)"
+        id :Admin
+        self.instance_exec &item_coding
+      },
+      itemtype {
+        description "Nominated Workers"
+        id :Nom
+        self.instance_exec &item_coding
+      },
+      itemtype {
+        description "Fixed Term Role (on School Payroll)"
+        id :FTA
+        self.instance_exec &item_coding
+      },
+  ]
+
+  agreement {
+    kind :Lot
+    id SUPPLY_TEACHER_RECRUITMENT_LOT_ID
+    name "Supply Teachers from Agency"
+    part_of_id SUPPLY_TEACHER_FRAMEWORK_ID
+    offerType "SupplyTeacherOfferings::ST_Offering"
+    version "0.1.0"
+    for item in Common_ST_items
+      item_type item
+    end
+
+  }
+
+  agreement {
+    kind :Lot
+    id SUPPLY_TEACHER_MANAGED_SERVICE_LOT_ID
+    name "Supply Teachers Managed Service"
+    part_of_id SUPPLY_TEACHER_FRAMEWORK_ID
+    offerType "SupplyTeacherOfferings::ST_Offering"
+    version "0.1.0"
+    for item in Common_ST_items
+      item_type item
+    end
+  }
+}
+
+domain(:SupplyTeacherOfferings) {
+
+  datatype(:ST_Offering, extends: Agreements::Offering,
+           description: " An offer for ST supply
+The offerings look the same for both lots - since they both relate to the same items and data") {
+    attribute :commission, String, "The percentage the supplier charges for the item"
+    attribute :duration, Selection(*ST_DURATIONS)
+    attribute :branch_name, String, "branch name from which the offer is supplied"
+    attribute :branch_contact_id, String, "links to contact at the address", links: Parties::Contact
+    attribute :vendor_type, Selection("Master_Vendor", "Neutral_Vendor"), "for managed service offerings", links: Parties::Contact
+  }
+}
+
+def colmap_managing_suppliers(row)
+  {
+      :Vendor_type => row[0],
+      :Supplier => row[1],
+      :Item_ID => row[2],
+      :Job_Type => row[3],
+      :Up_to_1_week => row[4],
+      :Between_1_and_12_weeks => row[5],
+      :Over_12_weeks => row[6],
+      :Contact_information => row[7]
+  }
+end
+
+# expects CSV of the form
+# 0          ,1        ,2      ,3       , 4          , 5                    , 6           , 7
+# Vendor type,Supplier ,Item ID,Job Type,Up_to_1_week,Between_1_and_12_weeks,Over_12_weeks,Contact information
+# @param [Domain] parties - all the parties involved; method adds new suppliers if not present by namne
+# @param [Object] filename - name of CSV file
+def load_managing_suppliers filename, parties
+
+
+  # Load the suppliers from the file
+  lines = CSV.foreach(filename)
+  lines.each do |row|
+    col = colmap_managing_suppliers(row)
+
+    if col[:Vendor_type] != "Vendor type" then
+      name = col[:Supplier]
+      unless parties.contents[:party].find {|p| p.name == [name]}
+        parties.instance_exec do
+          party {
+            org_name name
+            id name # TODO will actually have to match this to a real supplier id, such as in SF
+          }
+        end
+      end
+    end
+  end
+
+  def time_options(item_type, colmap)
+    if (:Nom == item_type.id || :FTA == item_type.id)
+      return [:Over_12_weeks]
+    else
+      return [:Up_to_1_week, :Between_1_and_12_weeks, :Over_12_weeks]
+    end
+  end
+
+
+  SupplyTeacherOfferings.new :ST_ManagementOfferings do
+    lines.each do |row|
+      col = colmap_managing_suppliers(row)
+      if row[0] != "Vendor type" then
+        item_type = get_st_item (col[:Item_ID])
+        if (!item_type)
+          puts "Warning can't match item '#{col[:Item_ID]}"
+          next
+        end
+        for row_dur in time_options(item_type, col)
+          name = row[1]
+          st_offering do
+            name "#{name}-#{item_type.description}-#{row_dur}"
+            agreement_id SUPPLY_TEACHER_MANAGED_SERVICE_LOT_ID
+            supplier_id name # TODO will actually have to match this to a real supplier id, such as in SF
+            item do
+              type_id item_type.id
+              unit :Commission
+              value col[row_dur]
+            end
+          end
+        end
+      end
+    end
+  end
+
+  return SupplyTeacherOfferings::ST_ManagementOfferings
+end
+
+def col_for_supplier row
+  {
+      :Col_Supplier_Name => row[0],
+      :Col_Branch_Name => row[1],
+      :Col_Branch_Contact_name => row[2],
+      :Col_Address_1 => row[3],
+      :Col_Address_2 => row[4],
+      :Col_Town => row[5],
+      :Col_County => row[6],
+      :Col_Post_Code => row[7],
+      :Col_Branch_Contact_Name_Email_Address => row[8],
+      :Col_Branch_Telephone_Number => row[9],
+      :Col_Region => row[10],
+      [:QT_NonSEN, :Up_to_1_week] => row[11],
+      [:QT_NonSEN, :Between_1_and_12_weeks] => row[12],
+      [:QT_NonSEN, :Over_12_weeks] => row[13],
+      [:QT_SEN, :Up_to_1_week] => row[14],
+      [:QT_SEN, :Between_1_and_12_weeks] => row[15],
+      [:QT_SEN, :Over_12_weeks] => row[16],
+      [:NQT_NonSEN, :Up_to_1_week] => row[17],
+      [:NQT_NonSEN, :Between_1_and_12_weeks] => row[18],
+      [:NQT_NonSEN, :Over_12_weeks] => row[19],
+      [:NQT_SEN, :Up_to_1_week] => row[20],
+      [:NQT_SEN, :Between_1_and_12_weeks] => row[21],
+      [:NQT_SEN, :Over_12_weeks] => row[22],
+      [:EdSup_NonSEN, :Up_to_1_week] => row[23],
+      [:EdSup_NonSEN, :Between_1_and_12_weeks] => row[24],
+      [:EdSup_NonSEN, :Over_12_weeks] => row[25],
+      [:EdSup_SEN, :Up_to_1_week] => row[26],
+      [:EdSup_SEN, :Between_1_and_12_weeks] => row[27],
+      [:EdSup_SEN, :Over_12_weeks] => row[28],
+      [:Senior, :Up_to_1_week] => row[29],
+      [:Senior, :Between_1_and_12_weeks] => row[30],
+      [:Senior, :Over_12_weeks] => row[31],
+      [:Admin, :Up_to_1_week] => row[32],
+      [:Admin, :Between_1_and_12_weeks] => row[33],
+      [:Admin, :Over_12_weeks] => row[34],
+      [:Nom, :Nominated_workers] => row[35],
+      [:FTA, :Fixed_Term_Contract] => row[36]
+  }
+end
+
+# expects CSV of the form
+# 0 Supplier Name,1 Branch Name/No.,2 Branch Contact name,3 Address 1,4 Address 2,5 Town,6 County,7 Post Code,8 Branch Contact Name Email Address,9 Branch Telephone Number,10 Region,11 QT_NonSEN/Up to 1 week,12 QT_NonSEN/Between 1 and 12 weeks,13 QT_NonSEN/Over 12 weeks,14 QT_SEN/Up to 1 week,15 QT_SEN/Between 1 and 12 weeks,16 QT_SEN/Over 12 weeks,17 NQT_NonSEN/Up to 1 week,18 NQT_NonSEN/Between 1 and 12 weeks,NQT_NonSEN/Over 12 weeks,NQT_SEN/Up to 1 week,NQT_SEN/Between 1 and 12 weeks,NQT_SEN/Over 12 weeks,EdSup_NonSEN/Up to 1 week,EdSup_NonSEN/Between 1 and 12 weeks,EdSup_NonSEN/Over 12 weeks,EdSup_SEN/Up to 1 week,EdSup_SEN/Between 1 and 12 weeks,EdSup_SEN/Over 12 weeks,Senior/Up to 1 week,Senior/Between 1 and 12 weeks,Senior/Over 12 weeks,Admin/Up to 1 week,Admin/Between 1 and 12 weeks,Over 12 weeks,Nom/Nominated workers,FTA/Fixed Term Contract (school payroll worker)
+# @param [Domain] parties - all the parties involved; method adds new suppliers if not present by namne
+# @param [Object] filename - name of CSV file
+def load_recruitment_suppliers filename, parties
+
+  SupplyTeacherOfferings.new :ST_RecruitmentOfferings do
+    lines = CSV.foreach(filename)
+    lines.each do |row|
+      col = col_for_supplier row
+      if col[:Col_Supplier_Name] != "0 Supplier Name" then
+        for dur in ST_DURATIONS
+          for role in ST_ROLES
+            supplier = col[:Col_Supplier_Name]
+            st_offering do
+              name "#{supplier}-#{role}-#{dur}"
+              agreement_id SUPPLY_TEACHER_RECRUITMENT_LOT_ID
+              supplier_id supplier # TODO will actually have to match this to a real supplier id, such as in SF
+              item do
+                type_id role
+                unit :Commission
+                value col[[role, dur]]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  return SupplyTeacherOfferings::ST_RecruitmentOfferings
+end
+
+
+def get_st_item item_id
+  return Common_ST_items.find {|i| i.id.to_s == item_id}
+end