moodle_rb 1.0.2 → 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3fdbc847a70cefe6a1641ceebba2f874b8ab8d1459aa475c23d8f1ae70ef4c11
+  data.tar.gz: 7e4034e714f6ca67e92a928bc9ae323e22b48042d4ebbfbab0bf401ec4a54cec
+SHA512:
+  metadata.gz: 1e7300716079888fed475a6dea164997ceb375fec6b870370064d88ac8a3a9821a63a63e73579bdf621b63563bfb95e3c33c2be309ecdc6863eda0e7fbf89e5b
+  data.tar.gz: f2613f30e5676831a666a76f8e54cde9e5a2c4b939ab00972833a0c200d86ddd502c50c200fc982ab0c9373b296e47f62b98ddfc525b0ca7dd2cd8df2b275a12

data/.github/workflows/build.yml

@@ -0,0 +1,36 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Build
+
+on:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.3']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler: 1.17.3
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec spec

data/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby 2.7
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '2.7'
+
+    - name: Publish to RubyGems
+      run: |
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/Dockerfile

@@ -0,0 +1,10 @@
+FROM ruby:2.3-slim
+
+RUN apt-get update -y && apt-get install -y git
+
+WORKDIR /app
+ADD . .
+RUN bundle install
+
+# ENV MOODLE_URL=http://localhost:8888/moodle29/
+# ENV MOODLE_TOKEN=87b95af2df709fa60b395b5c59a3fc2e

data/README.md

@@ -1,4 +1,9 @@
 # MoodleRb
+
+[![Build](https://github.com/jobready/moodle-rb/actions/workflows/build.yml/badge.svg)](https://github.com/jobready/moodle-rb/actions/workflows/build.yml) 
+
+[![Gem Version](https://badge.fury.io/rb/moodle_rb.svg)](https://badge.fury.io/rb/moodle_rb)
+
 A Ruby Client for the Moodle REST API.
 
 https://docs.moodle.org/dev/Web_services#Developer_documentation
@@ -42,6 +47,21 @@ Delete a course
 moodle.courses.destroy(course_id)
 ```
 
+Get course grades
+```
+moodle.courses.grade_items(course_id)
+```
+
+Get course contents
+```
+moodle.courses.contents(course_id)
+```
+
+Get course module
+```
+moodle.courses.module(course_module_id)
+```
+
 ### Categories
 
 Create a category
@@ -68,7 +88,7 @@ moodle.categories.destroy(category_id)
 
 ### Enrolments
 
-Create an enrolment
+Create a student enrolment
 ```
 moodle.enrolments.create(
   :user_id => user_id,
@@ -76,6 +96,23 @@ moodle.enrolments.create(
 )
 ```
 
+Create a teacher enrolment
+```
+moodle.enrolments.create(
+  :user_id => user_id,
+  :course_id => course_id,
+  :role_id => 3
+)
+```
+
+Delete an enrolment
+```
+moodle.enrolments.destroy(
+  :user_id => user_id,
+  :course_id => course_id
+)
+```
+
 View enrolled users by course
 ```
 moodle.courses.enrolled_users(course_id)
@@ -114,16 +151,51 @@ Search for a user
 moodle.users.search(:email => 'admin@localhost')
 ```
 
+Search for a user via identity
+```
+moodle.users.search_identity('admin@localhost')
+```
+
 Update a user
 ```
 moodle.users.update(:id => 4, :email => 'bwayne@wayneenterprises.com')
 ```
 
+## Development
+
+To start development, spin up a container
+
+```
+docker build -t moodle .
+```
+
+To run the test suite with docker
+
+
+```
+docker run -v "$(pwd):/app" --rm moodle rspec spec
+```
+
+Docker compose
+
+```
+docker-compose build
+docker-compose run app bundle exec rspec spec
+```
+
 ## Tests
 
+Tests must be written for new lines of code added as part of a pull request and the test suite must pass. If creating new cassettes, consider updating the hardcoded moodle token and url parameters throughout the suite. They can also be configured with environment variables.
+
 You will need to set some environment variables to create new cassettes. We build using MAMP https://www.mamp.info/en/ so it might be
 
 ```
 export MOODLE_URL=http://localhost:8888/moodle29/
 export MOODLE_TOKEN=87b95af2df709fa60b395b5c59a3fc2e
 ```
+
+## Deployment
+
+The gem is automatically published when a new release is created on github. If there is an issue or a new release is required, please contact one of the maintainers
+
+- Jordan Huizenga (jordan.huizenga@readytech.io)

data/docker-compose.yml

@@ -0,0 +1,6 @@
+version: '2'
+services:
+  app:
+    build: .
+    volumes:
+      - .:/app

data/lib/moodle_rb/categories.rb

@@ -3,11 +3,12 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token
+    attr_reader :token, :query_options
     ROOT_CATEGORY = 0
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
+      @query_options = query_options
       self.class.base_uri url
     end
 
@@ -16,8 +17,9 @@ module MoodleRb
         '/webservice/rest/server.php',
         {
           :query => query_hash('core_course_get_categories', token)
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response
     end
 
@@ -46,13 +48,10 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.parsed_response.first
-      end
+      check_for_errors(response)
+      response.parsed_response.first
     end
 
     def show(id)
@@ -68,8 +67,9 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response.first
     end
 
@@ -86,8 +86,9 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response.nil?
     end
   end

data/lib/moodle_rb/client.rb

@@ -3,11 +3,12 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token, :url
+    attr_reader :token, :url, :query_options
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
       @url = url
+      @query_options = query_options
       self.class.base_uri url
     end
 
@@ -16,29 +17,30 @@ module MoodleRb
         '/webservice/rest/server.php',
         {
           :query => query_hash('core_webservice_get_site_info', token)
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response
     end
 
     def courses
-      MoodleRb::Courses.new(token, url)
+      MoodleRb::Courses.new(token, url, query_options)
     end
 
     def categories
-      MoodleRb::Categories.new(token, url)
+      MoodleRb::Categories.new(token, url, query_options)
     end
 
     def users
-      MoodleRb::Users.new(token, url)
+      MoodleRb::Users.new(token, url, query_options)
     end
 
     def enrolments
-      MoodleRb::Enrolments.new(token, url)
+      MoodleRb::Enrolments.new(token, url, query_options)
     end
 
     def grades
-      MoodleRb::Grades.new(token, url)
+      MoodleRb::Grades.new(token, url, query_options)
     end
   end
 end

data/lib/moodle_rb/courses.rb

@@ -3,10 +3,11 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token
+    attr_reader :token, :query_options
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
+      @query_options = query_options
       self.class.base_uri url
     end
 
@@ -15,8 +16,9 @@ module MoodleRb
         '/webservice/rest/server.php',
         {
           :query => query_hash('core_course_get_courses', token)
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response
     end
 
@@ -44,13 +46,10 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.parsed_response.first
-      end
+      check_for_errors(response)
+      response.parsed_response.first
     end
 
     def show(id)
@@ -65,8 +64,9 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response.first
     end
 
@@ -80,9 +80,10 @@ module MoodleRb
               '0' => id
             }
           }
-        }
+        }.merge(query_options)
       )
-      response.parsed_response.nil?
+      check_for_errors(response)
+      response.parsed_response
     end
 
     def enrolled_users(course_id)
@@ -93,9 +94,54 @@ module MoodleRb
           :body => {
             :courseid => course_id
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response
     end
+
+    def grade_items(course_id, user_id=0, group_id=0)
+      response = self.class.post(
+        '/webservice/rest/server.php',
+        {
+          :query => query_hash('gradereport_user_get_grade_items', token),
+          :body => {
+            :courseid => course_id,
+            :userid => user_id,
+            :groupid => group_id
+          }
+        }.merge(query_options)
+      )
+      check_for_errors(response)
+      response.parsed_response['usergrades']
+    end
+
+    def contents(course_id)
+      response = self.class.post(
+        '/webservice/rest/server.php',
+        {
+          :query => query_hash('core_course_get_contents', token),
+          :body => {
+            :courseid => course_id
+          }
+        }.merge(query_options)
+      )
+      check_for_errors(response)
+      response.parsed_response[0]
+    end
+
+    def module(course_module_id)
+      response = self.class.post(
+        '/webservice/rest/server.php',
+        {
+          :query => query_hash('core_course_get_course_module', token),
+          :body => {
+            :cmid => course_module_id
+          }
+        }.merge(query_options)
+      )
+      check_for_errors(response)
+      response.parsed_response['cm']
+    end
   end
 end

data/lib/moodle_rb/enrolments.rb

@@ -3,16 +3,20 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token
+    attr_reader :token, :query_options
     STUDENT_ROLE_ID = 5
+    TEACHER_ROLE_ID = 3
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
+      @query_options = query_options
       self.class.base_uri url
     end
 
     # required params:
     # user_id course_id
+    # optional params:
+    # role_id - defaults to student role id
     def create(params)
       response = self.class.post(
         '/webservice/rest/server.php',
@@ -23,17 +27,38 @@ module MoodleRb
               '0' => {
                 :userid => params[:user_id],
                 :courseid => params[:course_id],
-                :roleid => STUDENT_ROLE_ID
+                :roleid => params[:role_id] || STUDENT_ROLE_ID
               }
             }
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.code == 200 && response.parsed_response.nil?
-      end
+      check_for_errors(response)
+      response.code == 200 && response.parsed_response.nil?
+    end
+
+    # required params:
+    # user_id course_id
+    # optional params:
+    # role_id - defaults to student role id
+    def destroy(params)
+      response = self.class.post(
+        '/webservice/rest/server.php',
+        {
+          :query => query_hash('enrol_manual_unenrol_users', token),
+          :body => {
+            :enrolments => {
+              '0' => {
+                :userid => params[:user_id],
+                :courseid => params[:course_id],
+                :roleid => params[:role_id] || STUDENT_ROLE_ID
+              }
+            }
+          }
+        }.merge(query_options)
+      )
+      check_for_errors(response)
+      response.code == 200 && response.parsed_response.nil?
     end
   end
 end

data/lib/moodle_rb/grades.rb

@@ -3,10 +3,11 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token
+    attr_reader :token, :query_options
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
+      @query_options = query_options
       self.class.base_uri url
     end
 
@@ -18,13 +19,10 @@ module MoodleRb
           :body => {
             :assignmentids => api_array(assignment_id)
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.parsed_response['assignments']
-      end
+      check_for_errors(response)
+      response.parsed_response['assignments']
     end
 
     def by_course(course_id, *user_ids)
@@ -36,13 +34,10 @@ module MoodleRb
             :courseid => course_id,
             :userids => api_array(user_ids)
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.parsed_response['items']
-      end
+      check_for_errors(response)
+      response.parsed_response['items']
     end
   end
 end

data/lib/moodle_rb/users.rb

@@ -3,10 +3,11 @@ module MoodleRb
     include HTTParty
     include Utility
 
-    attr_reader :token
+    attr_reader :token, :query_options
 
-    def initialize(token, url)
+    def initialize(token, url, query_options)
       @token = token
+      @query_options = query_options
       self.class.base_uri url
     end
 
@@ -25,13 +26,10 @@ module MoodleRb
               '0' => params
             }
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.parsed_response.first
-      end
+      check_for_errors(response)
+      response.parsed_response.first
     end
 
     def show(id)
@@ -47,9 +45,11 @@ module MoodleRb
               }
             }
           }
-        }
+        }.merge(query_options)
       )
-      response.parsed_response['users'] && response.parsed_response['users'].first
+      check_for_errors(response)
+      response.parsed_response['users'] &&
+        response.parsed_response['users'].first
     end
 
     def destroy(id)
@@ -62,8 +62,9 @@ module MoodleRb
               '0' => id
             }
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response.nil?
     end
 
@@ -75,8 +76,9 @@ module MoodleRb
           :body => {
             :userid => user_id
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response
     end
 
@@ -90,11 +92,28 @@ module MoodleRb
           :body => {
             :criteria => key_value_query_format(params)
           }
-        }
+        }.merge(query_options)
       )
+      check_for_errors(response)
       response.parsed_response['users']
     end
 
+    # Return list of users identities matching the given criteria in their name or other identity fields.
+    # Performs a partial match on id, idnumber, fullname, and email
+    def search_identity(search_query)
+      response = self.class.post(
+        '/webservice/rest/server.php',
+        {
+          :query => query_hash('core_user_search_identity', token),
+          :body => {
+            :query => search_query
+          }
+        }.merge(query_options)
+      )
+      check_for_errors(response)
+      response.parsed_response['list']
+    end
+
     # params must include the id of the user
     # it may include any other standard user attributes:
     # username, password, firstname, lastname, email ...
@@ -108,13 +127,10 @@ module MoodleRb
               '0' => params
             }
           }
-        }
+        }.merge(query_options)
       )
-      if error_response?(response)
-        raise MoodleError.new(response.parsed_response)
-      else
-        response.response.code == '200'
-      end
+      check_for_errors(response)
+      response.response.code == '200'
     end
   end
 end

data/lib/moodle_rb/utility.rb

@@ -27,6 +27,13 @@ module MoodleRb
       end
     end
 
+    def check_for_errors(response)
+      return unless error_response?(response)
+      raise MoodleError.new(response.parsed_response)
+    end
+
+    private
+
     def error_response?(response)
       response && response.parsed_response.is_a?(Hash) &&
         response.parsed_response.has_key?('exception')

data/lib/moodle_rb/version.rb

@@ -1,5 +1,5 @@
 module MoodleRb
-  VERSION = '1.0.2' unless defined?(self::VERSION)
+  VERSION = '1.1.3' unless defined?(self::VERSION)
 
   def self.version
     VERSION