Skip to content

StrongMind/agilix-buzz-client

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

76 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Gem Version Build Status Coverage Status

Agilix Buzz

Fully Implements the Agilix Buzz API in Ruby

Installation

Add this line to your application's Gemfile:

gem 'agilix'

And then execute:

$ bundle

Or install it yourself as:

$ gem install agilix

Be sure to define your Agilix Buzz credentials by setting up environment variables in your application appropriately. Refer to the .env.sample file for details.

AGILIX_BUZZ_USERNAME = 'my-username'
AGILIX_BUZZ_PASSWORD = 'my-password'

Optionally, if your Buzz instance runs on your own url, you can define it as well:

AGILIX_BUZZ_URL = 'https://api.mycustomdomain.com'

Usage

There are many primary APIs that are wrapped. Below you will see basic examples of how to use them. For more information about what optional query parameters are available, please consult the Agilix Buzz API Docs

Auth

You need to authenticate to use the api. Set the credentials in Environment variables as seen above. If you've done that, you can set and refernce the api object by:

api = Agilix::Buzz::Api.new

Otherwise, you can pass :username, :password, and :domain into the initializer

api = Agilix::Buzz::Api.new username: 'my-username', password: 'my-password', domain: 'my-domain'

The authentication API gives you back a token that can be used within a 15 minute window. This library will manage the need to fetch a new token or extend_session by setting the token & token expiration in the initialized api object.

Passing arguments

All APIs have defined required arguments and optional arguments, and an argument cleaner will prevent the calls from being made if conditions are not met. Additionally it will strip out any unsupported api params that are not defined in the required or optional fields.

Below are instructions for basic invocation of the api methods. For additional information about each API method, please consult the Agilix documentation, linked in each method's name.

Domains

api.create_domains [{name: "BuzzTest1", userspace: 'buzz-test-fc-1', parentid: '57025'}]
api.delete_domain domainid: '57027'

This is aliased to get_domain

api.get_domain domainid: '57025'
api.get_domain_content domainid: '57025'
api.get_domain_enrollment_metrics domainid: '57025'
api.get_domain_parent_list domainid: '57025'
api.get_domain_settings domainid: '57025', path: "AgilixBuzzSettings.xml"
api.get_domain_stats domainid: '57025', options: "users|courses"
api.list_domains domainid: '57025'
api.restore_domain domainid: '57027'
api.update_domains [{ domainid: "57027", name: "BuzzTestUpdated1", userspace: 'buzz-test-fc-1', parentid: '57025'}]

Reports

get_runnable_report_list and run_report are probably the only ones you would use.

api.get_report_info reportid: 127
api.get_report_list domainid: 1
api.get_runnable_report_list domainid: 57025
api.run_report reportid: 127, entityid: 57025, format: 'json'

Users

This is aliased to create_users

api.create_users( [{
  domainid: '57025',
  username: "BuzzUserTest1",
  email: '[email protected]',
  password: 'testpassword1234',
  firstname: 'Buzz',
  lastname: "Man",
  passwordquestion: "Who's your best friend?",
  passwordanswer: "Me"
  }] )
api.delete_users [userid: '57181']
api.get_active_user_count domainid: '57025'
api.get_active_user_count domainid: '5', includedescendantdomains: true, bymonth:true, startdate: '2018-01-01', enddate: '2019-03-01'
api.get_domain_activity domainid: '57025'

Returns base 64 encoded picture

api.get_profile_picture entityid: 57026

The api will return 404 not found if they don't have one, unless you supply it with a default profile pic, then it will return that

api.get_profile_picture entityid: 57025, default: "https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mm"

This is aliased to get_user

api.get_user userid: 57026
api.get_user_activity userid: 57026
api.get_user_activity_stream userid: 57026
api.list_users domainid: 57025
api.restore_user userid: 57026
api.update_users  [{ userid: '57026', username: "BuzzUserTestUpdated1", email: '[email protected]',firstname: 'Buzz', lastname: "ManUpdated"}]

Second Priority

Authentication

This is handled automatically by instantiation of a base Agilix::Buzz::Api instance. It wouldn't need to be called manually unless using for other users or making calls on their behalf

api.login username: 'my-username', password: 'my-password', domain: 'my-domain'

Clears your login session

api.logout

This is handled automatically by instantiation of a base Agilix::Buzz::Api instance and on subsequent calls to the api through the check_authentication method

api.extend_session
api.force_password_change userid: 57181
api.get_password_login_attempt_history userid: 57181
api.get_password_login_attempt_history userid: 57181, earliestrecordtoreturn: '2018-01-01'

For current domain

api.get_password_policy

for a specific domain

api.get_password_policy domainid: 57031
api.get_password_question username: "auto-tests/BuzzUserUp1"

ISSUE: This works with a GET call

api.update_password_question_answer userid: 57181, passwordquestion: "Where is your favorite vacation place?", passwordanswer: "Hawaii"

  api.proxy userid: 57181

In addition to these, we've created a proxy api method that will setup an api client for the proxied connection:

Proxy Api

proxy_api = api.proxy_api userid: 57181

This will allow you to make requests as the proxied user, like you would the main api user. It's required to demonstrate how unproxy works below

First setup a proxy_api

proxy_api = api.proxy_api userid: 57181

Then you can unproxy out of it to logout as the proxied user

proxy_api.unproxy userid: 57181
api.reset_lockout userid: 57181
api.reset_password username:'auto-tests/BuzzUserUp1'
api.update_password userid: 57181, password: "IChanged123"

ISSUE: This should be a POST method as it's storing data

api.put_key entityid: 57031, name: 'secret_key_1', value: "Super Secret"
api.get_key entityid: 57031, name: 'secret_key_1'

This requires a key to exist with the given keyname, see put_key. not sure what its used for yet

api.compute_hmac domainid: 57025, keyname: "secret_key_1", message:"my-secret-1"

Courses

api.copy_courses [{courseid: 60982, domainid: 57025}]
api.create_courses title: "Starter Course", domainid: 57025

ISSUE: documentation on request format is inconsistent, not sure if it is bulk

api.create_demo_course courseid: 60982, domainid: 57025, title: "Demo Course",

ISSUE: get request should be delete, put, patch

api.deactivate_course

ISSUE: Why so different than deactivate course

api.delete_courses [{courseid: 60994}]
api.get_course2 courseid: 60994
api.get_course_history courseid: 60994
api.list_courses domainid: 5
api.merge_courses courseid: 60994
api.restore_course courseid: 60994
api.update_courses [{courseid: 60994, title: "Updated Course"}]

Enrollments

ISSUE: API format is very inconsistent on this one, requires both query string modification & body modification

api.create_enrollments [{userid: 57026, entityid: 57025}]

ISSUE: Inconsistent from other delete apis. many are singular, not plural

api.delete_enrollments [ { enrollmentid: 60997 }]

This is aliased to get_enrollment

api.get_enrollment enrollmentid: 60997
api.get_enrollment_activity enrollmentid: 60997
api.get_enrollment_gradebook enrollmentid: 60997
api.get_enrollment_group_list enrollmentid: 60997

This is available in two types: Student Report

api.get_enrollment_metrics_report entityid: 50725, report: "Student"

Enrollment Report

api.get_enrollment_metrics_report entityid: 50725, report: "Enrollment"
api.list_enrollments domainid: 50725
api.list_enrollments_by_teacher teacheruserid: 50726

# If you don't pass in a teacher user id, it will default to the logged in API user

api.list_enrollments_by_teacher
api.list_entity_enrollments entityid: 60982
api.list_user_enrollments userid: 57181

ISSUE: this should be a post, not a get

api.put_self_assessment enrollmentid: 60997, understanding: 200, effort: 220, interest: 100
api.restore_enrollment enrollmentid: 60997
api.update_enrollments [{enrollmentid: 60997, status: 7}]

General

api.echo test: 'param'
api.get_command_list

ISSUE: nothing saying this is an authenticated call, when others are non-authenticated

api.get_entity_type entityid: 57025

ISSUE: docs in getting started reference a level param, actual docs suggest using rating

api.get_status rating: 4, html: true, sms: true

# you can also call this one non-authenticated
api.get_basic_status

ISSUE: Docs have cmd spelled wrong, this API doesn't seem to work at all AccessDenied. It did say experimental

api.get_upload_limits
api.get_upload_limits domainid: 57025

This is one of the more confusing APIs, it allows you to send emails to people in the same enrollment grouping as the person wanting to send the email (enrollmentid).

api.send_mail subject: "Test email", body: "Did you get this?", enrollmentid: 60997, enrollment_ids: ["all"]

Resources

api.copy_resources [ {sourceentityid: 57025, destinationentityid: 57031, sourcepath: "banner.css" }]
api.delete_resources [{entityid: 57031, path: 'banner.css'}]
api.get_entity_resource_id entityid: 57025
api.get_resource entityid: 57031, path: "banner.css"

ISSUE: This is a get request with a POST verb. The documentation only suggests getting a single resoure, so I'm not sure why it would be a bulk post syntax. it does seem to respond to multiple resources though,so we'll adapt

api.get_resource_info  [{entityid: 57031, path: "banner.css"}]
api.get_resource_list entityid: 57025
api.list_restorable_resources entityid: 57025
file_name = "my-file.pdf"
file = File.open file_name
api.put_resource file, {entityid: 57025, path: file_name}
api.put_resource_folders [{entityid: 57031, path: 'test/folder-1'}]
api.restore_resources [{entityid: 57031, path: 'banner.css'}]

Rights

ISSUE: Why is this create singular, not multiple?

api.create_role domainid: 57025, name: "Test Role", privileges: api.right_flags[:create_domain]
api.delete_role roleid: 61316

ISSUE: Why is this create singular, not multiple?

api.delete_subscriptions subscriberid: 57181, entityid: 57025

ISSUE: Why is this create singular, not multiple?

api.create_role domainid: 57025, name: "Test Role", privileges: api.right_flags[:create_domain]
api.get_effective_rights entityid: 57025
api.get_effective_subscription_list
api.get_entity_rights entityid: 57025
api.get_entity_subscription_list entityid: 57025
api.get_personas userid: 57026
api.get_rights actorid: 57026, entityid: 57025
api.get_rights_list domainid: 57025
api.get_role roleid: 61316
# Get for a domain
api.get_subscription_list subscriberid: 57025
# Get for a user
api.get_subscription_list subscriberid: 57026
api.list_roles domainid: 57025
api.restore_role roleid: 61316
api.update_rights [ {actorid: 57026, entityid: 57025, roleid: 61316}]
api.update_role roleid: 61316, name: "Test Role Updates", privileges: api.right_flags[:update_domain]

ISSUE: Why is this root node singular?

api.update_subscriptions subscriberid: 57181, entityid: 60982, startdate: "2019-03-15", enddate: "2019-03-15"

Third Priority

Assessments

Manifests and Items

Ratings

Resources


Not Prioritized

Announcements

Badges

Blogs

Command Tokens

Conversion

Discussion Boards

Groups

Gradebook

Objectives

Peer Grading

Signals

Submissions

Wikis

Features

Implemented APIs from Agilix Buzz API Docs

(Last updated on March 7, 2019)

API Methods & Docs Implemented? Priority
Announcements DeleteAnnouncements, GetAnnouncement, GetAnnouncementInfo, GetAnnouncementList, GetUserAnnouncementList, ListRestorableAnnouncements, PutAnnouncement, RestoreAnnouncements, UpdateAnnouncementViewed ❌ πŸ”Ό
Assessments DeleteQuestions, GetAttempt, GetAttemptReview, GetExam, GetNextQuestion, GetQuestion, GetQuestionScores, GetQuestionStats, GetSubmissionState, ListQuestions, ListRestorableQuestions, PrepareOfflineAttempt, PutQuestions, RestoreQuestions, SaveAttemptAnswers, SubmitAttemptAnswers, SubmitOfflineAttempt ❌ ⏺
Authentication ExtendSession, GetKey, ForcePasswordChange, GetPasswordLoginAttemptHistory, GetPasswordPolicy, GetPasswordQuestion, Login2, Logout, Proxy, PutKey, ResetLockout, ResetPassword, Unproxy, UpdatePassword, UpdatePasswordQuestionAnswer ❌ πŸ”Ό
Badges CreateBadge, DeleteBadge, GetBadge, GetBadgeAssertion, GetBadgeList ❌ πŸ”½
Blogs DeleteBlogs, GetBlog, GetBlogList, GetBlogSummary, GetRecentPosts, PutBlog, UpdateBlogViewed ❌ ⏬
Command Tokens CreateCommandTokens, GetCommandToken, GetCommandTokenInfo, DeleteCommandTokens, UpdateCommandTokens, ListCommandTokens, RedeemCommandToken ❌ ⏬
Conversion ExportData, GetConvertedData, ImportData ❌ ⏬
Courses CopyCourses, CreateCourses, CreateDemoCourse, DeactivateCourse, DeleteCourses, GetCourse2, GetCourseHistory, ListCourses, MergeCourses, RestoreCourse, UpdateCourses ❌ πŸ”Ό
Discussion Boards DeleteMessage, DeleteMessagePart, GetMessage, GetMessageList, ListRestorableMessages, PutMessage, PutMessagePart, RestoreMessages, SubmitMessage, UpdateMessageViewed ❌ πŸ”½
Domains CreateDomains, DeleteDomain, GetDomain2, GetDomainContent, GetDomainEnrollmentMetrics, GetDomainParentList, GetDomainSettings, GetDomainStats, ListDomains, RestoreDomain, UpdateDomains βœ… ⏫
Enrollments CreateEnrollments, DeleteEnrollments, GetEnrollment3, GetEnrollmentActivity, GetEnrollmentGradebook2, GetEnrollmentGroupList, GetEnrollmentMetricsReport, ListEnrollments, ListEnrollmentsByTeacher, ListEntityEnrollments, ListUserEnrollments, PutSelfAssessment, RestoreEnrollment, UpdateEnrollments ❌ πŸ”Ό
General Echo, GetCommandList, GetEntityType, GetStatus, GetUploadLimits, SendMail ❌ ⏺
Groups AddGroupMembers, CreateGroups, DeleteGroups, GetGroup, GetGroupEnrollmentList, GetGroupList, RemoveGroupMembers, UpdateGroups ❌ ⏬
Gradebook CalculateEnrollmentScenario, GetCalendar, GetCalendarItems, GetCalendarToken, GetCertificates, GetDueSoonList, GetEntityGradebook2, GetEntityGradebook3, GetEntityGradebookSummary, GetEntityWork2, GetGrade, GetGradebookList, GetGradebookSummary, GetGradebookWeights, GetGradeHistory, GetItemAnalysis2, GetItemReport, GetRubricMastery, GetRubricStats, GetUserGradebook2 ❌ πŸ”½
Manifests and Items AssignItem, CopyItems, DeleteItems, FindPersonalizedEntities, GetCourseContent, GetItem, GetItemInfo, GetItemLinks, GetItemList, GetManifest, GetManifestData, GetManifestInfo, GetManifestItem, ListAssignableItems, ListRestorableItems, NavigateItem, PutItems, RestoreItems, Search2, UnassignItem, UpdateManifestData ❌ ⏺
Objectives CreateObjectiveSets, DeleteObjectiveMaps, DeleteObjectives, DeleteObjectiveSets, GetMasteryDetail, GetMasterySummary, GetObjectiveList, GetObjectiveMapList, GetObjectiveMastery, GetObjectiveSet2, GetObjectiveSubjectList, ListObjectiveSets, PutObjectiveMaps, PutObjectives, RestoreObjectiveSet, UpdateObjectiveSets ❌ ⏬
Peer Grading GetPeerResponse, GetPeerResponseInfo, GetPeerResponseList, GetPeerReviewList, PutPeerResponse ❌ ⏬
Ratings GetItemRating, GetItemRatingSummary, PutItemRating ❌ ⏺
Reports GetReportInfo, GetReportList, GetRunnableReportList, RunReport ❌ ⏫
Resources CopyResources, DeleteDocuments, DeleteResources, GetDocument, GetDocumentInfo, GetEntityResourceId, GetResource, GetResourceInfo2, GetResourceList2, ListRestorableDocuments, ListRestorableResources, PutResource, PutResourceFolders, RestoreDocuments, RestoreResources ❌ ⏺
Rights CreateRole, DeleteRole, DeleteSubscriptions, GetActorRights, GetEffectiveRights, GetEffectiveSubscriptionList, GetEntityRights, GetEntitySubscriptionList, GetPersonas, GetRights, GetRightsList, GetRole, GetSubscriptionList, ListRoles, RestoreRole, UpdateRights, UpdateRole, UpdateSubscriptions ❌ πŸ”Ό
Signals CreateSignal, GetLastSignalId, GetSignalList2 ❌ πŸ”½
Submissions DeleteWorkInProgress, GenerateSubmission, GetScoData, GetStudentSubmission, GetStudentSubmissionHistory, GetStudentSubmissionInfo, GetTeacherResponse, GetTeacherResponseInfo, GetWorkInProgress2, PutItemActivity, PutScoData, PutStudentSubmission, PutTeacherResponse, PutTeacherResponses, PutWorkInProgress, SubmitWorkInProgress ❌ πŸ”½
Users CreateUsers2, DeleteUsers, GetActiveUserCount, GetDomainActivity, GetProfilePicture, GetUser2, GetUserActivity, GetUserActivityStream, ListUsers, RestoreUser, UpdateUsers ❌ ⏫
Wikis CopyWikiPages, DeleteWikiPages, GetWikiPage, GetWikiPageList, ListRestorableWikiPages, PutWikiPage, RestoreWikiPages, UpdateWikiPageViewed ❌ ⏬
Example Name Example Description βœ… or ❌ β«πŸ”ΌβΊπŸ”½β¬

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Run this command at the application's root directory to view test code coverage:

open coverage/index.html 

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/beneggett/agilix. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Agilix::Buzz project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

About

No description, website, or topics provided.

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Ruby 98.7%
  • HTML 1.2%
  • Shell 0.1%