Create New Users in Canvas

#   _____           _              _____        __      
#  |  __ \         (_)            |_   _|      / _|     
#  | |__) |___  ___ _ _ __   ___    | |  _ __ | |_ ___  
#  |  _  // _ \/ __| | '_ \ / _ \   | | | '_ \|  _/ _ \ 
#  | | \ \  __/ (__| | |_) |  __/  _| |_| | | | || (_) |
#  |_|  \_\___|\___|_| .__/ \___| |_____|_| |_|_| \___/ 
#                    | |                                
#                    |_|                                
#

# Project Name - CREATE NEW USERS IN CANVAS

# Recipe URL - https://app.lingk.io/a/10932/tf/17553

# Description -  This recipe creates Canvas users based on a data source. It will not update users, only create new ones.
              #  To run this recipe, set up the Canvas connector in your environment, choose your Environment, and click "Run".

# Industry - Higher Ed
# Business Process - Graduate Reporting

# Systems - Canvas
# Connectors - Canvas, JSON
# Data Flows - Single Direction
# Connection Type - API to API

# Data Models
## Canvas Models Used:
#1. Users

# Add Recipe notes / Change log information here!

#    _____                            _                 
#   / ____|                          | |                
#  | |     ___  _ __  _ __   ___  ___| |_ ___  _ __ ___ 
#  | |    / _ \| '_ \| '_ \ / _ \/ __| __/ _ \| '__/ __|
#  | |___| (_) | | | | | | |  __/ (__| || (_) | |  \__ \
#   \_____\___/|_| |_|_| |_|\___|\___|\__\___/|_|  |___/
#

# CONNECTORS specify what data will be pulled into the in-memory database during processing

connectors:

# Configure Canvas credentials in your Environment before running this recipe
  # Canvas Setup - https://help.lingk.io/en/articles/263-canvas-setup-guide

###### Start - JSON connectors ######

# SOURCE User Data
- 
    name: sourceUsers
    type: json
    properties:
      jsonObject: |
         [
            {"StudentId":"131e1w131e1w","FirstName":"John","LastName":"Doe", "Email":"john@doe.com"},
            {"StudentId":"23e2#123e2#1","FirstName":"Tammy","LastName":"Doe", "Email":"tammy@doe.com"}
         ]

###### End - JSON connectors ######

###### Start - Canvas Reader connectors ######

# Reader (this reads all the users into memory to compare against the new user dataset)
-
    name: currentUsers
    type: canvasReader
    properties:
      path: /api/v1/accounts/1/users 
    schema:
      fields:
        - name: id
          type: String
        - name: login_id
          type: String

###### End - Canvas Reader connectors ######

###### Start - Canvas Writer connectors ######
-
    name: userWriter
    type: canvasWriter
    properties:
      path: /api/v1/accounts/1/users

###### End - Canvas Writer connectors ######

# Can be uncommented to add Course Enrollment functionality
# You need a data source with registrations though!!!! (sourceRegistrations)

#-
#    name: canvasCourseReader
#    type: canvasReader
#    parameterizedBy: uniqueCourses
#    properties:
#      path: /api/v1/accounts/1/courses?search_term={{var.event_code}}
#    schema:
#      fields:
#        - name: id
#          type: String
#        - name: course_code
#          type: String

# You can't write duplicate enrollments in Canvas, so you may not need to worry about upserts
#-
#    name: canvasEnrollmentWriter
#    type: canvasWriter
#    properties:
#      path: /api/v1/courses/{{var.course_id}}/enrollments

#    _____ _        _                            _       
#   / ____| |      | |                          | |      
#  | (___ | |_ __ _| |_ ___ _ __ ___   ___ _ __ | |_ ___ 
#   \___ \| __/ _` | __/ _ \ '_ ` _ \ / _ \ '_ \| __/ __|
#   ____) | || (_| | ||  __/ | | | | |  __/ | | | |_\__ \
#  |_____/ \__\__,_|\__\___|_| |_| |_|\___|_| |_|\__|___/

# STATEMENTS specify how the data should be processed while in memory

statements:

#******************************************************************** D I S C L A I M E R ***********************************************************************************************
#                                                                                                                                                                                       * 
# Note that in an effort to keep recipes optimized for DPH (Data Processing Hours), print statements should be commented out after development has concluded for a recipe.              *
# For more information on DPH optimization, please visit the following help article - https://help.lingk.io/en/articles/212-minimizing-data-processing-hours-on-the-lingk-platform      *
#                                                                                                                                                                                       * 
#******************************************************************** D I S C L A I M E R ***********************************************************************************************

# CANVAS PROCESSES
# 1. FIND EXISTING CANVAS USERS IN NEW TRANSACTIONS
# NUMBER OF ALL USERS BEFORE INSERT
  #- statement: print currentUsers
  - statement: (currentUserCount) => select count(*) from currentUsers

# 2. COMPARE CURRENT USERS VERSUS REGISTRANTS TO GET A LIST OF NEW USERS
  # The named_struct function - creates a struct with the given field names and values.
  - statement: |
          (newUsers) => SELECT distinct
               false                              enable_sis_reactivation,
               false                              force_validations,
               named_struct(
                "name", concat( first(sourceUsers.FirstName)," ",first(sourceUsers.LastName) ),
                "skip_registration",true,
                "terms_of_use",true
                 )                                user,
               named_struct(
                "unique_id", first(sourceUsers.Email),  
                "sis_user_id", sourceUsers.StudentId,
                "send_confirmation", true,
                "force_self_registration", false
                )                               pseudonym,
               named_struct(
                "type","email",  
                "address", first(sourceUsers.Email),
                "skip_confirmation", false
                )                               communication_channel
               FROM sourceUsers 
                    LEFT ANTI JOIN currentUsers ON lcase(sourceUsers.StudentId) = lcase(currentUsers.sis_user_id)
               GROUP BY sourceUsers.StudentId

#- statement: print newUsers

# NUMBER OF NEW USERS

- statement: (newUsersCount) => select count(*) from newUsers  
  #- statement: print newUsersCount

# INSERT NEW USERS
  - statement: insert newUsers into userWriter

# MAKE SURE ALL NEW USERS ARE IN CACHED DATASET
  - statement: refresh currentUsers

#- statement: print currentUsers
# NUMBER OF ALL USERS AFTER INSERT
  - statement: (currentUserCount) => select count(*) from currentUsers
#  - statement: print currentUserCount

# 4. SELECT COURSES ASSOCIATED WITH NEW REGISTRATIONS

#  - statement: |
#        (uniqueCourses) => select distinct course_code 
#            from sourceRegistrations 
#            where course_code != ''
#  - statement: print uniqueCourses
#  - statement: refresh canvasCourseReader

#  - statement: print canvasCourseReader

# 5. CREATE ANY NEW CANVAS ENROLLMENTS
#  - statement: |
#      (enrollments) => 
#      select distinct
#       canvasCourseReader.id                  course_id,
#       named_struct(
#        "user_id", currentUsers.id,
#        "enrollment_state", "active",
#        "notify", false
#         )                                    enrollment
#       from sourceRegistrations  
#          inner join currentUsers on lcase(sourceRegistrations.StudentId) = lcase(currentUsers.sis_user_id)
#          inner join canvasCourseReader on sourceRegistrations.CourseCode = canvasCourseReader.course_code
#      where
#          registrant_sid > 0

#  - statement: print enrollments

#  - statement: insert enrollments into canvasEnrollmentWriter

# Add more statements to convert, join, aggregrate, transform, and integrate your data